README

一个PHP库，用于简化对Fulfillment邮费API的使用

特性

• 简单的凭证配置
• 自动认证处理
• 代表API请求和响应的完整PHP类
• API数据的灵活实现选项
• 映射到邮费API的全面方法（进行中）
• 具有描述性、有帮助信息的模型验证
• 描述性的调试输出
• 由FDC员工编写和使用

示例

use Fulfillment\Postage\Postage;
use Fulfillment\Postage\Models\Request;

$postageWrapper = new PostageClient(__DIR__); //instantiate Postage with a configuration file or array of settings

$postageObj = new Postage($data); //use plain PHP classes to model a the JSON request that should be sent to the API
$postageObj->setShipper = 'YOUR_SHIPPER';

$postageResponse = $postageWrapper->postage->createPostage($postageObj); //make a request, get a response back as a model

安装

composer require fulfillment/postage-api

配置

所需的配置简单

• USERNAME - 账户的电子邮件地址
• PASSWORD - 账户密码
• CLIENT_ID - 商家的客户端ID
• CLIENT_SECRET - 商家的客户端密钥
• ACCESS_TOKEN - 如果已经创建，则为商家创建的访问令牌
• API_ENDPOINT - 您使用的邮费API服务的端点（https://postage.fulfillment.com）

可选配置

• JSON_ONLY - 默认为false。如果设置为true，则所有响应都将返回为纯JSON，就像从服务器返回的那样。
• VALIDATE_REQUESTS -- 默认为true。如果传入的数据实现了 Validatable 并未覆盖单独方法请求验证，则将对请求进行验证。

有两种方式来配置OMS API

使用dotenv

使用与fantastic phpdotenv库兼容的 .env 文件。只需将包含您的 .env 文件的文件夹的绝对路径作为参数传递给OMS构造函数即可。

$postageWrapper = new PostageClient('absolute/path/to/a/folder')

在根目录中可以找到一个名为 .env.example 的示例文件。

使用数组

或者，创建一个具有与上述指定配置匹配的键/值数组的数组，并将其作为参数传递给PostageClient构造函数。

$config = [
    'username' => '',
    'password' => '',
    'clientId' => '',
    'clientSecret' => '',
    'accessToken' => '',
    'endpoint' => '',
    'jsonOnly' => false,
    'validateRequests' => true
];

$postageWrapper = new PostageClient($config)

用法

将数据传递给请求方法

此包为使用封装器请求方法提供几种数据结构选项

数组

所有封装器方法都接受一个普通的PHP数组。如果您的数据已经结构化为生成请求有效JSON主体的有效JSON主体，则可以将其传递给方法。

契约

位于 Request 模型的契约可在

Fulfillment\Postage\Models\Request\Contracts

所有封装器方法都将接受相应的模型契约作为参数。

抽象模型

这些是 abstract class 模型，实现了上述提到的契约。如果您想使用实现的契约，但又不想使用具体模型中使用的验证供应商或构造函数（您想自己扩展），这就是您想要的。

位于

Fulfillment\Postage\Models\Request\Base

具体模型

这些是具有内置验证的 即用型类。位于

Fulfillment\Postage\Models\Request\

模型类型

有两种类型的模型

请求模型

位于 Fulfillment\Postage\Models\Request 的请求模型用于制作任何需要数据的请求（如POST或PUT请求）。与其他类型（Response 模型）略有不同，因为它们不需要返回api的数据那么多。

响应模型

在 Fulfillment\Postage\Models\Response 中找到，这些是响应json解析到的模型。它们继承自 Request 模型，因此可以重用来发送请求。目前没有选项使用自己实现的 Response 模型进行响应填充，但这是一个正在开发中的特性。

验证

默认情况下，如果传入方法的对象实现了 Validatable 接口，则在发送请求之前（在POST或PUT请求的情况下）进行验证。如果模型有任何验证失败，将抛出一个描述性错误。

有两种方式来配置它

• 设置全局验证 - 在客户端实例化时设置验证，请参阅上面的配置部分了解参数名称
• 按方法 - 所有POST/PUT请求都有一个可选的 $requestValidation 参数，它将覆盖全局设置。

路线图

还有很多工作要做，请查看问题部分了解正在开发的内容或提出请求。