Extending plugins
Extending with events
The Event service is the primary way to inject or modify the functionality of core classes or other plugins. This service can be imported for use in any class by adding use Event; to the top of your PHP file (after the namespace statement) to import the Event facade.
Subscribing to events
The most common place to subscribe to an event is the boot method of a Plugin registration file. For example, when a user is first registered you might want to add them to a third party mailing list, this could be achieved by subscribing to a winter.user.register global event.
public function boot()
{
Event::listen('winter.user.register', function ($user) {
// Code to register $user->email to mailing list
});
}
The same can be achieved by extending the model's constructor and using a local event.
User::extend(function ($model) {
$model->bindEvent('user.register', function () use ($model) {
// Code to register $model->email to mailing list
});
});
If you need to access protected or private methods when extending the model's constructor, you may pass true as the second parameter for the extend() method to force your code to act in the scope of the model.
User::extend(function ($model) {
if ($model->privateProperty === true) {
$model->bindEvent('user.register', function () use ($model) {
// Code to register $model->email to mailing list
});
}
}, true);
Declaring / Firing events
You can fire events globally (through the Event service) or locally.
Local events are fired by calling fireEvent() on an instance of an object that implements Winter\Storm\Support\Traits\Emitter. Since local events are only fired on a specific object instance, it is not required to namespace them as it is less likely that a given project would have multiple events with the same name being fired on the same objects within a local context.
$this->fireEvent('post.beforePost', [$firstParam, $secondParam]);
Global events are fired by calling Event::fire(). As these events are global across the entire application, it is best practice to namespace them by including the vendor information in the name of the event. If your plugin Author is ACME and the plugin name is Blog, then any global events provided by the ACME.Blog plugin should be prefixed with acme.blog.
Event::fire('acme.blog.post.beforePost', [$firstParam, $secondParam]);
If both global & local events are provided at the same place it's best practice to fire the local event before the global event so that the local event takes priority. Additionally, the global event should provide the object instance that the local event was fired on as the first parameter.
$this->fireEvent('post.beforePost', [$firstParam, $secondParam]);
Event::fire('winter.blog.beforePost', [$this, $firstParam, $secondParam]);
Once this event has been subscribed to, the parameters are available in the handler method. For example:
// Global
Event::listen('acme.blog.post.beforePost', function ($post, $param1, $param2) {
Log::info($post->name . 'posted. Parameters: ' . $param1 . ' ' . $param2);
});
// Local
$post->bindEvent('post.beforePost', function ($param1, $param2) use ($post) {
Log::info($post->name . 'posted. Parameters: ' . $param1 . ' ' . $param2);
});
Extending backend views
Sometimes you may wish to allow a backend view file or partial to be extended, such as a toolbar. This is possible using the fireViewEvent method found in all backend controllers.
Place this code in your view file:
<div class="footer-area-extension">
<?= $this->fireViewEvent('backend.auth.extendSigninView', [$firstParam]) ?>
</div>
This will allow other plugins to inject HTML to this area by hooking the event and returning the desired markup.
Event::listen('backend.auth.extendSigninView', function ($controller, $firstParam) {
return '<a href="#">Sign in with Google!</a>';
});
NOTE: The first parameter in the event handler will always be the calling object (the controller).
The above example would output the following markup:
<div class="footer-area-extension">
<a href="#">Sign in with Google!</a>
</div>
Usage examples
These are some practical examples of how events can be used.
Extending a User model
This example will modify the model.getAttribute event of the User model by binding to its local event. This is carried out inside the boot method of the Plugin registration file. In both cases, when the $model->foo attribute is accessed it will return the value bar.
class Plugin extends PluginBase
{
[...]
public function boot()
{
// Local event hook that affects all users
User::extend(function ($model) {
$model->bindEvent('model.getAttribute', function ($attribute, $value) {
if ($attribute === 'foo') {
return 'bar';
}
});
});
// Double event hook that affects user #2 only
User::extend(function ($model) {
$model->bindEvent('model.afterFetch', function () use ($model) {
if ($model->id !== 2) {
return;
}
$model->bindEvent('model.getAttribute', function ($attribute, $value) {
if ($attribute === 'foo') {
return 'bar';
}
});
});
});
}
}
Extending backend forms
There are a number of ways to extend backend forms.
This example will listen to the backend.form.extendFields global event of the Backend\Widget\Form widget and inject some extra fields when the Form widget is being used to modify a user. This event is also subscribed inside the boot method of the Plugin registration file.
class Plugin extends PluginBase
{
[...]
public function boot()
{
// Extend all backend form usage
Event::listen('backend.form.extendFields', function ($widget) {
// Only apply this listener when the Users controller is being used
if (!$widget->getController() instanceof \Winter\User\Controllers\Users) {
return;
}
// Only apply this listener when the User model is being modified
if (!$widget->model instanceof \Winter\User\Models\User) {
return;
}
// Only apply this listener when the Form widget in question is a root-level
// Form widget (not a repeater, nestedform, etc)
if ($widget->isNested) {
return;
}
// Add an extra birthday field
$widget->addFields([
'birthday' => [
'label' => 'Birthday',
'comment' => 'Select the users birthday',
'type' => 'datepicker'
]
]);
// Remove a Surname field
$widget->removeField('surname');
});
}
}
NOTE: In some cases (adding fields that should be made translatable by Winter.Translate for example), you may want to extend the
backend.form.extendFieldsBeforeevent instead.
Extending a backend list
This example will modify the backend.list.extendColumns global event of the Backend\Widget\Lists class and inject some extra columns values under the conditions that the list is being used to modify a user. This event is also subscribed inside the boot method of the Plugin registration file.
class Plugin extends PluginBase
{
[...]
public function boot()
{
// Extend all backend list usage
Event::listen('backend.list.extendColumns', function ($widget) {
// Only for the User controller
if (!$widget->getController() instanceof \Winter\User\Controllers\Users) {
return;
}
// Only for the User model
if (!$widget->model instanceof \Winter\User\Models\User) {
return;
}
// Add an extra birthday column
$widget->addColumns([
'birthday' => [
'label' => 'Birthday'
],
]);
// Remove a Surname column
$widget->removeColumn('surname');
});
}
}
Extending a component
This example will declare a new global event winter.forum.topic.post and local event called topic.post inside a Topic component. This is carried out in the Component class definition.
class Topic extends ComponentBase
{
public function onPost()
{
[...]
/*
* Extensibility
*/
$this->fireEvent('topic.post', [$post, $postUrl]);
Event::fire('winter.forum.topic.post', [$this, $post, $postUrl]);
}
}
Next this will demonstrate how to hook to this new event from inside the page execution life cycle. This will write to the trace log when the onPost event handler is called inside the Topic component (above).
[topic]
slug = "{{ :slug }}"
==
function onInit()
{
$this['topic']->bindEvent('topic.post', function ($post, $postUrl) {
trace_log('A post has been submitted at '.$postUrl);
});
}
Extending the backend menu
This example will replace the label for CMS and Pages in the backend with ....
class Plugin extends PluginBase
{
[...]
public function boot()
{
Event::listen('backend.menu.extendItems', function ($manager) {
$manager->addMainMenuItems('Winter.Cms', [
'cms' => [
'label' => '...'
]
]);
$manager->addSideMenuItems('Winter.Cms', 'cms', [
'pages' => [
'label' => '...'
]
]);
});
}
}
Similarly we can remove the menu items with the same event:
Event::listen('backend.menu.extendItems', function ($manager) {
$manager->removeMainMenuItem('Winter.Cms', 'cms');
$manager->removeSideMenuItem('Winter.Cms', 'cms', 'pages');
$manager->removeSideMenuItems('Winter.Cms', 'cms', [
'pages',
'partials'
]);
});