xmlworld/api-client

简单连接到 xml.world API

维护者

详细信息

github.com/XMLWorld/api-client

主页

源代码

问题

文档

安装: 498

依赖: 0

建议者: 0

安全: 0

星标: 1

关注者: 3

分支: 0

开放问题: 0

v1.0.2 2023-07-28 15:26 UTC

Requires

Requires (Dev)

MIT dc71a4f3e30d22a390fe3bc830adabc52847805c

xmlapiclienthttps

This package is auto-updated.

Last update: 2024-09-24 16:26:16 UTC

README

简单连接到 xml.world API

安装

您可以使用 Composer 将此库作为本地、项目级别的依赖项添加到您的项目中。

composer require xml-world/api-client

描述

此库提供了一种快速集成您的预订系统与 XML.world API 的方法。

您将能够根据多个标准搜索酒店住宿，预订房间，检查预订，将预订作为交易更新，并在必要时取消预订。

API 将返回您预订的详尽摘要。

使用

您首先需要从 XML World 申请交易凭证。

一旦您拥有它们，您就可以这样开始使用 API

$xmlClient = new XMLClient(login: 'login', password: 'password');

XMLClient 暴露了 XML World API 的 5 个方法。

搜索请求

使用此请求，我们发送搜索标准以便检索满足这些标准的库存列表。

我们使用 SearchDetails 类，该类接受如 arrivalDate、duration、regionID、roomRequests properties、propertyID、mealBasisID、minStarRating、minimumPrice 和 maximumPrice 等参数。

$searchDetails = new SearchDetails(
	arrivalDate: '2023-09-01',	        // arrival date
	duration: 5,				// duration in days
	roomRequests: new RoomRequests(		// list of rooms
		RoomRequest::fromAges(2),
		RoomRequest::fromAges(
			1,		        // number of adults
			16,		        // age of first child (variadic)
			8,		        // age of second child
			2		        // age of third child
		),
	),
	properties: new Properties(19, 21),	// list of properties if searching for some
	propertyID: null,			// if only one we can use this param, but they exclude each other
	mealBasisID: 0,				// meal basis
	minStarRating: 0,			// filter by star rating
	minimumPrice: 0,			// filter by minimum price
	maximumPrice: 0				// filter by max price
);

roomRequests 和 properties 参数是请求的房间列表和属性列表。我们使用 RoomRequests 和 Properties 对象来表达这些列表。

RoomRequests 接受一个或多个 RoomRequest 对象的列表，其中我们指定成人数和非成人访客的年龄。
每个 RoomRequest 实例是我们请求的不同房间。

Properties 接受一个属性 ID 的列表。当请求多个酒店时使用。如果我们只对一家酒店感兴趣，可以将此参数设置为 null 并使用 propertyID。这两个参数是互斥的。

例如，搜索 ID 为 19 和 21 的属性中的房间，两个房间，一个供两位成人使用，另一个供一位成人和三位未成年人使用。系统会推断出 2 岁的孩子实际上是婴儿。

最后，我们提交请求

try {
	$result = $xmlClient->search(searchDetails: $searchDetails);
} catch (Throwable $e) {

}

在 $result 中，我们得到请求的结果。它是一个 SearchResponse 对象。如果 ReturnStatus 为真，它将带来一个包含与我们的搜索匹配的房间列表的 PropertyResults 对象，或者错误消息否则。

预订请求

使用从上一个请求中获得的 roomIDs，现在我们可以预订房间。

为了做到这一点，我们构建一个 BookDetails 对象。此对象接受与 SearchDetails 对象相同的某些参数，如 arribalDate 和 duration，以及进一步的参数，如 tradeReference、totalPrice、leadGuest、roomBookings。

$bookingDetails = new BookDetails(
	arrivalDate: '2023-11-01',
	duration: 5,
	tradeReference: 'TEST_REF',
	totalPrice: 1040,
	leadGuest: new LeadGuest(
		firstName: 'TestLeadFName',
		lastName: 'TestLeadLName',
		title: 'Mr'
	),
	roomBookings: new RoomBookings(
		new RoomBooking(
			roomID: 20011,
			mealBasisID: 6,
			adults: 2,
			children: 0,
			infants: 0,
			guests: new Guests(
				new Guest(
					type: 'Adult',
					firstName: 'TestGuestFName',
					lastName: 'TestGuestLName',
					title: 'Mrs',
					age: null,
					nationality: 'French'
				)
			)
		),
	)
);

这些名称说明了这些参数的用途。

重要的是要提到，totalPrice 是可选的但建议使用。它确保我们在指定的价格下预订，如果它仍然可用，否则它将按当前价格预订。
这是为了避免我们进行搜索并获取房间和价格，但稍后预订时价格已改变，它可能既低于也可能高于原始价格的情况。

