Event System

Guzzle uses an event emitter to allow you to easily extend the behavior of a request, change the response associated with a request, and implement custom error handling. All events in Guzzle are managed and emitted by an event emitter.

Event Emitters

Clients, requests, and any other class that implements the GuzzleHttp\Event\HasEmitterInterface interface have a GuzzleHttp\Event\Emitter object. You can add event listeners and event subscribers to an event emitter.

emitter

An object that implements GuzzleHttp\Event\EmitterInterface. This object emits named events to event listeners. You may register event listeners on subscribers on an emitter.

event listeners

Callable functions that are registered on an event emitter for specific events. Event listeners are registered on an emitter with a priority setting. If no priority is provided, 0 is used by default.

event subscribers

Classes that tell an event emitter what methods to listen to and what functions on the class to invoke when the event is triggered. Event subscribers subscribe event listeners to an event emitter. They should be used when creating more complex event based logic in applications (i.e., cookie handling is implemented using an event subscriber because it’s easier to share a subscriber than an anonymous function and because handling cookies is a complex process).

priority

Describes the order in which event listeners are invoked when an event is emitted. The higher a priority value, the earlier the event listener will be invoked (a higher priority means the listener is more important). If no priority is provided, the priority is assumed to be 0.

When specifying an event priority, you can pass "first" or "last" to dynamically specify the priority based on the current event priorities associated with the given event name in the emitter. Use "first" to set the priority to the current highest priority plus one. Use "last" to set the priority to the current lowest event priority minus one. It is important to remember that these dynamic priorities are calculated only at the point of insertion into the emitter and they are not rearranged after subsequent listeners are added to an emitter.

propagation

Describes whether or not other event listeners are triggered. Event emitters will trigger every event listener registered to a specific event in priority order until all of the listeners have been triggered or until the propagation of an event is stopped.

Getting an EventEmitter

You can get the event emitter of GuzzleHttp\Event\HasEmitterInterface object using the getEmitter() method. Here’s an example of getting a client object’s event emitter.

  1. $client = new GuzzleHttp\Client();
  2. $emitter = $client->getEmitter();

Note

You’ll notice that the event emitter used in Guzzle is very similar to the Symfony2 EventDispatcher component. This is because the Guzzle event system is based on the Symfony2 event system with several changes. Guzzle uses its own event emitter to improve performance, isolate Guzzle from changes to the Symfony, and provide a few improvements that make it easier to use for an HTTP client (e.g., the addition of the once() method).

Adding Event Listeners

After you have the emitter, you can register event listeners that listen to specific events using the on() method. When registering an event listener, you must tell the emitter what event to listen to (e.g., “before”, “after”, “progress”, “complete”, “error”, etc.), what callable to invoke when the event is triggered, and optionally provide a priority.

  1. use GuzzleHttp\Event\BeforeEvent;
  3. $emitter->on('before', function (BeforeEvent $event) {
  4.     echo $event->getRequest();
  5. });

When a listener is triggered, it is passed an event that implements the GuzzleHttp\Event\EventInterface interface, the name of the event, and the event emitter itself. The above example could more verbosely be written as follows:

  1. use GuzzleHttp\Event\BeforeEvent;
  3. $emitter->on('before', function (BeforeEvent $event, $name) {
  4.     echo $event->getRequest();
  5. });

You can add an event listener that automatically removes itself after it is triggered using the once() method of an event emitter.

  1. $client = new GuzzleHttp\Client();
  2. $client->getEmitter()->once('before', function () {
  3.     echo 'This will only happen once... per request!';
  4. });

Event Propagation

Event listeners can prevent other event listeners from being triggered by stopping an event’s propagation.

Stopping event propagation can be useful, for example, if an event listener has changed the state of the subject to such an extent that allowing subsequent event listeners to be triggered could place the subject in an inconsistent state. This technique is used in Guzzle extensively when intercepting error events with responses.

