README

ShipEngine PHP

基于 ShipEngine API 的 PHP 库，提供低级别访问以及便捷方法。

目录

• 快速入门
• 示例
  • 方法
  • 类对象
  • 实例化 ShipEngine 类
• 测试
• 代码风格检查
• 贡献

快速入门

使用 Composer 安装 ShipEngine

composer require shipengine/shipengine

• 唯一的配置要求是 API 密钥。

以下示例假设您已使用 putenv() 函数设置了包含您的 Api 密钥的 SHIPENGIEN_API_KEY 环境变量。

示例

方法

• validateAddress - 判断提供的地址是否有效。如果地址有效，则方法返回基于地址所在国家标准的地址规范化版本。
• normalizeAddress - 返回地址的规范化或标准化版本。如果地址无法规范化，则返回错误。
• trackPackage - 通过 packageId 或通过 carrierCode 和 trackingNumber 跟踪包裹。该方法返回给定运货的所有跟踪事件。

类对象

• ShipEngine - 可配置的 ShipEngine API SDK 入口点，此类为各种 ShipEngine API 服务提供便捷方法。

实例化 ShipEngine 类

<?php declare(strict_types=1);

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

use ShipEngine\ShipEngine;

$apiKey = getenv('SHIPENGINE_API_KEY');

$shipengine = new ShipEngine($apiKey);

• 您还可以将包含 configuration 选项的 array 传递给 ShipEngine 对象，而不是传递 string。

<?php declare(strict_types=1);

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

use ShipEngine\ShipEngine;

$apiKey = getenv('SHIPENGINE_API_KEY');

$config = array(
    'apiKey' => $apiKey,
    'pageSize' => 75,
    'retries' => 3,
    'timeout' => \DateInterval('PT60S')
);

$shipengine = new ShipEngine($config);

测试

• 现在您可以使用 PHPUnit 运行所有测试：phpunit

composer test

代码风格检查

您可以使用运行 phpcs、phpstan 和 php-cs-fixer 的 composer 脚本。

composer lint

贡献

欢迎贡献、增强和修复错误！在 GitHub 上 提交问题 并 提交拉取请求。

我们使用 Nix 和 Direnv 管理 php environment，并建议在贡献此项目之前下载它们。

• 安装 Nix 的最快方法是打开终端并运行以下命令，确保遵循安装脚本输出的说明

  curl -L https://nixos.org/nix/install | sh

• 接下来，使用他们安装页面上的方法之一安装 Direnv： Direnv Installation

• 最后，打开您的终端，在此存储库中，作为当前工作目录运行 direnv allow，这将允许 direnv 在每次您导航到存储库时自动加载。这将自动加载 Nix 环境，该环境运行着支持/要求的正确版本的 PHP 和 Xdebug (PHP 7.4)。

  direnv allow

  • 在首次安装 direnv 并在项目目录中运行 direnv allow 之后，您需要从项目目录中 cd 出来，然后 cd 回项目目录，以便 direnv 能够正确地自动加载 Nix 环境。

本项目还利用了 pre-commit hooks 来帮助在提交时运行代码检查和测试，为了利用这个功能，您需要安装 pre-commit 并在此仓库中运行以下命令：

pre-commit install