README

这是一个为 Hellocash API（https://hellocash.docs.apiary.io/#）提供的非官方 PHP SDK 实现。它帮助以面向对象的方式访问 API，并使用 Saloon 作为 API 的包装器。

要求

PHP >= 8.1

安装

composer require weisl/hellocash-php-sdk

使用

通过创建一个 HellocashClient 对象开始发送请求

$client = new HellocashClient('email@example.com', 'secret-password');
$response = $client->invoices()->all();

请查看 src/Interfaces/HellocashClientInterface 以了解如何访问 API 资源。每个资源都有自己的接口，例如，带有关于方法和响应类型的更详细信息的 src/Interfaces/Resources/InvoiceResourceInterface。

错误处理

基本上，SDK 区分了两种错误

SDK 使用不当
API 使用不当

以下示例显示了两者之间的区别。请注意，例如，如果您将错误的类型作为参数传递给 SDK，它将抛出异常。更具体地说，SDK 抛出一个名为 SDKRequestFailedException 的异常。如果您可以成功通过并实际向 API 发送请求，但请求失败，例如没有您提供的 ID 的发票，您将始终收到以下格式的响应

[
  'error' => 'Invoice with ID 123 not found'
]

示例：发票

此示例将指导您使用 SDK。

all()

SDK 中的每个资源都提供了一个 all() 方法，它执行您可能期望的操作：从资源获取所有文档。这也为您处理分页（因此您不需要处理限制、偏移量等）。

$client->invoices()->all(); // gets all resources, no matter how many

这直接返回文档作为数组，如果没有文档，则返回空数组。

query()

假设您想要搜索特定的发票。一些资源支持参数，例如 limit, offset, search, ...。一个完整的 API 请求可能看起来像这样：https://api.hellocash.business/api/v1/invoices?limit=1000&offset=1&search=test&showDetails=true。由于 all() 可能需要很长时间才能获取，并且在有很多文档的情况下不可用，因此您可以使用 query() 方法充分利用所有查询参数。

$client->invoices()->query([ // query all invoices with supported parameters
  'limit' => 50,
  'offset' => 2,
  ...
]);

这返回与 API 相同的响应，因此您可以根据自己的逻辑定义逻辑。SDK 还为您做了一些额外的事情：验证传递给查询函数的属性。如果您传递了一个 API 不支持的参数，SDK 将抛出一个 SDKRequestFailedException，其中包含有关哪个参数无效的信息。它还检查值类型。当 API 指的是 number 类型时，它可以是一个整数、一个浮点数或一个双精度浮点数。其他类型应该是直接的。

get()

使用 get(int $id) 方法获取一个特定的发票。

$client->invoices()->get($id); // get specific invoice by id

由于 API 在错误消息方面并不完全一致，SDK 为您处理了这一点。如果您输入的 ID 没有找到任何发票，SDK 提供了一个统一的错误消息，如下所示

[
  'error' => 'Invoice with ID 123 not found',
]

cancel()

取消操作接受发票的 ID 作为参数。您还可以在请求体中指定收银员。在 SDK 中，您只需将一个数组传递给取消方法

$client->invoices()->cancel($id, [
  'cancellation_cashier_id' => 123,
]);

再次提醒，SDK会检查传递的参数，并为您处理类型检查。有趣的是，API在错误信息方面并不一致（也没有提供很多关于错误的信息）。SDK会以相同的格式提供所有错误。

[
  'error' => 'Cancellation of Invoice with 123 was not successful. API error message: An Error occurred',
]

create()

创建发票。

$client->invoices()->create([
  'cashier_id' => 123,
  'items' => [
      [
        'item_name' => 'test',
      ],
  ],
]);

同样，主体将进行验证和类型检查（仅限第一级数组）。

pdf()

获取PDF发票。

$client->invoices()->pdf(123);

贡献

如果您想改进某些内容，或者发现任何错误，请通过电子邮件或创建一个问题与我联系。

测试

vendor/bin/phpunit

文档

请参阅Hellocash API文档或此包的src/Interfaces目录中的接口。

许可

此软件包受MIT许可证许可。

请注意，我与Hellocash没有任何形式的关联。对此名称、品牌等所有版权均归各自所有者所有，而不是我。

weisl / hellocash-php-sdk

维护者

详细信息