Events, listeners and model observers

When Pathshala’s front desk records a fee payment, three more things should follow: the day’s collection total moves, the guardian gets a receipt and the instalment’s change of status goes into an audit trail. If the payment code makes those three calls itself, a mail server that takes 2 seconds to answer keeps the cashier waiting 2 seconds for every payment, and each new reaction means editing the code that handles money.

Laravel’s events keep the payment apart from its reactions. The code that stores a payment dispatches one event, and each reaction is a listener the framework finds by itself. This lesson builds that for Pathshala: two listeners, one of them queued, an observer on the Instalment model, listeners that wait for the transaction to commit, and the tests. Every output below was recorded on Laravel 13.34.0.

One payment, many reactions: an event keeps them apart

The action that stores a payment is the place where money is handled, so it should hold only what decides whether the payment counts. Pathshala’s RecordPayment action saves the row inside a transaction, dispatches one event, refuses an overpayment and marks the instalment paid:

<?php

namespace App\Actions;

use App\Events\PaymentReceived;
use App\Models\Instalment;
use App\Models\Payment;
use Illuminate\Support\Facades\DB;
use RuntimeException;

// Stores one payment against an instalment. What must succeed for the payment to count (the row, the overpayment
// check, the instalment's status) happens here, in one transaction; everything optional listens to the event.
class RecordPayment
{
    public function handle(Instalment $instalment, int $amountPaise, string $method = 'cash'): Payment
    {
        return DB::transaction(function () use ($instalment, $amountPaise, $method) {
            $payment = $instalment->payments()->create([
                'amount_paise' => $amountPaise,
                'method' => $method,
                'paid_at' => now(),
            ]);

            PaymentReceived::dispatch($payment);

            $paid = $instalment->payments()->sum('amount_paise');
            if ($paid > $instalment->amount_paise) {
                throw new RuntimeException("Instalment {$instalment->id} would be overpaid: {$paid} of {$instalment->amount_paise} paise");
            }

            if ($paid === $instalment->amount_paise) {
                $instalment->update(['status' => 'paid', 'paid_on' => now()]);
            }

            return $payment;
        });
    }
}

PaymentReceived is an application eventapplication event: A small class that announces something that happened in the app, such as a stored payment, and carries its data. The code that dispatches it does not know who reacts.: a small class that carries the payment and names nobody who reacts to it. php artisan make:event PaymentReceived creates it, and php artisan make:listener SendPaymentReceipt --event=PaymentReceived creates an event listenerevent listener: A class that reacts to one event class. Laravel registers it for the event that its handle or __invoke method is type-hinted with. whose handle() method is already type-hinted with the event.

No file lists which listener belongs to which event. With event discoveryevent discovery: Laravel's way of wiring listeners without a list: it scans app/Listeners and registers each handle or __invoke method for the event class in its signature. event:cache stores the result., Laravel scans app/Listeners and registers every handle or __invoke method for the event class in its signature. php artisan event:list prints what it found. The documentation advises caching that list during deployment with event:cache or optimize, and this run shows what the cache does to a listener added afterwards:

from session import run

# Event discovery: event:list shows which listeners Laravel found for PaymentReceived by reading the type-hint of each
# handle() method in app/Listeners. Then the cached manifest of a deploy (event:cache) hides a listener added later,
# until the cache is built again.
run(
    """
php artisan event:list --event=PaymentReceived
php artisan event:cache
php artisan make:listener NotifyCentreManager --event=PaymentReceived
php artisan event:list --event=PaymentReceived
php artisan event:cache
php artisan event:list --event=PaymentReceived
""",
    app=True,
    overlay=("payments",),
)

$ php artisan event:list --event=PaymentReceived
  App\Events\PaymentReceived .................................................
  ⇂ App\Listeners\UpdateCollectionTotals@handle
  ⇂ App\Listeners\SendPaymentReceipt@handle (ShouldQueue)
$ php artisan event:cache
   INFO  Events cached successfully.
$ php artisan make:listener NotifyCentreManager --event=PaymentReceived
   INFO  Listener [app/Listeners/NotifyCentreManager.php] created successfully.
