Getting Started with Laravel Events and Listeners

Laravel's event system provides a simple observer implementation, allowing you to subscribe and listen for various events that occur in your application.

This can be particularly useful for decoupling various parts of your application's logic and not blocking the main request flow. Queued listeners can also be used to handle time-consuming tasks asynchronously, improving the performance of your application.

In this guide, we'll walk through the process of setting up and using Laravel Events and Listeners, with a focus on database operations using Neon Postgres.

Prerequisites

Before we begin, ensure you have the following:

PHP 8.1 or higher installed on your system
Composer for managing PHP dependencies
A Neon account for database hosting
Basic knowledge of Laravel and database operations

Setting up the Project

Let's start by creating a new Laravel project and setting up the necessary components. If you already have a Laravel project set up, you can skip this section.

Creating a New Laravel Project

Open your terminal and run the following command to create a new Laravel project:

composer create-project laravel/laravel laravel-events
cd laravel-events

This will create a new Laravel project in a directory named laravel-events with all the necessary dependencies installed.

Setting up the Database

Once you have your Laravel project set up, you'll need to configure your Neon database connection. If you don't have a Neon account, you can sign up here.

Update your .env file with your Neon database credentials:

DB_CONNECTION=pgsql
DB_HOST=your-neon-hostname.neon.tech
DB_PORT=5432
DB_DATABASE=your_database_name
DB_USERNAME=your_username
DB_PASSWORD=your_password

Make sure to replace your-neon-hostname, your_database_name, your_username, and your_password with your actual Neon database credentials.

Creating a Model and Migration

For this tutorial, let's create a simple Order model that we'll use to demonstrate events and listeners.

To create the model and migration, run the following command:

php artisan make:model Order -m

This command creates both the Order model and a migration file for the orders table.

Open the newly created migration file in database/migrations and update the up method with the following content:

public function up()
{
    Schema::create('orders', function (Blueprint $table) {
        $table->id();
        $table->string('customer_name');
        $table->decimal('total', 8, 2);
        $table->enum('status', ['pending', 'processing', 'completed', 'cancelled'])->default('pending');
        $table->timestamps();
    });
}

Run the migration to create the 'orders' table in your Neon database:

php artisan migrate

Next update the Order model in app/Models/Order.php to include the customer_name, total, and status to the $fillable property:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Order extends Model
{
    use HasFactory;

    protected $fillable = ['customer_name', 'total', 'status'];
}

As a reference, the $fillable property specifies which attributes are mass-assignable, meaning they can be set using the create method on the model. This helps protect against mass assignment vulnerabilities in your application.

Creating an Event

An event in Laravel is a simple class that represents something that has happened in your application. Events can be used to trigger actions or notify other parts of your application that something has occurred.

Now, let's create an event that will be triggered when an order is placed. Run the following command:

php artisan make:event OrderPlaced

This creates a new event class in app/Events/OrderPlaced.php. Update it with the following content:

<?php

namespace App\Events;

use App\Models\Order;
use Illuminate\Broadcasting\Channel;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Broadcasting\PresenceChannel;
use Illuminate\Broadcasting\PrivateChannel;
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class OrderPlaced
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    public $order;

    public function __construct(Order $order)
    {
        $this->order = $order;
    }
}

This event will carry the Order model instance, allowing listeners to access the order details. In a real application, you would perform additional actions, such as sending an email or updating other records in the database, when this event is triggered.

Creating a Listener

A listener in Laravel is a class that listens for a specific event and performs actions in response to that event.

Now that we have an event, let's create a listener that will respond to this event.

Run the following command to create a new listener:

php artisan make:listener SendOrderConfirmation --event=OrderPlaced

This creates a new listener in app/Listeners/SendOrderConfirmation.php. Update it with the following content:

<?php

namespace App\Listeners;

use App\Events\OrderPlaced;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Support\Facades\Log;

class SendOrderConfirmation implements ShouldQueue
{
    use InteractsWithQueue;

    public function handle(OrderPlaced $event)
    {
        // In a real application, you would send an email here
        Log::info('Order confirmation sent for Order #' . $event->order->id);

        // Additional actions related to order confirmation
        Log::info('Slack notification sent for Order #' . $event->order->id);
        Log::info('SMS notification sent for Order #' . $event->order->id);
        Log::info('Update inventory for Order #' . $event->order->id);
    }
}

A very important thing to note here is that we are implementing the ShouldQueue interface.

Here our listener implements the ShouldQueue interface, meaning it will be handled by Laravel's queue system, which is beneficial for performance when dealing with time-consuming tasks.

If we didn't implement the ShouldQueue interface, the listener would be executed synchronously, which could slow down the response time of your application but could be useful for certain use cases where you need to perform actions synchronously rather than asynchronously.

Here, we're simply logging a message to the Laravel log file, but in a real application, you would send an email along with other actions related to order confirmation, which could be time-consuming.

Registering the Event and Listener

Laravel 11.x and later versions automatically discover events and listeners, so you don't need to manually register them. If you are using an older version of Laravel, you can register your events and listeners in the EventServiceProvider.

For more information on registering events and listeners, refer to the Laravel documentation.

Dispatching the Event

Now that we have set up our event and listener, let's create a simple controller to simulate an order placement. This controller will handle order creation and dispatch our event.

Run the following command to create a new controller:

php artisan make:controller OrderController

Open app/Http/Controllers/OrderController.php and add the following content:

<?php

namespace App\Http\Controllers;

use App\Models\Order;
use App\Events\OrderPlaced;
use Illuminate\Http\Request;

