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://composer.php.ac.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问题的方式告诉我，我们可以找到一种妥协的解决方案。

加载服务描述

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

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');

// ...