Download the PHP package bradfeehan/guzzle-modular-service-descriptions without Composer
On this page you can find all versions of the php package bradfeehan/guzzle-modular-service-descriptions. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download bradfeehan/guzzle-modular-service-descriptions
More information about bradfeehan/guzzle-modular-service-descriptions
Files in bradfeehan/guzzle-modular-service-descriptions
Package guzzle-modular-service-descriptions
Short Description A better ServiceDescriptionLoader for Guzzle 3.x
License MIT
Informations about the package guzzle-modular-service-descriptions
guzzle-modular-service-descriptions
A better ServiceDescriptionLoader for Guzzle 3.x
Features
Guzzle's service descriptions 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
To get this library in to an existing project, the best way is to use Composer.
-
Add
bradfeehan/guzzle-modular-service-descriptions
as a Composer dependency in your project'scomposer.json
file: -
If you haven't already, download and install Composer:
-
Set up Composer's autoloader:
"More on the composer.json format" "More detailed installation instructions on the Composer site" "More detailed instructions on the Composer site" "More information about the autoloader on the Composer site"
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
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:
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
Another, more complex example:
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:
__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
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
To load a modular service description, load it using the included loader, and add it to the web service client instance: