README

这是一个用于PTV API的SDK。

目前它部分实现了数据API和路由API。

底层使用Saloon来处理请求。

它只包含2个依赖项

• saloonphp/saloon用于处理请求和SDK构建
• moneyphp/money用于表示价格和货币

每个参数和响应对象都与专门的DTO类和Enum进行仔细映射

安装

composer require weble/ptv-php

基本用法

只需创建客户端并与每个API交互。

use PTV\PTV;

$ptv = new PTV('[YOUR-API-KEY]');

$profiles = $ptv->data()->vehicleProfiles()->all();
$route $ptv->routing()->route()->calculate(['lat,lng', 'lat2,lng2']);

设置语言

use PTV\PTV;

$ptv = new PTV('[YOUR-API-KEY]', 'it');

数据API

截至目前，仅实现了3个端点

1. vehicleProfiles

use PTV\PTV;

$ptv = new PTV('[YOUR-API-KEY]');
$profiles = $ptv->data()->vehicleProfiles()->all();

2. vehicleModels

use PTV\Data\Enums\VehicleType;
use PTV\PTV;

$ptv = new PTV('[YOUR-API-KEY]');

$profiles = $ptv->data()->vehicleModels()->all();
$profiles = $ptv->data()->vehicleModels()->all([
    VehicleType::TRAILER,
    VehicleType::SEMI_TRAILER,
]);

3. mapInformation

use PTV\Data\Enums\VehicleType;
use PTV\PTV;

$ptv = new PTV('[YOUR-API-KEY]');

$mapInfo = $ptv->data()->mapInformation()->all();

路由API

目前仅支持3个端点

1. calculate

这是最完整的一个，也是最可能被使用的。您可以在调用中通过链式参数来计算路线。

每个参数都已进行了类型化，以便实现完全的IDE自动完成和易于使用。

use Money\Currency;
use PTV\Data\Enums\EngineType;
use PTV\Data\Enums\FuelType;
use PTV\PTV;
use PTV\Routing\DTO\MonetaryCostOptions;
use PTV\Routing\DTO\Options;
use PTV\Routing\DTO\Vehicle;
use PTV\Routing\Enums\ResultType;
use PTV\Routing\Enums\TrafficMode;

$ptv = new PTV('[YOUR-API-KEY]');
$route = $ptv
    ->routing()
    ->route()
    ->return([
        ResultType::MONETARY_COSTS,
            ResultType::POLYLINE,
            ResultType::LEGS,
            ResultType::LEGS_POLYLINE,
            ResultType::ROUTE_ID,
            ResultType::TOLL_COSTS,
            ResultType::TOLL_SYSTEMS,
            ResultType::TOLL_SECTIONS,
            ResultType::TOLL_EVENTS,
            ResultType::ALTERNATIVE_ROUTES,
            ResultType::GUIDED_NAVIGATION,
    ])
    ->forVehicle(
         new Vehicle(
            engineType: EngineType::COMBUSTION,
            fuelType: FuelType::DIESEL,
            numberOfAxles: 2,
            totalPermittedWeight: 75000,
         )
    )
    ->withCostOptions(
        new MonetaryCostOptions(
             costPerKilometer: 1.2
        )
    )
    ->withOptions(
        new Options(
            startTime: DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2025-01-01 09:00:00'),
            trafficMode: TrafficMode::AVERAGE,
            currency: new Currency('EUR'),
        )
    )
    ->calculate([
        "45.5422993,11.5220921",
        "53.5418064,9.9991367"
])

2. recalculate

使用先前返回的路线ID重新计算路线结果的部分

use Money\Currency;
use PTV\Data\Enums\EngineType;
use PTV\Data\Enums\FuelType;
use PTV\PTV;
use PTV\Routing\DTO\MonetaryCostOptions;
use PTV\Routing\DTO\Options;
use PTV\Routing\DTO\Vehicle;
use PTV\Routing\Enums\ResultType;
use PTV\Routing\Enums\TrafficMode;

$ptv = new PTV('[YOUR-API-KEY]');
$route = $ptv
    ->routing()
    ->route()
    ->return([
        ResultType::MONETARY_COSTS,
    ])
    ->withCostOptions(
        new MonetaryCostOptions(
             costPerKilometer: 1.2
        )
    )
    ->withOptions(
        new Options(
            startTime: DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2025-01-01 09:00:00'),
            trafficMode: TrafficMode::AVERAGE,
            currency: new Currency('EUR'),
        )
    )
    ->recalculate('[your-route-id]');

获取路线

获取先前计算的路线详情，甚至替代路线详情。

use Money\Currency;
use PTV\Data\Enums\EngineType;
use PTV\Data\Enums\FuelType;
use PTV\PTV;
use PTV\Routing\DTO\MonetaryCostOptions;
use PTV\Routing\DTO\Options;
use PTV\Routing\DTO\Vehicle;
use PTV\Routing\Enums\ResultType;
use PTV\Routing\Enums\TrafficMode;

$ptv = new PTV('[YOUR-API-KEY]');
$route = $ptv
    ->routing()
    ->route()
    ->get('[your-route-id]');

路线对象

Route对象是一个完全类型化的DTO，以便轻松阅读API的结果

use PTV\Routing\DTO\Route;
/** @var Route  $route **/

$route->alternativeRoutes;
$route->monetaryCosts->distanceCost;
$route->toll->costs;

// ...

测试

要测试，您可以运行

composer test

它将使用测试json来测试SDK。

如果您愿意，还可以设置一个.env文件，包含专用的PTV密钥，并用API进行一些实际测试。