Download the PHP package dvarilek/laravel-snap without Composer

On this page you can find all versions of the php package dvarilek/laravel-snap. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package laravel-snap

Laravel Snap

Latest Version on Packagist GitHub Workflow Status License

Overview

Laravel Snap is a robust and easily configurable package for versioning your application's Eloquent Models by capturing their full context in a Snapshot - this even includes attributes from related Models.

Model versions are stored in Snapshots. A Snapshot is a copied state of a Model - state meaning its attributes alongside important metadata like their casts. Obviously, since the attributes are copied, no synchronization is done on updates, meaning the state gets truly persisted.

A Snapshot can not only store Model attributes from a single Model, but Laravel Snap even handles storing of related Model attributes relative to the origin Model. Related attributes are stored directly in the Snapshot - no 'related' Snapshot gets created and linked to. This means that the full context of a record gets captured and persisted in a single Snapshot. (useful for legislative requirements and auditing purposes)


Installation

1. Install the package:

2. Initialize the package

Additionally, you can publish the config:


Getting Started

[!NOTE]\ To see all configuration options for SnapshotDefinition, see the Snapshot Configuration section.

[!NOTE]\ For more information and options, see the Snapshots section.


Snapshot Configuration

The configuration of what exactly gets and doesn't get captured in a Snapshot is done fluently through a SnapshotDefinition.

Capturing Model Attributes

Capture all model attributes. Hidden attributes are excluded unless specifically enabled:

\ Capture only specific attributes from the model:

\ By default, hidden attributes are excluded even when specified in the capture method. To enable capturing hidden attributes you can use:

\ Prevent specified attributes from being included in the Snapshot:

\ By default, attribute casting (like dates, enums, arrays, collections) is preserved in the Snapshot. To store attributes without their original casting types, you can specifically disable this feature:

\ Exclude Laravel's timestamp fields (created_at, updated_at, deleted_at) from the snapshot:

[!IMPORTANT]\ When timestamps are captured (not excluded), they are prefixed with 'origin_' to prevent conflicts with the Snapshot's own timestamps. For example, the model's 'created_at' becomes 'origin_createdat' in the Snapshot. The timestamp prefix ('origin' by default) can be modified in the package's config file.

Capturing Related Attributes

Capturing attributes from related models stores them in the same Snapshot. The captured attributes are prefixed by their relation path relative to the main model. This is done to avoid potential naming conflicts between attributes.

To capture related attributes you need to provide a RelationDefinition(s):

[!NOTE]\ RelationDefinition is a superset of SnapshotDefinition, meaning it has access to all its methods, meaning methods like captureAll(), exclude(), excludeTimestamps(), etc. are available.

[!IMPORTANT]\ Currently, only BelongsTo relationship is supported. Support for other relationships is planned for future releases.

Capturing Nested Related Attributes

You can capture deeply nested related attributes by capturing them like this: The same prefix rules apply.



Snapshots

Working With Snapshots

Taking Snapshots \ After using the Snapshotable trait in your Model, you can take Snapshots like this:

The 'takeSnapshot' method accepts an array of extra attributes that can be provided at runtime. These attributes are then stored in the created Snapshot:

[!TIP] The extra attributes can even bypass SnapshotDefinition constraints.

Retrieving\ For convenience, the Snapshotable trait adds two relationships for getting the latest and oldest Snapshots out of the box:

The Snapshot stores its captured attributes in a special JSON column structure. However, you are able to interact with them directly as if they were regular model attributes with property access:

[!NOTE]\ For more information about how these attributes are stored, see the Internal Implementation section.


Updating \ Snapshots support both mass assignment and individual property updates:


Querying \ Because Snapshot attributes are stored in a JSON column, they can't be queried directly as they need to be queried in the JSON column. For more information about JSON querying see the Official Laravel Documentation

Reverting & Versioning

Basic Reverting\ Reverting allows you to restore a Model's state to one of its previous snapshots:

The sync method on Snapshot model is a convenient shortcut to synchronize the Snapshot's state with its origin model. In other words, the code above can be replaced with this:

Currently, there is no way to configure what exactly gets and doesn't get reverted from a Snapshot like there is for taking Snapshots with SnapshotDefinition. However, you can optionally configure if related model attributes should be also restored from the Snapshot.

Versioning\ To enable full versioning capabilities, your Snapshotable model can optionally include a column that tracks the model's current version. This column is optional but required for version-based operations like 'rewind' and 'forward'.

If you don't want to manually create and migrate the migration, you can do so by running:

The command automatically generates a migration for your model and, if confirmed, migrates it.

[!NOTE]\ If you run this command without specifying a model, or if the specified model is invalid, the command will attempt to look for valid models and prompt you for selection.

Once versioning is enabled, you can navigate through the Model's history by steps. The 'rewind' method allows you to move backward through your model's history by a specified number of steps:

Similar to 'rewind', the 'forward' method allows you to move forward through your model's history:

Both 'forward' and 'rewind' methods call the 'revertTo' method internally and accept the following optional arguments:

Race Conditions

Concurrent snapshotting and reverting operations by different users can lead to inconsistent behavior. Laravel Snap prevents these race conditions by using Laravel's atomic locks feature. Once a lock is acquired, it waits until the operation finishes before allowing other processes to proceed.

The cache lock names and timeouts can be configured inside the package's config file under 'concurrency'.

Event Hooks

While working with snapshots, you can hook into the snapshotting and reverting processes:

[!IMPORTANT]\ Both 'rewind' and 'forward' methods dispatch the 'reverting' and 'reverted' events.


Advanced

Internal Implementation

Storage\ Snapshots are stored in a dedicated table (model_snapshots) and connected to their original models through a polymorphic relationship. The captured attributes are kept in a special JSON 'storage' column with in a structured format, preserving all of their necessary metadata.

[!NOTE]\ relationPath is an array of ordered relationship names relative to the base model.


Data Manipulation \ Working with JSON-encoded data directly through the Snapshot model is possible by hooking into the Model's event handling.

Attributes are decoded from the storage column and set as the model's attributes, subsequent updates to these attributes are then persisted by encoding them back into the storage column's JSON. The internal implementation of attributes encoding and decoding is partially derived from VirtualColumn Laravel package

Advanced Usage

DTO Usage\ Internally, all Snapshot attributes are set using the mentioned special DTO's. This is useful to know when you want to update Snapshots by appending them with extra attributes or by modifying their existing attributes if you for example wish to change their casts.

Additionally, extra attribute information can also be provided when creating a Snapshot with extra attributes.


Testing


Changelog

Please refer to Package Releases for more information about changes.

License

This package is under the MIT License. Please refer to License File for more information


All versions of laravel-snap with dependencies

PHP Build Version
Package Version
Requires php Version ^8.2|^8.3|^8.4
illuminate/database Version ^10.0|^11.0
illuminate/support Version ^10.0|^11.0
illuminate/contracts Version ^10.0|^11.0
spatie/laravel-package-tools Version ^1.18
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package dvarilek/laravel-snap contains the following files

Loading the files please wait ....