README

这是 Seats.io V2 REST API 的官方 PHP 客户端库。

安装 seatsio-php

推荐通过 Composer 安装 seatsio-php。

composer require seatsio/seatsio-php

最低要求的 PHP 版本是 8.1。

版本控制

自 v62.3.0 版本起，seatsio-php 遵循 semver。

使用方法

一般说明

要使用此库，您需要创建一个 SeatsioClient

require 'vendor/autoload.php';

use Seatsio\Region;
use Seatsio\SeatsioClient;

$seatsio = new SeatsioClient(Region::EU(), <WORKSPACE SECRET KEY>);
...

您可以在 工作空间的设置部分 找到您的 工作区密钥。

区域应与您的账户区域相对应

• Region::EU(): 欧洲
• Region::NA(): 北美洲
• Region::SA(): 南美洲
• Region::OC(): 大洋洲

如果您不确定您的区域，请查看您的 公司设置页面。

创建图表和事件

require 'vendor/autoload.php';

use Seatsio\Region;
use Seatsio\SeatsioClient;

$seatsio = new SeatsioClient(Region::EU(), <WORKSPACE SECRET KEY>);
$chart = $seatsio->charts->create();
$event = $seatsio->events->create($chart->key);
echo 'Created event with key ' . $event->key;

预订对象

将对象状态更改为 '已预订'。已预订的座位在渲染的图表中不可选。

https://docs.seats.io/docs/api-book-objects

require 'vendor/autoload.php';

use Seatsio\Region;
use Seatsio\SeatsioClient;

$seatsio = new SeatsioClient(Region::EU(), <WORKSPACE SECRET KEY>);
$seatsio->events->book(<AN EVENT KEY>, ["A-1", "A-2"]);

已保留的预订对象

require 'vendor/autoload.php';

use Seatsio\Region;
use Seatsio\SeatsioClient;

$seatsio = new SeatsioClient(Region::EU(), <WORKSPACE SECRET KEY>);
$seatsio->events->book(<AN EVENT KEY>, ["A-1", "A-2"], <A HOLD TOKEN>);

预订通用入场区域

或者

require 'vendor/autoload.php';

use Seatsio\Region;
use Seatsio\SeatsioClient;

$seatsio = new SeatsioClient(Region::EU(), <WORKSPACE SECRET KEY>);
$seatsio->events->book(<AN EVENT KEY>, ["GA1", "GA1", "GA1"]);

或者

require 'vendor/autoload.php';

use Seatsio\Region;
use Seatsio\SeatsioClient;

$seatsio = new SeatsioClient(Region::EU(), <WORKSPACE SECRET KEY>);
$seatsio->events->book(<AN EVENT KEY>, [["objectId" => "GA1", "quantity" => 3]]);

释放对象

将对象状态更改为 '空闲'。空闲座位在渲染的图表中可选。

https://docs.seats.io/docs/api-release-objects

require 'vendor/autoload.php';

use Seatsio\Region;
use Seatsio\SeatsioClient;

$seatsio = new SeatsioClient(Region::EU(), <WORKSPACE SECRET KEY>);
$seatsio->events->release(<AN EVENT KEY>, ["A-1", "A-2"]);

更改对象状态

将对象状态更改为您选择的自定义状态。如果您需要的状态不止已预订和空闲，您可以使用此方法将座位、桌子或展位的状态更改为您自己的自定义状态。

https://docs.seats.io/docs/api-custom-object-status

require 'vendor/autoload.php';

use Seatsio\Region;
use Seatsio\SeatsioClient;

$seatsio = new SeatsioClient(Region::EU(), <WORKSPACE SECRET KEY>);
$seatsio->events->changeObjectStatus(<AN EVENT KEY>, ["A-1", "A-2"], "unavailable");

检索对象类别和状态（以及其他信息）

require 'vendor/autoload.php';

use Seatsio\Region;
use Seatsio\SeatsioClient;

$seatsio = new SeatsioClient(Region::EU(), <WORKSPACE SECRET KEY>);
$objectInfos = $seatsio->events->retrieveObjectInfos($event->key, ["A-1", "A-2"]);

print_r($objectInfos["A-1"]->categoryKey)
print_r($objectInfos["A-1"]->categoryLabel)
print_r($objectInfos["A-1"]->status)

print_r($objectInfos["A-2"]->categoryKey)
print_r($objectInfos["A-2"]->categoryLabel)
print_r($objectInfos["A-2"]->status)

活动报告

想知道活动的哪些座位已预订，哪些座位空闲？这正是报告发挥作用的地方。

您可以选择的报告类型有

• byStatus
• byCategoryLabel
• byCategoryKey
• byLabel
• byOrderId

https://docs.seats.io/docs/api-event-reports

require 'vendor/autoload.php';

use Seatsio\Region;
use Seatsio\SeatsioClient;

