### Install MongoDB Package

Source: https://laravel-auditing.com/guide/audit-implementation

Install the jenssegers/mongodb package to enable MongoDB support.

```sh
composer require jenssegers/mongodb
```

--------------------------------

### Install Larasupport for Lumen

Source: https://laravel-auditing.com/guide/installation

Install the irazasyed/larasupport package to enable Artisan commands and configuration publishing in Lumen.

```sh
composer require irazasyed/larasupport
```

--------------------------------

### Install doctrine/dbal for Migrations

Source: https://laravel-auditing.com/guide/upgrading

The doctrine/dbal package is required to successfully execute upgrade migrations. Ensure it is installed before proceeding with upgrades.

```bash
composer require doctrine/dbal
```

--------------------------------

### Create Custom TenantIdResolver

Source: https://laravel-auditing.com/guide/audit-resolvers

Implement the Resolver interface to create a custom resolver. This example adds a tenant_id based on the auditable model.

```php
<?php

namespace App\AuditResolvers;

use OwenIt\Auditing\Contracts\Auditable;
use OwenIt\Auditing\Contracts\Resolver;

class TenantIdResolver implements Resolver
{

    public static function resolve(Auditable $auditable = null)
    {
        if(method_exists($auditable, 'tenant')) {
            return $auditable->tenant_id;
        }

        return null;
    }
}
```

--------------------------------

### Configure Audit Implementation

Source: https://laravel-auditing.com/guide/audit-implementation

Set the 'implementation' key in your config/audit.php file to the FQCN of your custom Audit model. This example shows how to set it to the MongoAudit model.

```php
return [
    // ...

    'implementation' => App\Models\MongoAudit::class,

    // Uncomment below if you need to specify the details of the mongo database connection (useful in hybrid setups with multiple DBs)
    // 'drivers' => [
    //     'database' => [
    //         'table' => 'audits',
    //         'connection' => 'mongodb'
    //     ]
    // ],    
    
    // ...
];
```

--------------------------------

### Install Laravel Auditing via Composer

Source: https://laravel-auditing.com/guide/installation

Use this command to install the latest version of the Laravel Auditing package in your project.

```sh
composer require owen-it/laravel-auditing
```

--------------------------------

### Setup Auditable Model in Laravel

Source: https://laravel-auditing.com/guide/model-setup.html

Use the `OwenIt\Auditing\Auditable` trait and implement the `OwenIt\Auditing\Contracts\Auditable` interface in your Eloquent model to enable auditing.

```php
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;
use OwenIt\Auditing\Contracts\Auditable;

class User extends Model implements Auditable
{
    use \OwenIt\Auditing\Auditable;

    // ...
}
```

--------------------------------

### Implement Resolver Contract for Custom Resolvers

Source: https://laravel-auditing.com/guide/upgrading

If you have custom resolver implementations for UrlResolver, UserAgentResolver, or IpAddressResolver, they now extend the Resolver contract. This example shows the basic structure for a UrlResolver.

```php
class UrlResolver implements \OwenIt\Auditing\Contracts\Resolver
```

--------------------------------

### Register Artisan Service Provider in Lumen

Source: https://laravel-auditing.com/guide/installation

Register the ArtisanServiceProvider from larasupport in your Lumen bootstrap file after installation.

```php
$app->register(Irazasyed\Larasupport\Providers\ArtisanServiceProvider::class);
```

--------------------------------

### MongoDB Audit Model Example

Source: https://laravel-auditing.com/guide/audit-implementation

Example of a custom Audit model implementing the Audit contract for MongoDB. Ensure your model extends Jenssegers	Mongodb	Eloquent	Model and uses the OwenIt	Auditing	Audit trait.

```php
<?php
namespace App\Models;

use Jenssegers\Mongodb\Eloquent\Model;

class MongoAudit extends Model implements \OwenIt\Auditing\Contracts\Audit
{
    use \OwenIt\Auditing\Audit;

    /**
     * {@inheritdoc}
     */
    protected $guarded = [];

    /**
     * {@inheritdoc}
     */
    protected $casts = [
        'old_values'   => 'json',
        'new_values'   => 'json',
    ];

    /**
     * {@inheritdoc}
     */
    public function auditable()
    {
        return $this->morphTo();
    }

    /**
     * {@inheritdoc}
     */
    public function user()
    {
        return $this->morphTo();
    }
}
```

--------------------------------

### Get Audit Metadata as Array

Source: https://laravel-auditing.com/guide/audit-presentation

Retrieve audit metadata as a PHP array using the getMetadata() method. This is useful for inspecting audit information.

```php
var_dump($audit->getMetadata());
```

--------------------------------

### Transform Audit Data

Source: https://laravel-auditing.com/guide/audit-transformation

Implement the `transformAudit` method to modify audit data. This example adds role names to the audit log when a role ID changes. Ensure the `Role` model and necessary relationships are set up.

```php
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Arr;
use OwenIt\Auditing\Contracts\Auditable;

class User extends Model implements Auditable
{
    use \OwenIt\Auditing\Auditable;

    // ...

    /**
     * {@inheritdoc}
     */
    public function transformAudit(array $data): array
    {
        if (Arr::has($data, 'new_values.role_id')) {
            $data['old_values']['role_name'] = Role::find($this->getOriginal('role_id'))->name;
            $data['new_values']['role_name'] = Role::find($this->getAttribute('role_id'))->name;
        }

        return $data;
    }
}

```

--------------------------------

### Get Audit Metadata as JSON

Source: https://laravel-auditing.com/guide/audit-presentation

Convert audit metadata to a JSON string using getMetadata(true). The second argument accepts json_encode options.

```php
echo $audit->getMetadata(true, JSON_PRETTY_PRINT);
```

--------------------------------

### Retrieve Audit Metadata

Source: https://laravel-auditing.com/guide/getting-audits

Get an array containing the metadata of a specific audit record. This includes details like the event, URL, IP address, user agent, tags, and timestamps.

```php
// Get first available Article
$article = Article::first();

// Get latest Audit
$audit = $article->audits()->latest()->first();

var_dump($audit->getMetadata());
```

```php
array(10) {
  ["audit_id"]=>
  string(1) "1"
  ["audit_event"]=>
  string(7) "updated"
  ["audit_url"]=>
  string(26) "http://example.com/articles/1"
  ["audit_ip_address"]=>
  string(9) "127.0.0.1"
  ["audit_user_agent"]=>
  string(68) "Mozilla/5.0 (X11; Linux x86_64; rv:53.0) Gecko/20100101 Firefox/53.0"
  ["audit_tags"]=>
  string(7) "foo,bar"
  ["audit_created_at"]=>
  string(19) "2017-01-01 01:02:03"
  ["audit_updated_at"]=>
  string(19) "2017-01-01 01:02:03"
  ["user_id"]=>
  string(1) "1"
  ["user_type"]=>
  string(8) "App\User"
}
```

--------------------------------

### Run Database Migrations

Source: https://laravel-auditing.com/guide/installation

Execute this command to create the 'audits' table in your database.

```sh
php artisan migrate
```

--------------------------------

### Configure Audit Implementation

Source: https://laravel-auditing.com/guide/general-configuration

Set the Audit model implementation. Defaults to OwenIt\Auditing\Models\Audit::class.

```php
return [
    // ...

    'implementation' => OwenIt\Auditing\Models\Audit::class,

    // ...
];
```

--------------------------------

### Load Configuration in Lumen

Source: https://laravel-auditing.com/guide/installation

Ensure the audit configuration is loaded on boot in Lumen by adding the configure call to bootstrap/app.php.

```php
$app->configure('audit');
```

--------------------------------

### Publish Configuration Settings

Source: https://laravel-auditing.com/guide/installation

Use this command to publish the configuration file for the Laravel Auditing package.

```sh
php artisan vendor:publish --provider "OwenIt\Auditing\AuditingServiceProvider" --tag="config"
```

--------------------------------

### Enable Facades and Eloquent in Lumen

Source: https://laravel-auditing.com/guide/installation

Ensure that Facades and Eloquent are enabled in your Lumen application's bootstrap file.

```php
$app->withFacades();

$app->withEloquent();
```

--------------------------------

### Access Audit Attributes Directly

Source: https://laravel-auditing.com/guide/audit-presentation

Access audit attributes directly as Eloquent model properties. This provides a convenient way to get specific audit details.

```php
echo $audit->id.PHP_EOL;
echo $audit->event.PHP_EOL;
echo $audit->url.PHP_EOL;
echo $audit->ip_address.PHP_EOL;
echo $audit->user_agent.PHP_EOL;
echo $audit->tags.PHP_EOL;
echo implode(',', $audit->getTags()).PHP_EOL;
echo $audit->created_at->toDateTimeString().PHP_EOL;
echo $audit->updated_at->toDateTimeString().PHP_EOL;
echo $audit->user_id.PHP_EOL;
echo $audit->user_type.PHP_EOL;
echo $audit->user->email.PHP_EOL;
echo $audit->user->name.PHP_EOL;
```

--------------------------------

### Configure Empty Audit Handling

Source: https://laravel-auditing.com/guide/auditable-configuration

Configure whether to store audits with empty old and new values, and specify events that are allowed to have empty values.

```php
return [
    // ...
    
    /*
    |--------------------------------------------------------------------------
    | Empty Values
    |--------------------------------------------------------------------------
    |
    | Should Audit records be stored when the recorded old_values & new_values
    | are both empty?
    |
    | Some events may be empty on purpose. Use allowed_empty_values to exclude
    | those from the empty values check. For example when auditing
    | model retrieved events which will never have new and old values
    |
    */
    'empty_values'         => true,
    'allowed_empty_values' => [
        'retrieved'
    ],
    
    // ... 
]


```

--------------------------------

### Custom URL Resolver (No Query Strings)

Source: https://laravel-auditing.com/guide/audit-resolvers

Create a URL resolver that excludes query strings and handles console requests.

```php
<?php
namespace App\Resolvers;

use Illuminate\Support\Facades\App;
use Illuminate\Support\Facades\Request;
use OwenIt\Auditing\Contracts\Auditable;

class UrlResolver implements \OwenIt\Auditing\Contracts\Resolver
{
    /**
     * {@inheritdoc}
     */
    public static function resolve(Auditable $auditable)
    {
        if (App::runningInConsole()) {
            return 'console';
        }

        // Just the full URL without query strings
        return Request::url();
    }
}
```

--------------------------------

### Get Modified Attributes as JSON

Source: https://laravel-auditing.com/guide/audit-presentation

Convert modified attributes to a JSON string using getModified(true). This method honors mutators and casts defined on the model.

```php
echo $audit->getModified(true);
```

--------------------------------

### Transition Auditable Model Using New or Old Values

Source: https://laravel-auditing.com/guide/auditable-transition

