Download the PHP package arpanihan/auditify without Composer

Auditify — High-Performance, Decoupled Audit Logging for Laravel

Auditify is an easy-to-use, high-performance audit logging and threat detection package for Laravel.

🔗 Official Landing Page & Demo: arpa12.github.io/laravel-auditify-landingPage

Unlike standard logging libraries, Auditify uses a decoupled database design to separate logs into three distinct tables. This optimizes database table indexing, reduces write congestion, and guarantees clean scale organization as your application grows.

Table of Contents

• Requirements
• Features
  • Dashboard
  • Reports & Analytics Module
  • Decoupled Log Modules
  • Real-Time Threat Engine
  • XSS Attack Shield
  • Frontend Event Logging API
  • Admin-Only Access & Custom Authorization Gate
• Installation
• Configuration
• Manual Logging & Helper Methods
• Artisan Commands
• Routes Reference
• Testing
• Author
• License

🖥️ Requirements

🚀 Features

📊 Dashboard

URL: /auditify

The main glassmorphic dashboard aggregates action logs, page visits, and threat alerts into an interactive screen:

• Metrics counters — total action logs, activity logs, and security logs with unread indicators.
• Log summaries — breakdowns of operations (Create, Update, Delete) and authentication events (Login, Logout).
• 7-day trend graph — comparative daily counts of Actions vs Activities plotted on Chart.js.
• Top active users & top modified modules — lists of most active user IDs and frequently changed models.
• Live recent logs — lists of the most recent visitor actions and security alerts.

📈 Reports & Analytics Module

URL: /auditify/reports

A comprehensive reporting panel offering detailed statistical breakdowns over custom timeframes (Last 7 Days, Last 30 Days, or Last 90 Days) featuring interactive Chart.js charts:

• Overview Analytics: System log activity trends mapped using multi-line charts.
• Action Reports: Actions by type (Doughnut Chart) and most changed models (Horizontal Bar Chart), coupled with a detailed database modifications table and CSV/Excel/PDF download options.
• Activity Reports: Top visited pages/URLs (Horizontal Bar Chart) and peak activity hours (Bar Chart), coupled with a detailed activity table and CSV/Excel/PDF download options.
• Security Reports: Alerts by severity (Doughnut Chart), top threat origin IPs (Bar Chart), and resolution status distribution (Pie Chart), coupled with a detailed security incident table and CSV/Excel/PDF download options.
• Format Exports: Support for exporting timeframe-filtered reports in CSV, Excel (xlsx), and clean printable PDF formats.

🗄️ Decoupled Log Modules

Auditify separates data logging into three target models under Auditify\Models to avoid write bottlenecks. Here is the exact database schema and attributes captured for each log type:

Action Logs (ActionLog)

• Table Name: audit_action_logs
• Purpose: Tracks Eloquent database modifications (inserts, updates, deletes, and restores).
• Captured Attributes / Database Columns:
  • id (BigInt, Primary Key)
  • user_id & user_type (Nullable Morphs) — Polymorphic relationship to the user making the database modification.
  • subject_id & subject_type (Nullable Morphs) — Polymorphic relationship to the actual model being modified.
  • action (String) — The query event (created, updated, deleted, restored).
  • module (String) — Name of the affected model module/class (e.g., Post, User, Role).
  • description (Text, Nullable) — Friendly readable log summary description.
  • old_values (JSON, Nullable) — Casted array of model attribute values before the operation.
  • new_values (JSON, Nullable) — Casted array of model attribute values after the operation.
  • ip_address (String, Nullable) — IP address of the client triggering the event.
  • url (Text, Nullable) — HTTP Request URL where the change originated.
  • user_agent (Text, Nullable) — HTTP User-Agent string.
  • created_at & updated_at (Timestamps)

Activity Logs (ActivityLog)

• Table Name: audit_activity_logs
• Purpose: Logs visitor requests, navigation, custom application actions, and auth flows. Features a dedicated detail page view (GET /activity-logs/{id}) to inspect logged metadata.
• Captured Attributes / Database Columns:
  • id (BigInt, Primary Key)
  • user_id & user_type (Nullable Morphs) — Polymorphic relationship to the visitor (if authenticated).
  • activity (String) — The type of operation/activity (e.g., Page Visit, Login, Logout, Failed Login, or custom events).
  • properties (JSON, Nullable) — Casted array storing context metadata or custom event payloads.
  • url (Text, Nullable) — Request URL path.
  • ip_address (String, Nullable) — Visitor IP address.
  • user_agent (Text, Nullable) — Visitor User-Agent string.
  • created_at & updated_at (Timestamps)

Security Logs (SecurityLog)

