cleaniquecoders/laravel-config-backup

Backup and restore Laravel configuration (.env and database settings) as a portable AES-256 encrypted archive.

v1.0.0 2026-06-08 13:39 UTC

Requires

• php: ^8.3||^8.4
• ext-zip: *
• illuminate/contracts: ^11.0||^12.0||^13.0
• illuminate/database: ^11.0||^12.0||^13.0
• illuminate/support: ^11.0||^12.0||^13.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.14
• livewire/livewire: ^3.0
• nunomaduro/collision: ^8.8
• orchestra/testbench: ^11.0.0||^10.0.0||^9.0.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-arch: ^4.0
• pestphp/pest-plugin-laravel: ^4.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• spatie/laravel-ray: ^1.35

Suggests

• livewire/flux: Flux UI components used by the optional management screen.
• livewire/livewire: Required for the Config Backup management screen (UI).
• spatie/laravel-settings: Register SettingsProperty in the database allowlist to back up DB-stored settings.

MIT

• Nasrul Hazim Bin Mohamad

• configuration
• encryption
• backup
• laravel
• Settings
• env
• restore
• Cleanique Coders
• laravel-config-backup

README

Back up and restore your Laravel application configuration — the .env file and database-stored settings — as a single portable, AES-256 password-encrypted ZIP.

The archive stores its contents decrypted, so on import every encrypted database column is re-encrypted with the destination server's APP_KEY. That makes a backup taken on one server restorable on another. Every restore takes an automatic pre-restore safety snapshot first, so you can always roll back.

Why

• Disaster recovery — capture your .env and DB-stored settings before a risky change.
• Server migration — move configuration between environments even when the APP_KEY differs.
• Auditable — each backup is a row with who/when/what, retained per your policy.

Features

• 🔐 AES-256 password-encrypted archives (the password is never stored)
• 📦 Two sections: env (the .env file) and database (allowlisted DB-stored settings)
• 🔁 Portable across servers — DB columns re-encrypted with the destination APP_KEY
• 🛟 Automatic pre-restore safety snapshot
• 🔎 Preview/diff before restoring (added/changed/removed .env keys, APP_KEY-change warning)
• 🧹 Retention pruning
• 🖥️ Artisan commands, optional scheduler, optional Livewire + Flux UI, and notifications

Installation

composer require cleaniquecoders/laravel-config-backup

Publish and run the migration:

php artisan vendor:publish --tag="laravel-config-backup-migrations"
php artisan migrate

Publish the config:

php artisan vendor:publish --tag="laravel-config-backup-config"

Store archives on a private disk. They contain every secret. The ZIP itself is encrypted, but never expose it on a public disk.

The database section (allowlist)

Out of the box only the env section has anything to back up. To include database-stored settings, register the models in config/config-backup.php. Rows are exported through each model's casts (so encrypted columns are decrypted) and re-imported via updateOrCreate (matched on match), which re-encrypts them with the active APP_KEY:

'database' => [
    'settings' => [
        'model' => \Spatie\LaravelSettings\Models\SettingsProperty::class,
        'match' => ['group', 'name'],
    ],
    // 'sso_providers' => ['model' => \App\Models\SsoProvider::class, 'match' => ['uuid']],
],

Usage

Programmatically

use CleaniqueCoders\ConfigBackup\Facades\ConfigBackup;

// Create an encrypted backup of both sections.
$backup = ConfigBackup::create(['env', 'database'], 'a-strong-password');

// Inspect an archive before applying it.
$absPath = Storage::disk($backup->disk)->path($backup->path);
$preview = ConfigBackup::preview($absPath, 'a-strong-password');

// Restore selected sections (takes a safety snapshot first).
$result = ConfigBackup::restore($absPath, 'a-strong-password', ['env', 'database']);

Artisan

# Create (password also reads from config-backup.schedule.password)
php artisan config-backup:create --sections=env,database --password=secret --notes="before upgrade"

# Restore an existing backup by UUID, or an external file
php artisan config-backup:restore {uuid} --password=secret
php artisan config-backup:restore --file=/path/to/backup.zip --password=secret --sections=env

# Prune beyond the retention count
php artisan config-backup:prune

Scheduled backups

Enable in config (config-backup.schedule.enabled) and set a password. The package registers a scheduled config-backup:create plus a daily prune automatically.

Notifications

Set config-backup.notifications.enabled and a recipient list in config-backup.notifications.mail to be emailed when a backup completes or fails.

Web UI (optional)

If your app has Livewire and Flux, a management screen is available at the configured route (config-backup.route.prefix, default admin/config-backup). Protect it with the config-backup.gate ability and/or route middleware.

Restoring after an APP_KEY change

When the restored .env carries a different APP_KEY, the package swaps the active encrypter mid-request so DB settings are re-encrypted with the final key, fires the ConfigRestored event (with appKeyChanged: true), and clears the config/cache. You may need to sign in again. Listen for ConfigRestored to flush any application-specific caches.

Testing

composer test

Local development (Testbench workbench)

The package ships a Testbench workbench — a real Laravel app with the package installed — so you can exercise it end-to-end. It seeds an admin user and three encrypted settings rows registered in the database allowlist.

# Build the workbench app (creates the sqlite db, migrates, seeds)
vendor/bin/testbench workbench:build
vendor/bin/testbench migrate:fresh --seed --seeder='Workbench\Database\Seeders\DatabaseSeeder'

# Drive the feature from the CLI
vendor/bin/testbench config-backup:create --sections=env,database --password=secret-pass --notes="manual test"
vendor/bin/testbench config-backup:restore <uuid> --password=secret-pass --force
vendor/bin/testbench config-backup:prune --keep=2

# Serve the app (welcome page + management UI at /admin/config-backup)
composer serve

The management UI renders with Flux components — install livewire/flux in the workbench to view it. The CLI and service work without it.

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

• Nasrul Hazim Bin Mohamad
• All Contributors

License

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