Download the PHP package iamfarhad/laravel-audit-log without Composer

Laravel Audit Logger

Overview

Laravel Audit Logger is a powerful and flexible package designed to provide detailed audit logging for Laravel applications. It enables tracking of all changes to your Eloquent models, ensuring compliance with regulatory requirements, aiding in debugging, and maintaining data integrity. Built with modern PHP and Laravel practices, this package adheres to strict typing, PSR-12 coding standards, and leverages dependency injection for maximum testability and maintainability.

Table of Contents

• Features
• Requirements
• Installation
• Configuration
• Usage
  • Basic Usage
  • Advanced Usage
• Customizing Audit Logging
• Retrieving Audit Logs
• Performance Optimization
• Testing
• Security Best Practices
• Troubleshooting
• Contributing
• License

Features

• Entity-Specific Audit Tables: Automatically creates dedicated tables for each audited model to optimize performance and querying.
• Comprehensive Change Tracking: Logs all CRUD operations (create, update, delete, restore) with old and new values.
• Customizable Field Logging: Control which fields to include or exclude from auditing.
• User Tracking: Automatically identifies and logs the user (causer) responsible for changes.
• Event-Driven Architecture: Utilizes Laravel Events for decoupled and extensible audit logging.
• Batch Processing: Supports batch operations for high-performance logging in large-scale applications.
• Type Safety: Built with PHP 8.1+ strict typing and modern features like readonly properties and enums.
• Extensible Drivers: Supports multiple storage drivers (currently MySQL) with the ability to implement custom drivers.
• Automatic Migration: Seamlessly creates audit tables for new models when enabled.

Requirements

• PHP: 8.1 or higher
• Laravel: 10.x, 11.x, or 12.x
• Database: MySQL 8.0+ (for the default driver)

Installation

Install the package via Composer:

After installation, publish the configuration file to customize settings:

This will create a configuration file at config/audit-logger.php where you can adjust settings like the storage driver, table naming conventions, and more.

Configuration

The configuration file config/audit-logger.php allows you to customize the behavior of the audit logger. Below are the key configuration options:

Ensure you review and adjust these settings based on your application's needs, especially for sensitive data exclusion and performance optimization.

Usage

Basic Usage

To make a model auditable, simply add the Auditable trait to your Eloquent model. Ensure strict typing is enabled as per the engineering rules.

Once the trait is added, any changes to the model (create, update, delete, restore) will be automatically logged to a dedicated audit table (e.g., audit_order_logs).

Excluding Fields

To exclude specific fields from being audited, define the $auditExclude property:

Including Specific Fields

Alternatively, you can specify only the fields to audit using $auditInclude:

Advanced Usage

Custom Metadata

You can enrich audit logs with custom metadata by implementing the getAuditMetadata method in your model:

Temporarily Disabling Auditing

For specific operations where auditing is not required, you can disable it temporarily:

Custom Audit Events

To log custom actions beyond standard CRUD operations, dispatch the ModelAudited event manually:

Fluent API for Custom Audit Events

For a more intuitive and readable way to log custom actions, use the fluent API provided by the audit() method:

This fluent interface allows you to chain methods to define the custom action, old and new values, and additional metadata before logging the event. It respects the model's auditable attributes and merges any default metadata defined in getAuditMetadata() with custom metadata provided.

Customizing Audit Logging

If you need to extend the audit logging functionality, you can implement a custom driver by adhering to the AuditDriverInterface. Register your custom driver in a service provider:

Retrieving Audit Logs

Audit logs are accessible via a relationship on the audited model. Use the auditLogs() method to query logs:

For advanced querying, you can directly use the EloquentAuditLog model with various scopes to filter audit logs based on specific criteria:

These scopes allow for flexible and efficient querying of audit logs, making it easier to analyze changes based on action type, date range, or the user responsible for the change.

Performance Optimization

• Batch Processing: Enable batch processing in the configuration to reduce database transactions for high-frequency operations.

• Selective Auditing: Limit audited fields to only those necessary for compliance or debugging to minimize storage and processing overhead.
• Database Indexing: Ensure audit tables have appropriate indexes for frequent queries (handled automatically by the package).

Testing

This package includes a robust test suite. To run the tests locally:

When writing tests for your application, ensure you cover audit logging behavior, especially for critical models. Mock the audit driver if necessary to isolate tests from actual logging.

Security Best Practices

• Exclude Sensitive Data: Always exclude fields containing personally identifiable information (PII) or sensitive data using $auditExclude.
• Access Control: Implement authorization checks (using Laravel Gates or Policies) to restrict access to audit logs.
• Data Retention: Consider implementing a retention policy to purge old audit logs, balancing compliance needs with data privacy.

Troubleshooting

• Audit Tables Not Created: Ensure 'auto_migration' => true in your configuration. If disabled, manually create tables using AuditLogger::driver()->createStorageForEntity(Model::class).
• Missing Logs: Verify that fields aren't excluded globally or in the model, and ensure auditing isn't disabled for the operation.
• Causer Not Recorded: Confirm that authentication is set up correctly and the user is logged in during the operation.

Contributing

Contributions are welcome! Please follow the guidelines in CONTRIBUTING.md for submitting pull requests, reporting issues, or suggesting features.

License

This package is open-sourced software licensed under the MIT license.