working on events

events.md

@@ -1,17 +1,21 @@
 # Events
 
+- [Introduction](#introduction)
 - [Registering Events / Listeners](#registering-events-and-listeners)
 - [Defining Events](#defining-events)
 - [Defining Listeners](#defining-listeners)
 - [Firing Events](#firing-events)
 - [Queued Event Listeners](#queued-event-listeners)
 - [Event Subscribers](#event-subscribers)
 
-<a name="registering-events-and-listeners"></a>
-## Registering Events / Listeners
+<a name="introduction"></a>
+## Introduction
 
 Laravel's events 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 listeners are stored in `app/Listeners`.
 
+<a name="registering-events-and-listeners"></a>
+## Registering Events / Listeners
+
 The `EventServiceProvider` included with your Laravel application provides a convenient place to register all event listeners. The `listen` property contains an array of all events (keys) and their listeners (values). Of course, you may add as many events to this array as your application requires. For example, let's add our `PodcastWasPurchased` event:
 
 	/**
@@ -27,14 +31,14 @@ The `EventServiceProvider` included with your Laravel application provides a con
 
 ### Generating Event / Listener Classes
 
-Of course, manually creating the files for each event and listener is cumbersome. Instead, simply add listeners and events to your `EventServiceProvider` and use the `event:generate` command. This command will generate any events or listeners that are listed in your `EventServiceProvider`:
+Of course, manually creating the files for each event and listener is cumbersome. Instead, simply add listeners and events to your `EventServiceProvider` and use the `event:generate` command. This command will generate any events or listeners that are listed in your `EventServiceProvider`. Of course, events and listeners that already exist will be left untouched:
 
 	php artisan event:generate
 
 <a name="defining-events"></a>
 ## Defining Events
 
-An event class is simply a data container which holds the information related to the event. For example, let's assume our generated `PodcastWasPurchased` event receives a `Podcast` [Eloquent ORM](/docs/{{version}}/eloquent) object:
+An event class is simply a data container which holds the information related to the event. For example, let's assume our generated `PodcastWasPurchased` event receives a [Eloquent ORM](/docs/{{version}}/eloquent) object:
 
 	<?php namespace App\Events;
 
@@ -65,7 +69,7 @@ As you can see, this event class contains no special logic. It is simply a conta
 <a name="defining-event-listeners"></a>
 ## Defining Event Listeners
 
-Next, let's take a look at the listener for our example event. Event listeners receive the event in their `handle` method. The `event:generate` command will automatically import the proper event class and type-hint the event on the `handle` method. Within the `handle` method, you may perform any logic necessary to respond to the event.
+Next, let's take a look at the listener for our example event. Event listeners receive the event instance in their `handle` method. The `event:generate` command will automatically import the proper event class and type-hint the event on the `handle` method. Within the `handle` method, you may perform any logic necessary to respond to the event.
 
 	<?php namespace App\Listeners;
 
@@ -113,7 +117,7 @@ Sometimes, you may wish to stop the propagation of an event to other listeners.
 <a name="firing-events"></a>
 ## Firing Events
 
-To fire an event, you may use the simple `Event` [facade](/docs/{{version}}/facades), passing the function an instance of the event to the `fire` method:
+To fire an event, you may use the `Event` [facade](/docs/{{version}}/facades), passing an instance of the event to the `fire` method. The `fire` method will dispatch the event to all of its registered listeners:
 
 	event(new PodcastWasPurchased($podcast));
 
@@ -143,18 +147,10 @@ To fire an event, you may use the simple `Event` [facade](/docs/{{version}}/faca
 		}
 	}
 
-Alternatively, you may use the `event` helper function to fire events:
+Alternatively, you may use the global `event` helper function to fire events:
 
 	event(new PodcastWasPurchased($podcast));
 
-#### Mocking Event Calls During Testing
-
-Frequently you will want to ignore all fired events while unit testing. You may do so using the `shouldReceive` method on the `Event` facade:
-
-	Event::shouldReceive('fire');
-
-> **Note:** For more information on unit testing, check out the [testing documentation](/docs/{{version}}/testing).
-
 <a name="queued-event-listeners"></a>
 ## Queued Event Listeners
 
@@ -171,13 +167,11 @@ Need to [queue](/docs/{{version}}/queues) an event listener? It couldn't be any
 		//
 	}
 
-That's it! Now, when this listener is called for an event, it will be queued automatically by the event dispatcher using Laravel's [queue system](/docs/{{version}}/queues).
-
-> **Note:** If no exceptions are thrown when the listener is executed by the queue, the queued job will automatically be deleted after it has processed.
+That's it! Now, when this listener is called for an event, it will be queued automatically by the event dispatcher using Laravel's [queue system](/docs/{{version}}/queues). If no exceptions are thrown when the listener is executed by the queue, the queued job will automatically be deleted after it has processed.
 
 #### Manually Accessing The Queue
 
-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 imported by default on generated listeners, gives you access to these methods:
+If you need to access the underlying queue job's `delete` and `release` methods manually, you may do so. The `Illuminate\Queue\InteractsWithQueue` trait, which is imported by default on generated listeners, gives you access to these methods:
 
 	<?php namespace App\Listeners;
 
@@ -191,7 +185,7 @@ If you need to access the queued job's `delete` and `release` methods manually,
 
 		public function handle(PodcastWasPurchased $event)
 		{
-			if (condition) {
+			if (true) {
 				$this->release(30);
 			}
 		}
@@ -200,9 +194,7 @@ If you need to access the queued job's `delete` and `release` methods manually,
 <a name="event-subscribers"></a>
 ## 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:
+Event subscribers are classes that may subscribe to multiple events from within the class itself, allowing you to define several event handlers within a single class. Subscribers should define a `subscribe` method, which will be passed an event dispatcher instance:
 
 	<?php namespace App\Listeners;
 
@@ -241,46 +233,7 @@ Event subscribers are classes that may subscribe to multiple events from within
 
 #### Registering An Event Subscriber
 
-Once the subscriber has been defined, it may be registered with the event dispatcher. A good place to perform this registration is the `boot` method of your `App\Providers\EventServiceProvider`, which already receives a dispatcher instance:
-
-	<?php namespace App\Providers;
-
-	use App\Listeners\UserEventListener;
-	use Illuminate\Contracts\Events\Dispatcher as DispatcherContract;
-	use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;
-
-	class EventServiceProvider extends ServiceProvider
-	{
-	    /**
-	     * The event listener mappings for the application.
-	     *
-	     * @var array
-	     */
-	    protected $listen = [
-	        'App\Events\PodcastWasPurchased' => [
-	            'App\Listeners\EmailPurchaseConfirmation',
-	        ],
-	    ];
-
-	    /**
-	     * Register any other events for your application.
-	     *
-	     * @param  \Illuminate\Contracts\Events\Dispatcher  $events
-	     * @return void
-	     */
-	    public function boot(DispatcherContract $events)
-	    {
-	        parent::boot($events);
-
-	        $events->subscribe(new UserEventListener);
-	    }
-	}
-
-You may also use the [service container](/docs/{{version}}/container) to resolve your subscriber. To do so, simply pass the name of your subscriber to the `subscribe` method:
-
-	$events->subscribe('App\Listeners\UserEventHandler');
-
-Alternatively, you may register subscribers using the `$subscribe` property on the `EventServiceProvider`. For example, let's add the `UserEventListener`.
+Once the subscriber has been defined, it may be registered with the event dispatcher. You may register subscribers using the `$subscribe` property on the `EventServiceProvider`. For example, let's add the `UserEventListener`.
 
     <?php namespace App\Providers;
 
@@ -306,15 +259,4 @@ Alternatively, you may register subscribers using the `$subscribe` property on t
         protected $subscribe = [
             'App\Listeners\UserEventListener',
         ];
-
-        /**
-         * Register any other events for your application.
-         *
-         * @param  \Illuminate\Contracts\Events\Dispatcher  $events
-         * @return void
-         */
-        public function boot(DispatcherContract $events)
-        {
-            parent::boot($events);
-        }
     }