$seatsio = new SeatsioClient(Region::EU(), <WORKSPACE SECRET KEY>);
$seatsio->eventReports->byStatus(<AN EVENT KEY>, <OPTIONAL FILTER>);

列出所有图表

require 'vendor/autoload.php';

use Seatsio\Region;
use Seatsio\SeatsioClient;

$seatsio = new SeatsioClient(Region::EU(), <WORKSPACE SECRET KEY>);

$charts = $seatsio->charts->listAll();
foreach($charts as $chart) {
    echo 'Chart ' . $chart->key;
}

注意： listAll() 返回一个迭代器，在底层调用 seats.io API 分页获取图表。因此，可能需要进行多个 API 调用来获取所有图表。

按页列出图表

例如，要在仪表板上以分页列表显示图表。

每一页包含一个包含图表的 items 数组，以及 nextPageStartsAfter 和 previousPageEndsBefore 属性。这些属性是下一页开始的图表 ID 或上一页结束的图表 ID。

// ... user initially opens the screen ...

$firstPage = $seatsio->charts->listFirstPage();
foreach($firstPage->items as $chart) {
    echo 'Chart ' . $chart->key;
}

// ... user clicks on 'next page' button ...

$nextPage = $seatsio->charts->listPageAfter($firstPage->nextPageStartsAfter);
foreach($nextPage->items as $chart) {
    echo 'Chart ' . $chart->key;
}

// ... user clicks on 'previous page' button ...

$previousPage = $seatsio->charts->listPageBefore($nextPage->previousPageEndsBefore);
foreach($page->items as $chart) {
    echo 'Chart ' . $chart->key;
}

创建工作区

require 'vendor/autoload.php';

use Seatsio\Region;
use Seatsio\SeatsioClient;

// company admin key can be found on https://app.seats.io/company-settings
$seatsio = new SeatsioClient(Region::EU(), <COMPANY ADMIN KEY>);
$seatsio->workspaces->create("a workspace");

使用公司管理员密钥创建图表和事件

require 'vendor/autoload.php';

use Seatsio\Region;
use Seatsio\SeatsioClient;

// company admin key can be found on https://app.seats.io/company-settings
// workspace public key can be found on https://app.seats.io/workspace-settings
$seatsio = new SeatsioClient(Region::EU(), <COMPANY ADMIN KEY>, <WORKSPACE PUBLIC KEY>);
$chart = $seatsio->charts->create();
$event = $seatsio->events->create($chart->key);
echo 'Created event with key ' . $event->key;

错误处理

当 API 调用导致 4xx 或 5xx 错误（例如，当找不到图表时），会抛出 SeatsioException。

此异常包含描述发生错误的字符串消息，以及另外两个属性

• messages：服务器返回的错误消息数组。在大多数情况下，此数组将只包含一个元素。
• requestId：您发出的请求的标识符。当您有疑问时，请提及此标识符，因为它将使调试更容易。

速率限制 - 指数退避

此库支持 指数退避。

当发送过多的并发请求时，服务器会返回错误 429 - Too Many Requests。客户端会等待一段时间后重试请求。如果请求仍然因错误 429 失败，它会等待更长一段时间，然后再次尝试。默认情况下，这将尝试 5 次，然后放弃（大约 15 秒后）。

当指数退避最终失败时，我们抛出 RateLimitExceededException（它是 SeatsioException 的子类）。

要更改最大重试次数，请按以下方式创建 SeatsioClient

require 'vendor/autoload.php';

use Seatsio\Region;
use Seatsio\SeatsioClient;

$seatsio = new SeatsioClient(Region::EU(), <WORKSPACE SECRET KEY>, null, 3);

传递 0 完全禁用指数退避。在这种情况下，客户端将永远不会重试失败的请求。

升级

v89 -> v90

• $client->usageReports->summaryForAllMonths() 现在返回一个 UsageSummaryForAllMonths 对象

v88 -> v89

• 如果您正在使用 $seatsioClient->subaccounts，应切换到 $seatsioClient->workspaces

v87 -> v88

• 社交距离功能已被移除。那些 API 调用没有替代方案。

v86 -> v87

• $seatsioClient->events->create() 现在接受一个 CreateEventParams 对象
• $seatsioClient->events->update() 现在接受一个 UpdateEventParams 对象

v85 -> v86

• $seatsioClient->events->channels->replace() 现在接受一个普通数组而不是关联数组。如果您只想替换通道元数据但保留对象（就像 replace() 之前所做的那样），您必须显式传递这些对象。
• 删除了 $seatsioClient->events->channels->setObjects()，以支持 $seatsioClient->events->channels->replace()

v84 -> v85

• 使用报告格式已更改

v83 -> v84

• 使用报告返回的字段已更改

v82 -> v83

• $seatsioClient->events->markAsForSale() 和 $seatsioClient->events->markAsNotForSale() 的签名已更改。添加了新参数 $areaPlaces，位于 $objects 和 $categories 之间。
• 添加了 $seatsioClient->charts->listCategories(string $chartKey) 以检索指定图表的 Category 实例数组。