class OrderController extends Controller
{
    public function store(Request $request)
    {
        $order = Order::create([
            'customer_name' => $request->customer_name,
            'total' => $request->total,
        ]);

        event(new OrderPlaced($order));

        return response()->json(['message' => 'Order placed successfully', 'order' => $order]);
    }
}

This controller creates a new order in the database and then dispatches the OrderPlaced event.

The event helper function is used to dispatch the event, passing the order instance to the event constructor.

This allows the listener to access the order details when the event is triggered rather than blocking the main request flow to perform the additional actions directly in the controller method itself.

We will use this controller to create a new order and trigger the event.

Adding a Route

To use our new controller, let's add a route. Open routes/api.php and add the following line:

Route::post('/orders', [App\Http\Controllers\OrderController::class, 'store']);

If you don't have a route file for API routes, you can create one by running the following command:

php artisan install:api

This will create a new api.php file in the routes directory.

Testing the Event System

Now, let's test our event system. You can use a tool like Postman or curl to send a POST request to your /api/orders endpoint.

Using curl:

curl -X POST http://laravel-events.test/api/orders \
     -H "Content-Type: application/json" \
     -d '{"customer_name":"John Doe","total":99.99}'

Replace laravel-events.test with your actual application URL.

If everything is set up correctly, you should see a new order in your Neon database, but you won't see any log messages in your Laravel log file yet because the listener is queued and we haven't run the queue worker to process the queued jobs.

Running Queued Jobs

As we mentioned earlier, the SendOrderConfirmation listener implements the ShouldQueue interface, meaning it will be handled by Laravel's queue system.

If you were to check your logs immediately after placing an order, you might not see the log messages from the listener. Instead, you can run the queue worker to process the queued jobs:

php artisan queue:work

This command starts the queue worker, which will process any queued jobs, including the order confirmation listener.

Once the queue worker is running, you should see the log messages from the listener and the following output:

$ php artisan queue:work

   INFO  Processing jobs from the [default] queue.

   App\Listeners\SendOrderConfirmation ....... RUNNING
   App\Listeners\SendOrderConfirmation ....... 1s DONE

In a different terminal window, you can place a new order using curl or Postman to see the listener in action.

If you were to remove the ShouldQueue interface from the listener, the actions would be executed synchronously, and you would see the log messages immediately after placing an order, but thanks to the queue system, the response time of your application is not affected.

The default QUEUE_CONNECTION in Laravel is database, which uses the database to manage the queue. This means that the queued jobs are stored in your Neon database and processed by the queue worker. You can change the queue connection in your .env file if you prefer a different queue driver like redis for example. To see all available queue drivers, refer to the Laravel documentation or review the config/queue.php file within your Laravel project where you can configure the queue connection.

The jobs are queued in the jobs table in your database, which is usually created by default with new Laravel installations, or you can run the migration to create the table:

php artisan queue:table
php artisan migrate

Using Database Transactions with Events

When working with database operations and events, it's important to understand how Laravel handles queued event listeners within database transactions. That way you can make sure that your data remains consistent and that your listeners are triggered at the right time.

Let's update our OrderController and SendOrderConfirmation listener to handle this correctly:

<?php

namespace App\Http\Controllers;

use App\Models\Order;
use App\Events\OrderPlaced;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;

class OrderController extends Controller
{
    public function store(Request $request)
    {
        $order = DB::transaction(function () use ($request) {
            $order = Order::create([
                'customer_name' => $request->customer_name,
                'total' => $request->total,
            ]);

            event(new OrderPlaced($order));

            return $order;
        });

        return response()->json(['message' => 'Order placed successfully', 'order' => $order]);
    }
}

Now, let's update our SendOrderConfirmation listener to ensure it handles the event after the database transaction has been committed:

<?php

namespace App\Listeners;

use App\Events\OrderPlaced;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Contracts\Events\ShouldHandleEventsAfterCommit;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Support\Facades\Log;

class SendOrderConfirmation implements ShouldQueue, ShouldHandleEventsAfterCommit
{
    use InteractsWithQueue;

    public function handle(OrderPlaced $event)
    {
        // In a real application, you would send an email here
        Log::info('Order confirmation sent for Order #' . $event->order->id);
    }
}

By implementing the ShouldHandleEventsAfterCommit interface, we're telling Laravel to only process this listener after all open database transactions have been committed. This is crucial when your listener depends on database changes made within the transaction.

This approach ensures that:

The order is created in the database.
The OrderPlaced event is dispatched within the transaction.
The transaction is committed, saving the order to the Neon database.
Only after the transaction is successfully committed, the SendOrderConfirmation listener is processed.

This prevents potential issues where the listener might try to access data that hasn't been committed to the database yet, ensuring data consistency between your event processing and your Neon database state.

If your queue connection's after_commit configuration option is set to true in your config/queue.php file, all of your queued listeners will automatically wait for open database transactions to commit before they are processed, and you won't need to use the ShouldHandleEventsAfterCommit interface.

Conclusion

In this guide, we've explored how to implement and utilize Laravel's event system, focusing on database operations with Neon as our database provider. We've covered creating and dispatching events, creating and registering listeners, and how to use database transactions with events.

Events and listeners provide a powerful way to decouple various aspects of your application, making your code more maintainable and scalable without blocking the main request flow for time-consuming tasks.

As a next step, you might want to look into implementing Supervisor to manage your queue workers in a production environment and Laravel Horizon for monitoring and managing your queues rather than using the queue:work command directly.