$ php artisan event:list --event=PaymentReceived
  App\Events\PaymentReceived .................................................
  ⇂ App\Listeners\UpdateCollectionTotals@handle
  ⇂ App\Listeners\SendPaymentReceipt@handle (ShouldQueue)
$ php artisan event:cache
   INFO  Events cached successfully.
$ php artisan event:list --event=PaymentReceived
  App\Events\PaymentReceived .................................................
  ⇂ App\Listeners\UpdateCollectionTotals@handle
  ⇂ App\Listeners\SendPaymentReceipt@handle (ShouldQueue)
  ⇂ App\Listeners\NotifyCentreManager@handle

The first event:list shows both listeners, and marks the receipt listener (ShouldQueue). After event:cache, a new listener file exists but the next event:list still shows two: the framework reads the cached manifest instead of the folder. Only the second event:cache adds NotifyCentreManager.

A slow listener belongs on the queue

A receipt waits for a mail server, and a mail server can take seconds. A queued listenerqueued listener: An event listener that implements ShouldQueue. Dispatching the event stores a job, and a queue worker runs the listener later, outside the request. moves that wait out of the request: the class implements ShouldQueue, so dispatching the event stores a job, and a queue worker runs the listener later. The receipt listener needs one interface more than an ordinary listener:

<?php

namespace App\Listeners;

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

// Sends the guardian a receipt. ShouldQueue: dispatching the event only stores a job; a queue worker runs this later,
// so the front desk does not wait for the mail server. (The mail itself is the mail-and-notifications lesson; here
// the receipt is written to the log.)
class SendPaymentReceipt implements ShouldQueue
{
    public function handle(PaymentReceived $event): void
    {
        $payment = $event->payment;
        $student = $payment->instalment->student;

        Log::info("Receipt for payment {$payment->id}: {$payment->amount_paise} paise from {$student->name}, sent to {$student->guardian_email}");
    }
}

The new project’s .env sets QUEUE_CONNECTION=database, and its first migrations already created the jobs table, so a queued listener works with no extra set-up. Step through one payment and watch which work is finished when the front desk’s command returns:

The same payment, recorded. The status lines come before and after the worker:

from session import run

# One payment at the front desk: the synchronous listener has updated the total before the command returns, while the
# queued receipt listener is only a row in the jobs table until a worker runs it. The clock is frozen on a fixed day.
run(
    """
export PATHSHALA_NOW=2026-06-15T10:00:00
export CACHE_STORE=file
php artisan migrate --force
php artisan db:seed --class=PathshalaSeeder --force
php artisan payments:record PS-1001 50000
php artisan payments:status
php artisan jobs:waiting
php artisan queue:work --stop-when-empty
php artisan jobs:waiting
cat storage/logs/laravel.log
""",
    app=True,
    overlay=("payments",),
)

$ export PATHSHALA_NOW=2026-06-15T10:00:00
$ export CACHE_STORE=file
$ php artisan migrate --force
   INFO  Running migrations.

  2026_01_05_090000_create_students_table ............................... DONE
  2026_01_05_091000_create_instalments_table ............................ DONE
  2026_01_05_092000_create_payments_table ............................... DONE
  2026_01_05_093000_create_instalment_changes_table ..................... DONE
$ php artisan db:seed --class=PathshalaSeeder --force
   INFO  Seeding database.

  Database\Seeders\PathshalaSeeder ................................... RUNNING
  Database\Seeders\PathshalaSeeder ...................................... DONE
$ php artisan payments:record PS-1001 50000
Payment 1 stored: 50000 paise for instalment 1 (paid)
$ php artisan payments:status
Payments stored: 1
Collected (cache total): 50000 paise
$ php artisan jobs:waiting
Jobs waiting in the queue: 1
$ php artisan queue:work --stop-when-empty
  … App\Listeners\SendPaymentReceipt ............... RUNNING
  … App\Listeners\SendPaymentReceipt .................. DONE
  … Worker STOPPED Queue empty
