README

VersionVault is a Laravel package for model versioning that is diff-first, snapshot-assisted, and relation-aware. It captures minimal diffs, supports nested relations (including pivot data), and can reconstruct or rollback historical state.

Features

Diff-first storage with periodic snapshots
Nested relations (single, collection, pivot)
Deterministic changed paths for audits and UI diffs
Rollback support with persisted changes
Optional created-by tracking and user relation
Morph map friendly (stores morph alias when configured)

Requirements

PHP 8.2+
Laravel 11+ (tested with Laravel 12)

Installation

composer require sthira-labs/version-vault

Publish & Migrate

Publish the config and migrations, then run migrations:

php artisan vendor:publish --provider="SthiraLabs\\VersionVault\\VersionVaultServiceProvider"
php artisan migrate

To publish only the config:

php artisan vendor:publish --provider="SthiraLabs\\VersionVault\\VersionVaultServiceProvider" --tag=config

To publish only the migrations:

php artisan vendor:publish --provider="SthiraLabs\\VersionVault\\VersionVaultServiceProvider" --tag=migrations

Quick Start

use SthiraLabs\VersionVault\Traits\HasVersioning;

class Project extends Model
{
    use HasVersioning;

    public function tasks() { return $this->hasMany(Task::class); }

    public function versioningConfig(): array
    {
        return [
            'name',
            'tasks:title' => [
                'users:name,pivot(role)'
            ],
        ];
    }
}

$project->recordVersion('created');
$project->recordVersionIfChanged('updated');

$result = $project->reconstructVersion(2);
$historic = $result->model;
$rollback = $project->rollbackToVersion(2);

Reconstruction Basics

Reconstruction is non-destructive by default: existing loaded relations on the template model are preserved, and only attributes present in the snapshot are applied. Relations not present in the snapshot remain untouched unless you enable attach_unloaded_relations or force_replace_relation.

reconstructVersion() always returns a ReconstructionResult DTO with:

model (Model): the reconstructed model instance
changedPaths (array): populated only when diff paths are enabled
diff (array): populated only when diff paths are enabled

When with_diff_paths is enabled, many-relation operations include id-scoped paths:

comments.added, comments.103.added
comments.removed, comments.102.removed
tags.attached, tags.7.attached
tags.detached, tags.6.detached

Relation Tracking Modes

Each relation can be tracked in one of two modes:

reference (default): only foreign keys are tracked; relation attributes are not snapshotted.
snapshot: selected relation attributes (and nested relations/pivot data) are snapshotted.

Implicit rule (Option B):

If a relation config includes attributes, relations, or pivot, it is treated as snapshot.
Otherwise it defaults to reference.

To force snapshot explicitly, add mode: snapshot to the relation config.

Example: Reference Mode (FK-only)

public function versioningConfig(): array
{
    return [
        'amount',
        // Reference mode: only FK tracked (no related attributes)
        'owner' => true,
        'manager' => true,
    ];
}

Example: Snapshot Mode (full relation)

public function versioningConfig(): array
{
    return [
        'name',
        // Snapshot mode (implicit because fields are listed)
        'category:name',
        'profile:bio',
        'tasks:title',
        'tags:name,pivot(order)',
        // Or explicitly:
        'owner' => [
            'mode' => 'snapshot',
            'attributes' => ['name', 'email'],
        ],
    ];
}

Reference Relations in Reconstruction

Reference relations are not hydrated from the snapshot. The foreign key is stored as a normal attribute, so you can eager load after reconstruction:

$result = $project->reconstructVersion(2);
$result->model->load('owner', 'manager');

If you want FK-only tracking without listing the relation, you can track the FK attribute directly:

public function versioningConfig(): array
{
    return [
        'name',
        'owner_id',
    ];
}

Snapshot Relations in Reconstruction

Snapshot relations are hydrated from stored data (or explicitly allowed via reconstruct_relations):

$result = $project->reconstructVersion(2, [
    'reconstruct_relations' => ['category', 'tasks', 'tags'],
    'attach_unloaded_relations' => true,
]);

Configuration

Config file: config/version-vault.php

snapshot_interval (int): store a full snapshot every N versions (default 10)
store_empty (bool): allow storing a version even when no changes are detected (default false)
debug (bool): enable structured debug logs (default false)
debug_channel (string|null): log channel to use for debug logs (default null)
migrations (bool): auto-load package migrations (default true)
table_name (string): versions table name
model (class-string): Version model class
user_model (class-string|null): model used for Version::user() relation (defaults to auth.providers.users.model)
reconstruct (array): default reconstruction options
reconstruct.hydrate_loaded_relations_only (bool): only hydrate relations already loaded on the template model (default true)
reconstruct.preserve_missing_attributes (bool): keep template attributes not present in the snapshot (default true)
reconstruct.attach_unloaded_relations (bool): build relations even when not loaded (default false)
reconstruct.force_replace_relation (bool): replace relation objects rather than update in-place (default false)
reconstruct.with_diff_paths (bool): include diff + changed paths in reconstruction result (default false)
reconstruct.reconstruct_relations (array|null): if set, only hydrate the listed relations
reconstruct.prune_missing_many_relations (bool): for loaded hasMany/morphMany/belongsToMany, remove items not present in target version (default true). When false, missing items are kept; if explicit removed/detached ids exist, unrelated stale items are still dropped.
bindings (array): override internal services (change detector, snapshot builder, resolver, manager, etc.)

Migration Note

Default relation tracking is now reference mode to avoid creating versions when related model attributes change but the foreign key does not. If you rely on deep relation snapshots, configure the relation with fields (implicit snapshot) or set mode: snapshot.

Version Records (created_by)

If an authenticated user exists, created_by is recorded on each version.
The Version model exposes a user() relation that resolves via version-vault.user_model or falls back to auth.providers.users.model.

Snapshot & Diff Format

See docs/NEW_NODE_FORMAT.md for the exact snapshot/diff schema and examples.

Events

VersionVault dispatches lifecycle events you can listen to:

SthiraLabs\VersionVault\Events\VersionRecording
SthiraLabs\VersionVault\Events\VersionRecorded
SthiraLabs\VersionVault\Events\VersionReconstructed
SthiraLabs\VersionVault\Events\VersionRollback

Details and payloads are documented in docs/EVENTS.md.

Testing

composer test

Useful Commands

Install package: composer require sthira-labs/version-vault
Publish config: php artisan vendor:publish --provider="SthiraLabs\\VersionVault\\VersionVaultServiceProvider" --tag=config
Publish migrations: php artisan vendor:publish --provider="SthiraLabs\\VersionVault\\VersionVaultServiceProvider" --tag=migrations
Run migrations: php artisan migrate
Run tests: composer test

Development

Local dev option: use the provided docker-compose / Makefile or Laravel Sail.

License

MIT

sthira-labs / version-vault

Maintainers

Package info

Statistics

Security