Action Logger Laravel Package

Getting Started

This package is part of the Laravel Enso ecosystem, so it assumes you already have an Enso application bootstrapped (laravel-enso/enso or the core Enso packages installed). Do not try to drop it into a vanilla Laravel app — you will fight the enso config namespace, the Enso User model, and the menu/permission scaffolding.

Minimal steps:

1. composer require laravel-enso/action-logger
2. Run the package migrations (php artisan migrate) — expect an action_logs table (model: LaravelEnso\ActionLogger\Models\ActionLog).
3. Rebuild the Enso menu (php artisan enso:menu:rebuild or the equivalent in your Enso version) so the "Action Log" entry shows up in the admin sidebar.
4. Grant the relevant permission to the roles that should see logs.

Where to look first:

• config/enso/action-logger.php (or the merged enso config) — this is where retention, model bindings, and the route-prefix live.
• src/Http/Controllers/ActionLogController.php — the JSON endpoint the Enso table component consumes.
• The ActionLog model + migration — check the columns so you know what's actually being captured (user id, model type/id, action, timestamps).

First useful use case: open the Action Log page in the Enso UI and confirm that a test edit on any tracked model (e.g. a user) produces a new row with created_by/model/action. If it does, the package is wired up correctly and you can move on to extending it.

Implementation Patterns

Model-level logging (the primary pattern). Attach the package's logging trait (or observer) to the models you want audited. In Enso this is usually done via a LogsActions-style trait or by registering the provider's observers. The convention in Enso is that any model change in a tracked model produces an action entry — so be deliberate about which models you attach it to, not just "all of them."

Wrapping user-generated operations. For custom commands/actions that aren't model events, log manually:

ActionLog::create([
    'model'     => $someModel->getMorphClass(),
    'model_id'  => $someModel->id,
    'action'    => 'approved',
    'created_by'=> auth()->id(),
]);

Wrap this in a service or job so it isn't scattered through controllers.

Reading logs from the UI. The package ships an Enso table component (Vue) driven by the controller endpoint. If you need a custom admin view, reuse the same controller but filter server-side: build filters as query parameters so the Enso Table component's pagination and search keep working.

Diffing changes. The most valuable audit data isn't the action name — it's what changed. When you attach the trait, capture before/after payloads (Enso models often already do this through activity() or a Revisionable-like trait). Storing the delta on the log row makes the UI readable and avoids joins later.

Integration tip — scoping by team/tenant. Enso logs include created_by. In multi-tenant Enso setups, denormalize a tenant_id (or team id) into the log row at write time. Reading it back later with a join to users is fragile if users move between teams.

Gotchas and Tips

• Enso version lock-step. laravel-enso/action-logger tracks the Enso release cycle. A minor Enso bump can break the trait, menu rebuild, or config keys. Pin Enso and its satellites together in composer.json and bump them as a set — never upgrade one satellite alone.
• "Who did what" is only as good as your auth()->id(). Console commands, queue jobs, and scheduled tasks have no authenticated user. Default created_by to a system user id (or 0) rather than letting it be NULL, and document that convention — otherwise every cron-driven change looks like an anonymous mutation.
• Mass assignment and bulk queries bypass logging. Model::query()->update([...]) and DB::table(...) fire no model events. If you rely on the trait, you will silently miss those. For anything critical, log explicitly around the bulk operation.
• Retention & volume. Action logs grow monotonically. Check the config for a prune/retention setting; if none is set, schedule your own ActionLog::where('created_at', '<', now()->subDays(90))->delete() and index (model, model_id) and created_by on the table — the default migration may not include those for a large dataset.
• Permission gating. Seeing the sidebar entry isn't the same as being allowed to query the endpoint. Verify roles/permissions in Enso (the Route is typically behind action-logger.index/show), and double-check the controller uses Enso's authorization middleware — an untracked endpoint here leaks audit data.
• Menu not appearing. After install, the #1 issue is "the menu item doesn't show." Run the Enso menu rebuild, then check resources/menu.json (or config/enso/menu.php) for the action-logger entries and clear cache (php artisan cache:clear — Enso caches menus in Redis by default).
• Extension point — override the model. If you need extra columns (IP, request id, tenant id), extend the package's ActionLog model and rebind it in a custom service provider / config binding, rather than editing the package's migration. Migrations shipped by satellites should be treated as read-only.
• Debugging a missing entry. Confirm in order: (1) the trait/observer is actually attached to the model, (2) the model event fires (it's not a raw query builder call), (3) the user has a valid id, (4) the migration ran and no DB constraint (created_by FK) is failing silently. Enso often swallows DB exceptions in jobs — check storage/logs/laravel.log explicitly.