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步中的客户端调用任何方法，并以（数组形式的）类PHP对象的形式获取API的输出。

数据类型

由于在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并填写值。

triquanta / libizi

维护者

详细信息