$ php artisan jobs:waiting
Jobs waiting in the queue: 0
$ cat storage/logs/laravel.log
[…] local.INFO: Receipt for payment 1: 50000 paise from Asha Verma, sent to guardian.ps1001@example.com

The total said 50000 paise as soon as the payment was stored, because UpdateCollectionTotals ran inside the command. The receipt was one row in the jobs table until queue:work --stop-when-empty ran SendPaymentReceipt and stopped. The event uses SerializesModels, so the job holds the payment’s id and the worker loads the row again before it calls handle(); the log line names payment 1 and the guardian’s address.

Workers, retries and failed jobs are the next lesson, Queues and jobs.

Observers react to model events, not to every query

Eloquent announces fifteen moments in a model’s life. Twelve of them come in six pairs, one dispatched before the change is written and one after it: creating and created, updating and updated, saving and saved, deleting and deleted, restoring and restored, forceDeleting and forceDeleted. The other three are retrieved (an existing row was loaded), trashed (a soft delete finished) and replicating (a copy was made). These are model eventsmodel event: A moment in an Eloquent model's life, such as creating, updated or deleted, that the model announces when it is saved or deleted through a model instance. Query-builder writes announce none..

Pathshala’s audit trail needs one row each time an instalment’s status changes. A model observermodel observer: A class that groups an Eloquent model's event handlers in methods named after the events, such as updated, and is attached to the model with the ObservedBy attribute. groups a model’s handlers in methods named after the events, and the #[ObservedBy] attribute on the model attaches it:

<?php

namespace App\Observers;

use App\Models\Instalment;
use App\Models\InstalmentChange;

// Writes the audit trail: one row each time an instalment's status changes through the model.
class InstalmentObserver
{
    public function updated(Instalment $instalment): void
    {
        if ($instalment->wasChanged('status')) {
            InstalmentChange::create([
                'instalment_id' => $instalment->id,
                'from_status' => $instalment->getOriginal('status'),
                'to_status' => $instalment->status,
            ]);
        }
    }
}

The Instalment model carries #[ObservedBy([InstalmentObserver::class])] above its class. Two commands change statuses in two different ways: one loads instalment 1 and calls $instalment->update(), the other marks every late instalment overdue with a single query-builder update():

from session import run

# The observer writes an audit row when an instalment's status changes through the model ($instalment->update()), and
# writes nothing for a query-builder update() that changes two rows in one statement. The clock is frozen on a fixed
# day, so "late" means due before that day.
run(
    """
export PATHSHALA_NOW=2026-06-15T10:00:00
php artisan migrate --force
php artisan db:seed --class=PathshalaSeeder --force
php artisan instalments:mark-paid 1
php artisan instalments:mark-overdue
php artisan instalments:audit
""",
    app=True,
    overlay=("payments",),
)

$ export PATHSHALA_NOW=2026-06-15T10:00:00
$ php artisan migrate --force
   INFO  Running migrations.

  2026_01_05_090000_create_students_table ............................... DONE
  2026_01_05_091000_create_instalments_table ............................ DONE
  2026_01_05_092000_create_payments_table ............................... DONE
  2026_01_05_093000_create_instalment_changes_table ..................... DONE
$ php artisan db:seed --class=PathshalaSeeder --force
   INFO  Seeding database.

  Database\Seeders\PathshalaSeeder ................................... RUNNING
  Database\Seeders\PathshalaSeeder ...................................... DONE
$ php artisan instalments:mark-paid 1
Instalment 1 marked paid through the model
$ php artisan instalments:mark-overdue
2 instalments marked overdue with one query-builder update
$ php artisan instalments:audit
+------------+---------+------+
| Instalment | From    | To   |
+------------+---------+------+
| 1          | pending | paid |
+------------+---------+------+
Statuses now: paid, overdue, overdue

Three instalments changed status, and the trail holds one row. The query-builder update() sent a single UPDATE statement for instalments 2 and 3 without loading them as models, so there was no model to announce anything. The documentation says the same of mass deletes. The writes compare like this:

Listeners that run before the commit count rolled-back payments

