Download the PHP package mahmoud-mhamed/spatie-activitylog-browse without Composer

Activity Log Browse

A Laravel package that extends spatie/laravel-activitylog v4 with automatic model logging, rich contextual enrichment, a web-based log browser, a statistics dashboard, automatic retention/cleanup, and a deletion audit trail — all with English/Arabic UI, dark mode, and an optional password gate.

Arabic version: README.ar.md

Features

Logging

• 🔁 Auto-log all models without the LogsActivity trait — opt-out via excluded list
• 📦 Rich enrichment — request, device, performance, app, session, and execution context attached to every log entry
• 🆔 UUID-friendly — morph ID columns automatically migrated to support UUIDs
• ⚡ Performance-optimized — per-class caching, request-scoped collectors, no per-event reflection

Browsing & Analytics

• 🌐 Browse UI — filter, search, popovers, color-coded diffs, related-model navigation
• 📊 Statistics dashboard — charts for hourly/daily/monthly activity, peak times, top models/causers/attributes
• 🌍 Localized — English & Arabic with automatic RTL layout
• 🌙 Dark mode — system-aware with manual toggle, persisted in localStorage
• 📝 Attribute translation — uses Laravel's validation.attributes

Cleanup & Audit

• 🧹 Manual cleanup page — preview-then-delete with model and date filters
• ⏱ Automatic retention — age + size limits, per-model overrides (incl. 'forever'), Laravel-scheduler integration
• 📜 Deletion history — JSON audit log of every cleanup with row-level diff (before/after, duration, trigger, user)

Security

• 🛡 Optional password gate with rate-limited login (5/min)
• 🚪 Authorization gate support for fine-grained permissions
• 🏢 Multi-tenancy aware (works out of the box with stancl/tenancy)

Table of Contents

• Requirements
• Installation
• Quick Start
• Configuration
  • Auto-Log
  • Enrichment
  • Browse UI
  • Password Gate
  • Retention / Auto-Cleanup
  • Deletion History
• Usage
• Browse UI
• Statistics Dashboard
• Deletion History Page
• Artisan Commands
• Localization
• Multi-Tenancy
• Performance Notes
• Architecture
• License

Requirements

• PHP 8.1+
• Laravel 10, 11, or 12
• spatie/laravel-activitylog ^4.0

Installation

If auto-discovery doesn't work, register the provider manually in bootstrap/providers.php (Laravel 11+) or config/app.php:

Then run the install command — publishes the spatie migration, the package config, runs migrations, fixes UUID-friendly morph columns, adds performance indexes, and prepares the deletion-history storage:

Re-running install after upgrading the package will offer to refresh your config so new options (e.g. retention, deletion_history) are picked up.

Publishing individual assets

Tip: Use --force to overwrite previously published files after upgrading the package:

Local Development

To install as a local path repository, add the following to your Laravel app's composer.json:

Quick Start

After running activitylog-browse:install:

1. Open /activity-log in your browser — protected by web + auth middleware by default.
2. Trigger any model change — it'll appear with full enrichment.
3. (Optional) Enable retention in config/activitylog-browse.php so old logs prune themselves.
4. (Optional) Set ACTIVITYLOG_BROWSE_PASSWORD in .env to add a password gate.

Configuration

The published config file is at config/activitylog-browse.php. Key sections below.

Auto-Log

Models that already use the LogsActivity trait are automatically skipped to prevent duplicate entries.

Enrichment

Each enrichment section can be enabled/disabled and has per-field toggles. Disabling an entire section removes all per-event overhead for that section.

Browse UI Config

Set gate to a Laravel Gate name to restrict access; the package will call Gate::authorize($name) on every browse request.

Password Gate