leadGuest 参数接受一个 LeadGuest 对象，该对象至少必须包含 firstName、lastName 和 title，但可以包含更多详细信息。这是第一位客人，它假定他将进入预订的第一间房。

参数 roomBookings 允许一个 RoomBookings 对象，这是一个房间列表，并接受一个或多个 RoomBooking 对象。

每个 RoomBooking 对象包含 roomID 和 mealBasisID，它们是之前搜索请求中的房间和餐标代码。

然后是 adults、children 和 infants，它们分别是这个房间中每个年龄段的人数。

最后，guests 接受一个表示该房间客人的列表的 Guests 对象。

如果房间只有主客人，我们可以设置 null，如果有更多客人，我们不需要在这里包括它。

每个 Guest 对象都有 type，表示是成人、儿童还是婴儿。还有 firstName 和 lastName。年龄 age 如果是成人则为 null，如果是儿童则指定。还有国籍。

现在我们可以提交预订

try {
	$result = $xmlClient->book(bookingDetails: $bookingDetails);
} catch (Throwable $e) {

}

变量 $result 将是一个 BookResponse 对象，如果 ReturnStatus 是 true，则 bookingDetails 将是一个包含我们刚预订的房间列表、特殊优惠、补充、税费、如有取消政策以及酒店详情，以及 XML World 的预订参考的 BookingDetails 对象。否则是一个错误信息。

预订请求

预订请求是用于检索我们在 XML World 的预订当前状态。

try {
	$result = $xmlClient->booking(reference: $bookingReference);
} catch (Throwable $e) {
}

我们提供从预订请求中获得的 XML World 预订参考，并得到一个与预订请求中的 BookResponse 对象相同的 BookingResponse 对象。

预订更新请求

预订更新请求是用于设置交易参考。

try {
	$result = $xmlClient->bookingUpdate(reference: $bookingReference, tradeReference: $tradeReference);
} catch (Throwable $e) {
}

该方法接受在 BookRequest 或 BookingRequest 请求中给出的预订参考和交易参考。它返回一个包含与 BookResponse 相同数据的 BookingUpdateRequestResponse 对象。

取消请求

使用取消请求，我们可以取消预订。

try {
	$result = $xmlClient->cancel(reference: $bookingReference, reason: $cancellationReason);
} catch (Throwable $e) {
}

该方法接受在 BookRequest 或 BookingRequest 请求中给出的预订参考和交易参考。它返回一个 CancelResponse，原则上类似于 BookResponse，但会告知取消是否成功。

一旦取消预订，BookingRequest 将返回一个包含与该 CancelResponse 相同详情的 BookingResponse 对象。

开发环境

XMLClient 支持两种环境，实时（默认）和开发。

实时环境攻击生产环境中的 API，调用会产生真实的结果和预订。

开发环境攻击我们的测试环境，数据可能反映生产环境，但预订没有实际效果。

要激活开发环境，请这样做

$env = XMLClient::ENV_DEV;

$xmlClient = new XMLClient(login: $login, password: $password, env: $env);

您只需要通过传递常量 XMLClient::ENV_DEV 作为第三个参数来指定开发环境。

如果您需要为测试目的在开发环境中请求不同的服务器，您可以这样做

XMLClient::setDevURL('your own dev url');

日志记录

XMLClient 还提供了记录调用和响应的方法。

为了做到这一点，您需要实现 Logger 接口。

$myLogger = function($payload){
	echo $payload;
};

//you can implement the Logger interface to inject your logging implementation in the client.
$logging = new class($myLogger) implements Logger
{
	protected Closure $myLogger;
	
	public function __construct(Closure $myLogger)
	{
		$this->myLogger = $myLogger;
	}

	public function logRequest(string $log): void
	{
		($this->myLogger)($log);
	}

	public function logResponse(int $statusCode, string $log): void
	{
		($this->myLogger)($log);
	}
};

$xmlClient = new XMLClient(login: $login, password: $password, env: $env, logger: $logging);

例如，我们构建了这个匿名类，它实现了 Logger 并将我们使用的任何日志对象作为第四个参数注入。

示例

您可以在 examples/ 文件夹中找到使用示例。

  1. 用于搜索，在 search_example.php 中。
  2. 用于预订，在 book_example.php 中。
  3. 用于检索预订，在 booking_example.php 中。
  4. 用于更新预订，在 booking_update_example.php 中。
  5. 用于取消预订，在 cancel_example.php 中。
  6. 用于日志注入，在 logging_injection_example.php 中。