Eloquent-observers en modelevents

Wat zijn modelevents?

Een Eloquent-model vuurt automatisch events af op verschillende momenten in zijn levenscyclus. Door op deze events in te haken kun je verwerking toevoegen vóór en na het opslaan, verwijderen, enzovoort. De events die Eloquent afvuurt:

Event	Moment
`retrieved`	Wanneer het model uit de DB wordt opgehaald
`creating`	Vlak vóór het opslaan van een nieuw model
`created`	Vlak ná het opslaan van een nieuw model
`updating`	Vlak vóór het bijwerken van een bestaand model
`updated`	Vlak ná het bijwerken van een bestaand model
`saving`	Vlak vóór het opslaan, bij zowel aanmaken als bijwerken
`saved`	Vlak ná het opslaan, bij zowel aanmaken als bijwerken
`deleting`	Vlak vóór het verwijderen van het model
`deleted`	Vlak ná het verwijderen van het model
`trashed`	Vlak ná een soft delete
`forceDeleting`	Vlak vóór een definitieve verwijdering
`forceDeleted`	Vlak ná een definitieve verwijdering
`restoring`	Vlak vóór het herstellen van een soft delete
`restored`	Vlak ná het herstellen van een soft delete
`replicating`	Wanneer `replicate()` wordt aangeroepen

Events die eindigen op -ing gaan af vóórdat de wijziging in de DB wordt vastgelegd; events die eindigen op -ed gaan daarna af.

Bij mass updates en mass deletes (zoals User::where(...)->update(...)) worden de events saving, saved, updating, updated, deleting en deleted niet afgevuurd, omdat de modellen niet daadwerkelijk worden opgehaald.

Eventlisteners met closures

Wil je events simpel afhandelen, dan kun je closures registreren in de booted-methode van het model.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected static function booted(): void
    {
        static::created(function (User $user) {
            // Verwerking die wordt uitgevoerd na het aanmaken van de gebruiker
        });

        static::deleting(function (User $user) {
            // Verwerking die wordt uitgevoerd vóór het verwijderen van de gebruiker
        });
    }
}

Wil je de verwerking asynchroon via een queue uitvoeren, gebruik dan de queueable-helper.

use function Illuminate\Events\queueable;

static::created(queueable(function (User $user) {
    // Wordt asynchroon via de queue uitgevoerd
}));

De property `$dispatchesEvents`

Wil je integreren met het eventsysteem van Laravel, dan map je modelevents met de property $dispatchesEvents naar eigen eventklassen.

<?php

namespace App\Models;

use App\Events\UserDeleted;
use App\Events\UserSaved;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    /**
     * Mapping van modelevents naar eventklassen
     *
     * @var array<string, string>
     */
    protected $dispatchesEvents = [
        'saved' => UserSaved::class,
        'deleted' => UserDeleted::class,
    ];
}

De gemapte eventklasse ontvangt de modelinstantie in zijn constructor.

<?php

namespace App\Events;

use App\Models\User;

class UserSaved
{
    public function __construct(
        public readonly User $user,
    ) {}
}

Een observerklasse maken

Verwerk je meerdere events voor één model, dan is een observerklasse overzichtelijker dan een reeks closures.

De klasse genereren met een Artisan-commando

Genereer een sjabloon met het commando make:observer. Geef je met de optie --model het model op, dan worden de bijbehorende methodes automatisch toegevoegd.

php artisan make:observer UserObserver --model=User

Er wordt een app/Observers/UserObserver.php gegenereerd.

De methodes voor de events implementeren

De methodenaam komt overeen met de eventnaam. Als argument wordt de modelinstantie doorgegeven.

<?php

namespace App\Observers;

use App\Models\User;

class UserObserver
{
    public function created(User $user): void
    {
        // Verwerking na het aanmaken van de gebruiker
    }

    public function updated(User $user): void
    {
        // Verwerking na het bijwerken van de gebruiker
    }

    public function deleted(User $user): void
    {
        // Verwerking na het verwijderen van de gebruiker
    }

    public function restored(User $user): void
    {
        // Verwerking na het herstellen van een soft delete
    }

    public function forceDeleted(User $user): void
    {
        // Verwerking na definitieve verwijdering
    }
}

De observer registreren bij het model

Er zijn twee manieren om te registreren. In Laravel 13 heeft het #[ObservedBy]-attribute de voorkeur.Manier 1: het #[ObservedBy]-attribute (aanbevolen)Alleen het attribute op de modelklasse zetten is genoeg; je hoeft de AppServiceProvider niet aan te passen.

<?php

namespace App\Models;

use App\Observers\UserObserver;
use Illuminate\Database\Eloquent\Attributes\ObservedBy;
use Illuminate\Foundation\Auth\User as Authenticatable;

#[ObservedBy(UserObserver::class)]
class User extends Authenticatable
{
    //
}

Wil je meerdere observers registreren, herhaal dan het attribute of geef een array door.

#[ObservedBy(UserObserver::class)]
#[ObservedBy(AuditObserver::class)]
class User extends Authenticatable
{
    //
}

Manier 2: registreren in de AppServiceProviderRoep observe aan in de boot-methode van de AppServiceProvider.

<?php

namespace App\Providers;

use App\Models\User;
use App\Observers\UserObserver;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        User::observe(UserObserver::class);
    }
}

Het #[ObservedBy]-attribute staat in de namespace Illuminate\Database\Eloquent\Attributes. Het is native syntaxis van PHP 8.0 en later en wordt in Laravel 13 actief toegepast.

