README

这是一个用于与FedEx的REST API交互的PHP SDK。该SDK是从FedEx的OpenAPI模型（经过大量模型重构）自动生成的，并建立在Saloon之上。

警告

此SDK尚未在生产环境中使用，仍处于beta测试阶段。可能存在我们尚未发现的错误。如果您发现任何问题，我们非常欢迎您提交问题。

安装

composer require shipstream/fedex-rest-sdk

快速入门

FedEx类是访问FedEx API所有部分的起点。要开始，请使用您的客户端ID和密钥实例化FedEx类

use ShipStream\FedEx\FedEx;

$connector = new FedEx(
    clientId: 'asdf1234.....',
    clientSecret: 'qwertyuiop1234567890.....'
);

要访问特定的一组端点，从连接器获取相关资源集合类的实例

$api = $connector->postalCodeValidationV1();

$response = $api->validatePostal(
    new FullSchemaValidatePostal(
        carrierCode: 'FDXG',
        countryCode: 'US',
        stateOrProvinceCode: 'NY',
        postalCode: '10001',
        shipDate: '2024-05-20',
    )
);

// To get the raw response JSON:
$json = $response->json();

// To get the response data as a DTO:
$dto = $response->dto();

要确定需要传递给特定端点方法的DTO（数据传输对象），请使用您的编辑器检查方法的参数

配置选项

FedEx类的构造函数接受以下参数

• clientId：开发者控制台中的OAuth客户端ID。必需。
• clientSecret：开发者控制台中的OAuth客户端密钥。必需。
• endpoint：一个ShipStream\FedEx\Enums\Endpoint值，可以是Endpoint::PROD或Endpoint::SANDBOX。默认为Endpoint::PROD。
• childKey：如果您正在使用子凭据，则这是子用户的OAuth客户端ID。可选。
• childSecret：如果提供了子客户端ID，则相应的密钥。可选。
• proprietaryChild：指定子凭据（如果有）是否为专有父子关系。默认false。
• tokenCache：实现TokenCache接口的实现。用于缓存访问令牌，以便每次请求都不需要检索新的令牌。默认为MemoryCache实现。
• transactionIdGenerator：一个闭包，它接受一个PendingRequest并返回一个string，该字符串将用于将x-customer-transaction-id头值注入到请求中。可选。

Saloon特性

由于此SDK建立在Saloon之上，因此它继承了Saloon的许多有用特性，例如自动请求重试、简单的请求调试、中间件、请求池等。

贡献

我们欢迎任何形式的贡献！您可以以几种方式为此项目做出贡献

• 如果在设置过程中遇到错误或遇到问题，请搜索现有问题现有问题，如果您找不到任何与您遇到的问题匹配的内容，请创建新问题。
• 浏览现有问题，帮助他人！
• 如果您发现一个问题并希望自行修复，请提交一个拉取请求！

问题

在提交问题之前，请确保您已经搜索了现有问题，以查看是否有人已经报告并/或解决了您报告的相同问题。如果没有找到与您的问题匹配的内容，请提交新问题。请确保包含以下内容：

• 您正在运行的库版本（您可以在您的 composer.json 文件中找到此信息）
• 您的完整代码，已移除任何凭证
• 对问题的详细描述
• 重现问题的步骤

拉取请求

我们欢迎PR！如果您想提交PR，我们鼓励您首先提交一个描述您想要进行的更改的问题。这样，您就不会陷入在PR上投入了大量工作，却发现我们拒绝了这个PR，因为它不是一个我们想要支持的更改/功能的令人沮丧的情况。

一旦您准备好开始处理您的PR，请查看下面的SDK设计部分，以确保您的更改符合该库的整体设计。

在提交PR进行审查之前，请确保测试套件使用composer test正常工作，并且代码使用composer lint进行了检查。

测试

要启动测试，您需要一套FedEx REST API沙箱凭证。由于FedEx有一个相当完整的沙箱环境，我们使用他们的实际沙箱而不是模拟响应。

一旦您有了凭证，将phpunit.dist.xml复制到phpunit.xml，并使用您的测试凭证填写CLIENT_ID和CLIENT_SECRET环境变量。现在您应该能够运行测试套件了！

由于我们使用的是实际的沙箱API而不是模拟，请确保在所有测试中使用Endpoint::SANDBOX端点！FedEx有独立的开发和沙箱凭证，所以如果您指定了开发端点，很可能会得到一个错误。但是，如果您不小心将开发凭证放入phpunit.xml中（见下文），您将在测试期间发出真实的API请求。

SDK设计

此SDK（几乎）完全由FedEx的OpenAPI模型文件自动生成，使用highsidelabs/saloon-sdk-autogenerator。与大多数大型多文件OpenAPI规范一样，FedEx规范需要相当多的调整才能以与自动生成器很好地工作的格式。我们投入了大量工作以确保从下载模型文件到生成代码的生成过程是幂等的和可靠的。

构建此库有三个主要步骤