You can stop the propagation of an event using the stopPropagation() method of a GuzzleHttp\Event\EventInterface object:

  1. use GuzzleHttp\Event\ErrorEvent;
  3. $emitter->on('error', function (ErrorEvent $event) {
  4.     $event->stopPropagation();
  5. });

After stopping the propagation of an event, any subsequent event listeners that have not yet been triggered will not be triggered. You can check to see if the propagation of an event was stopped using the isPropagationStopped() method of the event.

  1. $client = new GuzzleHttp\Client();
  2. $emitter = $client->getEmitter();
  3. // Note: assume that the $errorEvent was created
  4. if ($emitter->emit('error', $errorEvent)->isPropagationStopped()) {
  5.     echo 'It was stopped!';
  6. }

Hint

When emitting events, the event that was emitted is returned from the emitter. This allows you to easily chain calls as shown in the above example.

Event Subscribers

Event subscribers are classes that implement the GuzzleHttp\Event\SubscriberInterface object. They are used to register one or more event listeners to methods of the class. Event subscribers tell event emitters exactly which events to listen to and what method to invoke on the class when the event is triggered by called the getEvents() method of a subscriber.

The following example registers event listeners to the before and complete event of a request. When the before event is emitted, the onBefore instance method of the subscriber is invoked. When the complete event is emitted, the onComplete event of the subscriber is invoked. Each array value in the getEvents() return value MUST contain the name of the method to invoke and can optionally contain the priority of the listener (as shown in the before listener in the example).

  1. use GuzzleHttp\Event\EmitterInterface;
  2. use GuzzleHttp\Event\SubscriberInterface;
  3. use GuzzleHttp\Event\BeforeEvent;
  4. use GuzzleHttp\Event\CompleteEvent;
  6. class SimpleSubscriber implements SubscriberInterface
  7. {
  8.     public function getEvents()
  9.     {
  10.         return [
  11.             // Provide name and optional priority
  12.             'before'   => ['onBefore', 100],
  13.             'complete' => ['onComplete'],
  14.             // You can pass a list of listeners with different priorities
  15.             'error'    => [['beforeError', 'first'], ['afterError', 'last']]
  16.         ];
  17.     }
  19.     public function onBefore(BeforeEvent $event, $name)
  20.     {
  21.         echo 'Before!';
  22.     }
  24.     public function onComplete(CompleteEvent $event, $name)
  25.     {
  26.         echo 'Complete!';
  27.     }
  28. }

To register the listeners the subscriber needs to be attached to the emitter:

  1. $client = new GuzzleHttp\Client();
  2. $emitter = $client->getEmitter();
  3. $subscriber = new SimpleSubscriber();
  4. $emitter->attach($subscriber);
  6. //to remove the listeners
  7. $emitter->detach($subscriber);

Note

You can specify event priorities using integers or "first" and "last" to dynamically determine the priority.

Event Priorities

When adding event listeners or subscribers, you can provide an optional event priority. This priority is used to determine how early or late a listener is triggered. Specifying the correct priority is an important aspect of ensuring a listener behaves as expected. For example, if you wanted to ensure that cookies associated with a redirect were added to a cookie jar, you’d need to make sure that the listener that collects the cookies is triggered before the listener that performs the redirect.

In order to help make the process of determining the correct event priority of a listener easier, Guzzle provides several pre-determined named event priorities. These priorities are exposed as constants on the GuzzleHttp\Event\RequestEvents object.

last

Use "last" as an event priority to set the priority to the current lowest event priority minus one.

first

Use "first" as an event priority to set the priority to the current highest priority plus one.

GuzzleHttp\Event\RequestEvents::EARLY

Used when you want a listener to be triggered as early as possible in the event chain.

GuzzleHttp\Event\RequestEvents::LATE

Used when you want a listener to be to be triggered as late as possible in the event chain.

GuzzleHttp\Event\RequestEvents::PREPARE_REQUEST

