events.md

Events

Masonite ships with a "pub and sub" style events feature that allows you to subscirbe to various events and run listeners, or additional logic, when those events get emitted.

Creating an Event

The first step in events is creating an event to listen to.

Events are simple classes that you can create wherever you like:

$ python craft event UserAdded

This will create a simple class we can later emit.

You can also fire events without an Event class. The event will just be a specific key you can listen to.

Creating A Listener

The listener will run the logic when the event is emitted. You can create as many listeners as you like and register as many listeners to events as you need to.

To create a listener simply run the command:

$ python craft listener WelcomeEmail

This will create a class like this:

class WelcomeEmail:
    def handle(self, event):
        pass

Handle Method

The handle method will run when the listener runs. It will pass the event as the first parameter and any additional arguments that are emitted from the event as additional parameters.

Registering Events and Listeners

After your events and listeners are created you will need to register them to the event class.

You can do this via the AppProvider or a Service Provider you will create yourself:

class EventsProvider(Provider):
    def register(self):
        self.application.make('event').listen(UserAddedEvent, [WelcomeListener])

You can also listen to events without Event classes:

class EventsProvider(Provider):
    def register(self):
        self.application.make('event').listen("users.added", [WelcomeListener])

Using event strings allow to use wildcard event listening. For example if the application is emitting multiple events related to users such as users.added, users.updated and users.deleted you can listen to all of those events at once:

event.listen("users.*", [UsersListener])

Firing Events

To fire an event with an event class you can use the fire method from the Event class:

from app.events import UserAddedEvent
from masonite.events import Event

class RegisterController:
    def register(self, event: Event):
        # Register user
        event.fire(UserAddedEvent)

To fire a simple event without a class you will use the same method:

from app.events import UserAddedEvent
from masonite.events import Event

class RegisterController:
    def register(self, event: Event):
        # ...
        # Register user
        event.fire("users.added", user)

Building a Welcome Email Listener

As an example, to build a listener that sends an email:

First, create the listener:

$ python craft listener WelcomeEmail

Then we can build out the listener.

To send an email we will need to import the mailable class and send the email using the mail key from the container:

from app.mailables.WelcomeMailable import WelcomeMailable

class WelcomeEmail:
  def handle(self, event):
    from wsgi import application

    application.make("mail").send(
      WelcomeMailable().to('idmann509@gmail.com')
    )

You can then register the event inside the provider:

class EventsProvider(Provider):
    def register(self):
        self.application.make('event').listen(UserAddedEvent, [WelcomeListener])

When you emit the UserAdded event inside the controller, or somewhere else in the project, it will now send this email out.

You can register as many listeners to the events as you like by simply adding more listeners to the list.