1. 从FedEx下载原始OpenAPI模式文件
2. 合并和编辑这些文件，使它们的格式更一致、更易用
3. 从修改后的OpenAPI模式文件生成最终代码

每个步骤的详细信息如下。每个步骤都通过其自己的CLI命令运行，该命令在bin/console中定义。CLI命令接受以下选项，两者都可以接受多个值

• --schema：应用于命令的模式的名称，如resources/apis.json中定义的连字符名称。
• --schema-version：应用命令的架构版本，通过在 resources/apis.json 中定义的版本代码来指定。

因此，要下载 v1 版本的 authorization 和 pickup-request API，您可以运行

$ php bin/console schema:download \
    --schema authorization --schema pickup-request \
    --schema-version 1

下载架构：php bin/console schema:download

这三个步骤中最简单的是这一步。 resources/apis.json 是 FedEx REST API 所有不同部分、它们的名称以及它们的 OpenAPI 架构文件 URL 的主要信息来源。一些 API 部分（例如，服务可用性 API）由多个 OpenAPI 模型文件组成。为了应对 FedEx 以后可能发布这些 API 的新版本，apis.json 文件也设计为支持同一 API 部分的多个版本。下面将更详细地描述 apis.json 文件。

下载的 OpenAPI 模型将放置在 resources/models/.raw/<api-name> 中。一旦下载了特定 API 部分的模型，就可以对它们进行重构。

重构架构：php bin/console schema:refactor

在原始架构上运行了各种重构过程，以便在下一步代码生成中使用。以下是对重构步骤的概述

• 合并原始架构：如果某个 API 部分有多个 OpenAPI 模型文件，它们将被合并成一个文件。路由、方法和组件架构将在原始 OpenAPI 文件中汇总，并合并成一个模型对象。到目前为止，我们还没有发现来自同一 API 部分的 OpenAPI 模型文件具有重叠的路由或冲突的组件架构，所以我们没有处理这些情况。
• 清理合并的架构：OpenAPI 模型中通常存在不一致性、缺少元素、重复或不必要的组件架构等问题，因此这一步将解决这些问题。以下是一些具体的当前步骤
  • 填充缺失的 404 响应架构
  • 从请求、响应和组件架构中移除不必要的 allOf 和 oneOf 定义
  • 设置缺少显式类型的架构和属性的类型
  • 展开多级 $ref，其中组件或属性是另一个 $ref 的引用。
  • 通过比较属性和需求来去重组件架构，并在可能的情况下合并组件架构
• 应用手动修改：某些架构更改需要手动进行，因为它们太具体或太繁琐，无法通过代码进行操作。这些修改在 resources/modifications.json 文件中定义，下面将更详细地解释。

一旦重构完成，最终 OpenAPI 模型文件将保存到 resources/models/<api-name>/<version>.json。这些文件是版本控制的，与原始模型不同，因为它们对所有人可用，使得推理自动生成过程变得更加容易。

生成代码：php bin/console schema:generate

最后，从最终 OpenAPI 模型生成代码。我们使用 highsidelabs/saloon-sdk-generator 进行此操作，它处理了大部分繁重的工作。 ShipStream\FedEx\Api 命名空间中的所有代码都是自动生成的，因此请不要直接编辑任何该代码！该命名空间中的任何更改都将被库下一次生成时覆盖，因此如果您想对任何该代码进行更改，必须通过以下方式之一进行更改：a) 修改/扩展生成器代码，或 b) 通过 modifications.json 文件。

config.json 文件为自动生成器提供了一些基本的配置参数，而 src/Generator/Generators 目录下的文件则覆盖了 highsidelabs/saloon-sdk-generator 的默认文件生成器，以进行一些小的修改。可以覆盖的生成器文件有多种，您可以在这里查看所有文件。如果您对如何扩展或修改生成器文件有疑问，请在 highsidelabs/saloon-sdk-generator 存储库中创建一个issue。

生成器控制文件

apis.json

该文件是所有API段、名称、版本和上游OpenAPI模型URL的真相来源。顶层对象的键（例如，authorization、address-validation等）是用于在整个代码库中引用和检索特定API段使用的名称。

每个顶层子对象是API段的定义。它包含一个可读的name和一个版本定义数组。每个版本由一个version代码（例如，1）和一个url键组成，该键是一个字符串或字符串数组，具体取决于FedEx是否通过单个OpenAPI模型文件或多个模型文件定义API段。

modifications.json

该文件包含手动定义的OpenAPI模型修改。这些修改在其他模型重构步骤之后应用。每个修改定义包含两个或三个元素：

• path，在模型文件中要修改的值的点分隔JSON路径
• action，以下是其中之一：
  • replace：将path处的值替换为value键中的值（见下文）
  • merge：将path处的值与value键中的值合并
  • delete：从模型中完全删除path处的值以及path中的最后一个键
• value，要合并/替换的值。如果action是delete，则不需要

作者

此SDK是由Jesse Evers和Highside Labs共同构建的。