Used when you want a listener to be trigger while a request is being prepared during the before event. This event priority is used by the GuzzleHttp\Subscriber\Prepare event subscriber which is responsible for guessing a Content-Type, Content-Length, and Expect header of a request. You should subscribe after this event is triggered if you want to ensure that this subscriber has already been triggered.

GuzzleHttp\Event\RequestEvents::SIGN_REQUEST

Used when you want a listener to be triggered when a request is about to be signed. Any listener triggered at this point should expect that the request object will no longer be mutated. If you are implementing a custom signature subscriber, then you should use this event priority to sign requests.

GuzzleHttp\Event\RequestEvents::VERIFY_RESPONSE

Used when you want a listener to be triggered when a response is being validated during the complete event. The GuzzleHttp\Subscriber\HttpError event subscriber uses this event priority to check if an exception should be thrown due to a 4xx or 5xx level response status code. If you are doing any kind of verification of a response during the complete event, it should happen at this priority.

GuzzleHttp\Event\RequestEvents::REDIRECT_RESPONSE

Used when you want a listener to be triggered when a response is being redirected during the complete event. The GuzzleHttp\Subscriber\Redirect event subscriber uses this event priority when performing redirects.

You can use the above event priorities as a guideline for determining the priority of you event listeners. You can use these constants and add to or subtract from them to ensure that a listener happens before or after the named priority.

Note

“first” and “last” priorities are not adjusted after they added to an emitter. For example, if you add a listener with a priority of “first”, you can still add subsequent listeners with a higher priority which would be triggered before the listener added with a priority of “first”.

Working With Request Events

Requests emit lifecycle events when they are transferred.

Important

Excluding the end event, request lifecycle events may be triggered multiple times due to redirects, retries, or reusing a request multiple times. Use the once() method want the event to be triggered once. You can also remove an event listener from an emitter by using the emitter which is provided to the listener.

before

The before event is emitted before a request is sent. The event emitted is a GuzzleHttp\Event\BeforeEvent.

  1. use GuzzleHttp\Client;
  2. use GuzzleHttp\Event\EmitterInterface;
  3. use GuzzleHttp\Event\BeforeEvent;
  5. $client = new Client(['base_url' => 'http://httpbin.org']);
  6. $request = $client->createRequest('GET', '/');
  7. $request->getEmitter()->on(
  8.     'before',
  9.     function (BeforeEvent $e, $name) {
  10.         echo $name . "\n";
  11.         // "before"
  12.         echo $e->getRequest()->getMethod() . "\n";
  13.         // "GET" / "POST" / "PUT" / etc.
  14.         echo get_class($e->getClient());
  15.         // "GuzzleHttp\Client"
  16.     }
  17. );

You can intercept a request with a response before the request is sent over the wire. The intercept() method of the BeforeEvent accepts a GuzzleHttp\Message\ResponseInterface. Intercepting the event will prevent the request from being sent over the wire and stops the propagation of the before event, preventing subsequent event listeners from being invoked.

  1. use GuzzleHttp\Client;
  2. use GuzzleHttp\Event\BeforeEvent;
  3. use GuzzleHttp\Message\Response;
  5. $client = new Client(['base_url' => 'http://httpbin.org']);
  6. $request = $client->createRequest('GET', '/status/500');
  7. $request->getEmitter()->on('before', function (BeforeEvent $e) {
  8.     $response = new Response(200);
  9.     $e->intercept($response);
  10. });
  12. $response = $client->send($request);
  13. echo $response->getStatusCode();
  14. // 200

Attention

Any exception encountered while executing the before event will trigger the error event of a request.

complete

The complete event is emitted after a transaction completes and an entire response has been received. The event is a GuzzleHttp\Event\CompleteEvent.

