README

StrawBlond PHP SDK 为 PHP 应用程序提供了方便访问 StrawBlond API 的途径。

要求

• PHP 8.1 及更高版本

安装

您可以通过 Composer 安装库

composer require strawblond/strawblond-php-sdk

入门指南

基本用法如下所示

// Initialize a new SDK client using your API key
$api = new StrawBlond\StrawBlond('YOUR_API_KEY');

// Retrieve an invoice
$invoice = $api->invoice()->get('jDe2KdWYK4')->json();

// Get all paid invoices and include their contact and company relations
$invoices = $api->invoice()->all(
    filters: ['status' => 'paid'],
    include: ['contact.company'],
)->json('data');

// Create a new contact
$contact = $api->contact()->create([
    'firstname' => 'Max',
    'lastname' => 'Muster',
    'email' => 'max@muster.com'
])->json();

StrawBlond API 使用个人 API 密钥对传入请求进行身份验证。您可以在 用户设置 中查看和管理您的 API 密钥。您的 API 密钥具有与您的常规用户账户相同的权限，因此请务必确保它们的安全！

重要

API 密钥在特定组织中充当您的用户。您不能使用单个密钥访问多个组织。

资源

SDK 使您能够访问 https://developers.strawblond.com/ 上记录的所有资源。

$api = new StrawBlond\StrawBlond('YOUR_API_KEY');

// CRUD resources
$api->contact();
$api->company();
$api->project();
$api->timeTracking();
$api->invoice();
$api->offer();
$api->documentElement();
$api->product();
$api->rate();
$api->unit();

// Special resources
$api->user();
$api->member();
$api->webhook();

可用方法

所有 CRUD 资源至少提供以下请求方法进行调用

有关暴露额外方法（如发票和报价上的 send()）的资源，请参阅 https://developers.strawblond.com 上的文档。

用法

首先，使用资源上可用的方法之一发送请求。在本例中，我们尝试根据发票 ID 获取单个发票。`get` 方法返回一个 `Response` 对象。

$response = $api->invoice()->get('jDe2KdWYK4');

现在我们可以检查请求是否成功，并使用获取到的数据以各种方式使用

if ($response->ok()) {
    // Get the response data as an json decoded array
    $invoice = $response->json();

    // Same as `json` but gets a single value from the data
    $dueDate = $response->json('due_at');

    // Get the response data as a Laravel Collection.
    // ! Requires `illuminate/collections` to be installed
    $lineItems = $response->collect('elements');
}

下面是创建新联系人的另一个示例

$contact = $api->contact()->create([
    'firstname' => 'Max',
    'lastname' => 'Muster',
    'email' => 'max@muster.com'
])->json();

有关 `Response` 对象的更多方法，请参阅 响应。

过滤

当在资源上调用 `all` 方法时，您可以向方法传递一个 `filters` 数组。（请参阅 https://developers.strawblond.com 上的 API 参考，了解哪些过滤器可以在给定的资源上使用）

$projects = $api->project()->all(
    filters: [
        'status' => 'active',
        'billing_type' => 'flat'
    ],
)->json('data');

排序

当在资源上调用 `all` 方法时，您可以向方法传递一个 `sort` 键。（请参阅 https://developers.strawblond.com 上的 API 参考，了解哪些排序键可以在给定的资源上使用）

$projects = $api->project()->all(
    sort: 'starts_at'
)->json('data');

默认情况下，排序是按升序进行的，可以通过在属性名开头添加连字符（-）来反转排序。

$projects = $api->project()->all(
    sort: '-starts_at'
)->json('data');

包括关系

当在资源上调用 `get` 或 `all` 方法时，您可以向方法传递一个 `include` 数组以包含相关资源。（请参阅 https://developers.strawblond.com 上的 API 参考，了解哪些资源可以在请求中包含）

$projects = $api->project()->all(
    include: ['company', 'user']
)->json('data');

您还可以使用点表示法来包含嵌套关系（https://developers.strawblond.com/guide/intro.html#nested-includes）

分页

大多数资源的 `all` 方法返回一个包含在 `data` 属性中的对象分页列表。`links` 和 `meta` 属性包含用于检索更多页面的有用信息。

您可以使用 `page` 参数设置页码。

$projects = $api->project()->all(
    page: 2,
)->json('data');

响应

发送请求后，StrawBlond SDK 资源将返回一个 Response 类。这个响应类包含许多有用的方法，用于与您的 HTTP 响应交互，例如查看 HTTP 状态码和获取正文。

$response = $api->invoice()->get('jDe2KdWYK4');

$response->status() // Returns the response status code
$response->headers() // Returns all response headers
$response->header('X-Something') // Returns a given header
$response->body() // Returns the raw response body as a string
$response->json() // Retrieves a JSON response body and json_decodes it into an array.
$response->collect() // Retrieves a JSON response body and json_decodes it into a Laravel Collection. Requires `illuminate/collections`.
$response->object() // Retrieves a JSON response body and json_decodes it into an object.

// Methods used to determine if a request was successful or not based on status code.
$response->ok();
$response->successful();
$response->redirect();
$response->failed();
$response->clientError();
$response->serverError();

// Will throw an exception if the response is considered "failed".
$response->throw();