Weave Code
Laravel Auditable Laravel Package
ss-ipg/laravel-auditable
Declarative audit logging for Laravel Eloquent models via PHP attributes. Automatically tracks create, update, delete, soft delete, and restore events with old/new value diffs, column filtering, redaction, and JSON output.
Laravel Auditable brings declarative, attribute-based audit logging to Eloquent models. Simply mark a model with #[Auditable] and every create, update, and delete event is automatically recorded with detailed, structured change tracking—no observers or manual logging required.
Built for PHP 8.3+ and Laravel 11+, it integrates cleanly with Laravel's logging channels and emits JSON suitable for aggregation tools like Datadog or Splunk.
- Declarative attribute — enable auditing per model with a single
#[Auditable]attribute - Full event coverage — tracks
created,updated,deleted,soft_deleted, andrestored - Old/new value diffs — captures precise before-and-after changes on updates
- Column filtering — include, exclude, or redact sensitive fields
- Extensible context — add custom metadata via pluggable context providers
Frequently asked questions about Laravel Auditable
- How do I audit changes to Eloquent models without writing custom event listeners?
- Simply add the `#[Auditable]` attribute to your model. The package automatically tracks created, updated, deleted, soft-deleted, and restored events with old/new value diffs. No manual event binding or logging code is required.
- Does this package support Laravel 10 or earlier versions?
- No, Laravel Auditable requires Laravel 11+ and PHP 8.3+ due to its reliance on PHP attributes. If you're on an older version, consider alternatives like `owen-it/laravel-auditing` or `spatie/laravel-activitylog`.
- Can I exclude or redact sensitive fields like passwords from audit logs?
- Yes. Use the `exclude` or `redact` options in the `#[Auditable]` attribute to filter out sensitive fields. For example, `#[Auditable(exclude: ['password', 'api_token'])]` will omit those fields from logs.
- How do I add custom metadata (e.g., request ID, tenant ID) to audit logs?
- Implement a `AuditContextProvider` class and register it in the `context_providers` array in `config/auditable.php`. The provider’s `getContext()` method can return any metadata you need, like `['request_id' => $request->id, 'tenant_id' => Auth::tenant()->id]`.
- Will mass updates (e.g., `Model::where(...)->update()`) trigger audit logs?
- No, mass operations bypass auditing because they don’t operate on individual model instances. To audit bulk changes, iterate over models explicitly, like `Model::where(...)->get()->each(fn($model) => $model->update(...))`.
- How do I test audit logs in PHPUnit or Pest?
- Use the `Audit::fake()` helper to assert audit logs in tests. For example: `Audit::fake(); $user->update(['name' => 'New Name']); Audit::assertLogged(fn($log) => $log->hasChanges(['name' => 'New Name']));`.
- Can I send audit logs to Datadog, Splunk, or other monitoring tools?
- Yes. The package outputs logs in JSON format by default, which is compatible with most monitoring tools. Configure your logging channel (e.g., `monolog` with a `DatadogHandler`) to forward audit logs to your preferred destination.
- How do I disable auditing for specific models or environments?
- Disable auditing for all models by setting `AUDITABLE_ENABLED=false` in `.env`. To exclude specific models, omit the `#[Auditable]` attribute. Restrict environments via `environments` in `config/auditable.php` (e.g., `['production', 'staging']`).
- Does this package handle soft deletes and restores automatically?
- Yes. The package detects soft deletes (`deleted_at` updates) and restores (`deleted_at` nullification) separately from hard deletes. Each event type is logged with the appropriate context, making it easy to track compliance-sensitive changes.
- What are the performance implications of enabling auditing in production?
- Audit logging adds I/O overhead, which can impact performance for high-volume models. Mitigate this by enabling async logging (e.g., using the `queue` channel) or sampling logs for non-critical models. Disable auditing in non-production environments via `environments` config.
Weaver
How can I help you explore Laravel packages today?