Transition an Auditable model using the `transitionTo()` method. The second argument, when set to `true`, uses the `old_values` from the Audit; otherwise, it defaults to using `new_values`. The method updates attributes without persisting to the database, requiring a manual `save()` call.

```php
<?php

// ...

// Get the latest Article
$latestArticle = Article::latest()->first();

// Get the first Audit from the latest Article
$firstAudit = $latestArticle->audits()->first();

// Update the Article properties with the corresponding ones in the new_values Audit attribute
$dirtyLatestArticleFromNew = $latestArticle->transitionTo($firstAudit);

// Update the Article properties with the corresponding ones in the old_values Audit attribute
$dirtyLatestArticleFromOld = $latestArticle->transitionTo($firstAudit, true);

// See the updated attributes during the state transition using the new values
dump($dirtyLatestArticleFromNew->getDirty());

// See the updated attributes during the state transition using the old values
dump($dirtyLatestArticleFromOld->getDirty());

// ...

```

--------------------------------

### Retrieve Modified Properties of an Audit

Source: https://laravel-auditing.com/guide/getting-audits

Get an array detailing the modified properties of an auditable model for a specific audit. It includes both the 'new' and 'old' values for each changed attribute.

```php
// Get first available Article
$article = Article::first();

// Get latest Audit
$audit = $article->audits()->latest()->first();

var_dump($audit->getModified());
```

```php
array(2) {
  ["title"]=>
  array(2) {
    ["new"]=>
    string(28) "How To Audit Eloquent Models"
    ["old"]=>
    string(19) "How to audit models"
  }
  ["content"]=>
  array(2) {
    ["new"]=>
    string(62) "First, let's start by installing the laravel-auditing package."
    ["old"]=>
    string(16) "This is a draft."
  }
}
```

--------------------------------

### Configure Custom IP Address Resolver

Source: https://laravel-auditing.com/guide/audit-resolvers

Update the audit.php configuration file to use the custom IpAddressResolver.

```php
return [
    // ...

    'resolvers' = [
        // ...
        'ip_address' => App\Resolvers\IpAddressResolver::class,
        // ...
    ],

    // ...
];
```

--------------------------------

### Get Modified Attributes as Array

Source: https://laravel-auditing.com/guide/audit-presentation

Retrieve the modified attributes of an auditable model as a PHP array using getModified(). This array contains 'old' and 'new' values for changed attributes.

```php
var_dump($audit->getModified());
```

--------------------------------

### Configure User Auth Guards

Source: https://laravel-auditing.com/guide/general-configuration

Specify which authentication guards the UserResolver should check to resolve a User.

```php
return [
    // ...

    'user' => [
        'guards' => [
            'web',
            'api',
        ],
    ],

    // ...
];
```

--------------------------------

### Manually Audit with Auditor Facade

Source: https://laravel-auditing.com/guide/auditor

Use the Auditor facade to manually execute an audit and prune old records for a given model. Ensure the model is updated before auditing.

```php
<?php
namespace App\Http\Controllers;

use App\Http\Requests\Request;
use App\Models\Article;
use OwenIt\Auditing\Facades\Auditor;

class ArticleController extends Illuminate\Routing\Controller
{
    public function update(Request $request, Article $article)
    {
        $article->update($request->all());

        if ($audit = Auditor::execute($article)) {
            Auditor::prune($article);
        }
    }
}

```

--------------------------------

### Enable Timestamp Auditing Globally

Source: https://laravel-auditing.com/guide/auditable-configuration

Set 'timestamps' to true in the `config/audit.php` file to include `created_at`, `updated_at`, and `deleted_at` in audit records.

```php
return [
    // ...

    'timestamps' => true,

    // ...
];

```

--------------------------------

### Configure User Agent Resolver

Source: https://laravel-auditing.com/guide/audit-resolvers

Set the custom User Agent resolver in the `config/audit.php` configuration file by specifying the class name.

```php
return [
    // ...

    'resolvers' => [
        // ...
        'user_agent' => App\Resolvers\UserAgentResolver::class,
        // ...
    ],

    // ...
];

```

--------------------------------

### Upgrade 5.1.x/6.1.x to 8.0.x Migration

Source: https://laravel-auditing.com/guide/upgrading

Use this migration to convert a default 5.1.x or 6.1.x table structure to the 8.0.x version. It adds the 'user_type' column and sets its value.

```php
<?php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schema;

class UpdateAuditsTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::table('audits', function (Blueprint $table) {
            $table->string('user_type')->nullable();
        });
        
        // Set the user_type value and keep the timestamp values.
        DB::table('audits')->update([
            'user_type'  => \App\User::class,
            'created_at' => DB::raw('created_at'),
            'updated_at' => DB::raw('updated_at'),
        ]);
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        // There's no turning back
    }
}

```

--------------------------------

### Configure Custom URL Resolver

Source: https://laravel-auditing.com/guide/audit-resolvers

Set the custom UrlResolver in the audit.php configuration file.

```php
return [
    // ...

    'resolvers' = [
        // ...
        'url' => App\Resolvers\UrlResolver::class,
        // ...
    ],

    // ...
];
```

--------------------------------

### Log Custom Events with `AuditCustom`

Source: https://laravel-auditing.com/guide/audit-custom

Dispatch the `AuditCustom` event to log any values from an Auditable model. Set `auditEvent`, `isCustomEvent`, `auditCustomOld`, and `auditCustomNew` properties on the model before dispatching the event.

