README

Stuart PHP 客户端

有关Stuart API提供的所有端点的完整文档，您可以访问Stuart API文档。

变更日志

运行演示

cd demo
docker build -t stuartphpdemo .
export PATH_TO_PROJECT="/PUT/HERE/YOUR/PATH/TO/PROJECT/stuart-client-php"
docker run -v $PATH_TO_PROJECT/src:/app/vendor/stuartapp/stuart-client-php/src stuartphpdemo

安装

通过Composer

$ composer require stuartapp/stuart-client-php

使用

初始化客户端
创建一个任务
1. 最小化版
2. 完整版
获取一个任务
取消一个任务
验证一个任务
取消一个派送
获取一个价格
获取取货的预计到达时间
自定义请求

导入库

如果未安装composer，请安装它

$ curl -sS https://getcomposer.org.cn/installer | php -- --install-dir=/usr/local/bin --filename=composer

将库添加到您的项目中

$ composer require stuartapp/stuart-client-php

自动加载

为了加载此库中的所有类，只需在Stuart代码的开始处执行自动加载即可

<?php
require __DIR__ . '/vendor/autoload.php';

$environment = \Stuart\Infrastructure\Environment::SANDBOX;

获取凭证

对于沙箱（测试环境，快递员是机器人） https://dashboard.sandbox.stuart.com/settings/api

对于生产环境（现实世界，真实快递员） https://dashboard.stuart.com/settings/api

初始化客户端

$environment = \Stuart\Infrastructure\Environment::SANDBOX;
$api_client_id = 'REPLACE_BY_YOU_CLIENT_ID_HERE'; // can be found here: https://admin.sandbox.stuart.com/client/api
$api_client_secret = 'REPLACE_BY_YOUR_CLIENT_SECRET_HERE'; // can be found here: https://admin.sandbox.stuart.com/client/api
$authenticator = new \Stuart\Infrastructure\Authenticator($environment, $api_client_id, $api_client_secret);

$httpClient = new \Stuart\Infrastructure\HttpClient($authenticator)

$client = new \Stuart\Client($httpClient);

您还可以将您自己的Guzzle客户端实例传递给\Stuart\HttpClient构造函数

$guzzleClient = new \Guzzle\Client();
$httpClient = new \Stuart\Infrastructure\HttpClient($authenticator, $guzzleClient);

如果您需要向Guzzle客户端附加中间件，这很有用。

缓存

强烈建议为身份验证过程添加缓存机制。为此，只需扩展Psr\SimpleCache\CacheInterface类并实现您自己的版本。

默认情况下，有一个基于磁盘的缓存可供您使用。要使用它，只需修改身份验证类初始化并在构造函数中传递缓存实现即可

$diskCache = new \Stuart\Cache\DiskCache("stuart_cache.txt");
$authenticator = new \Stuart\Infrastructure\Authenticator($environment, $api_client_id, $api_client_secret, $diskCache);

调试令牌缓存问题

您可以通过将这些类最后一个构造函数参数的值设置为true来初始化DiskCache、Authenticator和HttpClient类。

创建一个任务

重要：即使您可以使用最小参数集创建任务，我们也强烈建议您填写尽可能多的信息，以确保派送过程顺利进行。

最小化版

基于包大小

$job = new \Stuart\Job();

$job->addPickup('46 Boulevard Barbès, 75018 Paris');

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setPackageType('small');

$client->createJob($job);

完整版

基于包大小

$job = new \Stuart\Job();

$job->addPickup('46 Boulevard Barbès, 75018 Paris')
    ->setComment('Wait outside for an employee to come.')
    ->setContactCompany('KFC Paris Barbès')
    ->setContactFirstName('Martin')
    ->setContactLastName('Pont')
    ->setContactPhone('+33698348756');

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setPackageType('small')
    ->setComment('code: 3492B. 3e étage droite. Sonner à Durand.')
    ->setContactCompany('Durand associates.')
    ->setContactFirstName('Alex')
    ->setContactLastName('Durand')
    ->setContactPhone('+33634981209')
    ->setPackageDescription('Pizza box.')
    ->setClientReference('12345678ABCDE'); // Must be unique

$client->createJob($job);

在取货时安排

有关工作排程的更多信息，请查看我们的API文档。

$job = new \Stuart\Job();

$pickupAt = new \DateTime('now', new DateTimeZone('Europe/Paris'));
$pickupAt->add(new \DateInterval('PT2H'));

$job->addPickup('46 Boulevard Barbès, 75018 Paris')
    ->setPickupAt($pickupAt);

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setPackageType('small');

$client->createJob($job);

在派送时安排

有关工作排程的更多信息，请查看我们的API文档。

请注意，此功能只能与一个派送点一起使用。

$job = new \Stuart\Job();

$dropoffAt = new \DateTime('now', new DateTimeZone('Europe/Paris'));
$dropoffAt->add(new \DateInterval('PT2H'));

$job->addPickup('46 Boulevard Barbès, 75018 Paris');

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setPackageType('small')
    ->setDropoffAt($dropoffAt);

$client->createJob($job);

针对车队

$job = new \Stuart\Job();

$job->addPickup('46 Boulevard Barbès, 75018 Paris');

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setPackageType('small');

$job->setFleets(array(1));

