roketin/laravel-auditing

personal used for Roketin Engine. Keep a change history for your models using laravel version 5.*

2.0 2016-03-17 03:41 UTC

Requires

• php: >=5.5.9
• illuminate/support: ~5.0|~5.1

Requires (Dev)

• phpunit/phpunit: ~4.0

MIT

• Ivan

• log
• register
• laravel
• auditing
• observe
• roketin

README

Laravel Auditing allows you to record changes to an Eloquent model's set of data by simply adding its trait to your model. Laravel Auditing also provides a simple interface for retreiving an audit trail for a piece of data and allows for a great deal of customization in how that data is provided.

Auditing is based on the package auditing

Installation

Laravel Auditing can be installed with Composer, more details about this package in Composer can be found here.

Run the following command to get the latest version package:

composer require roketin/laravel-auditing

Open the file config/app.php and then add the service provider, this step is required.

'providers' => [
    // ...
    Roketin\Auditing\AuditingServiceProvider::class,
],

Note: This provider is important for the publication of configuration files.

Only after complete the step before, use the following command to publish configuration settings:

php artisan vendor:publish --provider="Roketin\Auditing\AuditingServiceProvider"

Finally, execute the migration to create the logs table in your database. This table is used to save audit the logs.

php artisan migrate

Docs

• Implementation
• Configuration
• Getting the Logs
• Customizing log message
• Examples
• Contributing
• Having problems?
• license

Implementation

Implementation using Trait

To register the change log, use the trait OwnerIt\Auditing\AuditingTrait in the model you want to audit

// app/Team.php
namespace App;

use Illuminate\Database\Eloquent\Model;
use Roketin\Auditing\AuditingTrait;

class Team extends Model 
{
    use AuditingTrait;
    //...
}

Base implementation Legacy Class

It is also possible to have your model extend the OwnerIt\Auditing\Auditing class to enable auditing. Example:

// app/Team.php
namespace App;

use Roketin\Auditing\Auditing;

class Team extends Auditing 
{
    //...    
}

Configuration

Auditing behavior settings

The Auditing behavior settings are carried out with the declaration of attributes in the model. See the examples below:

• Turn off logging after a number of logs: $historyLimit = 500
• Disable / enable logging: $auditEnabled = false
• Turn off logging for specific fields: $dontKeepLogOf = ['field1', 'field2']

// app/Team.php
namespace App;

use Illuminate\Database\Eloquent\Model;

class Team extends Model 
{
    use Roketin\Auditing\AuditingTrait;
    // Disables the log record in this model.
    protected $auditEnabled  = false;
    // Disables the log record after 500 records.
    protected $historyLimit = 500; 
    // Fields you do NOT want to register.
    protected $dontKeepLogOf = ['created_at', 'updated_at'];
    // Tell what actions you want to audit.
    protected $auditableTypes = ['created', 'saved', 'deleted'];
}

Auditing settings

Using the configuration file, you can define:

• The Model used to represent the current user of application.
• A different database connection for audit.
• The table name used for log registers.

The configuration file can be found at config/auditing.php

// config/auditing.php
return [

    // Authentication Model
    'model' => App\User::class,

    // Database Connection
    'connection' => null,

    // Table Name
    'table' => 'logs',
];

Getting the Logs

// app/Http/Controller/MyAppController.php
namespace App\Http\Controllers;

use App\Team;

class MyAppController extends BaseController 
{
    public function index()
    {
        $team = Team::find(1); // Get team
        $team->logs; // Get all logs
        $team->logs->first(); // Get first log
        $team->logs->last();  // Get last log
        $team->logs->find(2); // Selects log
    }
    //...
}

Getting logs with user responsible for the change.

use Roketin\Auditing\Log;

$logs = Log::with(['user'])->get();

or

use App\Team;

$logs = Team::logs->with(['user'])->get();

Note: Remember to properly define the user model in the file config/auditing.php

...
'model' => App\User::class,
... 

Customizing log message

You can define your own log messages for presentation. These messages can be defined for both the model as well as for each one of fields.The dynamic part of the message can be done by targeted fields per dot segmented as{object.property.property} or {object.property|Default value} or {object.property||callbackMethod}.

Note: This implementation is optional, you can make these customizations where desired.

Set messages to the model

// app/Team.php
namespace App;

use Roketin\Auditing\Auditing;

class Team extends Auditing 
{
    //...
    public static $logCustomMessage = '{user.name|Anonymous} {type} a team {elapsed_time}'; // with default value
    public static $logCustomFields = [
        'name'  => 'The name was defined as {new.name||getNewName}', // with callback method
        'owner' => [
            'updated' => '{new.owner} owns the team',
            'created' => '{new.owner|No one} was defined as owner'
        ],
    ];
    
    public function getNewName($log)
    {
        return $log->new['name'];
    }
    //...
}

Getting change logs

// app/Http/Controllers/MyAppController.php 
//...
public function auditing()
{
    $logs = Team::find(1)->logs; // Get logs of team
    return view('auditing', compact('logs'));
}
//...
    

Featuring log records:

    // resources/views/my-app/auditing.blade.php
    ...
    <ol>
        @forelse ($logs as $log)
            <li>
                {{ $log->customMessage }}
                <ul>
                    @forelse ($log->customFields as $custom)
                        <li>{{ $custom }}</li>
                    @empty
                        <li>No details</li>
                    @endforelse
                </ul>
            </li>
        @empty
            <p>No logs</p>
        @endforelse
    </ol>
    ...
    

Result:

1. Antério Vieira created a team 1 day ago
   • The name was defined as gestao
   • No one was defined as owner
2. Rafael França deleted a team 2 day ago
   • No details
3. ...

Examples

Spark Auditing

For convenience we decided to use the spark for this example, the demonstration of auditing is simple and self explanatory. Click here and see for yourself.

Dreams

Dreams is a developed api to serve as an example or direction for developers using laravel-auditing. You can access the application here. The back-end (api) was developed in laravel 5.1 and the front-end (app) in angularjs, the detail are these:

• Link for application
• Source code api-dreams
• Source code app-dreams

Contributing

Contributions are welcomed; to keep things organized, all bugs and requests should be opened on github issues tab for the main project in the roketin/laravel-auditing/issues.

All pull requests should be made to the branch Develop, so they can be tested before being merged into the master branch.

Having problems?

If you are having problems with the use of this package, there is likely someone has faced the same problem. You can find common answers to their problems:

• Github Issues

License

The laravel-audit package is open source software licensed under the license MIT