README

detrack-core-php

PHP 应用程序与 Detrack API 交互的官方核心库。

重要的 v2 版本发布 由于后端 API 的重大重构，v2 版本与使用 v1 库的代码不兼容。类名和方法名已更改。请仔细查阅文档，并根据您的决定相应地重构代码。

安装

通过 composer 安装包

composer require detrack/detrack-core:^2.0

Composer 将为您处理所有依赖项。

先决条件

需要 PHP >= 7.1

PHP 5.6 和 7.0 已被官方弃用；我们的新库和 API 利用 PHP 7.1 的新功能，以提高稳定性。

您还必须在 Detrack 上创建（免费！）账户，并了解我们的基本工作流程。

如果您尚未包含自动加载器，请记住包含它

require_once "vendor/autoload.php";

简单使用指南

在这个简短的指南中，我们将假设我们是一家销售冰淇淋的网店，并使用 Detrack 服务来跟踪我们的配送。我们将使用此库来实现 Detrack 功能的最低限度的功能。（更详细的指南见下方）

客户端外观

首先，您需要配置 Detrack\DetrackCore\Client\DetrackClientStatic 的静态外观。

Detrack\DetrackCore\Client\DetrackClientStatic::setApiKey($apiKey);

此库中的所有对象将使用此 API 密钥处理您请求生命周期的其余部分。

创建配送

当您的网店确认客户的付款时，您需要向我们发送一个关于配送详情的请求，以便您的车队中空闲的车辆可以完成此次配送。这通过 Job 和 Item 对象表示。

Detrack\DetrackCore\Resource\Job 表示您分配给司机的单个配送工作。在网店的情况下，这也表示店铺上的单个订单。 Detrack\DetrackCore\Resource\Model\Item 表示订单中您商店中的单个商品。虽然您不需要此功能使 Detrack 运行，但当配送标记为完成时，您和您的客户将在电子交货证明（POD）中看到它。

在提交 Job 对象之前，您必须给出三个属性，即 date（日期）、do_number（配送订单号）和 address（地址）。

use Detrack\DetrackCore\Resource\Job;

$delivery = new Job([
  "date"=>"2018-12-19",
  "do_number"=>"DO# 12345",
  "address"=>"Null Island",
  "instructions"=>"Tell recipient to come out and retrieve ice cream from van" //not required, but you can specify other fields that are documented on our API reference
]);

$delivery->save();

您也可以首先将构造函数的参数传递为空，然后稍后修改这些属性

use Detrack\DetrackCore\Resource\Job;

$delivery = new Job();
$delivery->date = "2018-12-19";
$delivery->do_number = "DO# 12345";
$delivery->address = "Null Island";
$delivery->instructions = "Tell recipient to come out and retrieve ice cream from van"; //not required, but you can specify other fields that are documented on our API reference
$delivery->save(); //submits the delivery to Detrack

请记住，在调用 save() 之前，您必须确保设置了所需的属性 date、do_number 和 address。

请注意，save() 函数的行为类似于“更新”函数，它自动创建尚未存在的作业或更新已存在的作业。如果您需要“严格插入”和“严格更新”，请分别使用 create() 和 save()，但请准备在调用具有相同日期上的冲突 do_number 的作业上的 create() 时捕获 Exception，以及在调用不存在于作业上的 update() 时。

这就完成了！您已将第一次配送提交给Detrack。如果您已经在Detrack控制面板上正确设置了您的车辆，系统将自动将配送分配给您的司机，您可以通过他们的其他应用开始跟踪它们。

向配送中添加物品

虽然前一部分中记录的是将您的应用程序集成到Detrack所需的最基本信息，但您应该添加更多对您的工作人员和客户都有用的信息。接下来我们将介绍如何在您的配送中添加物品。这些物品将显示在收据和电子 POD 上，您和客户都将收到。

Item 对象有三个基本必需属性：sku（库存单位（编号）），qty（数量）和desc（描述）。

创建 Item 对象的过程与 Deliveries 类似，但您不需要使用工厂，因为没有客户端要附加。

use Detrack\DetrackCore\Resource\Model\Item;

$item = new Item([
  "sku"=>"IC 456",
  "qty"=>"5",
  "desc"=>"Strawberry flavoured ice-cream"
]);

或者，像工作一样，您可以在构造函数中传递一个空参数，然后稍后设置属性。

use Detrack\DetrackCore\Model\Item;

$item = new Item();
$item->sku = "IC 456";
$item->qty = "5";
$item->desc = "Strawberry flavoured ice-cream";

然后，您需要通过首先访问items属性，然后调用add()方法，将它们添加到配送对象中。

$delivery->items->add($item);
$delivery->save() //sends the info to Detrack

就这样：items属性是Detrack\DetrackCore\Model\ItemCollection的实例，包含push()、pop()等方法，您可以用来操作附加到配送的物品。别忘了之后调用save()以将更改提交到Detrack API。

高级使用指南

这部分包含了一些零散的信息，如果您需要更细粒度的控制，请参考。

查找配送

存储在 Detrack 数据库中的配送通过其do_number和计划配送的date来标识。

存在hydrate()方法，可以根据do_number和date填充其余属性。

这通常用于检索配送的更新信息。

Upsert 和删除

save()和delete()函数以对象-关系映射（ORM）风格工作，您可以在任何Job对象上调用它们。

// Update instructions
$delivery->instructions = "Change of plan, leave ice cream package in the mailbox instead";
$delivery->save();

