README

A Laravel package that provides content snapshots with restore functionality for Filament applications. This package allows you to create, manage, and restore content snapshots for any model fields - not just HTML and CSS, but any content you want to track.

Features

📸 Automatic snapshots - Automatically create snapshots before content updates/deletions
🔧 Manual snapshots - Create snapshots with custom descriptions
🔄 Easy restore - Restore content from any snapshot with diff preview
🎯 Configurable fields - Track any model fields, not just HTML/CSS
🎨 Filament integration - Beautiful UI components for Filament admin panels
⚡ Livewire powered - Real-time updates and interactions
🗂️ Polymorphic - Works with any Eloquent model
🧹 Auto-cleanup - Automatically clean up old snapshots
📊 JSON storage - Efficient field storage with PostgreSQL JSONB support
🔍 Advanced diffs - Multi-field comparison with tabbed interface

Installation

Install the package via Composer:

composer require rayzenai/filament-snapshots

Publish and run the migrations:

php artisan vendor:publish --tag="filament-snapshots-migrations"
php artisan migrate

Optionally, publish the config file:

php artisan vendor:publish --tag="filament-snapshots-config"

Usage

1. Add the Trait to Your Model

Add the HasContentSnapshots trait to any model that has content you want to track:

use Rayzenai\FilamentSnapshots\Concerns\HasContentSnapshots;

class Page extends Model
{
    use HasContentSnapshots;

    // Your model code...
}

2. Add the Action to Your Filament Resource

Add the snapshots action to your Filament resource header actions:

use Rayzenai\FilamentSnapshots\Actions\ManageContentSnapshotsAction;

class PageResource extends Resource
{
    // ... other resource methods

    public static function getHeaderActions(): array
    {
        return [
            ManageContentSnapshotsAction::make(),
            // ... other actions
        ];
    }
}

3. Configure Fields to Track

By default, the package tracks html and css fields. You can customize which fields to track per model:

// In config/filament-snapshots.php
return [
    'models' => [
        'App\\Models\\Page' => [
            'fields' => [
                'content' => 'content',           // field_key => model_attribute
                'meta_description' => 'meta_description',
                'title' => 'title',
            ],
        ],
        
        'App\\Models\\BlogPost' => [
            'fields' => [
                'body' => 'body',
                'excerpt' => 'excerpt',
                'title' => 'title',
            ],
        ],
    ],
    
    // Default fields for models without specific configuration
    'default_fields' => [
        'html' => 'html',
        'css' => 'css',
    ],
];

4. Using Snapshots

Automatic Snapshots

Snapshots are automatically created:

Before updating content (when any tracked fields change)
Before deleting a model

Manual Snapshots

Create manual snapshots programmatically:

$page = Page::find(1);
$snapshot = $page->createSnapshot('Before major redesign');

Restore from Snapshot

Restore content from a snapshot:

$snapshot = ContentSnapshot::find(1);
$snapshot->restore();

Get Snapshots

Get all snapshots for a model:

$snapshots = $page->getSnapshots();

Configuration

The package comes with a configuration file that allows you to customize various aspects:

return [
    'table_name' => 'content_snapshots',

    'auto_snapshot' => [
        'enabled' => true,
        'on_update' => true,
        'on_delete' => true,
    ],

    'snapshot_limits' => [
        'max_per_model' => 50,
        'cleanup_after_days' => 30,
    ],

    'ui' => [
        'modal_width' => 'seven_extra_large',
        'snapshots_per_page' => 20,
        'diff_height' => 'h-64',
    ],

    'content_columns' => [
        'html' => 'html',
        'css' => 'css',
    ],

    'metadata' => [
        'track_user' => true,
        'track_ip' => false,
        'track_user_agent' => false,
    ],
];

Customization

Custom Column Names

If your model uses different column names for HTML/CSS content:

// In your config/filament-snapshots.php
'content_columns' => [
    'html' => 'content',
    'css' => 'styles',
],

Custom Views

Publish the views to customize the UI:

php artisan vendor:publish --tag="filament-snapshots-views"

API

Model Methods

// Create a snapshot
$snapshot = $model->createSnapshot('Description');

// Get snapshots
$snapshots = $model->getSnapshots($limit);

// Restore from snapshot
$model->restoreFromSnapshot($snapshot);

// Delete all snapshots
$model->deleteSnapshots();

Snapshot Methods

// Restore snapshot
$snapshot->restore();

// Get the related model
$model = $snapshot->snapshotable;

Requirements

PHP 8.1+
Laravel 10.0+
Filament 3.0+
Livewire 3.0+

License

MIT License. Please see License File for more information.

Contributing

Please see CONTRIBUTING.md for details.

Credits

Support

For support, please contact us at info@rayzenai.com or create an issue on GitHub.

rayzenai / filament-snapshots

Maintainers

Details