---
title: "PHP"
description: "Official CarsXE SDK for PHP."
canonical_url: "https://docs.carsxe.com/docs/sdks/php"
markdown_url: "https://docs.carsxe.com/docs/sdks/php.md"
last_updated: "1980-01-01"
---

# PHP
URL: /docs/sdks/php
LLM index: /llms.txt
Description: Official CarsXE SDK for PHP.

The `carsxe/carsxe` Packagist package ships typed PHP 8.1 model classes for all CarsXE API responses. It does not bundle an HTTP client — use it alongside Guzzle (or any PSR-18 client) to make requests and hydrate the typed models from the JSON response. Requires PHP 8.1 or later.

## Installation

```bash
composer require carsxe/carsxe guzzlehttp/guzzle
```

## Quick start

```php
<?php

require_once __DIR__ . '/vendor/autoload.php';

use CarsXE\Models\VehicleSpec;
use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://api.carsxe.com']);

$response = $client->get('/specs', [
    'query' => [
        'key' => $_ENV['CARSXE_API_KEY'],
        'vin' => 'WBAFR7C57CC811956',
    ],
]);

$body = json_decode((string) $response->getBody(), true);
$spec = VehicleSpec::fromArray($body['data']);

echo "{$spec->year} {$spec->make} {$spec->model}\n";
```

## Available models

| Class | Description |
|---|---|
| `VehicleSpec` | Full vehicle specification (VIN, make, model, engine, etc.) |
| `BulkRecallBatchJob` | Completed bulk recall batch job |
| `BulkRecallBatchJobPending` | In-progress bulk recall batch job |
| `BulkRecallBatchResult` | Result row for a single VIN in a batch |
| `BulkRecallBatchRow` | Raw recall row within a batch result |

Each class exposes a `static fromArray(array $data): self` factory method that maps the API response directly to typed readonly properties.

## Additional endpoints

The same Guzzle pattern works for every CarsXE endpoint — just change the path and query parameters:

```php
// Market value
$response = $client->get('/market-value', [
    'query' => [
        'key'      => $_ENV['CARSXE_API_KEY'],
        'vin'      => 'WBAFR7C57CC811956',
        'mileage'  => 45000,
        'state'    => 'CA',
    ],
]);

// Safety recalls
$response = $client->get('/recalls', [
    'query' => [
        'key' => $_ENV['CARSXE_API_KEY'],
        'vin' => 'WBAFR7C57CC811956',
    ],
]);

// Vehicle history
$response = $client->get('/history', [
    'query' => [
        'key' => $_ENV['CARSXE_API_KEY'],
        'vin' => 'WBAFR7C57CC811956',
    ],
]);
```

## Error handling

Guzzle throws `GuzzleHttp\Exception\ClientException` on 4xx responses and `GuzzleHttp\Exception\ServerException` on 5xx:

```php
use GuzzleHttp\Exception\GuzzleException;

try {
    $response = $client->get('/specs', [
        'query' => ['key' => $_ENV['CARSXE_API_KEY'], 'vin' => 'WBAFR7C57CC811956'],
    ]);
    $body = json_decode((string) $response->getBody(), true);
    $spec = VehicleSpec::fromArray($body['data']);
} catch (GuzzleException $e) {
    // $e->getCode() → HTTP status
    // $e->getMessage() → error details
    error_log('CarsXE error: ' . $e->getMessage());
}
```

## Best practices

**Load your key from the environment.** Never hardcode it.

```php
// .env (loaded via vlucas/phpdotenv or similar)
CARSXE_API_KEY=your_key_here
```

```php
$apiKey = $_ENV['CARSXE_API_KEY'] ?? getenv('CARSXE_API_KEY');
```

**Reuse the Guzzle client.** Instantiate it once (e.g. in a service container) and inject it — Guzzle reuses the underlying cURL handle pool.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).