Weave Code
Trail Laravel Package
astrophp/trail
Trail is a Laravel package that adds a simple audit trail to your Eloquent models. It automatically logs create, update, and delete events, capturing who made each change and when. Use it to improve debugging, accountability, and compliance with minimal setup.
Laravel AI SDK observability. Monitor agent runs, traces, tool calls, token usage, and estimated costs with a self-hosted dashboard.
Frequently asked questions about Trail
- How do I install astrophp/trail in a Laravel application?
- Install it with Composer using composer require astrophp/trail, then publish the package's configuration and migration files so the audit tables are created in your application database. Run your migrations and add the Trail trait to each Eloquent model you want audited. Because the package is Laravel-native, it uses your existing database connection and Eloquent model events, so there is no extra service to deploy or maintain.
- Which Laravel and PHP versions does astrophp/trail support?
- Trail is built as a Laravel-native package that hooks into Eloquent model events, so it is intended for current Laravel releases. Check the composer.json require block on the repository for the exact Laravel and PHP constraints before upgrading a major framework version, and pin a version in composer.json for production. Running your test suite against the target Laravel version in CI is the quickest way to confirm compatibility after an upgrade. As with any small package, review recent commits and release tags to judge maintenance activity.
- How does Trail know who made a change to a model?
- Trail captures actor context alongside each recorded event, so every entry can be tied back to the user or process responsible. In a typical setup the actor is resolved automatically from the authenticated user for HTTP requests. For console commands, queue workers, and scheduled jobs where no authenticated user exists, you should set the actor explicitly so the audit entries are not left unattributed. This actor context is what makes the history useful for accountability and debugging rather than just a diff log.
- Does Trail store both the old and new values of a change?
- Yes. Trail records the old values and the new values for each tracked update, in addition to the create and delete events it logs. Storing both sides means you can reconstruct exactly what a record looked like before and after a change without keeping full copies of the row. This is what lets you answer questions like who changed a status field, when, and what it was previously. It also makes the history queryable for debugging and audit review.
- Can I exclude sensitive attributes from being written to the audit trail?
- You should treat audit tables as a second copy of your data and exclude anything sensitive before it lands there. Configure an ignore or hidden list for attributes such as passwords, API tokens, and personal data you are not permitted to retain in a log, and review the list whenever a model gains a new column. Plain-text payloads such as user-submitted content or transcription text are the highest-risk case, so confirm your retention and PII policy covers anything you choose to log. Bytes and files are not the concern here; verbatim text is.
- Does Trail log deletes and soft deletes?
- Trail records delete events alongside create and update events, so removals are captured in the audit history. Soft deletes are implemented in Eloquent as an update that sets the deleted_at column, so they are normally recorded as an update rather than a hard delete. A force delete removes the row and is recorded as a delete event. If your retention policy requires audit entries to survive the underlying records, make sure the audit table itself is not cascade-deleted alongside the model.
- Will adding an audit trail slow down my Laravel application in production?
- Every tracked model event adds a database write, so the cost scales with how many audited models you write per request. For normal web traffic this is usually negligible, but bulk imports, batch jobs, and high-volume write paths should be measured rather than assumed. If the extra writes become a problem, keep only the models that genuinely need auditing in scope and consider moving the write off the request path. Also watch table growth: audit tables accumulate quickly and need a retention or archival plan.
- How do I query the history for a specific model or record?
- Because Trail stores entries in queryable database tables, you can retrieve history with ordinary Eloquent queries rather than parsing log files. Entries are typically linked to the model instance, so you can fetch a single record's timeline and inspect the old and new values for each event. The same tables support wider queries such as everything a given user changed in a period, which is useful for audits and incident investigation. Index the columns you filter on most, such as model type, model id, and timestamp, as the table grows.
- Does the audit trail catch mass updates and bulk inserts?
- Trail relies on Eloquent model events, which fire when you save or delete individual models. Updates issued through the query builder, such as a mass update call or an insert of many rows at once, bypass model events and will not be recorded. If bulk operations are part of your workflow, route the ones that matter through model instances or record an explicit entry yourself. This is the most common reason an audit log appears to have gaps.
- How does astrophp/trail compare to spatie/laravel-activitylog or owen-it/laravel-auditing?
- All three give Laravel developers a record of changes to Eloquent models, and the right choice depends on how much you need beyond the basics. Trail is deliberately lightweight: trait-based opt-in, automatic create, update and delete capture, old and new values, and actor context, with no heavy abstractions. spatie/laravel-activitylog is more general-purpose activity logging, while owen-it/laravel-auditing offers a broader auditing feature set with more configuration surface. If you want a small, readable audit trail with minimal setup, Trail is a reasonable fit; if you need extensive auditing rules, compare the feature lists directly before committing.
Weaver
How can I help you explore Laravel packages today?