Eloquent Auditing Laravel Package

Getting Started

• Install with composer require mintbridge/eloquent-auditing — pin it ("0.0.5" exactly, not ^0.0.5). At 0.0.x the public API and schema are still moving.
• Publish and run the package migration to create the audits table. If you already ran the migration from an earlier version, re-publish and diff it — v0.0.5 makes ip_address nullable, which is a schema change, not just a code change.
• Add the package's auditing trait to the models you want tracked (typically a use Auditable;-style trait on the Eloquent model alongside your existing traits). Start with one high-value model — an Invoice, Order, or User — rather than rolling it out everywhere at once.
• Where to look first: the trait source (to see which model events are hooked: created / updated / deleted / restored), the migration stub (for the columns you'll be querying), and the CHANGELOG.md linked in the release notes.
• First use case: attach the trait to a model, make an edit through your normal controller flow, then inspect the resulting audit row — who changed it, what the old and new values were, and (new in v0.0.5) the originating IP address populated automatically from the current Request. Render that as a "history" tab on a detail page; it's the fastest way to prove value to stakeholders.

Implementation Patterns

• Automatic capture, read-side aggregation. The package's value is that you don't write logging code in controllers. Mutate the model normally and read the trail back through the model's audit relation. Keep your write path untouched; put the effort into the read path (an admin timeline, an export, a per-record changelog view).
• Let the package own the IP. v0.0.5 auto-populates the IP from the request, so delete any manual setIpAddress(...)-style plumbing you added in your controllers or form requests. Fewer injection points, fewer places to get it wrong.
• Context that isn't the request. Web requests now get IP for free, but queue workers, scheduled commands, and tests have no request — that's exactly why ip_address became nullable. Treat "IP present" as an HTTP-only signal and design the UI accordingly (show — or "system" rather than an empty cell).
• Wrap audit writes in your own transaction boundaries. Auditing is an extra insert per model write. For bulk imports or multi-model operations, chunk the work so you don't hold a long transaction open across thousands of audit inserts.
• Testing pattern. Assert on the audits table directly (assertDatabaseHas against the audit table with the model's morph columns) rather than on rendered history pages. Freeze time with Carbon::setTestNow() so the audit's timestamp is deterministic, and add one test that hits a real HTTP route and asserts an IP was recorded, plus one console/queued test that asserts it's null.
• Integration tips. Add indexes on the polymorphic columns (auditable_type, auditable_id) and on created_at before you ship — the history tab will query by record and by date range, and the table grows faster than any other table in your schema.

Gotchas and Tips

• The ip_address nullable change is the real story in this release. Two failure modes: (a) you upgraded the package but not your published migration, so writes without a request fail with a NOT NULL constraint violation; (b) you're changing the column on an existing install and need a proper ->nullable()->change() migration (plus doctrine/dbal on older Laravel). Diff the stub, don't assume.
• Proxies and load balancers. The auto-populated IP comes from the request, so behind a proxy or CDN you'll record the proxy's address unless TrustProxies / TrustedProxy middleware is configured correctly. Verify with a request through your real edge, not from artisan serve.
• Pin the version. 0.0.x means every release can break you. 0.0.5 already changed a column definition; assume a future release renames columns or moves the trait. Budget a read of the changelog per bump.
• Don't audit models holding secrets. Old/new payloads are typically serialized in full, so password, remember_token, API keys, and card data will land in your audit table. Prefer excluding those attributes if the trait supports a hidden/except list; otherwise don't put the trait on those models at all. This is a compliance issue, not a cosmetic one.
• Long-running queue workers. If the package resolves the IP from the request container, confirm it degrades to null in a worker instead of throwing on a missing request. v0.0.5's nullable column implies this is the intended path, but verify with a queued job before you rely on it.
• Debugging missing audits. Check the model's events actually fire — save() with no dirty attributes won't produce an update, and Model::query()->update() / raw SQL bypass Eloquent events entirely and will not be audited. That's the most common "why is my history empty" answer.
• Extension points to lean on. If the package allows overriding the audit payload or substituting your own audit model, use that for redaction and for adding tenant/actor columns rather than forking the package — forking an 0.0.x dependency is a maintenance trap.