PHPackages                             filipefernandes/laravel-model-access-audit - 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. filipefernandes/laravel-model-access-audit

ActiveLibrary

filipefernandes/laravel-model-access-audit
==========================================

Track, store, and visualize access and mutations of sensitive Eloquent models in enterprise applications.

00PHP

Since Mar 14Pushed 2mo agoCompare

[ Source](https://github.com/filipefernandes9747/laravel-model-access-audit)[ Packagist](https://packagist.org/packages/filipefernandes/laravel-model-access-audit)[ RSS](/packages/filipefernandes-laravel-model-access-audit/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Laravel Model Access Audit
==========================

[](#laravel-model-access-audit)

Track, store, and visualize access and mutations of sensitive Eloquent models in enterprise applications. This package provides a **Telescope-inspired** dashboard for auditing with advanced relationship and field-level tracking.

Features
--------

[](#features)

- **Comprehensive Event Tracking:** Logs `read`, `create`, `update`, `delete`, and `restore`.
- **Relation Auditing:**
    - **Automatic:** Detects and labels foreign key changes (e.g., `user_id` -> `Owner`).
    - **Reciprocal:** Automatically logs the inverse change on related models (e.g., Post changed? Log on User too).
    - **Manual:** Helper for pivot changes (`attach`, `detach`, `sync`).
- **Field-Level Control:** Explicitly `include` or `exclude` specific attributes from logs.
- **Dashboard:**
    - **Dynamic Sidebar:** Lists all auditable models automatically.
    - **Real-time Feel:** Quick reload and purge buttons.
    - **Diff Viewer:** Premium side-by-side comparison of changes.
- **Masking:** Protect sensitive fields (passwords, tokens) with `[MASKED]`.
- **Performance:** Optional queued logging for high-traffic apps.

Installation
------------

[](#installation)

```
composer require filipefernandes/laravel-model-access-audit
```

Publish configuration and assets:

```
php artisan vendor:publish --provider="FilipeFernandes\ModelAccessAudit\ModelAccessAuditServiceProvider"
php artisan migrate
```

Usage
-----

[](#usage)

### 1. Basic Setup

[](#1-basic-setup)

Add the `Auditable` trait and implement the `AuditableModel` contract.

```
use FilipeFernandes\ModelAccessAudit\Traits\Auditable;
use FilipeFernandes\ModelAccessAudit\Contracts\AuditableModel;

class Document extends Model implements AuditableModel {
    use Auditable;
}
```

### 2. Field-Level Auditing

[](#2-field-level-auditing)

Control exactly what gets logged.

```
class User extends Model implements AuditableModel {
    use Auditable;

    // Only log these fields
    protected array $auditInclude = ['name', 'role'];

    // OR exclude specific fields
    protected array $auditExclude = ['remember_token'];
}
```

### 3. Relation Auditing

[](#3-relation-auditing)

Track foreign key changes with human-readable labels. To enable **Reciprocal Auditing** (logging on both models), provide the inverse relationship name.

```
class Post extends Model implements AuditableModel {
    use Auditable;

    protected array $auditRelations = [
        // 'foreign_key' => ['label', 'inverse_relation_on_target']
        'user_id' => ['owner', 'posts'],
    ];
}
```

For **ManyToMany** (pivots), use the manual helper. You can pass an optional inverse relation name for reciprocal logging:

```
// User #12 attaches Role #3 -> Also logs on Role #3 for 'users' relation
$user->auditRelation('roles', 'attach', [3], [], 'users');
```

### 4. Masking

[](#4-masking)

Mask sensitive data globally in `config/audit.php` or per model:

```
protected array $auditMasked = ['ssn_number'];
```

Dashboard & Security
------------------------

[](#dashboard--security)

Access the dashboard at `/audit`.

**Authorization:**Define the `viewAuditDashboard` gate in your `AuthServiceProvider`:

```
Gate::define('viewAuditDashboard', function ($user) {
    return $user->isSystemAdmin();
});
```

Retrieving Audits
-----------------

[](#retrieving-audits)

### 1. Basic Retrieval

[](#1-basic-retrieval)

```
// Via relationship
$history = $model->audits;

// Via scopes
$logs = Audit::for($model)->latest()->get();
$logs = Audit::byUser($user)->between($start, $end)->get();
```

### 2. Timeline & History

[](#2-timeline--history)

Retrieve a human-readable stream of events or a detailed history collection.

```
// Returns a collection of formatted strings: "[2026-03-09] Email changed"
$timeline = $user->timeline();

// Returns a collection of Audit instances (stable id-based ordering)
$history = $user->history();
```

Configuration
-------------

[](#configuration)

Review `config/audit.php` to customize:

- `queue`: Enable background processing.
- `route_prefix`: Change `/audit` to something else.
- `log_reads`: Toggle read access tracking.

License
-------

[](#license)

The MIT License (MIT).

###  Health Score

19

—

LowBetter than 10% of packages

Maintenance58

Moderate activity, may be stable

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/44c4a0ab684a6ff2f571c5b6b1db79320570f053120dadb2793c9b8ee41529a3?d=identicon)[filipe9747](/maintainers/filipe9747)

---

Top Contributors

[![filipefernandes9747](https://avatars.githubusercontent.com/u/22693486?v=4)](https://github.com/filipefernandes9747 "filipefernandes9747 (3 commits)")

### Embed Badge

![Health badge](/badges/filipefernandes-laravel-model-access-audit/health.svg)

```
[![Health](https://phpackages.com/badges/filipefernandes-laravel-model-access-audit/health.svg)](https://phpackages.com/packages/filipefernandes-laravel-model-access-audit)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)