```php
$article = Article::find(1);
$article->auditEvent = 'whateverYouWant';
$article->isCustomEvent = true;
$article->auditCustomOld = [
    'customExample' => 'Anakin Skywalker'
];
$article->auditCustomNew = [
    'customExample' => 'Darth Vader'
];
Event::dispatch(new AuditCustom($article));

```

--------------------------------

### Custom User Agent Resolver

Source: https://laravel-auditing.com/guide/audit-resolvers

Implement this resolver to provide a default User-Agent string when the HTTP header is unavailable. It uses the `Request::header()` method with a fallback value.

```php
<?php
namespace App\Resolvers;

use Illuminate\Support\Facades\Request;
use OwenIt\Auditing\Contracts\Auditable;

class UserAgentResolver implements \OwenIt\Auditing\Contracts\Resolver
{
    /**
     * {@inheritdoc}
     */
    public static function resolve(Auditable $auditable)
    {
        // Default to "N/A" if the User Agent isn't available
        return Request::header('User-Agent', 'N/A');
    }
}

```

--------------------------------

### Configure Custom User Resolver

Source: https://laravel-auditing.com/guide/audit-resolvers

Set the custom User resolver in the `config/audit.php` configuration file by specifying the class name for the 'resolver' key.

```php
return [
    // ...

    'user' => [
        // ...
        'resolver' => App\Resolvers\UserResolver::class,
        // ...
    ],

    // ...
];

```

--------------------------------

### Transition Auditable Model with Audit Record

Source: https://laravel-auditing.com/guide/auditable-transition

Use this snippet to transition an Auditable model to a state defined by an Audit record. Ensure the Audit record has the same `auditable_id` and `auditable_type` as the model, and that attribute compatibility is met. Catches `AuditableTransitionException` for incompatible attributes.

```php
<?php

// ...

try {
    $article = Article::find(123);

    // An old Audit from when the Article
    // model had different property names
    $audit = $article->audits()->first();

    $article->transitionTo($audit);
    
} catch (AuditableTransitionException $e) {
    echo sprintf('Incompatible attributes: %s', implode(', ', $e->getIncompatibilities()));
}

// ...

```

--------------------------------

### Initialize Vue App for Audit Data

Source: https://laravel-auditing.com/guide/audit-presentation

This JavaScript snippet initializes a Vue instance to parse and set audit metadata and modified data from HTML attributes. Ensure the target element has the necessary data attributes.

```javascript
new Vue({
    el: '.container',
    data: {
        metadata: JSON.parse(document.getElementById('article').getAttribute('data-metadata')),
        modified: JSON.parse(document.getElementById('article').getAttribute('data-modified'))
    }
});
```

--------------------------------

### Custom Audit Driver Interface Implementation

Source: https://laravel-auditing.com/guide/audit-drivers

This is the basic structure of a custom audit driver class. It must implement the AuditDriver interface, which requires defining the `audit` and `prune` methods.

```php
<?php
namespace App\AuditDrivers;

use OwenIt\Auditing\Contracts\Audit;
use OwenIt\Auditing\Contracts\Auditable;
use OwenIt\Auditing\Contracts\AuditDriver;

class MyCustomDriver implements AuditDriver
{
    /**
     * Perform an audit.
     *
     * @param \OwenIt\Auditing\Contracts\Auditable $model
     *
     * @return \OwenIt\Auditing\Contracts\Audit
     */
    public function audit(Auditable $model): Audit
    {
        // TODO: Implement the audit logic
    }

    /**
     * Remove older audits that go over the threshold.
     *
     * @param \OwenIt\Auditing\Contracts\Auditable $model
     *
     * @return bool
     */
    public function prune(Auditable $model): bool
    {
        // TODO: Implement the pruning logic
    }
}

```

--------------------------------

### Configure Database Driver Settings

Source: https://laravel-auditing.com/guide/general-configuration

Modify the database connection and table name for the Database audit driver.

```php
return [
    // ...

    'drivers' => [
        'database' => [
            'table'      => 'audits',
            'connection' => null,
        ],
    ],

    // ...
];
```

--------------------------------

### Global Attribute Exclusion Configuration

Source: https://laravel-auditing.com/guide/auditable-configuration

Configure a default set of attributes to exclude from auditing globally in the `config/audit.php` file.

```php
return [
    // ...
    
    'exclude' => ['id'],
    
    // ...
];

```

--------------------------------

### Publish Audit Table Migration

Source: https://laravel-auditing.com/guide/installation

Publish the migration file for the 'audits' table to your database directory.

```sh
php artisan vendor:publish --provider "OwenIt\Auditing\AuditingServiceProvider" --tag="migrations"
```

--------------------------------

### Create Custom Audit Driver Command

Source: https://laravel-auditing.com/guide/audit-drivers

Use this Artisan command to generate a new custom audit driver class. The command creates a boilerplate file in the app/AuditDrivers directory.

```sh
php artisan auditing:audit-driver MyCustomDriver
```

--------------------------------

### Configure User Morph Prefix

Source: https://laravel-auditing.com/guide/general-configuration

Define the prefix for user relation column names when using the MorphTo relation. Update migrations accordingly.

```php
return [
    // ...

    'user' => [
        'morph_prefix' => 'user',
    ],

    // ...
];
```

--------------------------------

### Handle Auditing Event

Source: https://laravel-auditing.com/guide/audit-events

Implement logic within the handle method of the AuditingListener. The Audit can be canceled by returning false.

