README

Statamic Logbook

A production-ready logging and audit trail addon for Statamic.

Statamic Logbook provides a centralized place to review:

• 📘 System logs (Laravel / Monolog)
• 📝 User audit logs (who changed what, and when)

All directly inside the Statamic Control Panel, with filtering, analytics, and CSV export.

✨ Features

System Logs

• Stores application logs directly in the database
• Captures request context (URL, method, IP, user)
• Filter by date, level, and message
• CSV export

Audit Logs

• Tracks user actions across Statamic
• Records what changed → from → to
• Supports entries, taxonomies, globals, navs, and nav trees
• Field-level ignore rules
• Safe truncation for large values
• CSV export

Control Panel

• Native Statamic CP UI
• Fast filtering & pagination
• Modal previews for context & changes
• No frontend frameworks or dependencies

📦 Installation

composer require emran-alhaddad/statamic-logbook

Publish the configuration file:

php artisan vendor:publish --tag=logbook-config

🗄 Database Configuration (Required)

Statamic Logbook requires a database connection defined via .env. If these variables are missing, the addon will not function.

Add the following to your .env file:

LOGBOOK_DB_CONNECTION=mysql
LOGBOOK_DB_HOST=127.0.0.1
LOGBOOK_DB_PORT=3306
LOGBOOK_DB_DATABASE=logbook_database
LOGBOOK_DB_USERNAME=logbook_user
LOGBOOK_DB_PASSWORD=secret

✅ What to do

• Create a dedicated database (example: logbook_database)

• Create a database user with full access to that database

• Add the variables above to .env

• Clear configuration cache:

  php artisan config:clear

❌ What NOT to do

• ❌ Do not use dots (.) in database names — use underscores (_)
• ❌ Do not reuse credentials from unrelated systems
• ❌ Do not point Logbook to a database you do not fully control
• ❌ Do not commit real credentials to version control

🏗 Install Database Tables

Once database variables are set, run:

php artisan logbook:install

This command creates all required tables.

⚙️ Configuration

All configuration options live in:

config/logbook.php

Environment variables are used only for sensitive or environment-specific values.

🧠 Audit Configuration

Ignore noisy or irrelevant fields

LOGBOOK_AUDIT_IGNORE_FIELDS=updated_at,created_at,slug,uri

Limit stored value size

LOGBOOK_AUDIT_MAX_VALUE_LENGTH=2000

Large values are automatically truncated to protect performance and storage.

🗑 Log Retention

Automatically prune old logs after a given number of days:

LOGBOOK_RETENTION_DAYS=365

Run manually:

php artisan logbook:prune

You may also schedule this command via cron.

🔐 Permissions

Logbook registers the following permissions:

• view logbook — View system & audit logs
• export logbook — Download CSV exports

Assign permissions via the Statamic Control Panel.

❌ What NOT to Do

• ❌ Do not log secrets, tokens, or passwords
• ❌ Do not modify Logbook database tables manually
• ❌ Do not disable retention without a cleanup strategy
• ❌ Do not treat audit logs as editable content

Logbook is designed to be read-only from the Control Panel.

🧪 Compatibility

📄 License

MIT License See LICENSE for details.

👤 Author

Built and maintained by Emran Alhaddad GitHub: https://github.com/emran-alhaddad

🧾 Changelog

See CHANGELOG.md for release history.