• Table Name: audit_security_logs
• Purpose: Logs alerts generated by the XSS protection middleware, rate limits, or automated threat rules.
• Captured Attributes / Database Columns:
  • id (BigInt, Primary Key)
  • user_id & user_type (Nullable Morphs) — Polymorphic relationship to the user (if authenticated).
  • severity (String) — Alert priority (low, medium, high, critical).
  • title (String) — Brief name of the incident (e.g., XSS Attack Blocked, Failed Logins Peak).
  • description (Text, Nullable) — In-depth details regarding why the threat was flagged.
  • is_read (Boolean) — Read/unread toggle flag for admin dashboard alerts.
  • status (String) — Alert resolution state (pending or resolved).
  • resolved_at (DateTime, Nullable) — Timestamp when the incident was marked resolved/read.
  • resolution_notes (Text, Nullable) — Text explaining the resolution strategy.
  • method (String, Nullable) — Request HTTP method (GET, POST, etc.).
  • route_name (String, Nullable) — Named route where the attack/alert occurred.
  • payload (JSON, Nullable) — Casted request body payload parameters scanned by the security shield.
  • ip_address (String, Nullable) — Origin IP address of the incident.
  • user_agent (Text, Nullable) — Incident Client User-Agent.
  • created_at & updated_at (Timestamps)

📈 Real-Time Threat Engine

Auditify automatically monitors activity logs and logs high-priority Security entries when rules are broken:

• Mass Delete Shield: Fires a critical security log if a user deletes 5 or more records (default) in a single model within 5 minutes.
• Bulk Update Shield: Fires a high security log if a user updates 10 or more records (default) in a single model within 5 minutes.
• Failed Logins monitor: Tracks failed logins. Fires a high security log if 3 or more failed login attempts are recorded within 5 minutes.
• Sensitive Module monitor: Triggers a medium security log whenever models listed in sensitive_modules (e.g. User, Role, Permission, Setting, Config) are modified.
• Permission Changes: Triggers a high security log whenever a permission, role, or gate mapping is added, modified, or deleted.

🛡️ XSS Attack Shield

Auditify has built-in XSS protection. It automatically scans all incoming request parameters (such as $_GET or $_POST) and route variables.

If it detects common XSS patterns (like <script>, javascript:, or SVG events), it:

1. Logs a critical security log entry.
2. Returns an HTTP 403 Forbidden response to block the request.

If you have pages that require rich text input (e.g. admin markdown or HTML editors), exclude them in your config/auditify.php file:

🔌 Frontend Event Logging API (Optional)

[!NOTE] What is this for? Standard backend code (like Laravel/PHP) cannot see what happens inside the user's browser. Out-of-the-box, it cannot track when a user clicks a button, closes a modal, or downloads a file.

This API provides a built-in route (/auditify/api/events) so you can easily send browser actions straight into your Activity Logs via JavaScript—without needing to write your own custom API controllers and routes. You can ignore this if you don't need to track frontend actions.

How to use it:

1. Create a reusable JavaScript helper to send a POST request (which automatically attaches Laravel's CSRF security token):

2. Trigger it on user actions (like clicking a button or a download link):

⚛️ Vue & React Integration (SPAs)

If your application uses a frontend framework like React or Vue.js:

• Same-domain or Laravel Inertia: You can call the /auditify/api/events endpoint directly using axios or fetch. Session cookies and CSRF security are handled automatically by the browser.
• Decoupled Setup (Different Domains): If your React/Vue frontend is hosted separately from your Laravel API:
  1. Add your frontend domain to the allowed origins list in Laravel's CORS configuration (config/cors.php).
  2. Authenticate requests via Laravel Sanctum or standard authorization headers so Auditify can link the logged events to the correct user.

⚛️ React Component Example (using Axios)

💚 Vue 3 Component Example (using Fetch API)

🔐 Admin-Only Access & Custom Authorization Gate

[!IMPORTANT] Who should access the logs? The Auditify log database and visual dashboard (/auditify) contain highly sensitive information including user IP addresses, request payloads, model modifications, and security alert histories.

Regular application users must never have access to this package. It is designed exclusively for system administrators, super-admins, and security officers.

By default, the package enables access control if configured in config/auditify.php. You should register an authorization callback inside your application so developers can custom-define exactly who is classified as an authorized admin.

To restrict dashboard views and log downloads to administrators only, register an authorization callback inside the boot method of your app/Providers/AppServiceProvider.php:

📦 Installation

1. Install via Composer

Run this command in your project root:

2. Run the Installer

Run the installation command to publish configuration files, copy migrations, and set up your database automatically (this command will also automatically clear your application cache using optimize:clear):

3. Clear Application Cache (Optional)

If needed, you can manually clear all cached configuration, routes, views, and other cached data to ensure Auditify loads the latest settings:

4. Start the Laravel Development Server

If your application is not already running, start the Laravel development server:

5. Access the Dashboard

Once the installer completes successfully, open your web browser and navigate to the Auditify dashboard URL:

(Note: If you change the 'route_prefix' config setting inside config/auditify.php, this route URL will update accordingly).

4. (Optional) Selective Model Auditing

By default, Auditify automatically audits all Eloquent models globally without any manual setup.

However, if you turn off global auditing ('auto_audit_models' => false) and prefer to manually select which models to audit, add the Auditable trait:

⚙️ Configuration

After publishing, customize your settings in config/auditify.php:

🔌 Manual Logging & Helper Methods

You can manually trigger Auditify logs or temporarily pause auditing from your own Laravel controllers, background jobs, or seeders using the Auditify facade.

[!TIP] Why use manual logging?

• Capture Intent over CRUD: Automated auditing only tracks database changes (inserts/updates). It cannot know when a user performs a non-CRUD action like downloading a PDF report, requesting a password reset, or opening a modal.
• Standardize Multi-step Workflows: Instead of cluttering logs with 10 automated database change entries during a checkout flow, you can pause automatic logging and write a single, clean entry (e.g., User Completed Purchase).
• Log Custom Threat Metrics: Manually document custom suspicious behaviors (like rate-limit hits, coupon code abuse, or restricted API probes) using Auditify::logSecurity.
• Optimize Seeding & Imports: Turn off auditing during massive database seeding or CSV user imports to prevent database write congestion, performance lags, and log spam.

1. Manual Log Generation

Import the facade in your file:

Manually Log a Database/Module Action

Manually Log a User Activity

Manually Log a Security Alert

Real-World Controller Example

Here is a practical example of how to implement manual logging inside a standard Laravel controller, complete with code comments:

2. Pausing Auditing (Seeders & Batch Imports)

When running data migrations, database seeders, or large CSV imports, you should temporarily disable logging:

• Prevent Database Congestion (Performance): Auditing bulk inserts doubles database queries (100k records = 200k queries). Pausing logs prevents database lockups and speeds up imports.
• Prevent Table Bloat (Log Spam): Seeders generate fake mock data. Pausing auditing prevents these fake records from filling up your audit log tables and slowing down search speeds.

Option A: Running a closure (Recommended for Seeders & Migrations)

Where to use: In database/seeders/DatabaseSeeder.php or data migration files.

This helper automatically pauses auditing for the duration of the callback execution and safely restores the previous auditing state.

[!TIP] Why Option A is recommended (Exception Safe): If an error occurs inside your import/seeder logic, this helper uses an underlying PHP finally block to guarantee that auditing is safely re-enabled for all subsequent requests.

Option B: Manually toggle auditing (Recommended for Artisan Commands & Test Suites)

Where to use: In custom Artisan console commands (app/Console/Commands/ImportData.php) or PHPUnit test setups (tests/TestCase.php).

Directly turns the auditing flag on or off.

[!WARNING] Use Option B with caution: If your code throws an exception after calling disableAuditing(), it will crash before reaching enableAuditing(), leaving auditing permanently disabled on that PHP worker/process. Only use this option when a closure structure cannot be used.

🛠️ Artisan Commands

Auditify provides dedicated commands to automate installation and database size optimization:

1. Why use the commands?

• auditify:install (Simpler Onboarding): Eliminates manual setup. Rather than forcing developers to copy configurations, move migration files, and migrate tables separately, this sets up the entire package in a single terminal line.
• auditify:prune (Optimize DB Speed & Storage): High-traffic production systems generate millions of logs. Storing logs indefinitely slows down database queries, increases backup sizes, and increases storage costs. Pruning deletes outdated entries, ensuring instant dashboard rendering and compliance retention alignment (e.g., GDPR, SOC2).

2. Automated Database Pruning Setup

To keep database tables small and performant automatically, schedule the pruning command in your application's task scheduler in routes/console.php (or app/Console/Kernel.php):

[!TIP] Set It and Forget It: Automating the pruning command to run daily ensures your database size remains constrained and healthy without manual administrator intervention. It is recommended to schedule it during low-traffic night hours.

🗺️ Routes Reference

All routes are grouped under the configured route_prefix (default: auditify) with the configured middleware.

🧪 Testing

The package features a comprehensive PHPUnit test suite covering models, middlewares, controller endpoints, and Artisan commands. Standalone tests run via orchestra/testbench without requiring a parent Laravel installation.

Clone the repository and install development dependencies:

Run all tests:

👤 Author

Arpa Nihan
Full Stack Developer

📄 License

Released under the MIT License.

⭐ If Auditify saves you time, please give it a star on GitHub! ⭐

Made with ❤️ for the Laravel Community

Copyright © 2026 Arpa Nihan. All rights reserved.