Event Handling

webman/event provides a sophisticated event mechanism that allows executing some business logic without code intrusion, achieving decoupling between business modules. A typical scenario is when a new user registers successfully; by simply publishing a custom event like user.register, each module can receive this event and execute the corresponding business logic.

Installation

composer require webman/event

Subscribing to Events

Event subscriptions are configured uniformly through the file config/event.php

<?php
return [
    'user.register' => [
        [app\event\User::class, 'register'],
        // ...other event handling functions...
    ],
    'user.logout' => [
        [app\event\User::class, 'logout'],
        // ...other event handling functions...
    ]
];

Note:

• user.register, user.logout, etc., are event names, of string type, recommended to be lowercase words separated by dots (.)
• An event can correspond to multiple event handling functions, and the calling order is based on the configuration order

Event Handling Functions

Event handling functions can be any class method, function, closure, etc.
For example, create the event handling class app/event/User.php (please create the directory if it doesn't exist)

<?php
namespace app\event;
class User
{
    function register($user)
    {
        var_export($user);
    }

    function logout($user)
    {
        var_export($user);
    }
}

Publishing Events

Use Event::dispatch($event_name, $data); or Event::emit($event_name, $data); to publish events, for example

<?php
namespace app\controller;
use support\Request;
use Webman\Event\Event;
class User
{
    public function register(Request $request)
    {
        $user = [
            'name' => 'webman',
            'age' => 2
        ];
        Event::dispatch('user.register', $user);
    }
}

There are two functions for publishing events, Event::dispatch($event_name, $data); and Event::emit($event_name, $data);, with the same parameters.
The difference is that emit will automatically catch exceptions internally, meaning that if an event has multiple handling functions, an exception in one handling function will not affect the execution of other handling functions.
In contrast, dispatch will not catch exceptions automatically; if any handling function of the current event throws an exception, it will stop executing the next handling function and directly throw the exception upward.

Tip
The parameter $data can be any data, such as an array, class instance, string, etc.

Wildcard Event Listening

Wildcard registration allows you to handle multiple events on the same listener. For example, configure in config/event.php

<?php
return [
    'user.*' => [
        [app\event\User::class, 'deal']
    ],
];

We can obtain the specific event name through the second parameter $event_data of the event handling function

<?php
namespace app\event;
class User
{
    function deal($user, $event_name)
    {
        echo $event_name; // Specific event name, such as user.register, user.logout, etc.
        var_export($user);
    }
}

Stopping Event Broadcasting

When we return false in the event handling function, the event will stop broadcasting.

Closure Functions Handling Events

Event handling functions can be class methods or closure functions, for example

<?php
return [
    'user.login' => [
        function($user){
            var_dump($user);
        }
    ]
];

Viewing Events and Listeners

Use the command php webman event:list to view all events and listeners configured for the project.

Supported Scope

In addition to the main project's base plugins and application plugins, the event.php configuration is also supported.
Base plugin configuration file config/plugin/PluginVendor/PluginName/event.php
Application plugin configuration file plugin/PluginName/config/event.php

Precautions

Event handling is not asynchronous, and events are not suitable for processing slow business. Slow business should be handled using a message queue, for example, webman/redis-queue