README

这是一个简单的 PHP 封装，围绕 Tripleseat 的 API。

需要至少 PHP 8.2

直到 v1 版本，每个小版本（0.x）可能会有不向后兼容的更改。

入门指南

首先，创建一个新的 Tripleseat 客户端实例，并提供用于身份验证的 API 密钥。

$ composer require bonroyage/tripleseat

use Tripleseat\Tripleseat;

$tripleseat = new Tripleseat([
    'api_key' => '',
    'secret_key' => '',
    'public_key' => ''
]);

API 密钥

您需要获得您的 Tripleseat 账户的 API 密钥。这些密钥可以通过登录您的 Tripleseat 账户并转到设置 -> Tripleseat API 来找到。

有两个公钥和私钥，用于大多数 API 调用。这些值分别配置为 api_key 和 secret_key。

第二个公钥单独显示，用于一些潜在客户操作。这配置为 public_key。

服务

以下服务受到支持

网站

网站表示一组场馆。网站可以有多个位置。

您可能只需要检索或修改单个网站的数据，这也是 Tripleseat 所强制执行的。例如，您不能创建属于不同网站账户的联系人。

如果网站不在您的 API 密钥可以访问的网站列表中，将会抛出 InvalidSite 异常。

// Create a new client for Site with ID 1
$mySite = $tripleseat[1];

// Search accounts in this site
$mySite->account->search([
    'query' => 'tripleseat'
]);

// is the same as
$tripleseat->account->search([
    'query' => 'tripleseat', 
    'site_id' => 1
]);

它后台执行什么操作？

当您在 Tripleseat 类上调用偏移量时，它首先检查网站 ID 是否由网站端点返回，然后使用传递给 $auth 数组中作为额外属性的 site_id 创建一个新的 Tripleseat 类实例。

通过此类发出的每个请求都将 site_id 添加到每个请求的查询参数中。

$sites = $tripleseat->site->all();

$mySite = new Tripleseat([
    'api_key' => '',
    'secret_key' => '',
    'public_key' => '',
    'site_id' => 1
]);

关于不使用 site_id 的端点怎么办？

如 site、location 和 user 这样的端点不支持 site_id 参数。无论传递什么网站 ID，它们总是返回相同的结果。

all 和 search 操作

当查询其中一个 all 或 search 端点时，客户端将返回一个分页响应。这些端点是分页的，每页返回 50 个结果。

分页响应类是可迭代的（在该页加载的结果）。它还提供以下辅助功能

• currentPage(): int - 获取当前页码
• totalPages(): int - 获取总页数
• hasMore(): bool - 检查页码是否低于总页数
• next(): ?PaginatedResponse - 获取下一页（如果适用）
• results(): array - 获取此页的结果数组
• all(): array - 将所有页的结果加载到数组中
• untilPage(int $page): array - 将当前页直到指定页的结果加载到数组中

注意：site 和 location 服务不是分页的。

$bookings = $tripleseat->booking->search([
    'query' => 'Birthday',
    'order' => 'created_by'
]);

foreach($bookings as $booking) {
    // do something with $booking
}

其他操作

$user = $tripleseat->user->get(1);

$tripleseat->lead->create([
    'first_name' => 'john',
    'last_name' => 'doe',
    'email_address' => 'johndoe@example.com',
    'phone_number' => '123-123-1234',
    'company' => 'Example Inc.',
    'event_description' => 'the event desc',
    'event_date' => '11/19/2020',
    'start_time' => '3pm',
    'end_time' => '5pm',
    'guest_count' => '50',
    'additional_information' => 'some more info',
    'location_id' => '1',
]);

$leadForms = $tripleseat->lead->forms();

创建和更新有效载荷

传递实际的有效载荷，客户端将自动使用正确的键封装此内容。您也可以提供一个已封装有效载荷的数组，这不会再次被封装。

// Calling ...
$tripleseat->contact->create([
    'account_id' => '',
    'first_name' => 'John',
    'last_name' => 'Doe',
    'email_addresses' => [
        [
            'address' => 'johndoe@example.com'
        ]
    ]
]);

// will send the request as ...

[
    'contact' => [
        'account_id' => '',
        'first_name' => 'John',
        'last_name' => 'Doe',
        'email_addresses' => [
            [
                'address' => 'johndoe@example.com'
            ]
        ]
    ]
]

异常

此库抛出的所有异常都实现了 Tripleseat\Exceptions\TripleseatException 接口。

HTTP 客户端兼容性

您可以使用任何与 PSR-18 兼容的客户端来与此库一起使用。无需额外的配置。兼容的HTTP客户端和客户端适配器列表可在 php-http.org 查找。

$httpClient = // some class implementing Psr\Http\Client\ClientInterface
$tripleseat = new Tripleseat($auth, $httpClient);