Download the PHP package inmanturbo/ecow without Composer

ecow

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

Artwork by DALL-E

Installation

You can install the package via composer:

You can run the migrations with:

You can run the migrations with:

You can publish and run the migrations with:

You can publish the config file with:

This is the contents of the published config file:

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 by storing data from native eloquent events and does not require adding any traits to your models!

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.

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

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.

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).

Replaying model history

You can replay the history of all recorded models using 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

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.

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.

Overriding the modelware pipelines

This package sends the event data through pipelines (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:

Where the {$event} is a wildcard event for eloquent:

• ecow.eloquent.creating* => eloquent.creating*
• ecow.eloquent.updating* => eloquent.updating*
• ecow.eloquent.deleting* => eloquent.deleting*

Example

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

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

You can also override individual pipes:

Disabling the Ecow Event listeners

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

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

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

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• inmanturbo
• spatie/laravel-event-sourcing
• spatie/laravel-deleted-models
• All Contributors

License

The MIT License (MIT). Please see License File for more information.