README

一个使用GLS Track & Trace Web API跟踪GLS包裹的PHP库。

安装

此库可以通过 Composer 安装

composer require benmorel/gls-tracker

需求

此库需要PHP 7.1或更高版本。

项目状态及发布流程

此库正在开发中。

当前版本编号为 0.x.y。当引入非破坏性更改（添加新方法、优化现有代码等）时，y 增量。

当引入破坏性更改时，总是开始新的 0.x 版本周期。

因此，将您的项目锁定在给定的发布周期（如 0.1.*）是安全的。

如果您需要升级到较新的发布周期，请查看 发布历史 以获取每个进一步的 0.x.0 版本引入的更改列表。

快速入门

首先，使用您的GLS API用户名和密码实例化跟踪器

use BenMorel\GLSTracker\GLSTracker;
use BenMorel\GLSTracker\GLSTrackerException;

// Instantiate the tracker
$tracker = new GLSTracker('username', 'password');

您可以可选地传递一个语言代码作为第三个参数，以获取以其他语言返回的结果（默认为 en）

$tracker = new GLSTracker('username', 'password', 'fr');

现在您可以跟踪单个包裹

try {
    $parcel = $tracker->trackOne('00AB1234');

    if ($parcel !== null) {
        echo $parcel->trackid, ' ', $parcel->status, PHP_EOL;
    
        foreach ($parcel->events as $event) {
            echo "\t", $event->timestamp, ' ', $event->description, PHP_EOL;
        }
    } else {
        echo 'Parcel not found!', PHP_EOL;
    }
} catch (GLSTrackerException $e) {
    // an error occurred
    echo $e;
}

或一次性跟踪多个包裹

try {
    $parcels = $tracker->trackMany('00AB1234', '00XY6789');

    foreach ($parcels as $parcel) {
        echo $parcel->trackid, ' ', $parcel->status, PHP_EOL;

        foreach ($parcel->events as $event) {
            echo "\t", $event->timestamp, ' ', $event->description, PHP_EOL;
        }
    }
} catch (GLSTrackerException $e) {
    // an error occurred
    echo $e;
}

请注意，API在单个调用中返回的搜索结果数量有限。如果您一次性请求过多的TrackID，可能会得到一个 TooManySearchResultsException。

错误处理

如果查询API时发生错误，总是抛出 GLSTrackerException。

异常层次结构

• GLSTrackerException
  所有异常的基类。
  • Exception\APIException
    从API收到一个已知的错误响应。
    • Exception\APIException\InputValidationException
      已给出一个无效的TrackID。
    • Exception\APIException\MissingRightsException
      用户可以访问API但没有必要的权限。
    • Exception\APIException\NotAuthorizedException
      用户名或密码不正确。
    • Exception\APIException\TooManySearchResultsException
      将返回过多的搜索结果；您应请求较少的TrackID。
    • Exception\APIException\UserAccountBlockedException
      用户账户已被阻止。
  • Exception\InvalidResponseException
    从API收到一个无效的响应，并且此库无法解码它。
  • Exception\NetworkException
    发生了网络错误，并且未从API收到任何响应。

这些细粒度的异常允许您针对每种类型的失败自动执行操作。例如，当收到 NetworkException 时，您可以在几分钟后安排重试。