RecordPayment dispatches its event inside DB::transaction, before it checks for an overpayment. The documentation describes the transaction’s contract: an exception inside the closure rolls back everything written to the database and is thrown again. A database transactiondatabase transaction: A group of database writes that succeed or fail together: either all of them are committed, or a rollback undoes every one. Work outside the database is not undone. undoes database writes only. Follow a second tap at the front desk for an instalment that is already paid:

Here is that tap, recorded with the cache in files so that it sits outside the database (the new project’s default database cache would join the same transaction and roll back with it):

from session import run

# A second tap at the front desk for an instalment that is already paid. The action stores the payment, dispatches
# PaymentReceived, then finds the overpayment and throws, so the transaction rolls back. The synchronous listener had
# already added 50,000 paise to the total in the cache, which the rollback cannot undo. The cache is the file store
# here (the skeleton's database store would sit inside the same transaction).
run(
    """
export PATHSHALA_NOW=2026-06-15T10:00:00
export CACHE_STORE=file
php artisan migrate --force
php artisan db:seed --class=PathshalaSeeder --force
php artisan payments:record PS-1001 50000
! php artisan payments:record PS-1001 50000
php artisan payments:status
""",
    app=True,
    overlay=("payments",),
)

$ export PATHSHALA_NOW=2026-06-15T10:00:00
$ export CACHE_STORE=file
$ php artisan migrate --force
   INFO  Running migrations.

  2026_01_05_090000_create_students_table ............................... DONE
  2026_01_05_091000_create_instalments_table ............................ DONE
  2026_01_05_092000_create_payments_table ............................... DONE
  2026_01_05_093000_create_instalment_changes_table ..................... DONE
$ php artisan db:seed --class=PathshalaSeeder --force
   INFO  Seeding database.

  Database\Seeders\PathshalaSeeder ................................... RUNNING
  Database\Seeders\PathshalaSeeder ...................................... DONE
$ php artisan payments:record PS-1001 50000
Payment 1 stored: 50000 paise for instalment 1 (paid)
$ php artisan payments:record PS-1001 50000
Instalment 1 would be overpaid: 100000 of 50000 paise; the transaction was rolled back.
[exit status 1]
$ php artisan payments:status
Payments stored: 1
Collected (cache total): 100000 paise

The rollback removed payment 2, and the total still counted it. The fix is to run the listener after the commitafter commit: Running a handler only once the surrounding database transaction has committed, so it never acts on writes that a rollback undoes. With no transaction open, the handler runs at once.. Implementing ShouldHandleEventsAfterCommit, or adding a public $afterCommit = true property, makes the dispatcher hand the listener to the open transaction, which runs it on commit and drops it on rollback. With no transaction open, the listener runs at once.

<?php

namespace App\Listeners;

use App\Events\PaymentReceived;
use Illuminate\Contracts\Events\ShouldHandleEventsAfterCommit;
use Illuminate\Support\Facades\Cache;

// The same listener, held back until the payment's transaction commits. If the transaction rolls back, the
// dispatcher drops it and the total never moves. Outside a transaction it runs at once, as before.
class UpdateCollectionTotals implements ShouldHandleEventsAfterCommit
{
    public function handle(PaymentReceived $event): void
    {
        Cache::increment('collected_paise', $event->payment->amount_paise);
    }
}

from session import run

# The same two taps with the listener of after-commit-fix/: it implements ShouldHandleEventsAfterCommit, so the
# dispatcher holds it until the transaction commits and drops it when the transaction rolls back.
run(
    """
export PATHSHALA_NOW=2026-06-15T10:00:00
export CACHE_STORE=file
php artisan migrate --force
php artisan db:seed --class=PathshalaSeeder --force
php artisan payments:record PS-1001 50000
! php artisan payments:record PS-1001 50000
php artisan payments:status
""",
    app=True,
    overlay=("payments", "after-commit-fix"),
)

$ export PATHSHALA_NOW=2026-06-15T10:00:00
$ export CACHE_STORE=file
$ php artisan migrate --force
   INFO  Running migrations.

  2026_01_05_090000_create_students_table ............................... DONE
  2026_01_05_091000_create_instalments_table ............................ DONE
  2026_01_05_092000_create_payments_table ............................... DONE
  2026_01_05_093000_create_instalment_changes_table ..................... DONE