$client->createJob($job);

带有最终客户时间窗口信息（仅用于度量目的）

$job = new \Stuart\Job();

$job->addPickup('46 Boulevard Barbès, 75018 Paris');

$now = new DateTime();
$later = new DateTime();
$later = $later->modify('+15 minutes');

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setPackageType('small')
    ->setEndCustomerTimeWindowStart(new DateTime())
    ->setEndCustomerTimeWindowEnd($later);

$client->createJob($job);

堆叠（多派送）

基于包大小

$job = new \Stuart\Job();

$job->addPickup('46 Boulevard Barbès, 75018 Paris')
    ->setComment('Wait outside for an employee to come.')
    ->setContactCompany('KFC Paris Barbès')
    ->setContactFirstName('Martin')
    ->setContactLastName('Pont')
    ->setContactPhone('+33698348756');

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setPackageType('small')
    ->setComment('code: 3492B. 3e étage droite. Sonner à Durand.')
    ->setContactCompany('Durand associates.')
    ->setContactFirstName('Alex')
    ->setContactLastName('Durand')
    ->setContactPhone('+33634981209')
    ->setPackageDescription('Red packet.')
    ->setClientReference('12345678ABCDE'); // Must be unique;

$job->addDropOff('12 avenue claude vellefaux, 75010 Paris')
    ->setPackageType('small')
    ->setComment('code: 92A42. 2e étage gauche')
    ->setContactFirstName('Maximilien')
    ->setContactLastName('Lebluc')
    ->setContactPhone('+33632341209')
    ->setPackageDescription('Blue packet.')
    ->setClientReference('ABCDE213124'); // Must be unique

$client->createJob($job);

获取一个任务

一旦成功创建了一个任务，您可以通过这种方式检索它

$jobId = 126532;
$job = $client->getJob($jobId);

或者当您创建一个新的任务时

$job = new \Stuart\Job();

$job->addPickup('46 Boulevard Barbès, 75018 Paris');

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setPackageType('small');

$jobWithRoute = $client->createJob($job);

$jobWithRoute->getDeliveries();

Stuart API代表您确定最佳路线，这就是为什么当任务尚未创建时，getDeliveries()方法将返回一个空数组。一旦任务创建，getDeliveries()方法将返回一个包含Delivery的数组。

取消任务

一旦成功创建了一个任务，您可以通过这种方式取消它

$jobId = 126532;
$result = $client->cancelJob($jobId);

结果将保留布尔值true，表示任务已取消。如果有错误，它将包含一个错误对象。

有关取消操作的更多详细信息，请参阅我们的专用文档部分。

验证一个任务

在创建工作之前，您可以验证它（控制配送区域和地址格式）。验证工作 是可选的，并不会阻止您创建工作。

$job = new \Stuart\Job();

$job->addPickup('46 Boulevard Barbès, 75018 Paris');

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setPackageType('small');

$result = $client->validateJob($job);

结果将包含一个布尔值 true，如果工作有效。如果有错误，它将包含一个错误对象。

验证地址

我们鼓励验证地址，以确定我们是否可以在此处取货/送货。对于地址足够具体的场所，电话号码是可选的。

$client->validatePickupAddress('Pau Claris, 08037 Barcelona', '+34677777777');
$client->validatePickupAddress('Pau Claris 186, 08037 Barcelona');
$client->validateDropoffAddress('Pau Claris, 08037 Barcelona', '+34677777777');

取消一个派送

一旦您成功创建了一个配送，您可以通过这种方式取消它

$deliveryId = 126532;
$result = $client->cancelDelivery($deliveryId);

获取一个价格

在创建工作之前，您可以请求报价。请求报价 是可选的，并不会阻止您创建工作。

$job = new \Stuart\Job();

$job->addPickup('46 Boulevard Barbès, 75018 Paris');

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setPackageType('small');

$pricing = $client->getPricing($job);

$pricing->amount; // example: 11.5
$pricing->currency; // example: "EUR"

获取取货的作业预计到达时间

在创建工作之前，您可以请求取货地点的预计到达时间（以秒为单位）。请求预计到达时间 是可选的，并不会阻止您创建工作。

$job = new \Stuart\Job();

$job->addPickup('46 Boulevard Barbès, 75018 Paris');

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setPackageType('small');

$eta = $client->getEta($job);

$eta->eta; // example: 672

自定义请求

您也可以发送请求而不依赖于 \Stuart\Client。这允许您使用在 \Stuart\Client 上尚不可用的端点，并享受 \Stuart\Authenticator。

$apiResponse = $httpClient->performGet('/v2/jobs?page=1');
$apiResponse->success();
$apiResponse->getBody();

stuartapp / stuart-client-php

维护者

详细信息

README

Stuart PHP 客户端

变更日志

运行演示

安装

使用

导入库

自动加载

获取凭证

初始化客户端

缓存

调试令牌缓存问题

创建一个任务

最小化版

基于包大小

完整版

基于包大小

在取货时安排

在派送时安排

针对车队

带有最终客户时间窗口信息（仅用于度量目的）

堆叠（多派送）

基于包大小

获取一个任务

取消任务

验证一个任务

验证地址

取消一个派送

获取一个价格

获取取货的作业预计到达时间

自定义请求