events.md

Events

• Basic Usage
• Queued Event Handlers
• Event Subscribers

Basic Usage

The Laravel event facilities provides a simple observer implementation, allowing you to subscribe and listen for events in your application. Event classes are typically stored in the app/Events directory, while their handlers are stored in app/Handlers/Events.

You can generate a new event class using the Artisan CLI tool:

php artisan make:event PodcastWasPurchased

Subscribing To An Event

The EventServiceProvider included with your Laravel application provides a convenient place to register all event handlers. The listen property contains an array of all events (keys) and their handlers (values). Of course, you may add as many events to this array as your application requires. For example, let's add our PodcastWasPurchased event:

/**
 * The event handler mappings for the application.
 *
 * @var array
 */
protected $listen = [
	'App\Events\PodcastWasPurchased' => [
		'App\Handlers\Events\EmailPurchaseConfirmation',
	],
];

To generate a handler for an event, use the handler:event Artisan CLI command:

php artisan handler:event EmailPurchaseConfirmation --event=PodcastWasPurchased

Of course, manually running the make:event and handler:event commands each time you need a handler or event is cumbersome. Instead, simply add handlers and events to your EventServiceProvider and use the event:generate command. This command will generate any events or handlers that are listed in your EventServiceProvider:

php artisan event:generate

Firing An Event

Now we are ready to fire our event using the Event facade:

$response = Event::fire(new PodcastWasPurchased($podcast));

The fire method returns an array of responses that you can use to control what happens next in your application.

You may also use the event helper to fire an event:

event(new PodcastWasPurchased($podcast));

Closure Listeners

You can even listen to events without creating a separate handler class at all. For example, in the boot method of your EventServiceProvider, you could do the following:

Event::listen('App\Events\PodcastWasPurchased', function($event)
{
	// Handle the event...
});

Stopping The Propagation Of An Event

Sometimes, you may wish to stop the propagation of an event to other listeners. You may do so using by returning false from your handler:

Event::listen('App\Events\PodcastWasPurchased', function($event)
{
	// Handle the event...

	return false;
});

Queued Event Handlers

Need to queue an event handler? It couldn't be any easier. When generating the handler, simply use the --queued flag:

php artisan handler:event SendPurchaseConfirmation --event=PodcastWasPurchased --queued

This will generate a handler class that implements the Illuminate\Contracts\Queue\ShouldBeQueued interface. That's it! Now when this handler is called for an event, it will be queued automatically by the event dispatcher.

If no exceptions are thrown when the handler is executed by the queue, the queued job will be deleted automatically after it has processed. If you need to access the queued job's delete and release methods manually, you may do so. The Illuminate\Queue\InteractsWithQueue trait, which is included by default on queued handlers, gives you access to these methods:

public function handle(PodcastWasPurchased $event)
{
	if (true)
	{
		$this->release(30);
	}
}

If you have an existing handler that you would like to convert to a queued handler, simply add the ShouldBeQueued interface to the class manually.

Event Subscribers

Defining An Event Subscriber

Event subscribers are classes that may subscribe to multiple events from within the class itself. Subscribers should define a subscribe method, which will be passed an event dispatcher instance:

class UserEventHandler {

	/**
	 * Handle user login events.
	 */
	public function onUserLogin($event)
	{
		//
	}

	/**
	 * Handle user logout events.
	 */
	public function onUserLogout($event)
	{
		//
	}

	/**
	 * Register the listeners for the subscriber.
	 *
	 * @param  Illuminate\Events\Dispatcher  $events
	 * @return void
	 */
	public function subscribe($events)
	{
		$events->listen('App\Events\UserLoggedIn', 'UserEventHandler@onUserLogin');

		$events->listen('App\Events\UserLoggedOut', 'UserEventHandler@onUserLogout');
	}

}

Registering An Event Subscriber

Once the subscriber has been defined, it may be registered with the Event class.

$subscriber = new UserEventHandler;

Event::subscribe($subscriber);

You may also use the service container to resolve your subscriber. To do so, simply pass the name of your subscriber to the subscribe method:

Event::subscribe('UserEventHandler');