$ php artisan db:seed --class=PathshalaSeeder --force
   INFO  Seeding database.

  Database\Seeders\PathshalaSeeder ................................... RUNNING
  Database\Seeders\PathshalaSeeder ...................................... DONE
$ php artisan payments:record PS-1001 50000
Payment 1 stored: 50000 paise for instalment 1 (paid)
$ php artisan payments:record PS-1001 50000
Instalment 1 would be overpaid: 100000 of 50000 paise; the transaction was rolled back.
[exit status 1]
$ php artisan payments:status
Payments stored: 1
Collected (cache total): 50000 paise

The wait can sit in four places, depending on who must wait:

The observer row comes from the dispatcher’s source: it leaves those six methods out of the wait, because they run before the write, and Model::save() stops when one of them returns false. A queued listener has the same problem in another form, which is why the queue connections have their own after_commit option, set to false in the new project.

Event, direct call or job: decide by what must succeed

The overpayment check sits in the action, not in a listener, and for a reason the first recorded run showed: a listener exists only when the framework registered it, and a stale event cache can leave a new one out without a word. Work that decides whether the payment counts belongs in the action, inside its transaction, where a failure rolls everything back together. Everything that only reacts to the payment can be a listener, and a listener that is slow or calls another service is queued.

A job is the third place. When the action needs one slow follow-up of its own, such as building a receipt PDF, the action can dispatch a job by name, and the queue lesson shows how. Answer the questions in the table for one piece of work that follows a payment:

In short: rules go in the action, reactions go to listeners, slow reactions go to the queue, and every reaction that a rollback cannot undo waits for the commit. A listener that returns false also stops every listener after it, so a rule placed in a listener can be skipped by its neighbour as well.

Testing events without switching off your observers

A test of RecordPayment should prove that a payment dispatches PaymentReceived without sending receipts or moving totals. An event fakeevent fake: A test double for the event dispatcher, installed by Event::fake(), that records dispatched events for assertions instead of running their listeners, model events included. does that: Event::fake() records every dispatched event instead of running its listeners, and Event::assertDispatched() checks what was recorded.

The fake has a reach that surprises people. Event::fake() also replaces the dispatcher that Eloquent uses, so model events are recorded instead of handled, and the observer goes quiet with everything else. The documentation warns about factories that rely on model events for the same reason. Pass the events to fake, Event::fake([PaymentReceived::class]), and everything else, model events included, runs as usual. Event::fakeExcept() turns it around: it fakes everything except the names you list (the documentation spells the same idea Event::fake()->except()), and a model event’s name has the form eloquent.updated: App\Models\Instalment.

<?php

namespace Tests\Feature;

use App\Actions\RecordPayment;
use App\Events\PaymentReceived;
use App\Listeners\SendPaymentReceipt;
use App\Models\Instalment;
use App\Models\InstalmentChange;
use App\Models\Student;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Event;
use Tests\TestCase;

class PaymentEventsTest extends TestCase
{
    use RefreshDatabase;

    private function instalment(): Instalment
    {
        return Student::create(['name' => 'Asha Verma', 'roll_no' => 'PS-1001', 'guardian_email' => 'guardian.ps1001@example.com'])
            ->instalments()
            ->create(['due_on' => '2026-06-10', 'amount_paise' => 50000, 'status' => 'pending']);
    }

    public function test_a_payment_dispatches_payment_received_once(): void
    {
        Event::fake([PaymentReceived::class]);

        app(RecordPayment::class)->handle($this->instalment(), 50000);

        Event::assertDispatchedOnce(PaymentReceived::class);
        Event::assertDispatched(fn (PaymentReceived $event) => $event->payment->amount_paise === 50000);
        $this->assertNull(Cache::get('collected_paise'));
        $this->assertSame(1, InstalmentChange::count());
    }

    public function test_a_full_fake_silences_the_observer_too(): void
    {
        $instalment = $this->instalment();
        Event::fake();

        app(RecordPayment::class)->handle($instalment, 50000);

        $this->assertSame('paid', $instalment->fresh()->status);
        $this->assertSame(0, InstalmentChange::count());
    }

