Download the PHP package iamfarhad/laravel-audit-log without Composer
On this page you can find all versions of the php package iamfarhad/laravel-audit-log. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download iamfarhad/laravel-audit-log
More information about iamfarhad/laravel-audit-log
Files in iamfarhad/laravel-audit-log
Package laravel-audit-log
Short Description Comprehensive entity-level audit logging package for Laravel applications with model-specific tables, field exclusion, and batch processing support
License MIT
Informations about the package laravel-audit-log
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 usingAuditLogger::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.
All versions of laravel-audit-log with dependencies
illuminate/support Version ^10.0|^11.0|^12.0
illuminate/database Version ^10.0|^11.0|^12.0
illuminate/events Version ^10.0|^11.0|^12.0
illuminate/config Version ^10.0|^11.0|^12.0