```php
<?php

namespace App\Listeners;

use OwenIt\Auditing\Events\Auditing;

class AuditingListener
{
    /**
     * Create the Auditing event listener.
     */
    public function __construct()
    {
        // ...
    }

    /**
     * Handle the Auditing event.
     *
     * @param \OwenIt\Auditing\Events\Auditing $event
     * @return void
     */
    public function handle(Auditing $event)
    {
        // Implement logic
    }
}

```

--------------------------------

### Prevent Empty Audits for Old/New Values

Source: https://laravel-auditing.com/guide/community/troubleshooting

Register an observer on the `Audit` model to prevent audit records from being created when both `old_values` and `new_values` are empty. This is useful for reducing noise when only metadata is needed.

```php
Audit::creating(function (Audit $model) {
    if (empty($model->old_values) && empty($model->new_values)) {
        return false;
    }
});
```

--------------------------------

### Configure Global Custom Audit Driver

Source: https://laravel-auditing.com/guide/audit-drivers

To use a custom driver globally, update the 'driver' key in the `config/audit.php` configuration file with the fully qualified class name of your custom driver.

```php
return [
    // ...

    'driver' => App\AuditDrivers\MyCustomDriver::class,

    // ...
];

```

--------------------------------

### Configure Audit Resolvers

Source: https://laravel-auditing.com/guide/audit-resolvers

Define custom resolvers in the audit.php configuration file. The key corresponds to the audit table column name.

```php
'resolvers' => [
    'ip_address' => OwenIt\Auditing\Resolvers\IpAddressResolver::class,
    'user_agent' => OwenIt\Auditing\Resolvers\UserAgentResolver::class,
    'url'        => OwenIt\Auditing\Resolvers\UrlResolver::class,
    'tenant_id' => \App\AuditResolvers\TenantIdResolver::class // resolver that sets a tenant_id on the audits
]
```

--------------------------------

### Enable Console and Job Auditing

Source: https://laravel-auditing.com/guide/general-configuration

Set to true to enable auditing for Eloquent events fired from console commands or jobs. Note: User resolution in the console may not work.

```php
return [
    // ...

    'console' => true,

    // ...
];
```

--------------------------------

### Implement generateTags() Method

Source: https://laravel-auditing.com/guide/audit-tags

Implement the `generateTags()` method in your auditable model to return an array of strings for tagging audits. This method is defined by the `Auditable` interface.

```php
<?php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use OwenIt\Auditing\Contracts\Auditable;

class Article extends Model implements Auditable
{
    use \OwenIt\Auditing\Auditable;

    /**
     * {@inheritdoc}
     */
    public function generateTags(): array
    {
        return [
            $this->editor->name,
            $this->reporter->name,
            $this->designer->name,
            $this->photographer->name,
        ];
    }

    // ...
}

```

--------------------------------

### Configure Global Audit Events

Source: https://laravel-auditing.com/guide/auditable-configuration

Specify which Eloquent events should trigger an audit globally by modifying the 'events' configuration in `config/audit.php`.

```php
return [
    // ...

    'events' => [
        'deleted',
        'restored',
    ],

    // ...
];

```

--------------------------------

### Custom IP Address Resolver

Source: https://laravel-auditing.com/guide/audit-resolvers

Extend the default IP Address Resolver to handle requests behind proxies by checking the X-Forwarded-For header.

```php
<?php
namespace App\Resolvers;

use OwenIt\Auditing\Contracts\Auditable;
use Illuminate\Support\Facades\Request;

class IpAddressResolver implements \OwenIt\Auditing\Contracts\Resolver
{
    /**
     * {@inheritdoc}
     */
    public static function resolve(Auditable $auditable)
    {
        return Request::header('HTTP_X_FORWARDED_FOR', '0.0.0.0');
    }
}
```

--------------------------------

### Set Global Audit Record Threshold

Source: https://laravel-auditing.com/guide/auditable-configuration

Configure a 'threshold' in `config/audit.php` to limit the number of `Audit` records kept for an `Auditable` model.

```php
return [
    // ...

    'threshold' => 10,

    // ...
];

```

--------------------------------

### Configure Empty Values Handling

Source: https://laravel-auditing.com/guide/upgrading

In version 13, you can choose to omit audit records with empty old_values and new_values. Configure the 'empty_values' and 'allowed_empty_values' options in your config/audit.php file.

```php
'empty_values'         => true,
'allowed_empty_values' => [
    'retrieved'
],
```

--------------------------------

### Common Translation File for Audit Details

Source: https://laravel-auditing.com/guide/audit-presentation

This translation file provides common labels used when displaying audit information, such as 'Attribute', 'Event', 'ID', 'IP Address', etc.

```php
return [
    // ...

    'attribute'  => 'Attribute',
    'event'      => 'Event',
    'id'         => 'ID',
    'ip_address' => 'IP Address',
    'user_agent' => 'User Agent',
    'new'        => 'New',
    'old'        => 'Old',
    'url'        => 'URL',
    'user'       => 'User',
    'tags'       => 'Tags',

    // ...
];
```

--------------------------------

### Upgrade 4.1.x to 8.0.x Migration

Source: https://laravel-auditing.com/guide/upgrading

This migration converts a default 4.1.x table structure to the 8.0.x version. It adds 'user_type' and 'tags' columns and sets the 'user_type' value.

```php
<?php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schema;

class UpdateAuditsTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::table('audits', function (Blueprint $table) {
            $table->string('user_type')->nullable();
            $table->string('tags')->nullable();
        });
        
        // Set the user_type value and keep the timestamp values.
        DB::table('audits')->update([
            'user_type'  => \App\User::class,
            'created_at' => DB::raw('created_at'),
            'updated_at' => DB::raw('updated_at'),
        ]);
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        // There's no turning back
    }
}

```

