======================
|
The web service client
|
======================
|
|
The ``Guzzle\Service`` namespace contains various abstractions that help to make it easier to interact with a web
|
service API, including commands, service descriptions, and resource iterators.
|
|
In this chapter, we'll build a simple `Twitter API client <https://dev.twitter.com/docs/api/1.1>`_.
|
|
Creating a client
|
=================
|
|
A class that extends from ``Guzzle\Service\Client`` or implements ``Guzzle\Service\ClientInterface`` must implement a
|
``factory()`` method in order to be used with a :doc:`service builder <using-the-service-builder>`.
|
|
Factory method
|
--------------
|
|
You can use the ``factory()`` method of a client directly if you do not need a service builder.
|
|
.. code-block:: php
|
|
use mtdowling\TwitterClient;
|
|
// Create a client and pass an array of configuration data
|
$twitter = TwitterClient::factory(array(
|
'consumer_key' => '****',
|
'consumer_secret' => '****',
|
'token' => '****',
|
'token_secret' => '****'
|
));
|
|
.. note::
|
|
If you'd like to follow along, here's how to get your Twitter API credentials:
|
|
1. Visit https://dev.twitter.com/apps
|
2. Click on an application that you've created
|
3. Click on the "OAuth tool" tab
|
4. Copy all of the settings under "OAuth Settings"
|
|
Implementing a factory method
|
-----------------------------
|
|
Creating a client and its factory method is pretty simple. You just need to implement ``Guzzle\Service\ClientInterface``
|
or extend from ``Guzzle\Service\Client``.
|
|
.. code-block:: php
|
|
namespace mtdowling;
|
|
use Guzzle\Common\Collection;
|
use Guzzle\Plugin\Oauth\OauthPlugin;
|
use Guzzle\Service\Client;
|
use Guzzle\Service\Description\ServiceDescription;
|
|
/**
|
* A simple Twitter API client
|
*/
|
class TwitterClient extends Client
|
{
|
public static function factory($config = array())
|
{
|
// Provide a hash of default client configuration options
|
$default = array('base_url' => 'https://api.twitter.com/1.1');
|
|
// The following values are required when creating the client
|
$required = array(
|
'base_url',
|
'consumer_key',
|
'consumer_secret',
|
'token',
|
'token_secret'
|
);
|
|
// Merge in default settings and validate the config
|
$config = Collection::fromConfig($config, $default, $required);
|
|
// Create a new Twitter client
|
$client = new self($config->get('base_url'), $config);
|
|
// Ensure that the OauthPlugin is attached to the client
|
$client->addSubscriber(new OauthPlugin($config->toArray()));
|
|
return $client;
|
}
|
}
|
|
Service Builder
|
---------------
|
|
A service builder is used to easily create web service clients, provides a simple configuration driven approach to
|
creating clients, and allows you to share configuration settings across multiple clients. You can find out more about
|
Guzzle's service builder in :doc:`using-the-service-builder`.
|
|
.. code-block:: php
|
|
use Guzzle\Service\Builder\ServiceBuilder;
|
|
// Create a service builder and provide client configuration data
|
$builder = ServiceBuilder::factory('/path/to/client_config.json');
|
|
// Get the client from the service builder by name
|
$twitter = $builder->get('twitter');
|
|
The above example assumes you have JSON data similar to the following stored in "/path/to/client_config.json":
|
|
.. code-block:: json
|
|
{
|
"services": {
|
"twitter": {
|
"class": "mtdowling\\TwitterClient",
|
"params": {
|
"consumer_key": "****",
|
"consumer_secret": "****",
|
"token": "****",
|
"token_secret": "****"
|
}
|
}
|
}
|
}
|
|
.. note::
|
|
A service builder becomes much more valuable when using multiple web service clients in a single application or
|
if you need to utilize the same client with varying configuration settings (e.g. multiple accounts).
|
|
Commands
|
========
|
|
Commands are a concept in Guzzle that helps to hide the underlying implementation of an API by providing an easy to use
|
parameter driven object for each action of an API. A command is responsible for accepting an array of configuration
|
parameters, serializing an HTTP request, and parsing an HTTP response. Following the
|
`command pattern <http://en.wikipedia.org/wiki/Command_pattern>`_, commands in Guzzle offer a greater level of
|
flexibility when implementing and utilizing a web service client.
|
|
Executing commands
|
------------------
|
|
You must explicitly execute a command after creating a command using the ``getCommand()`` method. A command has an
|
``execute()`` method that may be called, or you can use the ``execute()`` method of a client object and pass in the
|
command object. Calling either of these execute methods will return the result value of the command. The result value is
|
the result of parsing the HTTP response with the ``process()`` method.
|
|
.. code-block:: php
|
|
// Get a command from the client and pass an array of parameters
|
$command = $twitter->getCommand('getMentions', array(
|
'count' => 5
|
));
|
|
// Other parameters can be set on the command after it is created
|
$command['trim_user'] = false;
|
|
// Execute the command using the command object.
|
// The result value contains an array of JSON data from the response
|
$result = $command->execute();
|
|
// You can retrieve the result of the command later too
|
$result = $command->getResult().
|
|
Command object also contains methods that allow you to inspect the HTTP request and response that was utilized with
|
the command.
|
|
.. code-block:: php
|
|
$request = $command->getRequest();
|
$response = $command->getResponse();
|
|
.. note::
|
|
The format and notation used to retrieve commands from a client can be customized by injecting a custom command
|
factory, ``Guzzle\Service\Command\Factory\FactoryInterface``, on the client using ``$client->setCommandFactory()``.
|
|
Executing with magic methods
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
When using method missing magic methods with a command, the command will be executed right away and the result of the
|
command is returned.
|
|
.. code-block:: php
|
|
$jsonData = $twitter->getMentions(array(
|
'count' => 5,
|
'trim_user' => true
|
));
|
|
Creating commands
|
-----------------
|
|
Commands are created using either the ``getCommand()`` method of a client or a magic missing method of a client. Using
|
the ``getCommand()`` method allows you to create a command without executing it, allowing for customization of the
|
command or the request serialized by the command.
|
|
When a client attempts to create a command, it uses the client's ``Guzzle\Service\Command\Factory\FactoryInterface``.
|
By default, Guzzle will utilize a command factory that first looks for a concrete class for a particular command
|
(concrete commands) followed by a command defined by a service description (operation commands). We'll learn more about
|
concrete commands and operation commands later in this chapter.
|
|
.. code-block:: php
|
|
// Get a command from the twitter client.
|
$command = $twitter->getCommand('getMentions');
|
$result = $command->execute();
|
|
Unless you've skipped ahead, running the above code will throw an exception.
|
|
PHP Fatal error: Uncaught exception 'Guzzle\Common\Exception\InvalidArgumentException' with message
|
'Command was not found matching getMentions'
|
|
This exception was thrown because the "getMentions" command has not yet been implemented. Let's implement one now.
|
|
Concrete commands
|
~~~~~~~~~~~~~~~~~
|
|
Commands can be created in one of two ways: create a concrete command class that extends
|
``Guzzle\Service\Command\AbstractCommand`` or
|
:doc:`create an OperationCommand based on a service description <guzzle-service-descriptions>`. The recommended
|
approach is to use a service description to define your web service, but you can use concrete commands when custom
|
logic must be implemented for marshaling or unmarshaling a HTTP message.
|
|
Commands are the method in which you abstract away the underlying format of the requests that need to be sent to take
|
action on a web service. Commands in Guzzle are meant to be built by executing a series of setter methods on a command
|
object. Commands are only validated right before they are executed. A ``Guzzle\Service\Client`` object is responsible
|
for executing commands. Commands created for your web service must implement
|
``Guzzle\Service\Command\CommandInterface``, but it's easier to extend the ``Guzzle\Service\Command\AbstractCommand``
|
class, implement the ``build()`` method, and optionally implement the ``process()`` method.
|
|
Serializing requests
|
^^^^^^^^^^^^^^^^^^^^
|
|
The ``build()`` method of a command is responsible for using the arguments of the command to build and serialize a
|
HTTP request and set the request on the ``$request`` property of the command object. This step is usually taken care of
|
for you when using a service description driven command that uses the default
|
``Guzzle\Service\Command\OperationCommand``. You may wish to implement the process method yourself when you aren't
|
using a service description or need to implement more complex request serialization.
|
|
.. important::::
|
|
When implementing a custom ``build()`` method, be sure to set the class property of ``$this->request`` to an
|
instantiated and ready to send request.
|
|
The following example shows how to implement the ``getMentions``
|
`Twitter API <https://dev.twitter.com/docs/api/1.1/get/statuses/mentions_timeline>`_ method using a concrete command.
|
|
.. code-block:: php
|
|
namespace mtdowling\Twitter\Command;
|
|
use Guzzle\Service\Command\AbstractCommand;
|
|
class GetMentions extends AbstractCommand
|
{
|
protected function build()
|
{
|
// Create the request property of the command
|
$this->request = $this->client->get('statuses/mentions_timeline.json');
|
|
// Grab the query object of the request because we will use it for
|
// serializing command parameters on the request
|
$query = $this->request->getQuery();
|
|
if ($this['count']) {
|
$query->set('count', $this['count']);
|
}
|
|
if ($this['since_id']) {
|
$query->set('since_id', $this['since_id']);
|
}
|
|
if ($this['max_id']) {
|
$query->set('max_id', $this['max_id']);
|
}
|
|
if ($this['trim_user'] !== null) {
|
$query->set('trim_user', $this['trim_user'] ? 'true' : 'false');
|
}
|
|
if ($this['contributor_details'] !== null) {
|
$query->set('contributor_details', $this['contributor_details'] ? 'true' : 'false');
|
}
|
|
if ($this['include_entities'] !== null) {
|
$query->set('include_entities', $this['include_entities'] ? 'true' : 'false');
|
}
|
}
|
}
|
|
By default, a client will attempt to find concrete command classes under the ``Command`` namespace of a client. First
|
the client will attempt to find an exact match for the name of the command to the name of the command class. If an
|
exact match is not found, the client will calculate a class name using inflection. This is calculated based on the
|
folder hierarchy of a command and converting the CamelCased named commands into snake_case. Here are some examples on
|
how the command names are calculated:
|
|
#. ``Foo\Command\JarJar`` **->** jar_jar
|
#. ``Foo\Command\Test`` **->** test
|
#. ``Foo\Command\People\GetCurrentPerson`` **->** people.get_current_person
|
|
Notice how any sub-namespace beneath ``Command`` is converted from ``\`` to ``.`` (a period). CamelCasing is converted
|
to lowercased snake_casing (e.g. JarJar == jar_jar).
|
|
Parsing responses
|
^^^^^^^^^^^^^^^^^
|
|
The ``process()`` method of a command is responsible for converting an HTTP response into something more useful. For
|
example, a service description operation that has specified a model object in the ``responseClass`` attribute of the
|
operation will set a ``Guzzle\Service\Resource\Model`` object as the result of the command. This behavior can be
|
completely modified as needed-- even if you are using operations and responseClass models. Simply implement a custom
|
``process()`` method that sets the ``$this->result`` class property to whatever you choose. You can reuse parts of the
|
default Guzzle response parsing functionality or get inspiration from existing code by using
|
``Guzzle\Service\Command\OperationResponseParser`` and ``Guzzle\Service\Command\DefaultResponseParser`` classes.
|
|
If you do not implement a custom ``process()`` method and are not using a service description, then Guzzle will attempt
|
to guess how a response should be processed based on the Content-Type header of the response. Because the Twitter API
|
sets a ``Content-Type: application/json`` header on this response, we do not need to implement any custom response
|
parsing.
|
|
Operation commands
|
~~~~~~~~~~~~~~~~~~
|
|
Operation commands are commands in which the serialization of an HTTP request and the parsing of an HTTP response are
|
driven by a Guzzle service description. Because request serialization, validation, and response parsing are
|
described using a DSL, creating operation commands is a much faster process than writing concrete commands.
|
|
Creating operation commands for our Twitter client can remove a great deal of redundancy from the previous concrete
|
command, and allows for a deeper runtime introspection of the API. Here's an example service description we can use to
|
create the Twitter API client:
|
|
.. code-block:: json
|
|
{
|
"name": "Twitter",
|
"apiVersion": "1.1",
|
"baseUrl": "https://api.twitter.com/1.1",
|
"description": "Twitter REST API client",
|
"operations": {
|
"GetMentions": {
|
"httpMethod": "GET",
|
"uri": "statuses/mentions_timeline.json",
|
"summary": "Returns the 20 most recent mentions for the authenticating user.",
|
"responseClass": "GetMentionsOutput",
|
"parameters": {
|
"count": {
|
"description": "Specifies the number of tweets to try and retrieve",
|
"type": "integer",
|
"location": "query"
|
},
|
"since_id": {
|
"description": "Returns results with an ID greater than the specified ID",
|
"type": "integer",
|
"location": "query"
|
},
|
"max_id": {
|
"description": "Returns results with an ID less than or equal to the specified ID.",
|
"type": "integer",
|
"location": "query"
|
},
|
"trim_user": {
|
"description": "Limits the amount of data returned for each user",
|
"type": "boolean",
|
"location": "query"
|
},
|
"contributor_details": {
|
"description": "Adds more data to contributor elements",
|
"type": "boolean",
|
"location": "query"
|
},
|
"include_entities": {
|
"description": "The entities node will be disincluded when set to false.",
|
"type": "boolean",
|
"location": "query"
|
}
|
}
|
}
|
},
|
"models": {
|
"GetMentionsOutput": {
|
"type": "object",
|
"additionalProperties": {
|
"location": "json"
|
}
|
}
|
}
|
}
|
|
If you're lazy, you can define the API in a less descriptive manner using ``additionalParameters``.
|
``additionalParameters`` define the serialization and validation rules of parameters that are not explicitly defined
|
in a service description.
|
|
.. code-block:: json
|
|
{
|
"name": "Twitter",
|
"apiVersion": "1.1",
|
"baseUrl": "https://api.twitter.com/1.1",
|
"description": "Twitter REST API client",
|
"operations": {
|
"GetMentions": {
|
"httpMethod": "GET",
|
"uri": "statuses/mentions_timeline.json",
|
"summary": "Returns the 20 most recent mentions for the authenticating user.",
|
"responseClass": "GetMentionsOutput",
|
"additionalParameters": {
|
"location": "query"
|
}
|
}
|
},
|
"models": {
|
"GetMentionsOutput": {
|
"type": "object",
|
"additionalProperties": {
|
"location": "json"
|
}
|
}
|
}
|
}
|
|
You should attach the service description to the client at the end of the client's factory method:
|
|
.. code-block:: php
|
|
// ...
|
class TwitterClient extends Client
|
{
|
public static function factory($config = array())
|
{
|
// ... same code as before ...
|
|
// Set the service description
|
$client->setDescription(ServiceDescription::factory('path/to/twitter.json'));
|
|
return $client;
|
}
|
}
|
|
The client can now use operations defined in the service description instead of requiring you to create concrete
|
command classes. Feel free to delete the concrete command class we created earlier.
|
|
.. code-block:: php
|
|
$jsonData = $twitter->getMentions(array(
|
'count' => 5,
|
'trim_user' => true
|
));
|
|
Executing commands in parallel
|
------------------------------
|
|
Much like HTTP requests, Guzzle allows you to send multiple commands in parallel. You can send commands in parallel by
|
passing an array of command objects to a client's ``execute()`` method. The client will serialize each request and
|
send them all in parallel. If an error is encountered during the transfer, then a
|
``Guzzle\Service\Exception\CommandTransferException`` is thrown, which allows you to retrieve a list of commands that
|
succeeded and a list of commands that failed.
|
|
.. code-block:: php
|
|
use Guzzle\Service\Exception\CommandTransferException;
|
|
$commands = array();
|
$commands[] = $twitter->getCommand('getMentions');
|
$commands[] = $twitter->getCommand('otherCommandName');
|
// etc...
|
|
try {
|
$result = $client->execute($commands);
|
foreach ($result as $command) {
|
echo $command->getName() . ': ' . $command->getResponse()->getStatusCode() . "\n";
|
}
|
} catch (CommandTransferException $e) {
|
// Get an array of the commands that succeeded
|
foreach ($e->getSuccessfulCommands() as $command) {
|
echo $command->getName() . " succeeded\n";
|
}
|
// Get an array of the commands that failed
|
foreach ($e->getFailedCommands() as $command) {
|
echo $command->getName() . " failed\n";
|
}
|
}
|
|
.. note::
|
|
All commands executed from a client using an array must originate from the same client.
|
|
Special command options
|
-----------------------
|
|
Guzzle exposes several options that help to control how commands are validated, serialized, and parsed.
|
Command options can be specified when creating a command or in the ``command.params`` parameter in the
|
``Guzzle\Service\Client``.
|
|
=========================== ============================================================================================
|
command.request_options Option used to add :ref:`Request options <request-options>` to the request created by a
|
command
|
command.hidden_params An array of the names of parameters ignored by the ``additionalParameters`` parameter schema
|
command.disable_validation Set to true to disable JSON schema validation of the command's input parameters
|
command.response_processing Determines how the default response parser will parse the command. One of "raw" no parsing,
|
"model" (the default method used to parse commands using response models defined in service
|
descriptions)
|
command.headers (deprecated) Option used to specify custom headers. Use ``command.request_options`` instead
|
command.on_complete (deprecated) Option used to add an onComplete method to a command. Use
|
``command.after_send`` event instead
|
command.response_body (deprecated) Option used to change the entity body used to store a response.
|
Use ``command.request_options`` instead
|
=========================== ============================================================================================
|
|
Advanced client configuration
|
=============================
|
|
Default command parameters
|
--------------------------
|
|
When creating a client object, you can specify default command parameters to pass into all commands. Any key value pair
|
present in the ``command.params`` settings of a client will be added as default parameters to any command created
|
by the client.
|
|
.. code-block:: php
|
|
$client = new Guzzle\Service\Client(array(
|
'command.params' => array(
|
'default_1' => 'foo',
|
'another' => 'bar'
|
)
|
));
|
|
Magic methods
|
-------------
|
|
Client objects will, by default, attempt to create and execute commands when a missing method is invoked on a client.
|
This powerful concept applies to both concrete commands and operation commands powered by a service description. This
|
makes it appear to the end user that you have defined actual methods on a client object, when in fact, the methods are
|
invoked using PHP's magic ``__call`` method.
|
|
The ``__call`` method uses the ``getCommand()`` method of a client, which uses the client's internal
|
``Guzzle\Service\Command\Factory\FactoryInterface`` object. The default command factory allows you to instantiate
|
operations defined in a client's service description. The method in which a client determines which command to
|
execute is defined as follows:
|
|
1. The client will first try to find a literal match for an operation in the service description.
|
2. If the literal match is not found, the client will try to uppercase the first character of the operation and find
|
the match again.
|
3. If a match is still not found, the command factory will inflect the method name from CamelCase to snake_case and
|
attempt to find a matching command.
|
4. If a command still does not match, an exception is thrown.
|
|
.. code-block:: php
|
|
// Use the magic method
|
$result = $twitter->getMentions();
|
|
// This is exactly the same as:
|
$result = $twitter->getCommand('getMentions')->execute();
|
|
You can disable magic methods on a client by passing ``false`` to the ``enableMagicMethod()`` method.
|
|
Custom command factory
|
----------------------
|
|
A client by default uses the ``Guzzle\Service\Command\Factory\CompositeFactory`` which allows multiple command
|
factories to attempt to create a command by a certain name. The default CompositeFactory uses a ``ConcreteClassFactory``
|
and a ``ServiceDescriptionFactory`` if a service description is specified on a client. You can specify a custom
|
command factory if your client requires custom command creation logic using the ``setCommandFactory()`` method of
|
a client.
|
|
Custom resource Iterator factory
|
--------------------------------
|
|
Resource iterators can be retrieved from a client using the ``getIterator($name)`` method of a client. This method uses
|
a client's internal ``Guzzle\Service\Resource\ResourceIteratorFactoryInterface`` object. A client by default uses a
|
``Guzzle\Service\Resource\ResourceIteratorClassFactory`` to attempt to find concrete classes that implement resource
|
iterators. The default factory will first look for matching iterators in the ``Iterator`` subdirectory of the client
|
followed by the ``Model`` subdirectory of a client. Use the ``setResourceIteratorFactory()`` method of a client to
|
specify a custom resource iterator factory.
|
|
Plugins and events
|
==================
|
|
``Guzzle\Service\Client`` exposes various events that allow you to hook in custom logic. A client object owns a
|
``Symfony\Component\EventDispatcher\EventDispatcher`` object that can be accessed by calling
|
``$client->getEventDispatcher()``. You can use the event dispatcher to add listeners (a simple callback function) or
|
event subscribers (classes that listen to specific events of a dispatcher).
|
|
.. _service-client-events:
|
|
Events emitted from a Service Client
|
------------------------------------
|
|
A ``Guzzle\Service\Client`` object emits the following events:
|
|
+------------------------------+--------------------------------------------+------------------------------------------+
|
| Event name | Description | Event data |
|
+==============================+============================================+==========================================+
|
| client.command.create | The client created a command object | * client: Client object |
|
| | | * command: Command object |
|
+------------------------------+--------------------------------------------+------------------------------------------+
|
| command.before_prepare | Before a command is validated and built. | * command: Command being prepared |
|
| | This is also before a request is created. | |
|
+------------------------------+--------------------------------------------+------------------------------------------+
|
| command.after_prepare | After a command instantiates and | * command: Command that was prepared |
|
| | configures its request object. | |
|
+------------------------------+--------------------------------------------+------------------------------------------+
|
| command.before_send | The client is about to execute a prepared | * command: Command to execute |
|
| | command | |
|
+------------------------------+--------------------------------------------+------------------------------------------+
|
| command.after_send | The client successfully completed | * command: The command that was executed |
|
| | executing a command | |
|
+------------------------------+--------------------------------------------+------------------------------------------+
|
| command.parse_response | Called when ``responseType`` is ``class`` | * command: The command with a response |
|
| | and the response is about to be parsed. | about to be parsed. |
|
+------------------------------+--------------------------------------------+------------------------------------------+
|
|
.. code-block:: php
|
|
use Guzzle\Common\Event;
|
use Guzzle\Service\Client;
|
|
$client = new Client();
|
|
// create an event listener that operates on request objects
|
$client->getEventDispatcher()->addListener('command.after_prepare', function (Event $event) {
|
$command = $event['command'];
|
$request = $command->getRequest();
|
|
// do something with request
|
});
|
|
.. code-block:: php
|
|
use Guzzle\Common\Event;
|
use Guzzle\Common\Client;
|
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
|
|
class EventSubscriber implements EventSubscriberInterface
|
{
|
public static function getSubscribedEvents()
|
{
|
return array(
|
'client.command.create' => 'onCommandCreate',
|
'command.parse_response' => 'onParseResponse'
|
);
|
}
|
|
public function onCommandCreate(Event $event)
|
{
|
$client = $event['client'];
|
$command = $event['command'];
|
// operate on client and command
|
}
|
|
public function onParseResponse(Event $event)
|
{
|
$command = $event['command'];
|
// operate on the command
|
}
|
}
|
|
$client = new Client();
|
|
$client->addSubscriber(new EventSubscriber());
|
