Eloquent-Observer und Modell-Events

Was sind Modell-Events?

Eloquent-Modelle lösen an bestimmten Punkten ihres Lebenszyklus automatisch Events aus. Indem Sie sich an diese Events hängen, können Sie vor oder nach dem Speichern, Löschen usw. eigene Logik einschleusen. Die von Eloquent ausgelösten Events sind:

Event	Zeitpunkt
`retrieved`	Nachdem das Modell aus der Datenbank geladen wurde
`creating`	Unmittelbar vor dem Speichern eines neuen Modells
`created`	Unmittelbar nach dem Speichern eines neuen Modells
`updating`	Unmittelbar vor dem Aktualisieren eines bestehenden Modells
`updated`	Unmittelbar nach dem Aktualisieren eines bestehenden Modells
`saving`	Unmittelbar vor dem Speichern (Neuanlage oder Update)
`saved`	Unmittelbar nach dem Speichern (Neuanlage oder Update)
`deleting`	Unmittelbar vor dem Löschen eines Modells
`deleted`	Unmittelbar nach dem Löschen eines Modells
`trashed`	Unmittelbar nach einem Soft Delete
`forceDeleting`	Unmittelbar vor einem harten Löschen
`forceDeleted`	Unmittelbar nach einem harten Löschen
`restoring`	Unmittelbar vor dem Wiederherstellen eines Soft-Deletes
`restored`	Unmittelbar nach dem Wiederherstellen eines Soft-Deletes
`replicating`	Beim Aufruf von `replicate()`

Events, die auf -ing enden, feuern vor der Persistierung in die DB, Events auf -ed danach.

Bei Massen-Updates oder Massen-Deletes (z. B. User::where(...)->update(...)) werden die Events saving, saved, updating, updated, deleting, deleted nicht ausgelöst, weil die Modelle nicht instanziiert werden.

Event-Listener über Closures

Für einfache Event-Behandlung können Sie Closures in der booted-Methode des Modells registrieren.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected static function booted(): void
    {
        static::created(function (User $user) {
            // Läuft nach dem Anlegen eines Nutzers
        });

        static::deleting(function (User $user) {
            // Läuft vor dem Löschen eines Nutzers
        });
    }
}

Um die Verarbeitung asynchron in einer Queue auszuführen, verwenden Sie den Helper queueable.

use function Illuminate\Events\queueable;

static::created(queueable(function (User $user) {
    // Wird asynchron in der Queue ausgeführt
}));

Property `$dispatchesEvents`

Wenn Sie das Laravel-Event-System nutzen möchten, ordnen Sie über die Property $dispatchesEvents Modell-Events eigenen Event-Klassen zu.

<?php

namespace App\Models;

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

class User extends Authenticatable
{
    /**
     * Zuordnung von Modell-Events zu Event-Klassen
     *
     * @var array<string, string>
     */
    protected $dispatchesEvents = [
        'saved' => UserSaved::class,
        'deleted' => UserDeleted::class,
    ];
}

Die zugeordneten Event-Klassen erhalten die Modell-Instanz per Konstruktor.

<?php

namespace App\Events;

use App\Models\User;

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

Eine Observer-Klasse anlegen

Wenn Sie mehrere Events desselben Modells bündeln möchten, ist eine Observer-Klasse übersichtlicher als eine Reihe von Closures.

Klasse per Artisan-Command erzeugen

Erzeugen Sie ein Gerüst mit make:observer. Mit der Option --model erhalten Sie passende Methoden.

php artisan make:observer UserObserver --model=User

Die Datei app/Observers/UserObserver.php wird angelegt.

Methoden je Event implementieren

Der Methodenname entspricht dem Event-Namen. Als Argument erhalten Sie die Modell-Instanz.

<?php

namespace App\Observers;

use App\Models\User;

class UserObserver
{
    public function created(User $user): void
    {
        // Verarbeitung nach dem Anlegen des Nutzers
    }

    public function updated(User $user): void
    {
        // Verarbeitung nach dem Aktualisieren
    }

    public function deleted(User $user): void
    {
        // Verarbeitung nach dem Löschen
    }