--------------------------------

### Upgrade 3.1.x to 8.0.x Migration

Source: https://laravel-auditing.com/guide/upgrading

This migration converts a default 3.1.x table structure to the 8.0.x version. It renames columns, changes data types, adds new columns, and sets the 'user_type' value.

```php
<?php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schema;

class UpdateAuditsTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::table('audits', function (Blueprint $table) {
            $table->increments('id')->change();
            $table->renameColumn('type', 'event');
            $table->renameColumn('old', 'old_values');
            $table->renameColumn('new', 'new_values');
            $table->unsignedInteger('user_id')->nullable()->change();
            $table->string('user_type')->nullable();
            $table->renameColumn('route', 'url');
            $table->string('user_agent')->nullable();
            $table->string('tags')->nullable();
            $table->timestamp('updated_at')->nullable();
        });

        // Set the user_type value and keep the timestamp values.
        DB::table('audits')->update([
            'user_type'  => \App\User::class,
            'created_at' => DB::raw('created_at'),
            'updated_at' => DB::raw('updated_at'),
        ]);
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        // There's no turning back
    }
}

```

--------------------------------

### Register Service Provider in Laravel

Source: https://laravel-auditing.com/guide/installation

Add the AuditingServiceProvider to your application's configuration file if you are not using Laravel 5.5 or higher.

```php
'providers' => [
    // ...

    OwenIt\Auditing\AuditingServiceProvider::class,

    // ...
],
```

--------------------------------

### Custom User Resolver for Sentinel

Source: https://laravel-auditing.com/guide/audit-resolvers

Implement this resolver to integrate with authentication systems other than the default Laravel Auth facade, such as Sentinel. It returns the logged-in user model or null.

```php
<?php
namespace App\Resolvers;

use Cartalyst\Sentinel\Laravel\Facades\Sentinel;

class UserResolver implements \OwenIt\Auditing\Contracts\UserResolver
{
    /**
     * {@inheritdoc}
     */
    public static function resolve()
    {
        return Sentinel::check() ? Sentinel::getUser() : null;
    }
}

```

--------------------------------

### Handle Audited Event

Source: https://laravel-auditing.com/guide/audit-events

Implement logic within the handle method of the AuditedListener for actions that need to occur immediately after an audit is created.

```php
<?php

namespace App\Listeners;

use OwenIt\Auditing\Events\Audited;

class AuditedListener
{
    /**
     * Create the Audited event listener.
     */
    public function __construct()
    {
        // ...
    }

    /**
     * Handle the Audited event.
     *
     * @param \OwenIt\Auditing\Events\Audited $event
     * @return void
     */
    public function handle(Audited $event)
    {
        // Implement logic
    }
}

```

--------------------------------

### Use Eloquent Model for Auditing Updates

Source: https://laravel-auditing.com/guide/community/troubleshooting

When updating records, use Eloquent's `find()` and `update()` methods instead of the Query Builder's `where()->update()` to ensure Eloquent events fire and audits are created.

```php
Article::where('id', $id)->update($data);
```

```php
Article::find($id)->update($data);
```

--------------------------------

### Enable Strict Auditing Locally

Source: https://laravel-auditing.com/guide/auditable-configuration

Set the `$auditStrict` property to `true` on an `Auditable` model to enable strict auditing for that specific model.

```php
<?php
namespace App;

use Illuminate\Database\Eloquent\Model;
use OwenIt\Auditing\Contracts\Auditable;

class Article extends Model implements Auditable
{
    use \OwenIt\Auditing\Auditable;

    /**
     * Should the audit be strict?
     *
     * @var bool
     */
    protected $auditStrict = true;

    // ...
}
```

--------------------------------

### Register Service Provider in Lumen

Source: https://laravel-auditing.com/guide/installation

Register the AuditingServiceProvider in your Lumen application's bootstrap file.

```php
$app->register(OwenIt\Auditing\AuditingServiceProvider::class);
```

--------------------------------

### Enable JSON Querying for Old and New Values

Source: https://laravel-auditing.com/guide/audit-migration

Change 'old_values' and 'new_values' columns from text to JSON type to leverage the Query Builder's JSON column querying capabilities. Ensure your RDBMS supports this feature.

```php
$table->text('old_values')->nullable();
$table->text('new_values')->nullable();
```

```php
$table->json('old_values')->nullable();
$table->json('new_values')->nullable();
```

--------------------------------

### Configure Local Custom Audit Driver

Source: https://laravel-auditing.com/guide/audit-drivers

To use a custom driver for a specific model, set the protected static property `$auditDriver` on the `Auditable` model to the fully qualified class name of your custom driver.

```php
<?php
namespace App\Models;

use App\AuditDrivers\MyCustomDriver;
use Illuminate\Database\Eloquent\Model;
use OwenIt\Auditing\Contracts\Auditable;

class Article extends Model implements Auditable
{
    use \OwenIt\Auditing\Auditable;

    /**
     * Custom Audit Driver.
     *
     * @var \App\AuditDrivers\MyCustomDriver
     */
    protected $auditDriver = MyCustomDriver::class;

    // ...
}

```

--------------------------------

### Set Local Audit Threshold

Source: https://laravel-auditing.com/guide/auditable-configuration

Define the maximum number of audit records to keep for a specific model. This setting takes precedence over global configurations.