v81 -> v82

• 从按月使用报告中删除了字段：$numFirstBookingsOrSelections、$numGASelectionsWithoutBooking、$numNonGASelectionsWithoutBooking。使用 $numUsedObjects 替代 $numFirstBookingsOrSelections。

v80 -> v81

• 当前支持的最低 PHP 版本是 PHP 7.4

v79 -> v80

• $seatsioClient->seasons->createEvents() 现在返回事件对象的数组，而不是季对象

v76 -> v77

• 将 $seatsioClient->events->retrieveObjectStatus() 重命名为 $seatsioClient->events->retrieveObjectInfo()
• 将 \Seatsio\Reports\Events\EventReportItem 重命名为 \Seatsio\Events\EventObjectInfo
• 将 \Seatsio\Events\ObjectStatus 重命名为 \Seatsio\Events\EventObjectInfo
• 将 \Seatsio\Reports\Charts\ChartReportItem 重命名为 \Seatsio\Charts\ChartObjectInfo
• 将 ObjectStatus->quantity 重命名为 EventObjectInfo->numBooked

v72 -> v73

SeatsioClient 现在将区域作为第一个参数。这是您的账户区域。

v69 -> v70

将创建社交距离规则集的方式改为构建器模式。删除了 SocialDistancingRuleset 类的构造函数。

基于规则的规则集

$ruleset = SocialDistancingRuleset::ruleBased("My first ruleset")
    ->setIndex(0)
    ->setNumberOfDisabledSeatsToTheSides(1)
    ->setDisableSeatsInFrontAndBehind(true)
    ->setDisableDiagonalSeatsInFrontAndBehind(true)
    ->setNumberOfDisabledAisleSeats(2)
    ->setMaxGroupSize(1)
    ->setMaxOccupancyAbsolute(10)
    ->setOneGroupPerTable(true)
    ->setDisabledSeats(["A-1"])
    ->setEnabledSeats(["A-2"])
    ->build();

固定规则集

$ruleset = SocialDistancingRuleset::fixed("My second ruleset")
    ->setIndex(1)
    ->setDisabledSeats(["A-1"])
    ->build();

v68 -> v69

将 SeatsioException->$messages 替换为 SeatsioException->$errors。一个错误包含一个 $code 和一个 $message。

要基于异常类型实现逻辑，请使用技术 $code 而不是可读的 $message。

v67 -> v68

检索活动

Event 类不再有 $bookWholeTables 和 $tableBookingModes 属性。这些已被单个 $tableBookingConfig 属性所取代。

• $bookWholeTables 等于 true 对应一个 $tableBookingConfig，其中 $mode 等于 ALL_BY_TABLE
• $bookWholeTables 等于 false 对应一个 $tableBookingConfig，其中 $mode 可以是 ALL_BY_SEAT、INHERIT 或 CUSTOM
• 现在在 $tableBookingModes 中的餐桌列表是 $tableBookingConfig->tables（但仅当 $mode 等于 CUSTOM 时）

创建事件

在创建事件时，现在传递一个（可选的）$tableBookingConfig，而不是传递 $bookWholeTablesOrTableBookingModes

$seatsioClient->events->create(
  "4250fffc-e41f-c7cb-986a-2c5e728b8c28", null,
  TableBookingConfig::custom(["T1" => "BY_TABLE", "T2" => "BY_SEAT"])
);

创建多个事件

在创建多个事件时，现在传递一个（可选的）$tableBookingConfig，而不是传递 $bookWholeTables 和 $tableBookingModes

$params = [
    CreateEventParams::create()
    ->setEventKey("event34")
    ->setTableBookingConfig(TableBookingConfig::allByTable(),
    CreateEventParams::create()
    ->setEventKey("event35")
    ->setTableBookingConfig(TableBookingConfig::allBySeat()
];

$events = $seatsioClient->events->createMultiple("4250fffc-e41f-c7cb-986a-2c5e728b8c28", $params);

v66 -> v67

无需迁移

v65 -> v66

现在需要使用 PHP 7.1 或更高版本才能使用此库。

v64 -> v65

在 SocialDistancingRuleset 的构造函数中添加了布尔参数 $oneGroupPerTable。传递 false 以不强制只让一个组坐在餐桌旁。

也将此参数添加到 SocialDistancingRuleset::ruleBased()

v63 -> v64

在 SocialDistancingRuleset 的构造函数中添加了 $maxOccupancyAbsolute、$maxOccupancyPercentage 和 $fixedGroupLayout。

为了保持默认行为，请传递以下内容

• $maxOccupancyAbsolute = 0
• $maxOccupancyPercentage = 0
• $fixedGroupLayout = false

v62 -> v63

events->bookBestAvailable()、events->holdBestAvailable() 和 events->changeBestAvailableObjectStatus() 接受可选的 $extraData 和 $ticketTypes 参数。传递 null 以保持默认行为。