[5.8] Event Discovery

[taylorotwell]

This PR provides automatic event / listener discovery.

Benefits

No longer necessary to manually register events and their listeners in the EventServiceProvider.

How It Works

Events and their listeners are discovered by reflecting into all listeners and inspecting all public handle methods or methods that begin with handle. We then can inspect the methods of those parameters to determine which events the listener is handling, allowing us to build an array of events / listeners that basically looks exactly like the manually built array that is currently configured in EventServiceProvider. We then merge the explicitly defined events on top of the discovered events and register everything with the event dispatcher.

Usage

Since I am adding this to the 5.8 release, automatic discovery is disabled by default. However, it may be enabled by overriding the shouldDiscoverEvents method on the EventServiceProvider. This function should return a boolean.

/**
 * Determine if events and listeners should be automatically discovered.
 *
 * @return bool
 */
public function shouldDiscoverEvents()
{
    return false;
}

If event discovery is enabled, discovered events are loaded in two ways.

1. Discovered events may be cached during deployment using the new event:cache command. If the framework finds an event cache file, the event / listener configuration will be loaded from that file. Note that any explicitly defined events / listeners in the EventServiceProvider will still be registered as well.

2. If no event cache file is found, the events / listeners will be discovered on-the-fly during the request. This is not recommended for production since it will be slightly slower; however, for local development it should be satisfactory. Of course, if someone has as unique application where this is too slow even in local development they can simply not use event discovery entirely and register all of their events as they would previously.

[nunomaduro]

No plans to merge.

[devcircus]

I really like this. I implemented cached and auto-discoverable "jobs/handlers" in a previous project. I was never happy with my implementation and removed it. May go back and revisit this now.

[misenhower]

Happy to see caching 👍, would be cool to have an event:list command to show the discovered mappings.

[browner12]

does this jive with the newly approved PSR-14?

https://www.php-fig.org/psr/psr-14/

[halaei]

Why methods that begin with handle? Why not just handle()

[patrickbrouwers]

Why methods that begin with handle? Why not just handle()

Will work for event subscribers as well then, I think. And for event listeners with multiple handlers in general (usually registered as Listener@handleSomeEvent)

[taylorotwell]

Why methods that begin with handle? Why not just handle()

I'm fine with removing this if people don't like it; however, I wondered if some people may listen to multiple events in one listener.

[devcircus]

I'm for allowing for methods that begin with "handle". This is a common pattern. I guess as long as that logic can be overridden in the service provider, then it's no big deal either way.

[edgarnadal]

Can this be customizable via a config on config/app.php? an also can this be an array of paths?

[halaei]

Can this be customizable via a config on config/app.php? an also can this be an array of paths?

It is now simple to override it in app\Providers\EventsServiceProvider.

[halaei]

This is listener discovery more than event discovery.

[nunomaduro]

I am not sure about this @throws \RuntimeException. When can it happen?

[halaei]

To have more configuration control, EventServiceProvider can initiate the discovery itself, just like what console kernel does with Commands directory:

public function listeners()
{
    $this->discover(app_path('Listeners'), 'handle*');
}

[erikgaal]

I think it makes more sense to remove the continue control flow and simplify the condition, like so:

foreach ($listener->getMethods(ReflectionMethod::IS_PUBLIC) as $method) {
    if (Str::is('handle*', $method->name) && isset($method->getParameters()[0])) {
        $listenerEvents[$listener->name.'@'.$method->name] = optional($method->getParameters([0]->getClass())->name;
    }
}

[knvpk]

What will happen for the below case mentioned. I have enabled auto discovery and for an event there are two listeners but I have mentioned one listener explicitly did the other listener will be discovered or ignored.

[taylorotwell]

To have more configuration control, EventServiceProvider can initiate the discovery itself, just like what console kernel does with Commands directory:

public function listeners()
{
    $this->discover(app_path('Listeners'), 'handle*');
}

@halaei What if it is called multiple times? What would the behavior be? How would caching work in this situation?

[halaei]

@halaei What if it is called multiple times? What would the behavior be? How would caching work in this situation?

I haven't think about it. Now that I see discoverEventsWithin() is in EventServiceProvider and it can return an array, I guess it is configurable after all.

[halaei]

shouldDiscoverEvents() is redundant because discoverEventsWithin() can return empty array. The non-empty array $this->app->path('Listeners') can be returned from App\Providers\EventServiceProvider and the feature can be enabled for new Laravel installations by default.

[driesvints]

You can use $this->app->basePath() here.

[TBlindaruk]

I`m not sure how. But I think w should try to cover this by tests;

[taylorotwell]

I will be writing tests.

[vicgonvt]

This is awesome. Thanks for that!

[tomirons]

Can someone explain how it knows the order of listeners? I've been trying to figure this out for a little while.

[erikgaal]

@tomirons, I don’t think you can specify or influence the order of the listeners. If you need a specific order, you should dispatch a new event from the “parent” listener.

[tomirons]

@erikgaal I did a quick test by creating an event Foo and two listeners in this order (Second, First). Sure enough, the order of the listeners was Second then First, so it must go by when the file was created?

[MichaelDeBoey]

@tomirons Just like @erikgaal (and @taylorotwell on Twitter) said: if you need to have an order/sequence, the first listener should dispatch a new event that the second listener can act on.

[tomirons]

@MichaelDeBoey This is what I thought was going to be said, it would be beneficial to just use the jobs at this point and chain them.

[driesvints]

@tomirons in general you shouldn't rely on the order of your listeners. If you need a specific sequence you should indeed use jobs and chain them.