README

EasyPost，简单的物流解决方案。您可以在 https://easypost.com 注册账户。

安装

注意： 此库依赖于 mbstring 扩展。在开始使用此库之前，请确保已正确安装。

# Install via Composer
composer require easypost/easypost-php

# Require the autoloader (when using composer - recommended):
require_once("/path/to/vendor/easypost/autoload.php");

# Alternatively, manually download and require the library,
# will require manually downloading and requiring other dependencies:
require_once("/path/to/lib/easypost.php");

使用

一个简单的创建和购买运货示例

require_once("/path/to/vendor/easypost/autoload.php");

$client = new \EasyPost\EasyPostClient(getenv('EASYPOST_API_KEY'));

$shipment = $client->shipment->create([
    "from_address" => [
        "company" => "EasyPost",
        "street1" => "118 2nd Street",
        "street2" => "4th Floor",
        "city"    => "San Francisco",
        "state"   => "CA",
        "zip"     => "94105",
        "phone"   => "415-456-7890",
    ],
    "to_address" => [
        "name"    => "Dr. Steve Brule",
        "street1" => "179 N Harbor Dr",
        "city"    => "Redondo Beach",
        "state"   => "CA",
        "zip"     => "90277",
        "phone"   => "310-808-5243",
    ],
    "parcel" => [
        "length" => 20.2,
        "width"  => 10.9,
        "height" => 5,
        "weight" => 65.9,
    ],
]);

$boughtShipment = $client->shipment->buy($shipment->id, $shipment->lowestRate());

echo $boughtShipment;

HTTP 钩子

用户可以通过 RequestHook 和 ResponseHook 对象订阅 HTTP 请求和响应。为此，将一个函数传递给 EasyPostClient 对象的 subscribeToRequestHook 或 subscribeToResponseHook 方法。

function customFunction($args)
{
    // Pass your code here, data about the request/response is contained within `$args`.
    echo "Received a request with the status code of: " . $args['http_status'];
}

$client = new \EasyPost\EasyPostClient(getenv('EASYPOST_API_KEY'));

$client->subscribeToResponseHook('customFunction');

// Make your API calls here, your customFunction will trigger once a response is received

您还可以通过使用客户端对象的 unsubscribeFromRequestHook 和 unsubscribeFromResponseHook 方法以类似的方式取消订阅您的函数。

文档

API 文档可在： https://docs.easypost.com 找到。

库文档可在以下网址找到： https://easypost.github.io/easypost-php/，或者通过执行 make docs 命令在本地构建。

升级主要版本？请参阅 升级指南。

支持

新功能和错误修复都发布在库的最新主要版本上。如果您使用的是库的较旧主要版本，我们建议您升级到最新版本，以便利用新功能、错误修复和安全补丁。只要它们所关联的 API 版本保持活动状态，较旧版本的库将继续工作并可用；然而，它们将不会收到更新，并被视为已到生命周期的结束。

如需更多支持，请参阅我们的 组织级支持策略。

开发

# Install dependencies
make install

# Update dependencies
make update

# Lint project
make lint
make lint-fix

# Run tests
EASYPOST_TEST_API_KEY=123... EASYPOST_PROD_API_KEY=123... make test

# Generate coverage reports (requires Xdebug for HTML report)
# NOTE: When using PHP 8.2, you must use 8.2.9+ to avoid segfaults when generating coverage
EASYPOST_TEST_API_KEY=123... EASYPOST_PROD_API_KEY=123... make coverage

# Run security analysis
make scan

# Generate library documentation (requires phpDocumentor.phar in the root of the project)
make docs

# Update submodules
make update-examples-submodule

测试

此项目中的测试套件是专门构建的，以在每次运行时产生一致的结果，无论它们何时运行或由谁运行。此项目使用 VCR 通过 "磁带" 记录和回放 HTTP 请求和响应。当套件运行时，如果不存在，每个测试函数的 HTTP 请求和响应将被保存到磁带中，如果已存在，则从该保存的文件中回放，这省去了每次测试运行时都需要进行实时 API 调用的麻烦。

敏感数据： 我们已尽力在记录磁带时包含清除器，以确保 PII 或敏感信息不会在版本控制中持续存在；然而，请在记录或重新记录磁带之前，检查磁带，以确保在提交更改之前没有 PII 或敏感信息被持久化。

进行更改： 如果您向此项目添加了内容，当在测试函数的开始处添加 TestUtil::setupCassette('object/action.yml'); 时，请求/响应将自动为您记录。当您对此项目进行更改时，您需要重新记录相关的磁带，以强制进行新的实时 API 调用，该调用将在下一次运行时记录请求/响应。

测试数据：测试套件已填充了各种有助于使用的固定装置，每个装置都与特定用户完全独立，除了 USPS 运输商账户 ID（有关更多信息，请参阅 单元测试 API 密钥），它具有我们的内部测试用户的 ID 作为后备值。某些固定装置使用硬编码的日期，如果磁带被重新录制（例如报告或取件），可能需要递增。

单元测试 API 密钥

以下内容在每个测试运行中都是必需的

• EASYPOST_TEST_API_KEY
• EASYPOST_PROD_API_KEY

某些测试可能需要一个具有特定启用功能的 EasyPost 用户，例如在创建推荐时使用 合作伙伴 用户。我们已尝试在其各自的文档字符串中指出这些功能。以下内容是在您需要为适用测试重新录制磁带时必需的

• USPS_CARRIER_ACCOUNT_ID（例如：为非 EasyPost 员工购买货物的单次通话购买）
• PARTNER_USER_PROD_API_KEY（例如：创建推荐用户）
• REFERRAL_CUSTOMER_PROD_API_KEY（例如：向推荐用户添加信用卡）

模拟

我们的一些单元测试需要 HTTP 调用，这些调用无法通过实时/录制调用轻松测试（例如触发支付或与外部 API 交互的 HTTP 调用）。

我们在该库中实现了一个自定义的轻量级 HTTP 模拟功能，允许我们模拟 HTTP 调用和响应。

模拟客户端与正常客户端相同，具有一组存储为属性的模拟请求-响应对。

在发出真实 HTTP 请求时，模拟客户端将检查哪个模拟请求条目与排队请求匹配（通过 HTTP 方法和一个用于 URL 的正则表达式模式进行匹配），并将返回相应的模拟响应（HTTP 状态码和正文）。

注意：如果客户端配置了模拟实用程序，它将仅执行模拟请求。如果它尝试执行与配置的任何模拟请求都不匹配的请求，则请求将失败并触发异常。

要使用模拟实用程序

use EasyPost\Test\mocking\MockingUtility;
use EasyPost\Test\mocking\MockRequest;
use EasyPost\Test\mocking\MockRequestMatchRule;
use EasyPost\Test\mocking\MockRequestResponseInfo;

// create a mocking utility with a list of mock request-response pairs
$mockingUtility = new MockingUtility(
    new MockRequest(
        new MockRequestMatchRule(
            // HTTP method and regex pattern for the URL must both pass for the request to match
            'post',
            '/v2\\/bank_accounts\\/\\S*\\/charges$/'
        ),
        new MockRequestResponseInfo(
            // HTTP status code and body to return when this request is matched
            200,
            '{}'
        )
    ),
    ... // more mock requests
);

// create a new client with the mocking utility
$client = new EasyPostClient("some_key", Constants::TIMEOUT, Constants::API_BASE, $mockUtility);

// use the client as normal