PHPackages justgabit/laravel-audit-trail - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. justgabit/laravel-audit-trail ActiveLibrary[Utility & Helpers](/categories/utility) justgabit/laravel-audit-trail ============================= Laravel package to handle audit trails 1.1.3(7y ago)15.2k1proprietaryPHPPHP >=7.0.0 Since Jan 31Pushed 7y ago3 watchersCompare [ Source](https://github.com/justgabit/laravel-audit-trail)[ Packagist](https://packagist.org/packages/justgabit/laravel-audit-trail)[ RSS](/packages/justgabit-laravel-audit-trail/feed)WikiDiscussions master Synced today READMEChangelogDependencies (6)Versions (15)Used By (0) Audit Trail package for Laravel 5+ ================================== [](#audit-trail-package-for-laravel-5) AuditTrail allows the creation of an audit trail (a detailed log) of any domain transactions. Currently it only works with a database but the table name and the connection name can be customized and many different tables can be used at once. This is useful if you need to create different kinds of audit trails in the same app (system transactions vs user transactions, etc). Release notes ============= [](#release-notes) - 1.1 - Added support for Eloquent models with compound primary keys that use the package `mopo922/laravel-treats`. - 1.0 - Initial release. Installation ------------ [](#installation) ``` composer require justgabit/laravel-audit-trail ``` AuditTrail comes with two database tables that you will need to create in order to use it. After the package is installed you will need to create the tables: ``` php artisan migrate ``` There will be two tables that are created `audit_trail` and `audit_trail_actions`. You may with to change the names of these tables by editing the package default configuration (more on this later) before running the migrations. Concepts -------- [](#concepts) An audit trail is a chronological list of "actions". It is meant to be read and written but NEVER updated or deleted. Whatever happened in the system should live in the audi trail log forever. **Actions** represent a domain transaction that you want to track. in other words, an action is something that happens in your app that you want to have a record of. Every audit trail that you generate will *always* be based on an action. The following are examples of actions you might have: - Login - Failed login - Logout - Record update - Purchase email sent Each action must be present in the `audit_trail_actions` table but AuditTrail will automatically update this table for you as new actions are created. Still it is a good idea to pre-populate this table with all the actions you will be having in order to avoid race conditions while running in production. The actions table also has a `description` field where you can describe what the action represents and what data it holds. It is entirely optional and it is not used at all within AuditTrail internally. To create an action you will need to create a class that extends `Mueva\AuditTrail\Action`. The action `id` in the `audit_trail_actions` table will be derived from what you call your class using kebab case. If your class is called `UpdateRecord` then the `id` for that action will become `update-record`. The `audit_trail` table contains the following fields by default: - **id**: Primary key of the table. - **parent\_id**: A foreign key referencing `id`. When a row contains a non-null `parent_id`, that row is considered to be a child row. This allows for tracking related transactions, for example, everything that happened in a single HTTP request. The first audit trail row gets an `id` and the following rows contain the first row's id as their parent. - **action\_id**: A foreign key referencing the `audit_trail_actions` table. This foreign key is set to cascade on update. If you ever need to rename an action, you can rename it in the parent table and all the rows in the `audit_trail` table will be renamed accordingly. - **user\_id**: This represents a user id in your own system. Every action is most likely a the result of a user interaction so this allows you to track which user triggered the action. If you have actions that happen without user interaction, like cron jobs, you can set this to null. - **action\_data**: This is a json object that is returned by your action class. You can fill this with whatever you want that will help you gain context into the action that happened. For example, if your action represents a record in your database being modified, you can fill this field with the diff of what changed, or even a before and after snapshot of the record. - **action\_brief**: This is a brief recollection of what happened during the action. For example, if your `action_data` contains the full row that was just updated, the `action_brief` might contain something like "User @JohnDoe updated row #89 (added +2 units) on the products table". In other words, a human readable short recolection of what the action. - **table\_name**: If your action represents a change in one of your system's tables, this is where you indicate in which table the change happened. If the action represents something else that is not table related, then this can be null. - **table\_id**: Just like with `table_name`, this represents the ID of a row that has had a change. So if your action represents deleting the row 30 on the products table, then `table_name` will contain "products" and `table_id` will contain 30. - **date**: Date the action happened. Config ------ [](#config) AuditTrail publishes a configuration file that can be overwritten by the application that consumes it. In order to publish the config to your Laravel install, do this: ``` php artisan vendor:publish ``` A menu will appear with all the packages that have something available for publishing. Choose the one that contains the `Mueva\AuditTrail\AuditTrailServiceProvider`. A new configuration file `app/config/audit-trail.php` will be available to you. Inside you will find documentation on each of the options available. Creating an Action ------------------ [](#creating-an-action) As stated earlier, every action must extend `Mueva\AuditTrail\Action`. The best place to know about the options available is the class itself. Every method is documented and should give you a good idea of what to do. Since the abstract action class extends PHP's `JsonSerializable`, the only required method that you must implement is `jsonSerialize()`. The output of this method is exactly what will be saved in `audit_action` field in the `audit_trail` table. Other than what's on the class methods documentation, there is one notable thing to mention. If your action represents an Eloquent model, then there is no need to override the `getTableName()` and `getTableId()` methods as those can be deduced from the Eloquent model itself. In that case, just return the model object in `getEloquentModel()` and AuditTrail will automatically fill the `table_name` and `table_id` fields automatically. Lastly, your action may want to populate extra fields in the `audit_trail` table implicitly. This is achieved by overriding the `getExtras()` method on your action and returning an array where the keys represent the field names and the array values represent the field values. So for example let's say you have a Login action that gets passed a User model and that your `audit_trail` table has a nullable `partner_id` field that you want to fill automatically every time a Login action gets executed. Inside your Login action's `getExtras()` method you should write the logic to get the `partner_id` based on the user logging in and then return the following array: ```