Laravel Loggable Laravel Package

Getting Started

1. Install the package:

   composer require alkhachatryan/laravel-loggable
   

   Treat this as a compatibility-sensitive step: the package is archived and its last release was February 2020, so it targets the Laravel 5.8–7 era. Check composer.json constraints before adding it to a modern app.

2. Publish the config and migration:

   php artisan vendor:publish --provider="Alkhachatryan\LaravelLoggable\LaravelLoggableServiceProvider"
   

   This should give you config/loggable.php and a migration for the log table. Verify the published file names against the README, since the package is old enough that docs and code may drift.

3. Run the migration:

   php artisan migrate
   

4. Add the Loggable trait to a model:

   use Alkhachatryan\LaravelLoggable\Loggable;
   
   class Order extends Model
   {
       use Loggable;
   
       protected $logExcept = ['internal_notes', 'payment_token'];
   }
   

   Confirm the exact property names ($logOnly, $logExcept, $logAttributes, etc.) in the package source or README before relying on them.

5. Where to look first:

   • config/loggable.php — default logger, available drivers, and any auth/user settings.
   • The published migration — table name, columns, and JSON/text storage for old/new values.
   • The Loggable trait source — which Eloquent events are hooked and how changes are captured.

6. First useful use case: add the trait to User, Order, or another business-critical model, then render a per-record history in an admin screen. A developer should be able to answer “who changed this record, when, and what changed?” without writing custom audit code.

Implementation Patterns

• Trait-based automatic logging. Put the trait on models where audit history matters. The package hooks Eloquent events (created, updated, deleted, and possibly restored) and writes a log entry automatically. Controllers and services do not need manual logging calls for normal Eloquent saves.

• Whitelist or blacklist attributes deliberately. For most apps, log only business-relevant columns and exclude secrets. A practical pattern is to exclude password, remember_token, API tokens, and free-text PII fields unless there is a compliance reason to retain them.

• Use the database logger for queryable audit trails. Database logging is the default choice when support staff or admins need to search history by model, user, or date. Add indexes on loggable_type, loggable_id, user_id, and created_at if the package migration does not already do so.

• Use the file logger for append-only or low-query use cases. If logs are shipped to an external system or only inspected during incidents, a file logger avoids adding write load to the primary database.

• Custom logger drivers are the main extension point. If the built-in database/file loggers do not fit, implement the package’s logger contract and register it in config/loggable.php. This is the right place to integrate Slack, CloudWatch, an SIEM, or an existing audit service — not editing vendor code.

• Handle actor attribution explicitly. The package likely records the authenticated user ID at write time. That works for HTTP requests but not for queued jobs, console commands, or impersonation flows. For those cases, set the user context manually if the package supports it, or route through a custom logger that accepts an actor.

• Query logs through the package model or a relationship. Prefer the package’s log model or a morphMany relationship over raw table queries so you respect its schema and casts. For admin screens, paginate by loggable_id and eager-load the actor if the package exposes a user relationship.

• Manual logging for non-Eloquent changes. Bulk updates such as Order::where(...)->update(...) bypass model events. If those changes need audit coverage, call the logger service explicitly or move the change through model instances.

• Keep the trait off high-churn, low-value models. Session tables, cache tables, and pivot rows usually do not need audit history. Logging every write can double write volume for little benefit.

Gotchas and Tips

• The package is archived and unmaintained. Last release was 2020, and it has low adoption (57 stars). Expect fewer examples, stale docs, and potential breakage on Laravel 9/10+ and PHP 8+. Test in a branch and be prepared to fork or replace it.

• Silent bypasses are easy to miss. saveQuietly(), updateQuietly(), Model::withoutEvents(), and query-builder updates all skip model events, so no log entry is written. Document these exceptions in your team’s conventions.

• Sensitive data can leak into logs. Passwords, tokens, and PII will be stored in plain text unless excluded. Review the logs table as part of security reviews and add redaction in a custom logger if needed.

• Logging failures can affect saves. If the logger writes synchronously and throws, the original model save may fail. Check how the package handles exceptions and consider wrapping custom loggers in try/catch so audit failures do not break business operations.

• Performance and retention are your responsibility. A synchronous insert on every model write adds overhead, and the package does not provide pruning. Plan a retention job or partition the log table before it grows into millions of rows.

• Serialization quirks are common. JSON casts, dates, and large text fields can produce bloated or inconsistently formatted old/new values. Inspect a few real rows after enabling the trait and confirm the data column type can handle the payload size.

• Config changes need a cache clear. After editing config/loggable.php, run php artisan config:clear locally and php artisan config:cache in production. A cached config is a frequent cause of “my logger change did nothing.”

• Watch for table-name collisions. If your app already has a logs table, rename the package table in config before migrating. Check the migration before running it in a shared database.

• Debug with a focused test. Write a feature test that creates and updates a model, then asserts a log row exists with the expected old/new values and actor ID. This quickly reveals whether the trait is registered, events are firing, and the auth context is correct.

• Prefer extension over patching. Use a custom logger class and config overrides for behavior changes. If you must patch the package for modern Laravel compatibility, fork it under your own namespace and pin the fork in composer.json.