PHPackages                             mrjutsu/ledger - 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. [Logging & Monitoring](/categories/logging)
4. /
5. mrjutsu/ledger

ActiveLibrary[Logging & Monitoring](/categories/logging)

mrjutsu/ledger
==============

A Laravel package that allows you to log everything

v0.12.5(4y ago)12[3 issues](https://github.com/mrjutsu/ledger/issues)MITPHPPHP ^7.1

Since Oct 12Pushed 2y ago1 watchersCompare

[ Source](https://github.com/mrjutsu/ledger)[ Packagist](https://packagist.org/packages/mrjutsu/ledger)[ RSS](/packages/mrjutsu-ledger/feed)WikiDiscussions main Synced today

READMEChangelog (2)Dependencies (1)Versions (4)Used By (0)

Ledger
======

[](#ledger)

Introduction
------------

[](#introduction)

Ledger is a package that aims to offer a nonrepudiation service by letting you log every single action performed on an Eloquent model. Ledger will help you know who did what when.

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

[](#installation)

Make sure to add

`\Mrjutsu\Ledger\LedgerServiceProvider::class`

to the list of providers in your application's `app.php` file.

After that, run the following command to publish the package's assets.

`php artisan vendor:publish --provider="Mrjutsu\Ledger\LedgerServiceProvider"`

This will publish migrations and a `ledger.php` config file located in your application's `config` directory.

After assets are published, run migrations.

`php artisan migrate`

Getting Started
---------------

[](#getting-started)

Using Ledger's basic features is very simple, just add the `Loggable` trait to the model you wish to log.

```
use Mrjutsu\Ledger\Traits\Loggable;

class User extends Model {
    use Loggable;
}
```

### Default Behavior

[](#default-behavior)

By default, Ledger will log the following events:

- `created`
- `updated`
- `deleted`
- `forceDeleted`

### Logging Certain Events Only

[](#logging-certain-events-only)

Logging only certain events is also very easy with Ledger.

In your model, create a constant called `EVENTS_LOGGED`, this will be an array that stores the names of the events you wish to log.

```
use Mrjutsu\Ledger\Traits\Loggable;

class User extends Model {
    use Loggable;

    const EVENTS_LOGGED = [
        'created',
        'saved',
        'deleted'
    ];
}
```

### Logging Changes To Certain Fields

[](#logging-changes-to-certain-fields)

Sometimes you might want to know what was changed to specific fields besides just knowing that the model was changed. For these cases, you can use the `FIELDS_LOGGED` constant.

```
use Mrjutsu\Ledger\Traits\Loggable;

class User extends Model {
    use Loggable;

    const FIELDS_LOGGED = [
        'name',
        'email',
        'address'
    ];
}
```

In the above example, when the user gets `saved`, the event will be logged as it should, but additionally, changes made to those fields will be stored in a `fields` object, containing the changed fields as keys and a nested object containing the old and new values.

By default, this will be an empty array.

```
$user = User::find(1);
// ['name' => 'John Doe', 'email' => 'email@example.com']

$user->name = 'Foo Bar';
$user->email = 'foo@bar.com';
$user->role = 'client';
$user->save();

$log = $user->ledgerLogs()->first();
$log->details;
//[
//    'fields' => [
//        'name' => [
//            'old' => 'John Doe',
//            'new' => 'Foo Bar'
//        ],
//        'email' => [
//            'old' => 'email@example.com',
//            'new' => 'foo@bar.com'
//        ],
//    ]
//]
```

In the above example, `role` is not logged because it was not declared in `FIELDS_LOGGED`.

If you wish to log changes made to all the fields, just add a `*` to the `FIELDS_LOGGED` array, Ledger will see this and log changes made to all the model's fields, except those ignored.

`const FIELDS_LOGGED = ['*']`

Even if a field is logged, if no changes are made to it, it won't be logged.

### Ignoring Certain Fields

[](#ignoring-certain-fields)

Similarly to how you can log certain fields, you can also ignore changes done to them.

By default, Ledger will always ignore the model's primary key and its timestamp fields, if they're used.

If you wish to ignore more fields, you can add them to the `FIELDS_IGNORED` constant.

### Custom Actions

[](#custom-actions)

Ledger allows you to log when a custom action is performed in a very simple way. To do so, just call the `log()` method on the loggable model and pass the action to log, you can also pass details as either a string or an array.

```
use Mrjutsu\Ledger\Traits\Loggable;

class Message extends Model {
    use Loggable;

    public function downloadFile($filename)
    {
        $details = sprintf('User downloaded: %s', $filename);

        $this->log('Downloaded', $details);
    }

    public function uploadFile($filename)
    {
        $details = [
            'filename' => $filename,
            'foo' => 'bar'
        ];

        $this->log('Uploaded', $details);
    }
}
```

### Replicating Models

[](#replicating-models)

Replication is a different process because Laravel creates a new instance of the model before firing the `replicating` event, this prevents Ledger from successfully logging the action since at the time of the event being fired, the new instance doesn't have an `id` set.

To mitigate this, Ledger overrides the `replicate` method and logs the `Replicating` action on the model being replicated prior to the new instance being created.

This is enabled by default, but if you wish to replicate models and not log it, you can define the constant `LOG_REPLICATING_ACTION`in your model and set it to `false`, Ledger will honor this and the replicating action will not be logged.

```
use Mrjutsu\Ledger\Traits\Loggable;

class User extends Model {
    use Loggable;

    /**
     * This means when you call replicate() on the model, the action won't be logged.
     */
    const LOG_REPLICATING_ACTION = false;
}
```

### Available Events To Log

[](#available-events-to-log)

Ledger logs the following model events:

- `created`.
- `updating`.
- `updated`.
- `saved`.
- `deleting`.
- `deleted`.
- `restoring`.
- `restored`.
- `forceDeleted`.

### Using Your Own Observers

[](#using-your-own-observers)

Ledger allows you to extend from its main class `ModelObserver` should you wish to perform a custom action prior to an event being logged.

In order to do so, you must first declare the observer action and its class, this is done in a constant array called `OBSERVERS`, in it, you will specify the event as the key and your observer as the value.

In your model:

```
use Mrjutsu\Ledger\Traits\Loggable;

class User extends Model {
    use Loggable;

    const OBSERVERS = [
        'created' => MyCreatedObserver::class,
    ];
}
```

Then, your observer should extend from `ModelObserver`.

```
use Mrjutsu\Ledger\Observers\ModelObserver;
use \Illuminate\Database\Eloquent\Model;

class MyCreatedObserver extends ModelObserver {
    public function created(Model $model)
    {
        // Your logic goes here

        $this->logAction($model, 'Your Action');
    }
}
```

Roadmap
-------

[](#roadmap)

Ledger is a package I'm expanding and maintaining in my free time, so I won't be able to provide a specific time on when a new feature, fix or improvement will be released.

If you do wish to track the status of a given project head to the [projects list](https://github.com/mrjutsu/Ledger/projects), over there you will see what's currently cooking and how many tasks are left.

Contributing
------------

[](#contributing)

If you wish to contribute to the project, follow these instructions:

- Fork the project.
- Give your branch a descriptive name, e.g.: `feature/my-awesome-feature`, `bugfix/issue-fix` or `improvement/some-optimization`, for example.
- Do your thing.
- Pull `main` into your branch.
- Make a Pull Request.

###  Health Score

14

—

LowBetter than 1% of packages

Maintenance0

Infrequent updates — may be unmaintained

Popularity4

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity38

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.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

1723d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/5807249?v=4)[David Rosillo](/maintainers/mrjutsu)[@mrjutsu](https://github.com/mrjutsu)

---

Top Contributors

[![mrjutsu](https://avatars.githubusercontent.com/u/5807249?v=4)](https://github.com/mrjutsu "mrjutsu (96 commits)")

### Embed Badge

![Health badge](/badges/mrjutsu-ledger/health.svg)

```
[![Health](https://phpackages.com/badges/mrjutsu-ledger/health.svg)](https://phpackages.com/packages/mrjutsu-ledger)
```

###  Alternatives

[statamic-rad-pack/runway

Eloquently manage your database models in Statamic.

135224.7k7](/packages/statamic-rad-pack-runway)[open-telemetry/opentelemetry-auto-laravel

OpenTelemetry auto-instrumentation for Laravel

592.7M9](/packages/open-telemetry-opentelemetry-auto-laravel)[guanguans/laravel-exception-notify

Monitor exception and report to the notification channels(Log、Mail、AnPush、Bark、Chanify、DingTalk、Discord、Gitter、GoogleChat、IGot、Lark、Mattermost、MicrosoftTeams、NowPush、Ntfy、Push、Pushback、PushBullet、PushDeer、PushMe、Pushover、PushPlus、QQ、RocketChat、ServerChan、ShowdocPush、SimplePush、Slack、Telegram、WeWork、WPush、XiZhi、YiFengChuanHua、ZohoCliq、ZohoCliqWebHook、Zulip).

14845.8k1](/packages/guanguans-laravel-exception-notify)[nightowl/agent

NightOwl monitoring agent — collects telemetry from laravel/nightwatch and writes to PostgreSQL

771.7k](/packages/nightowl-agent)[ecotone/laravel

Ecotone for Laravel — CQRS, Event Sourcing, Sagas, Durable Workflows, and Outbox on top of Laravel Queue, via PHP attributes.

21318.6k3](/packages/ecotone-laravel)

PHPackages © 2026

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