README

PHP ^7.4 和 ^8.0 兼容的SDK，适用于开发者友好的车辆API。请查看我们的文档以更好地了解SDK的工作原理

• https://carapi.app/docs/
• https://carapi.app/api

安装

使用 composer 安装SDK

composer require car-api-team/carapi-php-sdk

如果你的项目有一个可发现的HTTP客户端，则SDK将自动使用它。如果没有，你需要添加一个。你可以在此处了解更多关于HTTP发现的信息：https://github.com/php-http/discovery

用法

使用你的token和secret创建SDK实例。以下示例假设你已经将它们存储在.env文件中，但你也可以按需加载它们。

$sdk = \CarApiSdk\CarApi::build([
    'token' => getenv('CARAPI_TOKEN'),
    'secret' => getenv('CARAPI_SECRET'),
]);

你现在已创建了SDK的一个实例。

认证

authenticate方法将返回JWT并在SDK内部存储JWT。我们不提供持久化存储，因此你需要在你的应用程序中处理缓存。我们将提供一个使用文件系统的基本缓存示例，但我们建议使用你框架的缓存库或类似symfony/cache或cake/cache的东西。

$filePath = '/some/path/not/readable/by/browsers/carapi_jwt.txt';
$jwt = file_get_contents($filePath);
if (empty($jwt) || $sdk->loadJwt($jwt)->isJwtExpired() !== false) {
    try {
        $jwt = $sdk->authenticate();
        file_put_contents($filePath, $jwt);
    } catch (\CarApiSdk\CarApiException $e) {
        // handle errors here
    }
}

// make your api calls here...

传递查询参数

查询参数可以作为键值数组传递给API端点。

$sdk->years(['query' => ['make' => 'Tesla']]);

传递JSON搜索

可以将JSON搜索参数作为对象传递给API端点。

$json = (new \CarApiSdk\JsonSearch())
    ->addItem(new \CarApiSdk\JsonSearchItem('make', 'in', ['Tesla']));
$sdk->years(['query' => ['json' => $json]])

分页

支持分页的端点将返回一个包含分页元数据的集合属性和一个包含实际结果的data属性。以下是通过/api/makes端点分页的示例

$page = 1;
do {
    $result = $sdk->makes(['query' => ['limit' => 1, 'page' => $page]]);
    $lastPage = $result->collection->pages;
    $page++;
    print_r($result->data);
} while ($page <= $lastPage);

异常

SDK在错误时将抛出\CarApiSdk\CarApiException。在某些情况下，这只是捕获并重新抛出底层的HTTP异常或JSON异常。在大多数情况下，这会捕获API响应中的错误并将它们格式化为CarApiException。

年份

years方法返回一个整数数组。

$years = $sdk->years();
foreach ($years as $year) {
    echo $year;
}

获取特斯拉销售汽车的所有年份

$sdk->years(['query' => ['make' => 'Tesla']]);

制造商

返回一个集合。

foreach ($sdk->makes()->data as $make) {
    echo $make->name;
}

获取2020年的所有制造商

$sdk->makes(['query' => ['year' => 2020]]);

型号

返回一个集合。

foreach ($sdk->models()->data as $model) {
    echo $model->name;
}

获取所有2020年丰田车型

$sdk->models(['query' => ['year' => 2020, 'make' => 'Toyota']]);

剪裁

返回一个集合。

foreach ($sdk->trims()->data as $trim) {
    echo $trim->name;
}

获取所有2020年福特F-150剪裁

$sdk->trims(['query' => ['year' => 2020, 'make' => 'Ford', 'model' => 'F-150']]);

获取所有2020年福特F-150和F-250剪裁

$json = (new \CarApiSdk\JsonSearch())
    ->addItem(new \CarApiSdk\JsonSearchItem('model', 'in', ['F-150', 'F-250']));
$sdk->trims(['query' => ['year' => 2020, 'make' => 'Ford', 'json' => $json]]);

获取2020年丰田或福特的全部轿车

$json = (new \CarApiSdk\JsonSearch())
    ->addItem(new \CarApiSdk\JsonSearchItem('make', 'in', ['Toyota', 'Ford']));
    ->addItem(new \CarApiSdk\JsonSearchItem('bodies.type', '=', 'Sedan'));
$result = $sdk->trims(['query' => ['year' => 2020, 'json' => $json]]);
foreach ($result->data as $trim) {
    echo $trim->name;
}

或者对于单个剪裁，返回一个对象

echo $sdk->trimItem($id)->name;

车辆识别号(VIN)

返回一个对象

$sdk->vin('1GTG6CEN0L1139305');

遍历VIN查找返回的所有剪裁

foreach ($sdk->vin('1GTG6CEN0L1139305')->trims as $trim) {
    echo $trim->name;
}

车身

返回一个集合。

foreach ($sdk->bodies()->data as $body) {
    echo $body->type;
}

引擎

返回一个集合。

foreach ($sdk->engines()->data as $engine) {
    echo $engine->engine_type;
}

里程数

返回一个集合。

$sdk->mileages();

内饰颜色

返回一个集合。

$sdk->interiorColors();

外观颜色

返回一个集合。

$sdk->exteriorColors();

CSV数据流

以ResponseInterface返回数据流。你需要在应用程序中处理提取文件。

$sdk->csvDataFeed();

CSV数据流最后更新

返回一个对象。

$sdk->csvDataFeedLastUpdated();

车辆属性

返回一个字符串数组。

$sdk->vehicleAttributes('bodies.type');

账户请求

返回一个对象数组。

$sdk->accountRequests();

账户请求今日

返回一个对象

$sdk->accountRequestsToday();