PHPackages                             inmanturbo/ecow - 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. [Database & ORM](/categories/database)
4. /
5. inmanturbo/ecow

ActiveLibrary[Database & ORM](/categories/database)

inmanturbo/ecow
===============

Eloquent copy-on-write: automatically copy all model changes to a separate table.

v1.0.4(1y ago)810[4 PRs](https://github.com/inmanturbo/ecow/pulls)MITPHPPHP ^8.2CI passing

Since Aug 7Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/inmanturbo/ecow)[ Packagist](https://packagist.org/packages/inmanturbo/ecow)[ Docs](https://github.com/inmanturbo/ecow)[ RSS](/packages/inmanturbo-ecow/feed)WikiDiscussions main Synced yesterday

READMEChangelog (5)Dependencies (13)Versions (12)Used By (0)

ecow
====

[](#ecow)

[![Latest Version on Packagist](https://camo.githubusercontent.com/5499d373e2cc0ac726040202ddc725744e253c6b86065c0e73558e6d0d612a3a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f696e6d616e747572626f2f65636f772e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/inmanturbo/ecow)[![GitHub Tests Action Status](https://camo.githubusercontent.com/d3e4c9db6e1674fc21b1fe4733063d21bdc7fb5dab013d6a6347430ca5805c46/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f696e6d616e747572626f2f65636f772f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/inmanturbo/ecow/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/9c77b95909a936234dac20d77c2327284bb4e38b49005b158d4a8b34fe72e508/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f696e6d616e747572626f2f65636f772f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/inmanturbo/ecow/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/edf2f41dd0acacc67531be2781f9005ed56ab5b79fe3fd602d92f2fa552b2b97/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f696e6d616e747572626f2f65636f772e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/inmanturbo/ecow)

Eloquent copy-on-write: automatically copy all model changes to a separate table.
---------------------------------------------------------------------------------

[](#eloquent-copy-on-write-automatically-copy-all-model-changes-to-a-separate-table)

[![ecow](art/ecow.svg)](art/ecow.svg)

Artwork by DALL-E

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

[](#installation)

You can install the package via composer:

```
composer require inmanturbo/ecow
```

You can run the migrations with:

```
php artisan ecow:migrate
```

You can run the migrations with:

```
php artisan ecow:migrate
```

You can publish and run the migrations with:

```
php artisan vendor:publish --tag="ecow-migrations"
php artisan migrate
```

You can publish the config file with:

```
php artisan vendor:publish --tag="ecow-config"
```

This is the contents of the published config file:

```
return [

    /*
     *  Enable or disable the event listeners.
     */
    'enabled' => env('ECOW_ENABLED', true),

    /*
     * The model used to store saved models.
     */
    'model' => \Inmanturbo\Ecow\Models\SavedModel::class,

    /*
     * After this amount of days, the records in `saved_models` will be deleted
     *
     * This functionality uses Laravel's native pruning feature.
     */
    'prune_after_days' => 365 * 1000000, // wouldn't delete this in a million years

    /*
     * The table name used to store saved models.
     *
     * Changing it is not supported at this time,
     * but it's here for reference and used by the `ecow:migrate` command.
     */
    'saved_models_table' => 'saved_models',

    /*
     * These tables will be created when running the migration.
     *
     * They will be dropped when running `php artisan ecow:migrate --fresh`.
     */
    'migration_tables' => [
        'saved_models',
        'saved_model_snapshots',
    ],

    /*
     * The Models that should be saved by default.
     *
     * You can use '*' to save all models.
     */
    'saved_models' => '*',

    /*
     * The Models that should not be saved by default.
     */
    'unsaved_models' => [],
];
```

Usage
-----

[](#usage)

This packages stores and tracks changes to all your models using creating, updating, and deleting events. This will NOT track any changes made using bulk updates, or changes written directly to the database using the DB facade.

It uses [event sourcing](https://martinfowler.com/eaaDev/EventSourcing.html?ref=bartoszsypytkowski.com) by storing data from native eloquent events and does not require adding any traits to your models!

### Storing arbitrary data

[](#storing-arbitrary-data)

You can store arbitrary data on the model and it will be stored in the model's history, which can be retrieved later using the `Inmanturbo\Ecow\Facades\Ecow` facade.

```
use Inmanturbo\Ecow\Facades\Ecow;

$model->fakeField = 'this is some fake data';

$model->save();
// no error

$model->fakeField;
// null

$clone = Ecow::retrieveModel(clone $model);

$clone->fakeField;
// 'this is some fake data'
```

It's recommended in most cases you use a clone when retrieving models, rather than modifying the original model, as adding a bunch of arbitrary properties from the history to say, `auth()->user()` at runtime could have unexpected results.

### Snapshotting Models

[](#snapshotting-models)

`Ecow::retrieveModel` loops through all previous versions of the model to build up state. If you have millions of versions for a model this could slow things down a bit. Snapshots set the current state, then changes are tracked from then on.

```
Ecow::snapshotModel($model);
```

### Querying versions and changes made on a model

[](#querying-versions-and-changes-made-on-a-model)

You can query all the saved versions of a model using `Inmanturbo\Ecow\Facades\Ecow::savedModelVersions($model)`.

```
use Inmanturbo\Ecow\Facades\Ecow;

$versions = Ecow::savedModelVersions($model)->latest('model_version')->limit(10)->get();

foreach ($versions as $version) {
    // get the saved models version
    $modelVersion = $version->model_version;

    // make an in memory copy of the model
    $modelCopy = $version->makeRestoredModel();

    // reset the current model's state to this version
    $modelCopy->save();

    //
}
```

### Replaying model history

[](#replaying-model-history)

You can replay the history of all recorded models using `php artisan ecow:replay-models`

```
php artisan ecow:replay-models
```

This will truncate all recorded models and replay through all of their built up state using current application logic.

### Excluding models from Ecow listeners

[](#excluding-models-from-ecow-listeners)

Some models you may not want to be recorded. You can add their class names to the `unsaved_models` array in the `ecow.php` config file.

```
php artisan vendor:publish --tag="ecow-config"
```

```
return [
    /...
    /*
     * The Models that should be saved by default.
     *
     * You can use '*' to save all models.
     */
    'saved_models' => '*',

    /*
     * The Models that should not be saved by default.
     */
    'unsaved_models' => [\App\Models\User::class],
];
```

### Only listening for and recording a few models

[](#only-listening-for-and-recording-a-few-models)

You might wish to only record a couple models. You can add their class names to the saved\_models array in the ecow.php config file.

```
return [
    /...
    /*
     * The Models that should be saved by default.
     *
     * You can use '*' to save all models.
     */
    'saved_models' => [\App\Models\Subscription::class],

    /*
     * The Models that should not be saved by default.
     */
    'unsaved_models' => [],
];
```

### Overriding the [`modelware`](https://github.com/inmanturbo/modelware) pipelines

[](#overriding-the-modelware-pipelines)

This package sends the event data through [pipelines](https://laravel.com/docs/11.x/helpers#pipeline) (similiar to middleware), which iterate through collections of invokable classes, these collections are bound into and resolved from the service container. They can be replaced or overridden in the boot method of a service provider using the following syntax:

```
app()->bind("ecow.{$event}", function () use ($pipes) {
    return collect($pipes)->map(fn ($pipe) => app($pipe));
});
```

Where the `{$event}` is a [wildcard event](https://laravel.com/docs/11.x/events#wildcard-event-listeners) for eloquent:

- `ecow.eloquent.creating*` => `eloquent.creating*`
- `ecow.eloquent.updating*` => `eloquent.updating*`
- `ecow.eloquent.deleting*` => `eloquent.deleting*`

#### Example

[](#example)

```
public function boot() {
    // pipes for all eloquent.creating events
    app()->bind('ecow.eloquent.creating*', fn () => collect($pipes = [
        \App\MyCustom\Invokable::class,
    ));
}
```

This package will send the following data object through your custom pipeline:

```
use Inmanturbo\Modelware\Data;

$data = app(Data::class, [
    'event' => $events,
    'model' => $payload[0],
    'payload' => $payload,
]);
```

It's recommended you use start your pipeline with the following defaults:

```
[
    \Inmanturbo\Ecow\Pipeline\InitializeData::class,
    \Inmanturbo\Ecow\Pipeline\EnsureModelShouldBeSaved::class,
    \Inmanturbo\Ecow\Pipeline\EnsureModelIsNotSavedModel::class,
    \Inmanturbo\Ecow\Pipeline\EnsureEventsAreNotReplaying::class,
    \Inmanturbo\Ecow\Pipeline\EnsureModelIsNotBeingSaved::class,

    // custom classes here

];
```

You can also override individual pipes:

```
app()->bind(\Inmanturbo\Ecow\Pipeline\InitializeData::class, \App\Pipeline\InitializeData::class)
```

### Disabling the Ecow Event listeners

[](#disabling-the-ecow-event-listeners)

You can disable ecow listeners at runtime with `Ecow::disable()`

```
use Inmanturbo\Ecow\Facades\Ecow;

Ecow::disable();

User::create([...]); // will not be recorded

Ecow::enable();

User::create([...]); // will be recorded
```

You can disable them globally with `config('ecow.enabled')` or `env('ECOW_ENABLED')`

```
// ecow.php
return [
    /*
     * Enable or disable the event listeners.
     */
    'enabled' => env('ECOW_ENABLED', true),
...
]
```

### A note on model keys

[](#a-note-on-model-keys)

The practice used here is event sourcing, which is best served by using `uuids`, or `guids`, as the model's id could not otherwise be known or globally identifiable, prior to it being committed to the database. However, for convenience, standard auto-incrementing keys are supported by the package, by backfilling the auto-incremented key on the creating event if there is no `uuid`, after the model is created. This requires the package to create the model itself and halt the creating event by returning `false`. The package will also store a guid property in its own table whenever a model is first created. Otherwise updating stored event history is usually a big no-no and it's definately not recommended. It is only done by the package on creating/created as a workaround.

Also supported, and perhaps the most preferred is using both a `uuid` and (auto incremented) `id` column on your models' tables. Whenever a column called `uuid` is used, `$model->uuid` will be used by the package instead of `$model->getKey()` for recording model versions.

Testing
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

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

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [inmanturbo](https://github.com/inmanturbo)
- [spatie/laravel-event-sourcing](https://github.com/spatie/laravel-event-sourcing)
- [spatie/laravel-deleted-models](https://github.com/spatie/laravel-deleted-models)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance62

Regular maintenance activity

Popularity11

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 90.4% 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

6

Last Release

693d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/0261babef618b8fb3bfcea84376ed5e71e7169586eb8de63a6550c2e7ea653a6?d=identicon)[inmanturbo](/maintainers/inmanturbo)

---

Top Contributors

[![inmanturbo](https://avatars.githubusercontent.com/u/47095624?v=4)](https://github.com/inmanturbo "inmanturbo (94 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (5 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (5 commits)")

---

Tags

databaseseloquentlaravellaravelinmanturboecow

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/inmanturbo-ecow/health.svg)

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

###  Alternatives

[spatie/laravel-permission

Permission handling for Laravel 12 and up

12.9k102.4M1.4k](/packages/spatie-laravel-permission)[spatie/laravel-pdf

Create PDFs in Laravel apps

1.0k4.8M47](/packages/spatie-laravel-pdf)[dedoc/scramble

Automatic generation of API documentation for Laravel applications.

2.1k11.2M100](/packages/dedoc-scramble)[wnx/laravel-backup-restore

A package to restore database backups made with spatie/laravel-backup.

213421.0k2](/packages/wnx-laravel-backup-restore)[spatie/laravel-passkeys

Use passkeys in your Laravel app

471890.7k39](/packages/spatie-laravel-passkeys)[rawilk/profile-filament-plugin

Profile & MFA starter kit for filament.

3914.6k](/packages/rawilk-profile-filament-plugin)

PHPackages © 2026

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