[7.x] Improve event subscribers

[imanghafoori1]

This allows the event subscribers to return an array like the $listen property on the EventsServiceProvider
In fact, it introduces some syntactic sugar, by removing $events->listen(

also improves the doc-block of the public interface.

The example in laravel documentation:

    public function subscribe($events)
    {
        $events->listen(
            'App\Events\UserLoggedIn',
            'App\Listeners\UserEventListener@onUserLogin'
        );

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

Can be refactored to:

    public function subscribe()
    {
         return [
            'App\Events\UserLoggedIn' => ['App\Listeners\UserEventListener@onUserLogin'],
            'App\Events\UserLoggedOut' =>  ['App\Listeners\UserEventListener@onUserLogout']
         ];
    }

This is mostly backward compatible except in case someone returns a sequential array from the subscriber for no reason.
(It is possible to make is fully backward compatible by checking the array is assoc but it has performance hit, in the boot phase.)

• If accepted I add the needed tests and documentation
• This introduces a little bit of code duplication from EventServiceProvider.php which can be refactored if accepted.
  (the two nested foreach loops are copy/pasted)
  

  framework/src/Illuminate/Foundation/Support/Providers/EventServiceProvider.php

  Line 34 in 192356b

  foreach ($events as $event => $listeners) {

[GrahamCampbell]

👎 for the array_unique

[imanghafoori1]

framework/src/Illuminate/Foundation/Support/Providers/EventServiceProvider.php

Line 34 in 192356b

foreach ($events as $event => $listeners) {

this is copied from the above link, I kept it an exact copy, in case you want to extract the logic into a single method, to be reused.
If it is to be removed, better to be removed from both places.

[taylorotwell]

It is in the service provider for a different reason. It is not needed here. I will remove it.