README

这是一个简单的 PHP 包装器，用于封装 Tripleseat 的 API。

需要至少 PHP 8

版本 v1 之前，可能每个小版本（0.x）都会有不兼容的更改。

这个分支有何不同

• 兼容 PHP 8
• 添加了一个获取总页数的方法，以便构建分页器。

入门

首先，创建一个 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 是否由 sites 端点返回，然后创建一个新的 Tripleseat 类实例，并将 site_id 作为附加属性传递到 $auth 数组中。

通过此类进行的每个请求都将 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 个结果。客户端将检查第一个响应中的 total_pages 属性，并确保加载每一页。下一页只有在迭代器到达该点时才会加载。

调用 iterator_to_array (?) 将生成器转换为数组并立即加载所有页面。

此外，您可以在这些操作中提供 $firstPage 或 $untilPage 来更改从哪一页开始以及/或加载到哪一页的数据（如果它少于总页数）。

注意：服务 site 和 location 不分页，不提供 $firstPage 或 $untilPage 参数。

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

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

// convert from Generator to array
$bookingsArray = iterator_to_array($bookings);

count 操作

对于返回分页结果的生成器的服务，存在一个获取总页数的方法。

$pageCount = $tripleseat->lead->pageCount();

其他操作

$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);