README

这是一个用于与 izi.TRAVEL API 通信的 PHP 库。

要求

所有要求都通过 Composer 解决。安装 composer 后，转到项目根目录并运行 composer install 以安装所有依赖项。

用法和功能

客户端

该库提供了一个与 API 通信的客户端。它处理所有请求、错误，并将所有 API 输出转换为 PHP 对象。在调用 API 之前，必须采取三个准备工作步骤

创建一个 \GuzzleHttp\Client 实例。
创建一个 \Triquanta\IziTravel\Client\*RequestHandler 实例，并注入步骤 1 中的 Guzzle 客户端和一个 API 密钥。
创建一个 Triquanta\IziTravel\Client\Client 实例，并注入步骤 2 中的请求处理器。

现在您可以从步骤 3 中的客户端调用任何方法，并获取 API 的输出（数组的）类 PHP 对象。

数据类型

由于在 PHP 中使用原始、无类型的数据是糟糕的开发者体验（DX），因此 API 中的每个数据类型都有相应的接口和库中的类。所有类都带有工厂方法（\Triquanta\IziTravel\DataType\FactoryInterface），用于根据 API 的原始 JSON 响应实例化对象。

事件

Symfony EventDispatcher 用于派发系统事件。事件名称和类在 \Triquanta\IziTravel\Event\IziTravelEvents 中有文档说明。

开发

版本

所有开发都在 master 分支上进行。版本根据语义版本发布。

支持新的 API 端点

每个 API 端点由 \Triquanta\IziTravel\Request 中的请求类表示，并且它必须实现 \Triquanta\IziTravel\Request\RequestInterface。它可以选择实现同一命名空间中的其他任何接口并使用任何特质以快速构建可配置的请求。任何端点返回的对象数据必须在返回 \Triquanta\IziTravel\Request\RequestInterface::execute() 实现之前转换为类对象。可以重用 Triquanta\IziTravel\DataType 中的现有数据类型。\Triquanta\IziTravel\ClientInterface 是一个方便层，用于轻松从同一代码中的不同端点请求数据。当添加新的请求类时，还必须向该接口添加其方法。

示例

新增了一个端点foo，用于通过UUID检索Foo内容。此外，内容可以以特定的语言和格式（完整/紧凑）返回。第一步是创建一个实现正确接口的类（该接口继承自RequestBase）

<?php
    
/**
 * @file Contains \Triquanta\IziTravel\Request\FooByUuid.
 */

namespace Triquanta\IziTravel\Request;

/**
 * Returns a Foo object by UUID.
 */
class FooByUuid extends RequestBase {

    /**
     * @return \Triquanta\IziTravel\DataType\FooInterface
     */
    public function execute() {
    }

}

现在我们有了任何请求的基础。因为这个端点支持表单和多语言，我们可以通过实现两个接口并使用两个特质轻松添加对它的支持

<?php

class FooByUuid extends RequestBase implements FormInterface, MultilingualInterface, UuidInterface {

    use FormTrait;
    use MultilingualTrait;
    use UuidTrait;

    /**
     * @return \Triquanta\IziTravel\DataType\FooInterface
     */
    public function execute() {
    }

}

该类将具有设置和存储表单、语言以及API应返回的内容的UUID的额外方法和属性。

现在我们可以配置这个类的实例，我们需要使用这个配置来执行实际请求并从响应中获取JSON

<?php

public function execute() {
    $json = $this->requestHandler->request('/foo', [
      'form' => $this->form,
      'languages' => $this->languageCodes,
      'uuid' => $this->limit,
    ]);
}

请求发送到端点，我们传递三个端点参数（表单、语言、UUID）的值。如您所见，我们使用特质的属性来完成这项工作。

剩下的是将此JSON转换为类对象。我们不必担心NULL值，因为API在请求的内容不可用时返回HTTP错误响应。这意味着当此代码执行时，我们可以确信响应是肯定的。

<?php

public function execute() {
    // ...
    
    return Foo::createFromJson($json, $this->form);
}

所有数据对象类都实现了FactoryInterface，必须使用接口的方法进行实例化。通过调用::createFromJson()，我们还验证了JSON与可用架构的一致性。

整个请求类现在看起来像这样

<?php
    
/**
 * @file Contains \Triquanta\IziTravel\Request\FooByUuid.
 */

namespace Triquanta\IziTravel\Request;

/**
 * Returns a Foo object by UUID.
 */
class FooByUuid extends RequestBase implements FormInterface, MultilingualInterface, UuidInterface {

    use FormTrait;
    use MultilingualTrait;
    use UuidTrait;

    /**
     * @return \Triquanta\IziTravel\DataType\FooInterface
     */
    public function execute() {
        $json = $this->requestHandler->request('/foo', [
          'form' => $this->form,
          'languages' => $this->languageCodes,
          'uuid' => $this->limit,
        ]);

        return Foo::createFromJson($json, $this->form);
    }

}

为了方便，我们还向ClientInterface添加了一个工厂方法。因为语言和UUID是唯一必需的请求参数，它们也是工厂方法的唯一参数。任何剩余的可选参数都可以通过返回的请求对象的设置器进行配置。

<?php

namespace Triquanta\IziTravel\Client;

interface ClientInterface
{

    // ...

    /**
     * Gets a request to get a Foo object by its UUID.
     *
     * @param string[] $languageCodes
     *   An array of ISO 639-1 alpha-2 language codes.
     * @param string $uuid
     *
     * @return \Triquanta\IziTravel\Request\FooByUuid
     */
    public function getFooByUuid(array $languageCodes, $uuid);

}

Client中方法的实现可能如下所示

<?php

namespace Triquanta\IziTravel\Client;

use namespace Triquanta\IziTravel\Request\FooByUuid;

class Client implements ClientInterface
{

    // ...

    public function getFooByUuid(array $languageCodes, $uuid)
    {
        return FooByUuid::create($this->requestHandler)
          ->setLanguageCodes($languageCodes)
          ->setUuid($uuid);
    }

}

然后可以使用新支持的端点

<?php

use Triquanta\IziTravel\Client\Client;

$client = new Client(/* ... */);
/** @var \Triquanta\IziTravel\DataType\FooInterface $foo */
$foo = $client->getFooByUuid(['en'], 'de305d54-75b4-431b-adb2-eb6b9e546014')->setForm(FormInterface::FORM_COMPACT)->execute();

PSR-2

所有代码都必须根据PSR-2指南编写。

PSR-4

使用以下命名空间映射使用PSR-4进行类和接口自动加载

\Triquanta\IziTravel映射到./src
\Triquanta\IziTravel\Tests映射到./tests

测试

该库包含基于PHPUnit的测试，可以使用./phpunit.xml.dist运行。所有测试都位于\Triquanta\IziTravel\Tests。

某些测试需要配置。将./test_configuration.example.yml复制到./test_configuration.local.yml并填写值。

informap / libtour

维护者

详细信息