One commonly used technique for manipulating existing processes or adding features in a custom module is the implementation of event handlers.
The most common core events used to manipulate existing features are described in the following guide.
Event handler configuration
Event handlers in HumHub modules are registered within the
events section of the config.php file.
It is recommended to implement the handler functions within a dedicated
Events.php file in the module root.
Some modules may use the
Module.php class for event handler implementations, this should only be considered for
simple and few event handlers in order to keep a clean module structure.
Example handler configuration
|The namespaced class string of the class responsible for triggering the event.|
|The event name, usually available as class const|
|Event handler callback class and function name|
When listening to a non core class event, use an actual string definition instead of an import with usage of
prevent errors when the required module is not enabled.
Example handler implementation
Depending on the triggered event, there are different types of events provided as event handler argument. Some of the most common event classes are listed in the following table.
|yii\base\Event||Base event class of Yii|
|yii\base\ModelEvent||Supports additional |
|yii\db\AfterSaveEvent||Event used for some ActiveRecord Events|
|yii\base\ActionEvent||Controller/Action related events|
|yii\base\WidgetEvent||Widget related events|
|yii\web\UserEvent||User identity related events|
|HumHub base event with additional |
|Used for user related events with additional |
|Events related to user following|
|Events related to user friendship|
|Events related to space memberships|
|Module related event with |
|ActiveQuery related events with additional |
|Custom modules may implement own event types|
Application events can be used to globally intercept requests and actions.
yii\base\Application provides the following events:
|Application::EVENT_BEFORE_ACTION||Raised before executing a controller action|
|Application::EVENT_AFTER_ACTION||Raised after executing a controller action|
|Application::EVENT_BEFORE_REQUEST||Raised before the application starts to handle a request|
|Application::EVENT_AFTER_REQUEST||Raised after the application successfully handles a request (before the response is sent out)|
humhub\components\console\Application additionally triggers the following event
|Raised at the end of |
|Raised before a module is enabled|
|Raised after a module is enabled|
|Raised before a module is disabled|
|Raised after a module is disabled|
humhub\components\ModuleEvent class provides the following additional properties and functions:
$moduleId: The moduleId of the module -
getModule(): Can be used to return a module instance
In the following example we use the
ModuleManager::EVENT_AFTER_MODULE_ENABLED to set a module setting of another module
right after the module is enabled.
humhub\modules\marketplace\components\OnlineModuleManager provides events triggered before and after a module was updated
by the marketplace.
|Raised before a module is updated|
|Raised after a module is updated|
Controller events can be used to intercept requests of web or console controller actions and manipulate the controller result.
|Controller::EVENT_AFTER_ACTION||Raised right after executing a controller action|
|Controller::EVENT_BEFORE_ACTION||Raised right before executing a controller action|
In the following example we listen to all web controller requests and redirect to a custom action in case some special condition is not met.
See Yii Controller Events for more information about the usage of Controller events.
Events of the
humhub\commands\CronController can be handled in order to implement scheduled tasks.
CronController::EVENT_BEFORE_ACTION in case you want to implement a custom scheduling interval.
Response events can be used to manipulate the server response.
|Response::EVENT_AFTER_PREPARE||Raised right after |
|Response::EVENT_AFTER_SEND||Raised at the end of |
|Response::EVENT_BEFORE_SEND||at the beginning of |
::info See Yii Response Events for more information. :::
The base Model class supports events useful to intercepting the validation of a model.
|Model::EVENT_BEFORE_VALIDATE||Raised at the beginning of |
|Model::EVENT_AFTER_VALIDATE||Raised at the end of |
In the following example we implement a handler for the
EVENT_BEFORE_VALIDATE of the
in order to intercept the registration process.
ActiveRecord (CRUD) Events
The ActiveRecord class supports additional events for intercepting CRUD related events. Those events are useful for manipulating model properties or synchronizing the creation/deletion of custom models with models of other modules.
|ActiveRecord::EVENT_AFTER_DELETE||Raised after a record is deleted|
|ActiveRecord::EVENT_AFTER_FIND||Raised after the record is created and populated with query result|
|ActiveRecord::EVENT_AFTER_INSERT||Raised after a record is inserted|
|ActiveRecord::EVENT_AFTER_REFRESH||Raised after a record is refreshed|
|ActiveRecord::EVENT_AFTER_UPDATE||Raised after a record is updated|
|ActiveRecord::EVENT_BEFORE_INSERT||Raised before inserting a record|
|ActiveRecord::EVENT_BEFORE_UPDATE||Raised before updating a record|
|ActiveRecord::EVENT_INIT||Raised when the record is initialized via |
Example use cases:
- Listen for
EVENT_BEFORE_DELETEevents of a specific record type in order to synchronize the creation or deletion of custom model relations
- Listen for
EVENT_BEFORE_SAVEto manipulate the properties of a model prior to persisting it to the database
- Listen for
EVENT_AFTER_FINDto manipulate model properties right after model queries.
See Yii ActiveRecord Events for more information about the usage of ActiveRecord events.
humhub\modules\user\model\User model provides the following additional events:
|Can be used to add conditions to |
|Raised after a soft deletion of a user model|
The following example adds an user visibility condition:
humhub\modules\user\components\ActiveQueryUser events may be used to add conditions
ActiveQueryUser::visible() (in addition to
This will manipulate the results of queries like:
|Raised within |
|Raised within |
In the following example we add an additional check to
ActiveQueryUser::visible() by checking a custom
user table field.
In this example the
user.is_visible_in_crm was added to the user table by our custom module.
humhub\modules\user\models\forms\Registration class provides events raised within the registration process:
|Raised after successful registration|
The following example shows how to synchronize the registration process with an external crm service.
User Follow Events
User follow events are triggered once a user follows or unfollows a content, space or another user by the
|Raised when a user follows a content/space/user|
|Raised when a user unfollows a content/space/user|
The following example sends out a custom
FollowAchievementNotification notification once the user reaches a certain amount of followers.
The notification is removed in case the follower decreases to lower thant 5.
User Friendship Events
Similar to the follow events, the friendship module triggers an events once a user friendship relation is created or
removed. The events are triggered by the
|Raised when a user makes a new friend|
|Raised when a user removes a friendship|
humhub\modules\friendship\FriendshipEvent class provides the following additional properties:
$user1: The user initiating the friendship -
$user2: The user who received the friendship request
Space membership events are triggered by the
humhub\modules\space\model\Membership model and can be used to trace the
creation or removal of space membership relations.
|Raised when a user joins a space or was added|
|Raised when a user leaves a space or was removed|
humhub\modules\space\model\Membership class provides the following additional properties:
humhub\modules\space\models\Spacemodel of the space -
$user: The respective user model of the membership relation
Widget events can be used to extend the output of a widget or even overwrite widget classes.
|Widget::EVENT_INIT||Raised when the widget is initialized via |
|Widget::EVENT_BEFORE_RUN||Raised right before executing a widget|
|Widget::EVENT_AFTER_RUN||Raised right after executing a widget|
|Raised before |
Extend widget output
Widget::EVENT_AFTER_RUN can be used to extend the output of a widget, as in the following example:
Prevent widget from rendering
Widget::EVENT_BEFORE_RUN can be used prevent widgets from rendering:
Overwrite a widget class
humhub\components\Widget::EVENT_CREATE can be used to overwrite the widget class.
Since the widget is created by a call to
Yii::createObject() the new widget class has to be compatible with the overwritten one,
which means it has to support all possible properties of the original widget class. This could be achieved by extending the original