```php
<?php
namespace App;

use Illuminate\Database\Eloquent\Model;
use OwenIt\Auditing\Contracts\Auditable;

class Article extends Model implements Auditable
{
    use \OwenIt\Auditing\Auditable;

    /**
     * Audit threshold.
     *
     * @var int
     */
    protected $auditThreshold = 10;

    // ...
}

```

--------------------------------

### Include Attributes for Auditing

Source: https://laravel-auditing.com/guide/auditable-configuration

Use the `$auditInclude` property to specify which attributes should be audited. Only properties listed in this array will be included.

```php
<?php
namespace App;

use Illuminate\Database\Eloquent\Model;
use OwenIt\Auditing\Contracts\Auditable;

class Article extends Model implements Auditable
{
    use \OwenIt\Auditing\Auditable;

    /**
     * Attributes to include in the Audit.
     *
     * @var array
     */
    protected $auditInclude = [
        'title',
        'content',
    ];

    // ...
}
```

--------------------------------

### Use UUIDs Instead of Auto-Incrementing IDs for User

Source: https://laravel-auditing.com/guide/audit-migration

Replace the default nullableMorphs for the User model with string UUIDs and appropriate indexing. This is for developers who prefer UUIDs over auto-incrementing IDs.

```php
$table->string('user_type')->nullable();
$table->uuid('user_id')->nullable();
$table->index([
    'user_type',
    'user_id',
]);
```

--------------------------------

### Enable Timestamp Auditing Locally

Source: https://laravel-auditing.com/guide/auditable-configuration

Set the `$auditTimestamps` property to `true` on an `Auditable` model to include timestamp attributes in audit records for that specific model.

```php
<?php
namespace App;

use Illuminate\Database\Eloquent\Model;
use OwenIt\Auditing\Contracts\Auditable;

class Article extends Model implements Auditable
{
    use \OwenIt\Auditing\Auditable;

    /**
     * Should the timestamps be audited?
     *
     * @var bool
     */
    protected $auditTimestamps = true;

    // ...
}
```

--------------------------------

### Retrieve Audits with Associated User

Source: https://laravel-auditing.com/guide/getting-audits

Eager load the associated user for each audit record to avoid N+1 query problems. Ensure `User` morph prefix and guards are correctly configured in `config/audit.php`.

```php
// Get all associated Audits
$all = $article->audits()->with('user')->get();
```

--------------------------------

### Define Custom Event Attributes

Source: https://laravel-auditing.com/guide/auditable-configuration

Specify custom methods for handling specific audit events, such as 'restored', or use wildcards for multiple events.

```php
protected $auditEvents = [
    'deleted',
    'restored' => 'myRestoredEventAttributes',
];

```

```php
protected $auditEvents = [
    '*ated' => 'getMultiEventAttributes',
];

```

--------------------------------

### Enable Strict Auditing Globally

Source: https://laravel-auditing.com/guide/auditable-configuration

Set 'strict' to true in the `config/audit.php` file to make auditing respect the model's `$hidden` and `$visible` properties.

```php
return [
    // ...

    'strict' => true,

    // ...
];

```

--------------------------------

### Set Local Audit Events

Source: https://laravel-auditing.com/guide/auditable-configuration

Define specific Eloquent events to audit on a per-model basis by assigning an array to the `$auditEvents` attribute. This overrides global settings.

```php
<?php
namespace App;

use Illuminate\Database\Eloquent\Model;
use OwenIt\Auditing\Contracts\Auditable;

class Article extends Model implements Auditable
{
    use \OwenIt\Auditing\Auditable;

    /**
     * Auditable events.
     *
     * @var array
     */
    protected $auditEvents = [
        'deleted',
        'restored',
    ];

    // ...
}

```

--------------------------------

### Retrieve Audit Records for a Model

Source: https://laravel-auditing.com/guide/getting-audits

Fetch all, the first, the latest, or a specific audit record associated with an Eloquent model.

```php
// Get first available Article
$article = Article::first();

// Get all associated Audits
$all = $article->audits;

// Get first Audit
$first = $article->audits()->first();

// Get last Audit
$last = $article->audits()->latest()->first();

// Get Audit by id
$audit = $article->audits()->find(4);
```

--------------------------------

### Update Custom Audit Event Dispatching

Source: https://laravel-auditing.com/guide/upgrading

In version 14, custom audits are dispatched differently. Change `Event::dispatch(AuditCustom::class, [$article]);` to `Event::dispatch(new AuditCustom($article));` if you are using custom audits.

--------------------------------

### Manually Audit with Injected Auditor

Source: https://laravel-auditing.com/guide/auditor

Inject the Auditor contract into a controller method to manually execute an audit and prune old records. This leverages the IoC container for dependency resolution.

```php
<?php
namespace App\Http\Controllers;

use App\Http\Requests\Request;
use App\Models\Article;
use OwenIt\Auditing\Contracts\Auditor;

class ArticleController extends Illuminate\Routing\Controller
{
    public function update(Request $request, Article $article, Auditor $auditor)
    {
        $article->update($request->all());

        if ($audit = $auditor->execute($article)) {
            $auditor->prune($article);
        }
    }
}

```

--------------------------------

### Use Different Column Name for User ID/Type

Source: https://laravel-auditing.com/guide/audit-migration

Change the default 'user_id' column to a different name using nullableMorphs. Ensure the 'morph_prefix' in the configuration matches the new column name.

```php
$table->nullableMorphs('owner');
```

```php
return [
    'user' => [
        'morph_prefix' => 'owner',
    ],
];
```