// Customer no longer wants ice cream
$delivery->delete();

删除后，配送工作将不再在Detrack仪表板上显示，也不再被跟踪。

创建和更新

如上所述，如果您需要严格的插入和更新，请使用create()和update()。

$delivery = new Job();
$delivery->do_number = "DO# 12345";
$delivery->address = "PHP Island";
$delivery->date = date("Y-m-d");
$delivery->items->add(new Item(["sku"=>"1","qty"=>5,"desc"=>"Chocolate Ice Cream"]));

//will throw exception
$delivery->update();
//ok
$delivery->create();

$delivery->items->pop();
$delivery->items->add(new Item(["sku"=>"2","qty"=>5,"desc"=>"Strawberry Ice Cream"]));
//will throw exception
$delivery->create();
//ok
$delivery->update();

检索文档

存在downloadDoc(String $document, String $format, String $target)方法，可以下载与每个Job相关的文档。

$document - "pod"（默认）或"shipping-label"
$format - "pdf"（默认）或"tiff"
$target - NULL（默认）或/path/to/folder或/path/to/nonexistent/file。
- 如果传递了NULL，则会以字符串形式返回原始文件数据。
- 如果提供了现有文件夹的路径，则文件将使用服务器上的默认文件名下载到该文件夹。
- 如果提供了不存在文件的路径，则文件将使用该名称和路径下载。

批量操作

对于列表、创建（严格）和删除，都提供了批量操作。但是，当处理大量数据集时，您应谨慎使用它们，因为如果您的PHP中的MAX_EXECUTION_TIME设置不够长，它们可能会导致您的脚本超时。

Job::listJobs(array $args, String $query) 如果您需要在仪表板中显示许多工作，如概览，则可以使用此方法。 $args是一个关联数组，具有以下键
- page int，默认1
- limit int，默认50
- sort String，提供要按其排序的属性名称（例如"date"）。在前面添加一个减号以反转顺序。**如果同时使用$query，则不起作用**。
- date String，日期，格式为Y-m-d，仅列出该天的配送。
- 类型 type "delivery"（默认）或 "collection"
- assign_to String 仅显示由该驾驶员驱动的任务
- status String 仅显示特定状态的任务。可用的是 "complete"、"completed_partial"、"failed"
- do_number String 仅显示具有特定DO号码的任务。用于显示重试（因为重试将具有相同的DO号码但不同的 date）$query 是一个搜索词，允许您搜索其他所有字段，如地址。
Job::createJobs(array $jobs) 批量创建任务数组。您可以传递一个 Job 对象数组或表示 Job 对象属性的关联数组。
Job::deleteJobs(array $jobs) 批量删除任务数组。您可以传递一个 Job 对象数组或表示 Job 对象属性的关联数组，尽管您只需要 id 字段。该方法将自动为您删除其他属性。

车辆

车辆也可以像任务一样创建、检索、更新和删除。完全限定类名为 Detrack\DetrackCore\Resource\Vehicle。

创建车辆

在Detrack后端，Vehicle 有三个关键字 - name，这是组织设置的驾驶员名称，detrack_id，驾驶员的唯一ID，以及 id，驾驶员和组织配对的唯一ID。

detrack_id 是每个驾驶员唯一的哈希字符串，可以在他们打开手机上的Detrack送货应用时看到。要创建送货，构造一个 Vehicle 对象并填写 detrack_id 和 driver 属性。

use Detrack\DetrackCore\Resource\Vehicle;

$vehicle = new Vehicle();
$vehicle->detrack_id = "SGVsbG8gV29ybGQ";
$vehicle->name = "Tom's Van";
$vehicle->save();
//or
$vehicle->create();

与 Job 类似，hydrate()、update()、delete() 函数也适用于 Vehicle 对象。

程序分配任务到车辆

使用 assignTo(Vehicle $vehicle) 方法在 Job 对象上分配任务给驾驶员。继续上面的示例

$tomsVehicle = new Vehicle();
$tomsVehicle->name = "Tom's Van";
$tomsVehicle = $tomsVehicle->hydrate(); //optional, assignTo will do it for you anyway

$delivery->assignTo($tomsVehicle);

然后在您的代码的另一个地方，您可以调用 getVehicle() 在 Job 对象上检索分配给它的 Vehicle。

echo $delivery->getVehicle()->name;
//prints "Tom's Van"

贡献

我们欢迎贡献。如果您觉得某些地方可以改进，请随时提交一个拉取请求。

错误报告 & 功能请求

在GitHub上打开问题，或发送电子邮件至 info@detrack.com，地址为工程团队。

设置开发环境

克隆此存储库并安装composer开发依赖项。

git clone https://github.com/detrack/detrack-core-php.git .
composer install

测试

参考 .env.example 文件并创建您自己的 .env 文件以输入测试API密钥、DO号码、驾驶员detrack_id等。测试将在您的Detrack仪表板上创建示例任务，并在成功完成后将其删除。（因此，需要互联网连接才能运行测试套件）在 tests 文件夹上运行 phpunit，通过 vendor 文件夹或通过全局安装的可执行文件。

构建

GuzzleHttp - 底层HTTP库

作者

Chester Koh - 初始工作 - chesnutcase

许可证

本项目采用MIT许可证 - 有关详细信息，请参阅 LICENSE.md 文件。

detrack / detrack-core

维护者

详情