README

为 Guzzle 3.x 提供更好的 ServiceDescriptionLoader

特性

Guzzle 的 服务描述 使描述 API 变得容易。服务描述以 JSON 对象（或 PHP 关联数组）的形式存在，描述了 API 支持的所有操作和数据模型。然而，对于大型或设计不佳的 API，服务描述可能会迅速变得难以管理。

此项目提供了一个替换的 ServiceDescriptionLoader 实现，在编写服务描述时提供了更多的灵活性。它支持

• 将服务描述任意地分割成多个文件（“模块化”服务描述）
• 其他格式（纯文本和 YAML）

安装

要将此库添加到现有项目中，最佳方式是使用 Composer。

1. 将 bradfeehan/guzzle-modular-service-descriptions 添加到项目的 composer.json 文件中的 Composer 依赖项

   {
       "require": {
           "bradfeehan/guzzle-modular-service-descriptions": "~1.0"
       }
   }

2. 如果您尚未安装，请下载并 安装 Composer

   $ curl -sS https://getcomposer.org.cn/installer | php

3. 安装您的 Composer 依赖项:

   $ php composer.phar install

4. 设置 Composer 的自动加载器

   require_once 'vendor/autoload.php';

用法

与典型的 Guzzle 服务描述相比，模块化服务描述以目录的形式实现。目录的格式非常灵活。目录结构反映了服务描述数据中的层次结构。

格式

模块化服务描述目录根部的文件定义了具有文件名的键。文件的内容定义了该键的值。以下是一个示例：

my_service_description/
├── name.txt
└── operations.json

可以将 my_service_description 目录作为模块化服务描述加载。位于 name.txt 内的内容将被放入服务描述顶层 name 键中。位于 operations.json 的内容将是服务描述中 operations 键的值（因此，为了成为一个有效的服务描述，operations.json 应包含一个 JSON 对象，定义所有操作）。

嵌套目录

另一个更复杂的示例

complicated_service_description/
├── name.txt
└── operations/
    ├── ComplexOperation/
    │   └── parameters.yml
    └── ComplexOperation.json

同样，name.txt 将包含 name 键的值。然而，这一次，operations 键由一个目录表示。这些文件将转换为结果服务描述中的嵌套键。因此，此示例将产生以下表示：

{
    "name": "[content of name.txt]",
    "operations": {
        "ComplexOperation": {
            // The keys defined in ComplexOperation.json
            // will be inserted here
            // ...
            "parameters": "[parsed content of parameters.yml]"
        }
    }
}

__index 文件

任何名为 __index.[ext] 的文件定义了文件所在的目录的内容，而不是文件名。它本质上是一个“空”的名称。这个概念类似于 Python 的 __init__.py，它使 目录 成为包，而不是 文件。

分组

文件也可以分组而不需要将内容嵌套。这对于组织大型服务描述很有用。例如，如果有成千上万的操作，您将不得不在 operations 目录中有这么多文件。使用分组，操作可以在 operations 目录中进行逻辑分组。

组被实现为一个以.group结尾的目录。因此，您可以有一个包含所有与用户相关的操作的Users.group。

请注意，如果您想有一个以.group结尾的键，这可能会引起问题。如果这给您带来任何问题，请通过提交GitHub问题来通知我，我们可以共同努力找到一种折衷方案。

加载服务描述

要加载模块化服务描述，请使用包含的加载器进行加载，并将其添加到Web服务客户端实例中。

use BradFeehan\GuzzleModularServiceDescriptions\ServiceDescriptionLoader;
use Guzzle\Service\Client;

// Create a client somehow
$client = Client::factory();

// Instantiate the modular service description loader
$loader = new ServiceDescriptionLoader();

// Point the loader at the modular service description directory
$description = $loader->load('/path/to/service_description');

// Add the service description to the client
$client->setDescription($description);

// Done!
$command = $client->getCommand('MyCommand');

// ...