Événements personnalisés#

Les événements CRUD standard sont capturés automatiquement, mais votre application possède aussi des événements propres à votre domaine — une commande expédiée, un document publié, un compte verrouillé. La méthode audit() vous permet de les enregistrer directement sur le model.

Utilisation de base#

Appelez audit() sur n'importe quel model auditable avec un nom d'événement :

$order->audit('shipped');
$document->audit('published');
$account->audit('locked');

Cela crée une entrée dans le journal d'audit avec le nom de votre événement personnalisé, l'utilisateur courant, l'adresse IP et l'horodatage.

Avec les anciennes et nouvelles valeurs#

Pour les événements qui représentent un changement d'état, passez oldValues et newValues :

$order->audit('status_changed',
    oldValues: ['status' => 'pending'],
    newValues: ['status' => 'shipped'],
);

$user->audit('role_upgraded',
    oldValues: ['role' => 'editor'],
    newValues: ['role' => 'admin'],
);

Ces valeurs sont stockées telles quelles — AuditChain ne les déduit pas des attributs du model.

Fonctionnement#

Les événements personnalisés suivent le même pipeline que les événements automatiques :

• L'utilisateur authentifié, l'adresse IP et le user agent sont capturés
• Le batch UUID et le contexte courants sont attachés
• Si withoutAudit() est actif, l'événement est silencieusement ignoré
• En mode complet (HasAuditTrail), l'entrée est ajoutée à la chaîne de hash

Combinaison avec les mises à jour du model#

Un événement personnalisé et une mise à jour du model sont deux entrées distinctes dans le journal d'audit. Utilisez le batch grouping pour les relier :

use GrayMatter\AuditChain\Facades\AuditChain;

AuditChain::batch(function () use ($order) {
    $order->audit('status_changed',
        oldValues: ['status' => 'pending'],
        newValues: ['status' => 'shipped'],
    );
    $order->update(['status' => 'shipped']);
});

Les deux entrées partagent le même batch_uuid, ce qui indique clairement qu'elles font partie de la même opération.

Interroger les événements personnalisés#

$order->auditLogs()->where('event', 'shipped')->get();
$order->auditLogs()->whereNotIn('event', ['created', 'updated', 'deleted'])->get();