PHPackages                             scotwells/guzzle-modular-service-descriptions - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. scotwells/guzzle-modular-service-descriptions

ActiveLibrary[HTTP & Networking](/categories/http)

scotwells/guzzle-modular-service-descriptions
=============================================

A better ServiceDescriptionLoader for Guzzle 3.x

v2.0(10y ago)07[1 PRs](https://github.com/scotwells/guzzle-modular-service-descriptions/pulls)MITPHPPHP >=5.3

Since May 5Pushed 5y ago1 watchersCompare

[ Source](https://github.com/scotwells/guzzle-modular-service-descriptions)[ Packagist](https://packagist.org/packages/scotwells/guzzle-modular-service-descriptions)[ RSS](/packages/scotwells-guzzle-modular-service-descriptions/feed)WikiDiscussions master Synced today

READMEChangelog (1)Dependencies (4)Versions (12)Used By (0)

guzzle-modular-service-descriptions
===================================

[](#guzzle-modular-service-descriptions)

[![Build Status](https://camo.githubusercontent.com/e04d9634b0f615a03e9a3833a173cc78909dff7860757786795ee75d43c5e225/68747470733a2f2f7472617669732d63692e6f72672f6272616466656568616e2f67757a7a6c652d6d6f64756c61722d736572766963652d6465736372697074696f6e732e737667)](https://travis-ci.org/bradfeehan/guzzle-modular-service-descriptions)[![Code Coverage](https://camo.githubusercontent.com/774290329264bb4b5aad9c2edf4e1548348ebd2612b8001fa7b20dfcf9c364a6/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6272616466656568616e2f67757a7a6c652d6d6f64756c61722d736572766963652d6465736372697074696f6e732f6261646765732f636f7665726167652e706e673f733d66313033383339316266333462663962303932623964643661363932363033653238616435633565)](https://scrutinizer-ci.com/g/bradfeehan/guzzle-modular-service-descriptions/)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/6280a0004913f2575bbb5eda44c20c76cea4e5995adae4c0e8095adf07717243/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6272616466656568616e2f67757a7a6c652d6d6f64756c61722d736572766963652d6465736372697074696f6e732f6261646765732f7175616c6974792d73636f72652e706e673f733d36653234353361643066636539363033353664383735656632333037363737666537373637346332)](https://scrutinizer-ci.com/g/bradfeehan/guzzle-modular-service-descriptions/)

A better ServiceDescriptionLoader for [Guzzle 3.x](https://github.com/guzzle/guzzle3)

Features
--------

[](#features)

Guzzle's [service descriptions](https://github.com/guzzle/guzzle3/blob/master/docs/webservice-client/guzzle-service-descriptions.rst) make it easy to describe APIs. A service description takes the form of a JSON object (or PHP associative array) that describes all the available operations and data models supported by the API. However, for large or poorly-designed APIs, the service description can quickly become hard to manage.

This project offers a replacement ServiceDescriptionLoader implementation, which allows for much more flexibility when writing service descriptions. It supports:

- Separating the service description arbitrarily into many files ("modular" service descriptions)
- Alternative formats (plain text and YAML)

Installation
------------

[](#installation)

To get this library in to an existing project, the best way is to use [Composer](http://getcomposer.org).

1. Add `bradfeehan/guzzle-modular-service-descriptions` as a Composer dependency in your project's [`composer.json`](http://getcomposer.org/doc/01-basic-usage.md#the-require-key "More on the composer.json format") file:

    ```
    {
        "require": {
            "bradfeehan/guzzle-modular-service-descriptions": "~1.0"
        }
    }
    ```
2. If you haven't already, download and [install Composer](http://getcomposer.org/doc/01-basic-usage.md#installation "More detailed installation instructions on the Composer site"):

    ```
    $ curl -sS https://getcomposer.org/installer | php
    ```
3. [Install your Composer dependencies](http://getcomposer.org/doc/01-basic-usage.md#installing-dependencies "More detailed instructions on the Composer site"):

    ```
    $ php composer.phar install
    ```
4. Set up [Composer's autoloader](http://getcomposer.org/doc/01-basic-usage.md#autoloading "More information about the autoloader on the Composer site"):

    ```
    require_once 'vendor/autoload.php';
    ```

Usage
-----

[](#usage)

In contrast to typical Guzzle service descriptions, a modular service description is implemented as a directory. The format of the directory is very flexible. The directory structure is reflected in the heirarchy of the service description data.

#### Format

[](#format)

A file in the root of a modular service description directory defines the key with the name of the file. The content of the file defines the value of that key. As an example, consider the following directory structure:

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

```

The `my_service_description` directory can be loaded as a modular service description. The content inside `name.txt` will be put into the key `name` at the top level of the service description. The content of `operations.json` will be the value for the `operations` key in the service description. (So, to be a valid service description, `operations.json` should contain a JSON object, defining all the operations).

##### Nested directories

[](#nested-directories)

Another, more complex example:

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

```

Again, `name.txt` will contain the value for the `name` key. However, this time, the `operations` key is represented by a directory. The files inside are converted to nested keys in the resulting service description. So this example will result in the following representation:

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

##### `__index` files

[](#__index-files)

Any files named `__index.[ext]` define the contents of the directory the file is in, rather than the name of the file. It's essentially an "empty" name. This concept is similar to Python's `__init__.py`, which makes the *directory* the package, rather than the *file*.

##### Groups

[](#groups)

Files can also be grouped without causing the contents to be nested. This is useful for organising a large service description. For example, if there are thousands of operations, you'd have to have that many files in the `operations` directory. Using groups, the operations can be grouped logically inside the `operations` directory.

A group is implemented as a directory ending with `.group`. So you could have `Users.group` containing all the operations relating to users, etc.

Note that this could cause problems if you wanted to have a key ending with `.group`. Please let me know by filing a GitHub issue if this causes you any issues, and we can work out a way to compromise.

### Loading the service description

[](#loading-the-service-description)

To load a modular service description, load it using the included loader, and add it to the web service client instance:

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

// ...
```

###  Health Score

27

—

LowBetter than 47% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity4

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity65

Established project with proven stability

 Bus Factor1

Top contributor holds 90.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~89 days

Recently: every ~156 days

Total

8

Last Release

3813d ago

Major Versions

v1.3.0 → v2.02016-01-21

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/6007097?v=4)[Scot Schuchert-Wells](/maintainers/scotwells)[@scotwells](https://github.com/scotwells)

---

Top Contributors

[![bradfeehan](https://avatars.githubusercontent.com/u/1052806?v=4)](https://github.com/bradfeehan "bradfeehan (48 commits)")[![dependabot-preview[bot]](https://avatars.githubusercontent.com/in/2141?v=4)](https://github.com/dependabot-preview[bot] "dependabot-preview[bot] (2 commits)")[![scotwells](https://avatars.githubusercontent.com/u/6007097?v=4)](https://github.com/scotwells "scotwells (2 commits)")[![jimcottrell](https://avatars.githubusercontent.com/u/1483197?v=4)](https://github.com/jimcottrell "jimcottrell (1 commits)")

---

Tags

Guzzleservice description

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/scotwells-guzzle-modular-service-descriptions/health.svg)

```
[![Health](https://phpackages.com/badges/scotwells-guzzle-modular-service-descriptions/health.svg)](https://phpackages.com/packages/scotwells-guzzle-modular-service-descriptions)
```

###  Alternatives

[rcsofttech/audit-trail-bundle

Enterprise-grade, high-performance Symfony audit trail bundle. Automatically track Doctrine entity changes with split-phase architecture, multiple transports (HTTP, Queue, Doctrine), and sensitive data masking.

1175.2k](/packages/rcsofttech-audit-trail-bundle)[playbloom/guzzle-bundle

Provide Symfony2 web profiler for Guzzle

82311.2k1](/packages/playbloom-guzzle-bundle)[auxmoney/opentracing-bundle-core

Symfony Opentracing bundle to easily enable distributed tracing

25906.5k9](/packages/auxmoney-opentracing-bundle-core)[dreamfactory/df-core

DreamFactory(tm) Core Components

1652.0k38](/packages/dreamfactory-df-core)[bradfeehan/desk-php

PHP client for Desk.com v2 API based on Guzzle

2181.4k](/packages/bradfeehan-desk-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)