README

Unified audit logging for Laravel: automatically log create, update, delete (plus restore/force_delete) with diffs, actor, and minimal context.

Install

1. Require the package (once published to Packagist):

composer require logforge/logforge-laravel

1. Publish config and migrations:

php artisan vendor:publish --tag=logforge-config
php artisan vendor:publish --tag=logforge-migrations

1. Run migrations:

php artisan migrate

Note: The audit_logs migration is designed to run last (timestamp: 2025-12-31 23:59:59) to ensure all user and resource tables exist before creating foreign key constraints.

Configure

Edit config/logforge.php.

• enabled: turn logging on/off
• events: ['create','update','delete','restore','force_delete']
• include/exclude/redact: global attribute controls
• per_model[Your\Model::class]: per-model include/exclude/redact
• context.capture_ip / context.capture_user_agent
• payload_max_bytes, suppress_exceptions, actor.resolver
• writer: 'db' (default, synchronous) or 'queue' (asynchronous)
• queue: connection, queue name, delay settings

ENV overrides:

• LOGFORGE_ENABLED, LOGFORGE_SNAPSHOT_ON_UPDATE, LOGFORGE_PAYLOAD_MAX_BYTES, LOGFORGE_SUPPRESS_EXCEPTIONS
• LOGFORGE_RETENTION_DAYS, LOGFORGE_ARCHIVE_ENABLED, LOGFORGE_ARCHIVE_PATH
• LOGFORGE_WRITER, LOGFORGE_QUEUE_CONNECTION, LOGFORGE_QUEUE_NAME, LOGFORGE_QUEUE_DELAY

Writer Options

Database Writer (Default)

• writer => 'db': Synchronous database writes
• Pros: Works immediately, no setup required, guaranteed delivery
• Cons: Slower response times, blocks user request
• Best for: Development, testing, low-volume production

Queue Writer (Recommended for Production)

• writer => 'queue': Asynchronous queue-based writes
• Pros: Better performance, non-blocking, scalable
• Cons: Requires queue worker, potential for lost logs if worker fails
• Best for: High-volume production environments

Setting Up Queue Writer

1. Change configuration:

   // config/logforge.php
   'writer' => 'queue',

2. Start queue worker:

   php artisan queue:work

3. Or use database queue:

   php artisan queue:table
   php artisan migrate
   php artisan queue:work

⚠️ Important: Queue writer requires a queue worker to be running. If no worker is active, audit logs won't be written.

Use

Add the trait to any Eloquent model:

use LogForge\Laravel\Audit\Traits\LogsActivity;

class Post extends Model
{
    use LogsActivity;
}

On create/update/delete/restore/forceDelete, an audit_logs row is written with:

• event_type, user_id, resource_type, resource_id
• data (diffs/snapshots), ip_address, context (user_agent)

Note: By default, logs are written synchronously to the database for immediate results. For better performance, set LOGFORGE_WRITER=queue and ensure your queue worker is running.

Update event payload example

For updates, data stores a before/after diff of changed fields:

{
  "old": { "title": "Old title", "status": "draft" },
  "new": { "title": "New title", "status": "published" }
}

If full snapshots are enabled (snapshot_on_update=true), the new section also includes a __full key:

{
  "old": { "title": "Old title" },
  "new": {
    "title": "New title",
    "__full": { "id": 123, "title": "New title", "status": "published" }
  }
}

Example model

See examples/ExamplePost.php for a minimal example using SoftDeletes and LogsActivity.

Maintenance

Pruning old logs

Remove old audit logs to manage storage:

# Use configured retention_days
php artisan logforge:prune

# Override retention period
php artisan logforge:prune --days=30

# Archive before deleting (creates timestamped JSON file)
php artisan logforge:prune --archive

Archive files are saved to storage/logs/logforge/ by default (configurable via LOGFORGE_ARCHIVE_PATH).

Archive format:

{
  "metadata": {
    "pruned_at": "2025-01-28T14:30:22.000000Z",
    "retention_days": 30,
    "cutoff_date": "2024-12-29T14:30:22.000000Z",
    "records_count": 150,
    "format": "json"
  },
  "records": [...]
}

Performance monitoring (optional)

Enable lightweight performance diagnostics to spot bottlenecks:

ENV:

LOGFORGE_PERF_ENABLED=true
LOGFORGE_PERF_SLOW_MS=100   # warn if an audit takes >= 100ms
LOGFORGE_PERF_SAMPLE=1.0    # sample rate 0..1 (1.0 = all)

Behavior:

• Measures total time and splits build_ms vs write_ms.
• Emits a structured warning when total_ms >= threshold.
• Uses Laravel’s default logger (e.g., storage/logs/laravel.log) and respects your logging channels.

Example log payload:

{
  "event_type": "update",
  "model_class": "App\\Models\\Post",
  "model_key": "123",
  "total_ms": 142,
  "build_ms": 35,
  "write_ms": 107
}

Notes

• Fail-safe: DB write failures are suppressed (configurable) and logged.
• JSON: uses JSON column; ensure your DB supports it (MySQL 5.7+, PostgreSQL, SQLite JSON via TEXT).
• Extensibility: config supports per-model overrides; writer abstraction can be added later for queues/streams.
• Archive: Enable automatic archiving via LOGFORGE_ARCHIVE_ENABLED=true in your .env.
• Queue: Default synchronous logging via database. For asynchronous logging, set LOGFORGE_WRITER=queue and ensure queue worker is running. Jobs are retried up to 3 times with 30-second timeout.

Enable Dashboard (config only)

The dashboard is disabled by default. To enable routes like /logforge/logs, set:

LOGFORGE_DASHBOARD_ENABLED=true

Optional (defaults shown):

LOGFORGE_DASHBOARD_PATH=logforge

Note: When enabling, ensure your app’s authentication is set up (web session login) and protect access according to your needs (e.g., Gate).