You can intercept the complete event with a different response if needed using the intercept() method of the event. This can be useful, for example, for changing the response for caching.

  1. use GuzzleHttp\Client;
  2. use GuzzleHttp\Event\CompleteEvent;
  3. use GuzzleHttp\Message\Response;
  5. $client = new Client(['base_url' => 'http://httpbin.org']);
  6. $request = $client->createRequest('GET', '/status/302');
  7. $cachedResponse = new Response(200);
  9. $request->getEmitter()->on(
  10.     'complete',
  11.     function (CompleteEvent $e) use ($cachedResponse) {
  12.         if ($e->getResponse()->getStatusCode() == 302) {
  13.             // Intercept the original transaction with the new response
  14.             $e->intercept($cachedResponse);
  15.         }
  16.     }
  17. );
  19. $response = $client->send($request);
  20. echo $response->getStatusCode();
  21. // 200

Attention

Any GuzzleHttp\Exception\RequestException encountered while executing the complete event will trigger the error event of a request.

error

The error event is emitted when a request fails (whether it’s from a networking error or an HTTP protocol error). The event emitted is a GuzzleHttp\Event\ErrorEvent.

This event is useful for retrying failed requests. Here’s an example of retrying failed basic auth requests by re-sending the original request with a username and password.

  1. use GuzzleHttp\Client;
  2. use GuzzleHttp\Event\ErrorEvent;
  4. $client = new Client(['base_url' => 'http://httpbin.org']);
  5. $request = $client->createRequest('GET', '/basic-auth/foo/bar');
  6. $request->getEmitter()->on('error', function (ErrorEvent $e) {
  7.     if ($e->getResponse()->getStatusCode() == 401) {
  8.         // Add authentication stuff as needed and retry the request
  9.         $e->getRequest()->setHeader('Authorization', 'Basic ' . base64_encode('foo:bar'));
  10.         // Get the client of the event and retry the request
  11.         $newResponse = $e->getClient()->send($e->getRequest());
  12.         // Intercept the original transaction with the new response
  13.         $e->intercept($newResponse);
  14.     }
  15. });

Attention

If an error event is intercepted with a response, then the complete event of a request is triggered. If the complete event fails, then the error event is triggered once again.

progress

The progress event is emitted when data is uploaded or downloaded. The event emitted is a GuzzleHttp\Event\ProgressEvent.

You can access the emitted progress values using the corresponding public properties of the event object:

  • $downloadSize: The number of bytes that will be downloaded (if known)
  • $downloaded: The number of bytes that have been downloaded
  • $uploadSize: The number of bytes that will be uploaded (if known)
  • $uploaded: The number of bytes that have been uploaded

This event cannot be intercepted.

  1. use GuzzleHttp\Client;
  2. use GuzzleHttp\Event\ProgressEvent;
  4. $client = new Client(['base_url' => 'http://httpbin.org']);
  5. $request = $client->createRequest('PUT', '/put', [
  6.     'body' => str_repeat('.', 100000)
  7. ]);
  9. $request->getEmitter()->on('progress', function (ProgressEvent $e) {
  10.     echo 'Downloaded ' . $e->downloaded . ' of ' . $e->downloadSize . ' '
  11.         . 'Uploaded ' . $e->uploaded . ' of ' . $e->uploadSize . "\r";
  12. });
  14. $client->send($request);
  15. echo "\n";

end

The end event is a terminal event, emitted once per request, that provides access to the response that was received or the exception that was encountered. The event emitted is a GuzzleHttp\Event\EndEvent.

This event can be intercepted, but keep in mind that the complete event will not fire after intercepting this event.

  1. use GuzzleHttp\Client;
  2. use GuzzleHttp\Event\EndEvent;
  4. $client = new Client(['base_url' => 'http://httpbin.org']);
  5. $request = $client->createRequest('PUT', '/put', [
  6.     'body' => str_repeat('.', 100000)
  7. ]);
  9. $request->getEmitter()->on('end', function (EndEvent $e) {
  10.     if ($e->getException()) {
  11.         echo 'Error: ' . $e->getException()->getMessage();
  12.     } else {
  13.         echo 'Response: ' . $e->getResponse();
  14.     }
  15. });
  17. $client->send($request);
  18. echo "\n";