For environments where you want a shared password protecting the browse UI (in addition to whatever auth/middleware you've configured):

When set, users hitting /activity-log are redirected to a login screen. The form is rate-limited to 5 attempts per minute per IP. Authentication is stored in the session — a logout button appears in the navbar when a user is signed in via password.

Set the env variable to an empty value (or remove it) to disable the gate entirely.

Retention / Auto-Cleanup

Automatically prune old activity log entries based on age and table size limits, with per-model overrides for sensitive data that should be kept longer (or forever).

Priority hierarchy (strongest → weakest)

1. per_model / per_log_name — always win.
   • 'forever' is fully protected from both age and size pruning.
   • An int day count protects records younger than the configured days from BOTH age and size pruning.
2. max_rows / max_size_mb — hard size caps. They win over default_days: when the table is over the cap, the oldest records (not protected by a per-model rule) are deleted even if they are still inside the default_days window.
3. default_days — the catch-all rule. Applies only to records not covered by a higher-priority rule.

What happens at the size limit?

TL;DR: Per-model retention is the authoritative rule. A model set to 365 days will keep its rows for the full 365 days even if the table is over its size cap — they only become eligible for size pruning after their own retention window expires. The size cap is therefore best-effort: if every record is still inside its per-model retention window, nothing is deleted and the table stays over the cap until the protections expire. Set realistic per-model values to keep the size cap effective.

How it runs

Deletion History Config

Every cleanup operation (manual, scheduled, CLI, dry-run) is recorded in an append-only JSON file:

Each entry captures: timestamp, trigger (schedule/cli/ui/manual), operation type, deleted count + breakdown, duration, table state before/after (rows + size MB), config snapshot, and user/IP context. Empty operations (0 rows deleted) are skipped.

The package automatically creates the storage directory and a .gitignore to prevent committing the JSON file.

Usage

Auto-Logging

Once installed, all Eloquent model events are logged automatically:

To exclude specific models:

Enrichment payload

Every activity log entry — whether from auto-logging, the LogsActivity trait, or manual activity() calls — is enriched with contextual data:

Browse UI

Visit /activity-log (or your configured prefix). Top navigation includes: Activity Log, Statistics, Cleanup, Deletion History, About — plus a language switcher, theme toggle, and (when password gate is on) logout.

The list view provides:

• Filtering — log name, event type, model type, model ID, causer, date range, description search
• Changed-attribute filter — select a model type, then filter by a specific attribute (e.g. only show logs where name changed)
• Quick preview popover — hover the info icon on a row to see the old/new diff inline
• Current-attributes popover — view the subject's live model data without leaving the list
• Model info sidebar — when a model type is selected, shows total logs, unique records, table name, table size, event-breakdown badges, and clickable attribute chips for quick filtering
• Related model navigation — jump to all logs for a related model instance
• Detail view — color-coded diff, request/device/performance/app/session/execution metadata, raw JSON

Attribute translation

Attribute names (column names like first_name, email_verified_at) are auto-translated using lang/{locale}/validation.php:

• If validation.attributes.{key} exists → "First Name" (first_name)
• Otherwise → "Email Verified At" (auto-headlined) with the original key in small text

Define translations once and they appear everywhere in the UI:

Statistics Dashboard

Visit /activity-log/statistics. Each section loads independently via AJAX with skeleton states for fast initial render.

A date-range filter at the top applies to all sections (cached for 60s when filtered, 120s for all-time).

Sections: Overview cards · Peak Hour chart · Daily Activity (30 days) · Activity by Day of Week · Peak Times · Monthly Activity · System vs User Actions · Events Breakdown · Log Names · Top Models · Top Causers · Most Changed Attributes (last 1000 updates).

Deletion History Page

/activity-log/deletion-history — auditable record of every cleanup operation:

• Stats cards — total entries, file size, current path
• Per-row — when, trigger badge (color-coded: schedule/cli/ui/manual + dry-run flag), operation, deleted count + breakdown (age vs size), table size before → after with diff, duration in ms, user/IP/command
• Expandable JSON — click a row to see the full entry payload (config snapshot, table state, context)
• Pagination — 25 per page
• Clear button — wipes the JSON file (with confirmation)

Artisan Commands

The prune command is automatically registered with the Laravel scheduler when retention.schedule is set (and you have schedule:work or cron running).

Localization

The package ships with English and Arabic translations. The UI auto-adapts to RTL when locale is ar.

Or at runtime:

The browse UI also includes a language switcher button that saves the preference in the session.

To customize translations:

This copies the files to lang/vendor/activitylog-browse/ where you can edit them or add new languages — then update available_locales in the config.

Multi-Tenancy

Works out of the box with stancl/tenancy (multi-database tenancy):

• Cache isolation — keys are prefixed with the tenant ID (e.g. activitylog-browse:t:1:stats:overview).
• Database connection — queries use whatever connection your Activity model defines.
• No hard dependency — tenant detection uses function_exists('tenant').

Setup for multi-database tenancy

1. Disable automatic migrations so they don't run on the central DB:

2. Publish migrations to your tenant migration path:

   Then move them to database/migrations/tenant/ (or wherever your tenant migrations live).

3. Add tenancy middleware to the browse routes:

Without tenancy, no extra setup is needed — everything works as expected.

Performance Notes

The package is designed for low-overhead operation even on high-traffic apps with auto-logging enabled:

• Per-class caching in GlobalModelLogger — LogsActivity trait detection runs once per model class, not per event
• Request-scoped collectors — debug_backtrace, auth guard enumeration, and source detection run once per request, results cached as static properties
• Disabled-aware enrichment — the observer only invokes collectors that are enabled in config; disabled sections add zero per-event overhead
• Console-only schedule registration — HTTP requests skip scheduler binding entirely
• Bulk-friendly delete chunks — retention pruning runs in chunks of 1000 (configurable) with set_time_limit(30) to avoid table-lock storms

For best results on high-throughput apps:

• Add high-frequency models to excluded_models
• Disable execution_context.fields.job_name if you don't need queue tracking (skips a debug_backtrace per request)
• Use Model::withoutEvents(...) around bulk imports

Architecture

License

MIT — see LICENSE.