Observers binnen databasetransacties

Wordt een model binnen een transactie aangemaakt of bijgewerkt, dan wil je de observer soms pas na de commit van de transactie laten draaien. Implementeer daarvoor de interface ShouldHandleEventsAfterCommit.

<?php

namespace App\Observers;

use App\Models\User;
use Illuminate\Contracts\Events\ShouldHandleEventsAfterCommit;

class UserObserver implements ShouldHandleEventsAfterCommit
{
    public function created(User $user): void
    {
        // Wordt uitgevoerd nadat de transactie is gecommit
    }
}

Gebeurt de uitvoering buiten een transactie, dan wordt de observer zoals gebruikelijk direct uitgevoerd.

Events tijdelijk uitschakelen

Alleen voor een specifieke bewerking events stoppen met `withoutEvents`

Binnen de closure die je doorgeeft aan User::withoutEvents() worden geen enkele modelevents afgevuurd.

use App\Models\User;

$user = User::withoutEvents(function () {
    User::findOrFail(1)->delete();

    return User::find(2);
});

Events bij het opslaan stoppen met `saveQuietly`

Wil je een model opslaan zonder events af te vuren, gebruik dan saveQuietly.

$user = User::findOrFail(1);

$user->name = 'Victoria Faith';

$user->saveQuietly();

Vergelijkbare methodes bestaan ook voor verwijderen, herstellen en repliceren.

$user->deleteQuietly();
$user->restoreQuietly();

Praktische use cases

Automatisch de cache legen

Automatisch de gerelateerde cache legen wanneer een model wordt bijgewerkt of verwijderd.

<?php

namespace App\Observers;

use App\Models\Post;
use Illuminate\Support\Facades\Cache;

class PostObserver
{
    public function saved(Post $post): void
    {
        Cache::forget("post:{$post->id}");
        Cache::forget('posts:latest');
    }

    public function deleted(Post $post): void
    {
        Cache::forget("post:{$post->id}");
        Cache::forget('posts:latest');
    }
}

Auditlogs bijhouden

De wijzigingsgeschiedenis van een model automatisch vastleggen. Met getDirty() haal je de gewijzigde waarden op.

<?php

namespace App\Observers;

use App\Models\AuditLog;
use App\Models\User;

class UserObserver
{
    public function updating(User $user): void
    {
        AuditLog::create([
            'model_type' => User::class,
            'model_id'   => $user->id,
            'changes'    => $user->getDirty(),
            'user_id'    => auth()->id(),
        ]);
    }

    public function deleted(User $user): void
    {
        AuditLog::create([
            'model_type' => User::class,
            'model_id'   => $user->id,
            'changes'    => ['deleted' => true],
            'user_id'    => auth()->id(),
        ]);
    }
}

Het updating-event gaat af vóór het opslaan in de DB, dus met getDirty() haal je de nog door te voeren waarden op. Roep je het aan na het updated-event, dan is getDirty() leeg.

Gerelateerde modellen automatisch bijwerken

Een voorbeeld dat automatisch de voorraad bijwerkt wanneer een bestelling is geplaatst.

<?php

namespace App\Observers;

use App\Models\Order;

class OrderObserver
{
    public function created(Order $order): void
    {
        foreach ($order->items as $item) {
            $item->product->decrement('stock', $item->quantity);
        }
    }

    public function deleted(Order $order): void
    {
        foreach ($order->items as $item) {
            $item->product->increment('stock', $item->quantity);
        }
    }
}

Volgende stap

Geavanceerd: PHP-attributes

Leer de PHP-attributes van Laravel 13 kennen, inclusief #[ObservedBy].

AI-ontwikkeling

Design patterns

Package-ontwikkeling

Applicatiestructuur

Nieuwe functies in Laravel 13

Eloquent in detail

Validatie-uitbreidingen

Authenticatie uitbreiden

Beveiliging

Queues

Testen

Wat zijn modelevents?

Eventlisteners met closures

De property `$dispatchesEvents`

Een observerklasse maken

Observers binnen databasetransacties

Events tijdelijk uitschakelen

Alleen voor een specifieke bewerking events stoppen met `withoutEvents`

Events bij het opslaan stoppen met `saveQuietly`

Praktische use cases

Automatisch de cache legen

Auditlogs bijhouden

Gerelateerde modellen automatisch bijwerken

Volgende stap

Geavanceerd: PHP-attributes

​Wat zijn modelevents?

​Eventlisteners met closures

​De property $dispatchesEvents

​Een observerklasse maken

​Observers binnen databasetransacties

​Events tijdelijk uitschakelen

​Alleen voor een specifieke bewerking events stoppen met withoutEvents

​Events bij het opslaan stoppen met saveQuietly

​Praktische use cases

​Automatisch de cache legen

​Auditlogs bijhouden

​Gerelateerde modellen automatisch bijwerken

​Volgende stap

Geavanceerd: PHP-attributes

Wat zijn modelevents?

Eventlisteners met closures

De property `$dispatchesEvents`

Een observerklasse maken

Observers binnen databasetransacties

Events tijdelijk uitschakelen

Alleen voor een specifieke bewerking events stoppen met `withoutEvents`

Events bij het opslaan stoppen met `saveQuietly`

Praktische use cases

Automatisch de cache legen

Auditlogs bijhouden

Gerelateerde modellen automatisch bijwerken

Volgende stap