Audit Service Laravel Package

Getting Started

• Install with composer require whitedigital-eu/audit-service, then publish the package assets: php artisan vendor:publish --provider="WhiteDigital\AuditService\AuditServiceProvider" (check the provider name in the package's composer.json / README if it differs).
• Publish and run the migrations before writing any audit entries. As of 0.7.2 the audit entity schema has moved to the whitedigital namespace, so a fresh install will create the table under that schema/prefix. Run php artisan migrate and confirm the audit table exists with the expected name.
• Inspect config/audit-service.php (or similarly named config) first — it typically controls the database connection, table name, and the model/entity used for audit records. This is the file you will touch most often.
• First use case: register the package's audit trait/observer on a model you already trust (e.g. User or Order) and perform a create/update/delete. Then query the audit table to confirm rows are written with the acting user, event type, and payload.

use WhiteDigital\AuditService\Concerns\Auditable; // verify exact namespace

class Order extends Model
{
    use Auditable;
}

Implementation Patterns

• Trait-based model auditing. Attach the package trait to Eloquent models you want tracked. This is the lowest-friction path and works well for CRUD-heavy domain models.
• Manual audit entries. For actions that aren't Eloquent events (logins, exports, external API calls), resolve the audit service from the container and record an entry explicitly. Wrap this in a small application-level helper so call sites stay tidy.
• Actor resolution. Configure how the current user is resolved (usually the authenticated guard). In queued jobs and console commands there is no authenticated user, so pass an explicit actor ID or use a withoutAuditing/system-actor escape hatch if the package provides one.
• Querying audits. Treat the audit table as read-mostly: build repository/query classes around it for admin dashboards and compliance exports rather than scattering raw queries through controllers.
• Testing. Use RefreshDatabase plus the package migrations, and assert on audit rows in feature tests after triggering model events. For unit tests, fake the audit service binding so you don't hit the database.
• Integration with existing event flows. If you already use model observers or domain events, decide whether the package trait or your own listener owns auditing — running both produces duplicate entries.

Gotchas and Tips

• 0.7.2 schema move is the big one. The audit entity schema changed to whitedigital and a migration was added. Existing installs upgrading from 0.7.1 must review that migration before running it in production: confirm whether it renames/relocates the table or creates a new one, and whether existing audit rows are preserved or need backfilling. Back up the audit table first — audit data is often the thing you can least afford to lose.
• Fresh vs. existing databases. 0.7.2 also "improves migration for non-existent scenarios," which suggests earlier migrations could fail when the table/schema didn't already exist. This should make clean installs and CI pipelines smoother, but re-run your full migration path from scratch (migrate:fresh) in a staging database to confirm.
• Schema/prefix assumptions leak into config. If your config, custom queries, or reporting tools hardcode the old table name or schema, update them alongside the migration.
• Connection mismatch. Audit writes can silently go to a different connection than your app models if the package config specifies one. Verify both point where you expect in each environment.
• Queues and console. Auditing that depends on the authenticated user will record a null/system actor in jobs and Artisan commands. Make actor resolution explicit for these paths.
• Noisy payloads. Full attribute snapshots on large models bloat the audit table quickly. Check whether the package supports hidden/ignored attributes and prune or archive old audit rows on a schedule.
• Extension points. Prefer overriding the audit model/entity and service binding via the container over editing vendor files; this keeps you upgrade-safe across the fast-moving 0.7.x line.
• Pin the version. At 0.7.x with schema changes landing in patch releases, pin whitedigital-eu/audit-service to an exact version and read each changelog before bumping.