    public function test_fake_except_lets_the_observer_run(): void
    {
        $instalment = $this->instalment();
        Event::fakeExcept(['eloquent.updated: '.Instalment::class]);

        app(RecordPayment::class)->handle($instalment, 50000);

        Event::assertDispatched(PaymentReceived::class);
        $this->assertSame(1, InstalmentChange::count());
    }

    public function test_the_receipt_listener_is_wired_to_the_event(): void
    {
        Event::fake();

        Event::assertListening(PaymentReceived::class, SendPaymentReceipt::class);
    }
}

from session import run

# COLLISION_IGNORE_DURATION=true: php artisan test prints no per-test times, so two runs print the same lines.

# Four tests of the payment action with Event::fake(): faking only PaymentReceived keeps the observer working, a full
# fake silences it too, fakeExcept() lets one model event through, and assertListening() checks the wiring.
run(
    """
export COLLISION_IGNORE_DURATION=true
php artisan test --filter=PaymentEventsTest
""",
    app=True,
    overlay=("payments",),
)

$ export COLLISION_IGNORE_DURATION=true
$ php artisan test --filter=PaymentEventsTest
   PASS  Tests\Feature\PaymentEventsTest
  ✓ a payment dispatches payment received once
  ✓ a full fake silences the observer too
  ✓ fake except lets the observer run
  ✓ the receipt listener is wired to the event

  Tests:    4 passed (9 assertions)
  Duration: …s

All four tests passed with 9 assertions. The first test faked only PaymentReceived and found one audit row, the second faked everything and found none, the third let the one model event through and found its row again, and the last used Event::assertListening() to check that the receipt listener is wired to the event.

Practise

Build the same pieces in your own Pathshala project:

1. Create PaymentReceived and two listeners with make:event and make:listener --event, then run php artisan event:list --event=PaymentReceived. Run event:cache, add a third listener and run event:list again before and after a second event:cache.
2. Make one listener queued with ShouldQueue, record a payment, count the rows of the jobs table, then run php artisan queue:work --stop-when-empty and read storage/logs/laravel.log.
3. Attach an observer with #[ObservedBy], change one status with $model->update() and three with one query-builder update(), and count the audit rows.
4. Set CACHE_STORE=file in .env, throw an exception after the dispatch inside DB::transaction, read the total, then implement ShouldHandleEventsAfterCommit on the listener and repeat.
5. Write the four tests, and make the second one fail on purpose by expecting one audit row.

The self-check takes each idea in turn:

Interview questions

Warm-up: an observer and a listener both react to events. How do they differ?

An event listener handles one application event, a class you dispatch yourself such as PaymentReceived, and Laravel wires it to that event by the type-hint of its handle() method. A model observer handles the events Eloquent dispatches about one model, such as created, updated and deleted, with one method per event, and you attach it to the model with the #[ObservedBy] attribute. A listener is often queued with ShouldQueue; an observer’s creating, updating, saving and deleting methods run before the write and can stop it by returning false. An observer is also blind to query-builder update() and delete() calls, which load no model and so fire no model event.

The module’s bank holds three longer questions about these ideas, each with a first step and follow-ups:

Key takeaways

• An event lets one action announce what happened while each reaction lives in its own listener, which discovery wires by the type-hint of handle(); a cached event manifest hides a listener added after event:cache until the cache is built again.
• A listener that implements ShouldQueue costs the request one row in the jobs table, and a worker runs it later with the payment loaded again from the database.
• Observers react to model events, which only writes made through a model dispatch, so a query-builder update() or delete() leaves an observer’s audit trail without a row.
• A listener that runs before the commit can count a payment that was rolled back; ShouldHandleEventsAfterCommit, $afterCommit, ShouldDispatchAfterCommit and ShouldQueueAfterCommit make it wait.
• Rules that decide whether a save counts belong in the action, reactions go to listeners and slow reactions to the queue.
• Event::fake() silences observers too, so fake only the events a test is about, or use Event::fakeExcept().