--------------------------------

### Use Base64Encoder for Attribute Encoding

Source: https://laravel-auditing.com/guide/attribute-modifiers

Apply the Base64Encoder to encode attribute values in Base64. This is useful for binary data that might cause issues when casting to JSON. Ensure the Auditable trait is used.

```php
<?php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use OwenIt\Auditing\Contracts\Auditable;
use OwenIt\Auditing\Encoders\Base64Encoder;

class Article extends Model implements Auditable
{
    use \OwenIt\Auditing\Auditable;

    /**
     * Attribute modifiers.
     *
     * @var array
     */
    protected $attributeModifiers = [
        'title' => Base64Encoder::class,
    ];

    // ...
}
```

--------------------------------

### Migrate Audits Table to 8.0.x Structure

Source: https://laravel-auditing.com/guide/upgrading

Use this migration to update your existing 'audits' table schema to the structure required by version 8.0.x. Ensure the `user_type` is correctly set to the FQCN of your User model if necessary.

```php
<?php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schema;

class UpdateAuditsTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::table('audits', function (Blueprint $table) {
            $table->unsignedInteger('user_id')->nullable()->change();
            $table->string('user_type')->nullable();
            $table->unsignedInteger('owner_id')->change();
            $table->renameColumn('owner_id', 'auditable_id');
            $table->renameColumn('owner_type', 'auditable_type');
            $table->index([
                'auditable_id',
                'auditable_type',
            ]);
            $table->renameColumn('type', 'event');
            $table->renameColumn('old_value', 'old_values');
            $table->renameColumn('new_value', 'new_values');
            $table->renameColumn('route', 'url');
            $table->renameColumn('ip', 'ip_address');
            $table->string('user_agent')->nullable();
            $table->string('tags')->nullable();
        });
        
        // Set the user_type value and keep the timestamp values.
        DB::table('audits')->update([
            'user_type'  => \App\User::class,
            'created_at' => DB::raw('created_at'),
            'updated_at' => DB::raw('updated_at'),
        ]);        
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        // There's no turning back
    }
}
```

--------------------------------

### Display Audit Collection in Unordered List

Source: https://laravel-auditing.com/guide/audit-presentation

Use this Blade template to render a collection of audits as an unordered list. It handles cases where no audits are available and displays metadata and modified attributes for each audit.

```php
return [
    // ...

    'unavailable_audits' => 'No Article Audits available',

    'updated'            => [
        'metadata' => 'On :audit_created_at, :user_name [:audit_ip_address] updated this record via :audit_url',
        'modified' => [
            'title'   => 'The Title has been modified from <strong>:old</strong> to <strong>:new</strong>',
            'content' => 'The Content has been modified from <strong>:old</strong> to <strong>:new</strong>',
        ],
    ],

    // ...
];
```

```php
<ul>
    @forelse ($audits as $audit)
    <li>
        @lang('article.updated.metadata', $audit->getMetadata())

        @foreach ($audit->getModified() as $attribute => $modified)
        <ul>
            <li>@lang('article.'.$audit->event.'.modified.'.$attribute, $modified)</li>
        </ul>
        @endforeach
    </li>
    @empty
    <p>@lang('article.unavailable_audits')</p>
    @endforelse
</ul>
```

--------------------------------

### Exclude Attributes from Auditing

Source: https://laravel-auditing.com/guide/auditable-configuration

Use the `$auditExclude` property to specify which attributes should NOT be audited. Properties listed here will be excluded.

```php
<?php
namespace App;

use Illuminate\Database\Eloquent\Model;
use OwenIt\Auditing\Contracts\Auditable;

class Article extends Model implements Auditable
{
    use \OwenIt\Auditing\Auditable;

    /**
     * Attributes to exclude from the Audit.
     *
     * @var array
     */
    protected $auditExclude = [
        'published',
    ];

    // ...
}
```

--------------------------------

### Disable Auditing Temporarily

Source: https://laravel-auditing.com/guide/auditable-configuration

Use `disableAuditing()` and `enableAuditing()` to control auditing for specific operations. For versions 13.6.6+, use `withoutAuditing()` with a callback for temporary disabling within a scope.

```php
<?php

// Disable auditing from this point on
Article::disableAuditing();

// This operation won't be audited
Article::create([
    // ...
]);

// Re-enable auditing
Article::enableAuditing();


```

```php
<?php

$article = Article::withoutAuditing(function () {
    // This operation won't be audited
    $article = Article::create([
        // ...
    ]);

    // This operation will be audited
    Category::create([
        'article_id' => $article->id,
        // ...
    ]);

    return $article;
});


```

```php
<?php

$article = Article::withoutAuditing(function () {
    // This operation won't be audited
    $article = Article::create([
        // ...
    ]);

    // This operation won't be audited
    Category::withoutAuditing(fn () => Category::create([
        'article_id' => $article->id,
        // ...
    ]));

    return $article;
});


```

--------------------------------

### Configure Resolvers in Laravel Auditing

Source: https://laravel-auditing.com/guide/upgrading

Version 13 replaces the 'resolver' config key with 'resolvers' and organizes them by type. Update your config/audit.php file to reflect this new structure.

```php
'resolvers' => [
    'ip_address' => OwenIt\Auditing\Resolvers\IpAddressResolver::class,
    'user_agent' => OwenIt\Auditing\Resolvers\UserAgentResolver::class,
    'url'        => OwenIt\Auditing\Resolvers\UrlResolver::class,
],
```