Laravel's event system provides a simple observer implementation, allowing you to subscribe and listen for various events that occur in your application.
Events help you decouple parts of your application's logic. Queued listeners move time-consuming tasks out of the main request flow, so responses return faster.
In this guide, we'll set up and use Laravel events and listeners, with a focus on database operations on a Neon database.
Prerequisites
Before we begin, make sure 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
Set up the project
Start by creating a new Laravel project. If you already have a Laravel project set up, you can skip this section.
Create 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-eventsThis will create a new Laravel project in a directory named laravel-events with all the necessary dependencies installed.
Set up the database
Next, configure your Neon database connection. If you don't have a Neon account, sign up.
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_passwordReplace your-neon-hostname, your_database_name, your_username, and your_password with your Neon database credentials. You can find them by clicking Connect in the Neon Console.
Create a model and migration
For this tutorial, let's create an 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 -mThis 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 migrateNext, update the Order model in app/Models/Order.php to add 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'];
}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.
Create an event
An event in Laravel is a class that represents something that happened in your application. Events trigger actions or notify other parts of your application.
Now, let's create an event that will be triggered when an order is placed. Run the following command:
php artisan make:event OrderPlacedThis 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.
Create 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=OrderPlacedThis 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);
}
}The listener implements the ShouldQueue interface, so Laravel's queue system handles it. That keeps time-consuming tasks out of the request.
Without ShouldQueue, the listener runs synchronously. That can slow down your application's response time, but it's useful when an action must finish before the response returns.
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.
Register 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.
Dispatch the event
With the event and listener in place, create a 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 OrderControllerOpen 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 dispatches the event and passes the order instance to the event constructor.
The listener gets the order details from the event, so the controller doesn't have to perform the additional actions itself and block the request.
We will use this controller to create a new order and trigger the event.
Add 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:apiThis will create a new api.php file in the routes directory.
Test the event system
Now, test the 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.
Run queued jobs
The SendOrderConfirmation listener implements the ShouldQueue interface, meaning it will be handled by Laravel's queue system.
If you check your logs right after placing an order, you won't see the log messages from the listener yet. Run the queue worker to process the queued jobs:
php artisan queue:workThis 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 DONEIn a different terminal window, you can place a new order using curl or Postman to see the listener in action.
If you removed the ShouldQueue interface from the listener, the actions would run synchronously and you'd see the log messages as soon as you placed an order. With the queue, that work doesn't add to your application's response time.
The default QUEUE_CONNECTION in Laravel is database, which uses the database to manage the queue. 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 migrateUse database transactions with events
When you dispatch events inside a database transaction, a queued listener can run before the transaction commits. Laravel lets you delay the listener until after the commit so your data stays consistent.
Update the 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, update the SendOrderConfirmation listener so it handles the event after the database transaction commits:
<?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 matters when your listener depends on database changes made within the transaction.
With this approach:
- The order is created in the database.
- The
OrderPlacedevent is dispatched within the transaction. - The transaction is committed, saving the order to the Neon database.
- The
SendOrderConfirmationlistener is processed only after the transaction commits.
This prevents the listener from reading data that hasn't been committed yet.
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
You built an order flow that dispatches a Laravel event, handles it with a queued listener, and waits for the database transaction to commit before the listener runs.
As a next step, look into 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.
