At Stormpath, we want to make it as easy as possible to create your application. Our Laravel Integration is no exception.

Events give developers an important tool to hook into different parts of a package to run your own business logic. Events can dramatically simplify application development, particularly when adding user functionality to a webapp.

A recent update to the Stormpath Laravel integration adds events fired by the built-in Laravel event system which your Laravel app can listen for and handle however you like, and use them to hook into user features like registration, login, logout, and more.

Let’s dive in to see how it works!

What Are Events?

An event in a programming language is a way to notify the developer of something that happened or is about to happen. This event can contain any kind of information, and a developer can program against that information.

One example of this is when a user signs up for your application. Without events, you must code everything related to the signup process. This can make your code very hard to maintain and very messy.

When you create a user signup event, you can trigger various sign-up related processes off that event. Things like sending an email to the user about signup, creating the user in the database, sending alerts to administration, and more.

Why Are Events Important?

There are many reasons why events are important. One of the main reasons is the single responsibility principle. Without events, your signup controller would be responsible for many different things during signup. When you fire an event, you can have handlers listen for them and handle what they need to. Doing so, allows you to not worry about what happens when a user signs up, but allows other parts of your application to handle it.

One of the other big advantages of using events is the flexibility of your code. When starting out with your application, there are some basics that you will want to include for a user registration. Later on, you may have some other business logic that you want to add to the process. With events, this is easy, you add a new process and attach it to the event. There is no need to go into the user registration code to add it there, cluttering up your controller.

What Events Stormpath Laravel Offers

At Stormpath, we want to give you the ability to have every aspect of the Laravel integration fire an event. Thanks to one of our community users of the Stormpath Laravel package, Kryten0807, we now offer events for every process.

The following events (and their corresponding classes) are triggered during Stormpath operations:

  • UserIsRegistering: A potential new user has completed the registration form and submitted it. The form data has passed validation. (cancellable)
  • UserHasRegistered: A new user has registered.
  • UserIsLoggingIn: A user has completed the login form and submitted it. The form data has passed the initial validation, but the user has not been authenticated yet. (cancellable)
  • UserHasLoggedIn: A user has successfully logged in.
  • UserIsLoggingOut: A user has visited the logout URL but has not been logged out yet. (cancellable)
  • UserHasLoggedOut: A user has successfully logged out.
  • UserHasRequestedPasswordReset: A user has completed the password reset form and the password reset email has been sent.
  • UserHasResetPassword: A user has successfully reset their password.

All of the above are the class names for the event and they live in the Stormpath\Laravel\Events namespace

Listening For Stormpath Laravel Events

Continuing with the examples from above of registering a user, lets say you have some business logic that needs to run before a user account is created. To do this, we offer the UserIsRegistering event. This event will be triggered before a user is created at Stormpath allowing you to run your business logic and stopping the registration if needed.
You will first need to register a listener for this event:

This can be placed in your EventServiceProvidrer file of your Laravel install. For more information about events and registering them, please visit the Laravel Documentation.

The file App\Listeners\handleNewUserIsRegistering is a class in your application which handles the event when it is fired. The listener class is defined according to the Laravel documentation on defining listeners.

Terminating Event Actions

There may be times when it is necessary to halt processing based on some processing you are doing in your listener. To do this, simply return false from the handle method of your listener. Note that this will only have an effect for the events that are marked as “cancellable” in the table above.

For example, maybe you want to prevent a user from registering if their first name is “Bob”. Your handler should look like this:

This will abort the registration request. When this is done, a Stormpath\Laravel\Exceptions\ActionAbortedException will be thrown. In the example above, you might catch that exception & redirect the user to a page that says “No Bobs Allowed!”

Try It Out

With the addition of the events in the Stormpath Laravel package, we have opened up a whole new way to work with the package, making it a much more flexible system that is also easier for you to work with.

For full documentation on the events that are used, visit our documentation page.

Let us know what you think of this addition. We love your feedback. You can contact us at [email protected] or hit us up on Twitter @goStormpath.

Like what you see? to keep up with the latest releases.