PHPackages                             obelaw/trail - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. obelaw/trail

ActiveLibrary[Database & ORM](/categories/database)

obelaw/trail
============

Minimal, activity trail for Eloquent models.

41.8k↓50%PHP

Since Aug 18Pushed 9mo agoCompare

[ Source](https://github.com/obelaw/trail)[ Packagist](https://packagist.org/packages/obelaw/trail)[ RSS](/packages/obelaw-trail/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Obelaw Trail
============

[](#obelaw-trail)

Activity trail/audit log for Eloquent models. Captures model changes and request context, supports optional queueing, and includes a prune command.

Features
--------

[](#features)

- Observes model events: created, updated, deleted, restored, forceDeleted
- Stores attribute changes and optional snapshot
- Captures request context: IP, user agent, method, URL, guard, request ID
- Masks sensitive fields by default: password, token, secret
- Optional queueing for non-blocking writes
- Artisan command to prune old records

Installation
------------

[](#installation)

Publish config and migrations, then migrate:

```
php artisan vendor:publish --tag=trail-config
php artisan vendor:publish --tag=trail-migrations
php artisan migrate
```

Middleware is auto-registered to the `web` and `api` groups to capture request context. An alias `trail.capture` is also available if you want to apply it manually.

Configuration
-------------

[](#configuration)

`config/trail.php` keys:

- `connection`: database connection (null = default)
- `table`: table name (default: trails)
- `events`: model events to observe
- `ignore_attributes`: attributes to ignore when computing diffs (e.g. updated\_at)
- `redact_attributes`: attributes to mask in logs (password, token, secret)
- `store_snapshot`: whether to store a full snapshot
- `queue`: write via queue job when true
- `broadcast`: fire TrailRecorded event after save
- `retention_days`: default prune retention
- `watch`: optional list of model classes to auto-observe

Usage
-----

[](#usage)

Attach to models via trait or config:

- Use the `TracksTrail` trait on your Eloquent model; or
- Add model classes to `trail.watch` in config.

Manual logging via facade/builder:

```
use Obelaw\Trail\Facades\Trail;

Trail::for($model)
	->event('custom')
	->changes(['name' => ['old' => 'A', 'new' => 'B']])
	->snapshot($model->toArray())
	->save();
```

Request context (IP, user agent, URL, method, guard, request ID) is captured automatically by the middleware.

Querying
--------

[](#querying)

```
use Obelaw\Trail\Models\Trail as TrailModel;

// All trails for a model
TrailModel::forTrailed($model->getMorphClass(), $model->getKey())->get();

// Filter by event
TrailModel::event('updated')->get();
```

Pruning
-------

[](#pruning)

Run manually with a custom retention:

```
php artisan trail:prune --days=180
```

Or schedule daily using the value from `retention_days`:

```
$schedule->command('trail:prune')->daily();
```

###  Health Score

22

—

LowBetter than 22% of packages

Maintenance41

Moderate activity, may be stable

Popularity24

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity13

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/31162701?v=4)[komicho](/maintainers/komicho)[@komicho](https://github.com/komicho)

---

Top Contributors

[![komtcho](https://avatars.githubusercontent.com/u/12757671?v=4)](https://github.com/komtcho "komtcho (3 commits)")

### Embed Badge

![Health badge](/badges/obelaw-trail/health.svg)

```
[![Health](https://phpackages.com/badges/obelaw-trail/health.svg)](https://phpackages.com/packages/obelaw-trail)
```

###  Alternatives

[doctrine/orm

Object-Relational-Mapper for PHP

10.2k285.3M6.2k](/packages/doctrine-orm)[jdorn/sql-formatter

a PHP SQL highlighting library

3.9k115.1M102](/packages/jdorn-sql-formatter)[illuminate/database

The Illuminate Database package.

2.8k52.4M9.4k](/packages/illuminate-database)[mongodb/mongodb

MongoDB driver library

1.6k64.0M546](/packages/mongodb-mongodb)[ramsey/uuid-doctrine

Use ramsey/uuid as a Doctrine field type.

90340.3M211](/packages/ramsey-uuid-doctrine)[reliese/laravel

Reliese Components for Laravel Framework code generation.

1.7k3.4M16](/packages/reliese-laravel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)