Download the PHP package laragear/rewind without Composer

Rewind

Travel back in time to see past model states, and restore them in one line.

Become a sponsor

Your support allows me to keep this package free, up-to-date and maintainable. Alternatively, you can spread the word!

Requirements

Call Composer to retrieve the package.

Setup

First, install the migration file. This migration will create a table to save all previous states from your models.

[!TIP]

You can change the table name.

Finally, add the HasRewind trait into your models you want its state to be saved when created and updated.

That's it. Next time you want restore the previous state of a model, use the rewind() method.

How it works?

When your model is created, and subsequently updated, a new state is saved into the database. That state in comprised of the raw attributes of your original model.

With the rewind() helper method, you can easily peek and restore a previous model states like the last one, or have a list of states ready to be restored from. Additionally, the HasRewind trait allows to control when to save states, and what to save and restore.

States are reactive, not proactive. In other words, states are saved after the original model is saved, not before.

Saving States

States are created automatically when the model is created or updated. There is nothing you need to do to ensure the state has been persisted, but you can hear for the StatePushed event.

Without creating states

Sometimes you will want to avoid creating a replica when a model is created or updated.

To do that, use the withoutCreatingStates() method of your model with a callback. Inside the callback, the states won't be pushed to the database.

Manually creating States

If you have disabled automatic states creation, then you may save a state manually using the create() method.

The create() method allows keep the state from automatic pruning, and also skip automatic pruning.

If you want, you can save a state without updating the original model. For example, you can create a bunch of articles "drafts".

Listing States

To get a list of all prior models states use the all() method. It will return an Eloquent Collection of all past models.

[!TIP]

You can use the state ID to later restore a given state ID.

Count

To count all the saved states, use the count() method. It will return the number of persisted states.

Existence

To avoid counting all the states and only check if there is at least one state made for the model, use the exists() method.

Alternatively, the missing() method checks if there are no states saved for the model.

Latest and Oldest states

You may also use findLatest() and findOldest() if you need to find the first or the last model state, respectively.

Retrieving a State ID

To retrieve a model instance by its state ID, use the find() method.

[!CAUTION]

Because the State ID is expected to exist, a ModelNotFoundException will be thrown if id doesn't exist.

Restoring States

The easiest way to restore a prior state data into the same model instance is using the to() method with the ID of the state to restore, and just calling save() to persist the changes in the database.

Alternatively, you can always restore the model to the latest or oldest state using toLatest() or toOldest(), respectively.

[!IMPORTANT]

When the model restored is updated, it will create a new state. To avoid this, use withoutCreatingStates().

Restoring states alongside the original model

If you retrieve prior model state, you will virtually have two instances in your code: the current one, and the past state model.

Saving the past state will replace the data of the original in the database. The original instance will not be aware of the changes made, so you should refresh the model, or discard it.

Deleting states

You may delete a state the delete() and the ID of the state.

You may also use the deleteLatest() or deleteOldest() to delete the latest or oldest state, respectively.

[!IMPORTANT]

Using deleteLatest() and deleteOldest() do not delete kept states, you will need to issue true to force its deletion.

Deleting all states

You may call the clear() method to delete all the states from a model.

Since this won't include kept states, you can use forceClear() to include them.

Pruning states

Every time the model is updated, it automatically prunes old model states to keep a limited number of states. If you have disabled it, you may need to call the prune() method manually to remove stale states.

[!NOTE]

When retrieving states, states to-be-pruned are automatically left out from the query.

Events

This package fires the following events:

For example, you can listen to the StatePushed event in your application with a Listener.

The StateRestored event is included for convenience. If you decide to restore a model to a previous state, you may trigger it using StateRestored::dispatch() manually with the model instance.

Raw States

Model States data are saved into the Laragear\Rewind\Models\RewindState model. This model is mostly responsable for creating a new model instance from the raw data it holds.

Querying Raw States

Use the query() method to start a query for the given model. You may use this, for example, to paginate results.

You may also use the model instance query directly for further custom queries.

Configuration

Sometimes you will want to change how the rewind procedure works on your model. You can configure when and how states are saved using the trait methods.

Limiting number of saved states

By default, the limit of rewind states is 10, regardless of how old these are. You may change the amount by returning an integer in the rewindLimit() method.

You may also change the limit to a moment in time. States created before the given moment won't be considered on queries and will be pruned automatically when saving a model.

To limit by both an amount and a date at the same time, return an array with both.

Finally, you may disable limits by returning falsy, which will ensure all states are saved.

Automatic State saving

Every time you create or update a model, a new state is created in the database. You may change this behaviour using shouldCreateRewindStateOnCreated() and shouldCreateRewindStateOnUpdated(), respectively.

This may be useful if you want to not save a model state, for example, if an Article doesn't have enough characters in its body, or if the User is not subscribed to a plan.

Automatic pruning

By default, everytime a new state is pushed into the database, it prunes the old states. You may disable this programmatically using shouldPruneOldRewindStatesOnUpdated().

Keep State

When you create a model, the initial state can be lost after pushing subsequent new states. To avoid this, you can always protect the first state, or any state, with shouldKeepFirstRewindState().

[!TIP]

If the first state is protected, it won't be pruned, so only newer states will rotate.

Attributes to save in a State

By default, all raw attributes of the model are added into the state data. You can override this by setting your own attributes to use in the state to save by returning an associative array or an \Illuminate\Contracts\Support\Arrayable instance.

Attributes to restore from a State

To modify how the model should be filled with the attributes from the state, use the setAttributesFromRewindState(). It receives the raw attributes from the state as an array.

Migrations

Laravel Octane compatibility

• There are no singletons using a stale application instance.
• There are no singletons using a stale config instance.
• There are no singletons using a stale request instance.
• There are no static properties written on every request.

There should be no problems using this package with Laravel Octane.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

License

This specific package version is licensed under the terms of the MIT License, at time of publishing.

Laravel is a Trademark of Taylor Otwell. Copyright © 2011-2024 Laravel LLC.