Events
Masonite Events is a simple to use integration for subscribing to events. These events can be placed throughout your application and triggered when various actions occur. For example you may want to do several actions when a user signs up like:
- Send an email
- Subscribe to MailChimp
- Update a section of your database
These actions can all be executed with a single line of code in you controller once you have setup your listeners
First we'll need to install the package using pip:
$ pip install masonite-events
Once installed we'll need to add the provider to our providers list:
config/providers.py
from events.providers import EventProvider
...
PROVIDERS = [
...
EventProvider,
...
]
This Service Provider will add a new
event:listener
command we can use to create new events. We'll walk through step by step on how to create one below.Masonite Events allows you to subscribe to arbitrary event actions with various event listeners. In this article we will walk through the steps on setting up listeners for a new user subscribing to our application.
We can create our event listener by executing the following command:
$ craft event:listener SubscribeUser
This will create a new event in the app/events directory that looks like this:
""" A SubscribeUser Event """
from events import Event
class SubscribeUser(Event):
""" SubscribeUser Event Class """
subscribe = []
def __init__(self):
""" Event Class Constructor """
pass
def handle(self):
""" Event Handle Method """
pass
This is a very simple class. We have the
__init__
method which is resolved by the container and we have a handle
method, also resolved by the container.This means that we can use syntax like:
from masonite.request import Request
...
def __init__(self, request: Request):
""" Event Class Constructor """
self.request = request
...
The subscribe attribute can be used as a shorthand later which we will see but it should be a list of events we want to subscribe to:
""" A SubscribeUser Event """
from events import Event
from package.action import SomeAction
class SubscribeUser(Event):
""" SubscribeUser Event Class """
subscribe = ['user.subscribed', SomeAction]
def __init__(self):
""" Event Class Constructor """
pass
def handle(self):
""" Event Handle Method """
pass
We can listen to events simply by passing the listener into one of your applications Service Provider's boot methods. Preferably this Service Provider should have
wsgi=False
so that you are not continuously subscribing the same listener on every request.You likely have a Service Provider whose wsgi attribute is false but let's create a new one:
$ craft provider ListenerProvider
Make sure we set the wsgi attribute to False:
''' A ListenerProvider Service Provider '''
from masonite.provider import ServiceProvider
class ListenerProvider(ServiceProvider):
wsgi = False
def register(self):
pass
def boot(self):
pass
Now we can import our listener and add it to our boot method:
''' A ListenerProvider Service Provider '''
from masonite.provider import ServiceProvider
from app.events.SubscribeUser.SubscribeUser
from events import Event
class ListenerProvider(ServiceProvider):
wsgi = False
def register(self):
pass
def boot(self, event: Event):
event.subscribe(SubsribeUser)
This is the recommended approach over the more manual approach found below but both options are available if you find a need for one over the other.
Since we have a subscribe attribute on our listener, we can simply pass the action into the subscribe method. This will subscribe our listener to the
SomeAction
and the user.subscribed
action that we specified in the subscribe
attribute of our listener class.If we don't specify the actions in the subscribe attribute, we can manually subscribe them using the listen method in our Service Provider's boot method:
''' A ListenerProvider Service Provider '''
from masonite.provider import ServiceProvider
from app.events.SubscribeUser.SubscribeUser
from events import Event
class ListenerProvider(ServiceProvider):
wsgi = False
def register(self):
pass
def boot(self, event: Event):
event.listen('user.subscribed', [SubsribeUser])
Ensure that the second parameter in the listen method is a list; even if it has only a single value
Now that we have events that are being listened to, we can start firing events. There are two ways to fire events. We can do both in any part of our application but we will go over how to do so in a controller method.
from events import Event
...
def show(self, event: Event):
event.fire('user.subscribed')
Masonite Events also comes with a new builtin helper method:
def show(self):
event('user.subscribed')
Both of these methods will fire all our listeners that are listening to the
user.subscribed
event action.As noted briefly above, we can subscribe to classes as events:
from package.action import SomeAction
def show(self):
event(SomeAction)
This will go through the same steps as an event subscribed with a string above.
We can also fire events using an * wildcard action:
def show(self):
event('user.*')
This will fire events such as
user.subscribed
, user.created
, user.deleted
.We can also fire events with an asterisk in the front:
def show(self):
event('*.created')
This will fire events such as
user.created
, dashboard.created
and manager.created
.We can also fire events with a wildcard in the middle:
def show(self):
event('user.*.created')
This will fire events such as
user.manager.created
, user.employee.created
and user.friend.created
.Sometimes you will want to pass an argument from your controller (or wherever you are calling your code) to your event's
handle
method. In this case you can simply pass keyword arguments to your fire
method like so:def show(self, event: Event):
event.fire('user.subscribed', to='[email protected]', active='True')
and you can fetch these values in your
handle
method using the argument
method:class SubscribeUser(Event):
""" SubscribeUser Event Class """
subscribe = ['user.subscribed', SomeAction]
def __init__(self):
""" Event Class Constructor """
pass
def handle(self):
""" Event Handle Method """
self.argument('to') # [email protected]
self.argument('active') # True
Last modified 5yr ago