Guzzle 3

A ServiceBuilder is a tool used to instantiate Guzzle web service clients based on centralized configuration. Instead of manually calling factory() methods on individual client classes, you use a ServiceBuilder to manage credentials, share configuration across multiple clients, and decouple your application from concrete client classes.

Key benefits include:

• Configuration Sharing: Use an "abstract" service to define common parameters (like API keys) and have other services extends it to inherit those parameters.
• Environment Management: Easily switch between development and production clients by defining them in the builder configuration.
• Dependency Injection: You can reference one service inside the parameters of another by enclosing the service name in curly braces (e.g., "{service_name}"). The builder will automatically instantiate the dependency first and inject it.
• Singleton-like Behavior: The ServiceBuilder acts as a multiton; it instantiates a client only once and returns the same instance for subsequent requests for that same service name.

use Guzzle\
use Guzzle\Service\Builder\ServiceBuilder;

// Define a hierarchy where 'foo' inherits from 'abstract_client'
$builder = ServiceBuilder::factory(array(
    'services' => array(
        'abstract_client' => array(
            'params' => array(
                'key'    => 'abc',
                'secret' => '123'
            )
        ),
        'foo' => array(
            'extends' => 'abstract_client',
            'class'   => 'MyService\\FooClient',
            'params'  => array(
                'custom' => 'and above all'
            )
        )
    )
));

$foo = $builder->get('foo');

In Guzzle, HTTP message bodies are treated as PHP streams via the Guzzle\Http\EntityBody class. You can create an EntityBody from a string or a PHP stream using the EntityBody::factory() method.

To protect against memory exhaustion, Guzzle uses temporary PHP streams. If the data exceeds 2MB, it is automatically stored on disk instead of in memory. This allows Guzzle to stream data during uploads and downloads without loading the entire body into a string.

You can specify a request body in Client::put() or Client::post() methods, or by calling setBody() on any object implementing Guzzle\Http\Message\EntityEnclosingRequestInterface.

use Guzzle\
Http\
EntityBody;

// Create an EntityBody from a file stream
$body = EntityBody::factory(fopen('/path/to/file.txt', 'r+'));

// Send a request using the body
$response = $client->put('http://localhost:8080/uploads', null, $body)->send();

Operations represent the actions available on a service. Each operation has a unique name, an HTTP method, and a URI.

Key attributes for an operation include:

• httpMethod: The HTTP verb (e.g., GET, POST, PUT, DELETE, PATCH).
• uri: The endpoint URI, which can use URI templates (e.g., /users/{id}). Variables in the template become parameters with location: "uri".
• responseClass: Defines what getResult() returns. Can be primitive, a class name (must implement Guzzle\Service\Command\ResponseClassInterface), or a model name.
• responseType: The type of response (primitive, class, model, or documentation). Defaults to primitive if not specified.
• errorResponses: An array of objects defining potential errors. Each object can contain code (HTTP status), reason (description), and class (the exception class to raise).
• additionalParameters: A catch-all rule for parameters not explicitly defined. This is useful for APIs with many similar parameters (e.g., Twitter's query string parameters).
• parameters: An object defining specific input data for the request.

{
    "operations": {
        "operationName": {
            "extends": "string",
            "httpMethod": "GET|POST|PUT|DELETE|PATCH|string",
            "uri": "string",
            "summary": "string",
            "class": "string",
            "responseClass": "string",
            "responseNotes": "string",
            "type": "string",
            "description": "string",
            "responseType": "primitive|class|(model by name)|documentation|(string)",
            "deprecated": false,
            "errorResponses": [
                {
                    "code": 500,
                    "reason": "Unexpected Error",
                    "class": "string"
                }
            ],
            "data": {
                "foo": "bar",
                "baz": "bam"
            },
            "parameters": {}
        }
    }
}

The Guzzle HTTP client is built on top of PHP libcurl bindings and consists of three primary components that work in a lifecycle:

1. Clients (Guzzle\Http\Client): Responsible for creating and sending requests, and associating a response with a request.
2. Requests (Guzzle\Http\Message\Request or Guzzle\Http\Message\EntityEnclosingRequest): Represents the HTTP request. Use Request for requests without a body and EntityEnclosingRequest for those with a body.
3. Responses (Guzzle\Http\Message\Response): The object returned after a request is successfully sent.

To perform an HTTP operation, you typically create a client, use a client method to generate a request, and then call send() on that request to receive a response.

use Guzzle\Http\Client;

$client = new Client('https://api.github.com');
$request = $client->get('/user');
$response = $request->send();

The Guzzle\Batch\Batch object acts as a queue. You add items to the queue and then call flush() to transfer them.

To manage the transfer, the batch object uses two components:

1. Divisor (Guzzle\Batch\BatchDivisorInterface): Responsible for dividing the queue into manageable chunks.
2. Transfer Strategy (Guzzle\Batch\BatchTransferInterface): Responsible for sending the chunks.

In many cases, a single class (like Guzzle\Http\BatchRequestTransfer) can act as both the divisor and the transfer strategy.

use Guzzle\Batch\Batch;
use Guzzle\Http\BatchRequestTransfer;

// BatchRequestTransfer acts as both the divisor and transfer strategy
$transferStrategy = new BatchRequestTransfer(10);
$divisorStrategy = $transferStrategy;

$batch = new Batch($transferStrategy, $divisorStrategy);

// Add items to the queue
$batch->add($request1)
    ->add($request2)
    ->add($request3);

// Flush the queue and retrieve the transferred items
$arrayOfTransferredRequests = $batch->flush();