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.
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 service builder.
You can use the factory() method of a client directly if you do not need a service builder.
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:
Creating a client and its factory method is pretty simple. You just need to implement Guzzle\Service\ClientInterface or extend from Guzzle\Service\Client.
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;
}
}
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 Using a service builder.
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":
{
"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 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, commands in Guzzle offer a greater level of flexibility when implementing and utilizing a web service client.
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.
// 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.
$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().
When using method missing magic methods with a command, the command will be executed right away and the result of the command is returned.
$jsonData = $twitter->getMentions(array(
'count' => 5,
'trim_user' => true
));
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.
// 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 'GuzzleCommonExceptionInvalidArgumentException' 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.
Commands can be created in one of two ways: create a concrete command class that extends Guzzle\Service\Command\AbstractCommand or create an OperationCommand based on a service description. 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.
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.
The following example shows how to implement the getMentions Twitter API method using a concrete command.
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:
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).
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 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:
{
"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.
{
"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:
// ...
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.
$jsonData = $twitter->getMentions(array(
'count' => 5,
'trim_user' => true
));
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.
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.
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 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 |
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.
$client = new Guzzle\Service\Client(array(
'command.params' => array(
'default_1' => 'foo',
'another' => 'bar'
)
));
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:
// 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.
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.
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.
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).
A Guzzle\Service\Client object emits the following events:
| Event name | Description | Event data |
|---|---|---|
| client.command.create | The client created a command object |
|
| command.before_prepare | Before a command is validated and built. This is also before a request is created. |
|
| command.after_prepare | After a command instantiates and configures its request object. |
|
| command.before_send | The client is about to execute a prepared command |
|
| command.after_send | The client successfully completed executing a command |
|
| command.parse_response | Called when responseType is class and the response is about to be parsed. |
|
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
});
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());