always-open/shipengine

ShipEngine API 包装器


README

Latest Version on Packagist GitHub Tests Action Status GitHub Code Style Action Status Total Downloads

ShipEngine API 包装器

安装

您可以通过 composer 安装此包

composer require always-open/shipengine

您可以使用以下命令发布配置文件

php artisan vendor:publish --tag="shipengine-config"

这是已发布配置文件的内容

return [
    /*
    |--------------------------------------------------------------------------
    | ShipEngine configurations
    |--------------------------------------------------------------------------
    |
    | API Key used to authenticate with ShipEngine APIs.
    | https://www.shipengine.com/docs/auth/
    |
    */
    'credentials' => [
        'key' => env('SHIP_ENGINE_API_KEY'),
    ],

    /*
    |--------------------------------------------------------------------------
    | ShipEngine configurations
    |--------------------------------------------------------------------------
    |
    | Values used to set configuration of ShipEngine API integration.
    |
    */
    'endpoint' => [
        'version'  => env('SHIP_ENGINE_API_VERSION', 'v1'),
        'base'     => env('SHIP_ENGINE_ENDPOINT', 'https://api.shipengine.com/'),
    ],
    'retries'  => env('SHIP_ENGINE_RETRIES', 1),
    'response' => [
        'as_object' => env('SHIP_ENGINE_RESPONSE_AS_OBJECT', false),
        'page_size' => env('SHIP_ENGINE_RESPONSE_PAGE_SIZE', 50),
    ],
    'timeout' => 'PT10S',
];

用法

配置

要使用 ShipEngine 包装器,您必须首先实例化一个新实例。

默认情况下,配置信息是从配置文件中读取的,但可以在运行时覆盖。这可以在实例化新实例时完成,这将影响所有后续调用,或者可以在调用时完成。

// Use default config settings from `config/shipengine.php`
$shipengine = new AlwaysOpen\ShipEngine\ShipEngine();
// Override config which will impact all calls made with this instance
$config = new \AlwaysOpen\ShipEngine\ShipEngineConfig(['asObject' => true]);
$custom_shipengine = new AlwaysOpen\ShipEngine\ShipEngine($config);
// Override config on a single specific call
$shipengine->listShipments(config: ['asObject' => true]);

调用

要调用 ShipEngine API,您必须在 ShipEngine 中设置凭据。这些 API 凭据将由该库用于处理调用和响应。

注意: 此库仍处于 0.x.x 阶段,并非所有端点都已完全映射。我们正在努力实现现有 API 端点的 100% 覆盖率。

方法名称应与官方 ShipEngine API 文档 中的 API 端点文档名称匹配。

示例调用

以下是如何获取运输清单以及 asObject => falseasObject => true 之间的区别的示例。

$shipengine = new AlwaysOpen\ShipEngine\ShipEngine();
$shipengine->listShipments();
//[
//    "shipments" => [
//        [
//            "shipment_id" => "se-123456789",
//            "carrier_id" => "se-123456",
//            ...
//        ],
//        [...],
//    ],
//    "total" => 12,
//    "page" => 1,
//    "pages" => 1,
//    "links" => [
//        "first" => [
//             "href" => "https://api.shipengine.com/v1/shipments?page=1&page_size=25",
//        ],
//        "last" => [
//             "href" => "https://api.shipengine.com/v1/shipments?page=1&page_size=25",
//        ],
//        "prev" => [],
//        "next" => [],
//     ],
//];
$shipengine->listShipments(config: ['asObject' => true]);
// [
//     "shipments" => [
//       AlwaysOpen\ShipEngine\DTO\Shipment {#4070
//           +shipment_id: "se-123456789",
//           +carrier_id: "se-123456",
//            ...
//        ],
//        [...],
//    ],
//    "total" => 12,
//    "page" => 1,
//    "pages" => 1,
//    "links" => [
//        "first" => [
//             "href" => "https://api.shipengine.com/v1/shipments?page=1&page_size=25",
//        ],
//        "last" => [
//             "href" => "https://api.shipengine.com/v1/shipments?page=1&page_size=25",
//        ],
//        "prev" => [],
//        "next" => [],
//     ],
//];

测试

composer test

变更日志

有关最近更改的更多信息,请参阅 变更日志

贡献

有关详细信息,请参阅 贡献指南

安全漏洞

有关如何报告安全漏洞的详细信息,请参阅 我们的安全策略

鸣谢

许可证

MIT 许可证 (MIT)。有关更多信息,请参阅 许可证文件