    public function restored(User $user): void
    {
        // Verarbeitung nach dem Wiederherstellen eines Soft-Deletes
    }

    public function forceDeleted(User $user): void
    {
        // Verarbeitung nach hartem Löschen
    }
}

Observer am Modell registrieren

Es gibt zwei Registrierungsvarianten. In Laravel 13 wird das Attribut #[ObservedBy] empfohlen.Variante 1: Attribut #[ObservedBy] (empfohlen)Sie versehen die Modellklasse mit dem Attribut — die Registrierung ist damit abgeschlossen. Änderungen am AppServiceProvider sind nicht nötig.

<?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
{
    //
}

Zum Registrieren mehrerer Observer wiederholen Sie das Attribut oder übergeben ein Array.

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

Variante 2: Registrierung im AppServiceProviderRufen Sie in der boot-Methode observe auf.

<?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);
    }
}

Das Attribut #[ObservedBy] liegt im Namensraum Illuminate\Database\Eloquent\Attributes und ist native PHP-Syntax ab 8.0, die Laravel 13 aktiv einsetzt.

Observer innerhalb von Datenbanktransaktionen

Werden Modelle innerhalb einer Transaktion erstellt oder aktualisiert, wollen Sie den Observer manchmal erst nach dem Commit ausführen. Implementieren Sie dazu das 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
    {
        // Läuft nach dem Commit der Transaktion
    }
}

Wird außerhalb einer Transaktion gearbeitet, läuft der Observer wie gewohnt sofort.

Events temporär deaktivieren

`withoutEvents` — Events während eines Codeabschnitts unterdrücken

Innerhalb der an User::withoutEvents() übergebenen Closure werden keinerlei Modell-Events ausgelöst.

use App\Models\User;

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

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

`saveQuietly` — Events beim Speichern unterdrücken

Wenn Sie ein Modell speichern wollen, ohne Events auszulösen, nutzen Sie saveQuietly.

$user = User::findOrFail(1);

$user->name = 'Victoria Faith';

$user->saveQuietly();

Analog gibt es Methoden für Löschen, Wiederherstellen und Replizieren.

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

Praktische Anwendungsfälle

Cache automatisch invalidieren

Wenn ein Modell aktualisiert oder gelöscht wird, den zugehörigen Cache automatisch leeren.

<?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');
    }
}

Audit-Logs schreiben

Änderungshistorien automatisch protokollieren. Mit getDirty() erhalten Sie die Werte vor und nach der Änderung.

<?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(),
        ]);
    }
}

Das Event updating feuert vor der Persistierung in die DB — hier liefert getDirty() die geplanten neuen Werte. Nach dem Event updated ist getDirty() bereits leer.

Verknüpfte Modelle automatisch aktualisieren

Beispiel: Nach Abschluss einer Bestellung den Lagerbestand automatisch anpassen.

<?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);
        }
    }
}

Nächste Schritte

Fortgeschritten: PHP-Attribute

Lernen Sie die PHP-Attribute von Laravel 13 inklusive #[ObservedBy] im Überblick.

​Was sind Modell-Events?

​Event-Listener über Closures

​Property $dispatchesEvents

​Eine Observer-Klasse anlegen

​Observer innerhalb von Datenbanktransaktionen

​Events temporär deaktivieren

​withoutEvents — Events während eines Codeabschnitts unterdrücken

​saveQuietly — Events beim Speichern unterdrücken

​Praktische Anwendungsfälle

​Cache automatisch invalidieren

​Audit-Logs schreiben

​Verknüpfte Modelle automatisch aktualisieren

​Nächste Schritte

Fortgeschritten: PHP-Attribute

Was sind Modell-Events?

Event-Listener über Closures

Property `$dispatchesEvents`

Eine Observer-Klasse anlegen

Observer innerhalb von Datenbanktransaktionen

Events temporär deaktivieren

`withoutEvents` — Events während eines Codeabschnitts unterdrücken

`saveQuietly` — Events beim Speichern unterdrücken

Praktische Anwendungsfälle

Cache automatisch invalidieren

Audit-Logs schreiben

Verknüpfte Modelle automatisch aktualisieren

Nächste Schritte