Laravel Backup Restore Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require wnx/laravel-backup-restore
   php artisan vendor:publish --tag="backup-restore-config"
   

   Ensure spatie/laravel-backup is installed (this package depends on it).

2. First Use Case: Restore the latest backup interactively:

   php artisan backup:restore
   

   • Select the backup file (defaults to APP_NAME folder).
   • Confirm decryption (uses config/backup.php password by default).
   • Confirm restore (resets DB unless --keep is used).

Where to Look First

• Configuration: config/backup.php (defines disks, connections, encryption).
• Health Checks: config/laravel-backup-restore.php (customize post-restore validation).
• Command Options: Run php artisan backup:restore --help for flags like --disk, --backup=latest, or --no-interaction.

Implementation Patterns

Core Workflow

1. Backup Selection:

   • Use --backup=latest for automation (e.g., cron jobs).
   • Specify exact paths (e.g., --backup=app_backup_2024-01-01.sql.gz).

   php artisan backup:restore --backup=app_backup_2024-01-01 --disk=s3
   

2. Database Handling:

   • Reset DB before restore with --reset (drops all tables).
   • Preserve downloaded files with --keep for debugging:

   php artisan backup:restore --keep --password=mysecret
   

3. Non-Interactive Mode:

   • Bypass prompts for CI/CD or scripts:

   php artisan backup:restore --no-interaction --connection=mysql --password=mysecret
   

Integration Tips

• Health Checks: Extend \Wnx\LaravelBackupRestore\HealthChecks\HealthCheck to validate critical data post-restore (e.g., user counts, schema integrity).

  // app/HealthChecks/CriticalDataCheck.php
  public function run(PendingRestore $pendingRestore): Result {
      return Result::make($this)
          ->okUnless(\App\Models\User::count() < 10, 'Missing users!');
  }
  

  Register in config/laravel-backup-restore.php:

  'health-checks' => [
      \App\HealthChecks\CriticalDataCheck::class,
  ],
  

• GitHub Actions: Use the provided workflow template to validate backups nightly. Store secrets (e.g., BACKUP_ARCHIVE_PASSWORD) in GitHub.

• Multi-Environment: Override APP_NAME in .env to match backup folders (e.g., APP_NAME=staging_backup).

Gotchas and Tips

Pitfalls

1. GTID Errors (MySQL):

   • Symptom: ERROR 3546: @@GLOBAL.GTID_PURGED cannot be changed.
   • Fix: Configure config/backup.php to skip GTID:

     'dump' => [
         'add_extra_option' => '--set-gtid-purged=OFF',
     ],
     

   • Workaround: Manually restore backups created without GTID.

2. Missing Backups:

   • Symptom: NoDatabaseDumpsFound exception.
   • Debug: Check the --keep output or logs for the db-dumps directory path.
   • Fix: Ensure APP_NAME matches the backup folder name.

3. Encryption Issues:

   • Symptom: Decryption fails silently.
   • Debug: Verify BACKUP_ARCHIVE_PASSWORD in .env or CLI --password.
   • Fix: Use --keep to inspect the decrypted folder (storage/app/backup-restore).

Debugging Tips

• Verbose Output: Add --verbose to see download/restore steps:

  php artisan backup:restore --verbose --backup=latest
  

• Dry Runs: Use --keep to inspect downloaded files before restoring.

• Health Check Failures: Check the command output for failed assertions. Extend checks for granular validation.

Extension Points

1. Custom Backup Paths: Override Wnx\LaravelBackupRestore\BackupFinder to scan non-standard locations.

2. Post-Restore Hooks: Use Laravel’s restored event (if supported) or extend the command class to run scripts after health checks.

3. Compression Support: The package supports .sql.gz and .bz2 out-of-the-box. For .zip, extend the Decompressor interface.

Config Quirks

• Default Disk: Uses the first disk in config/backup.php if --disk is omitted.
• Default Connection: Uses the first source DB in config/backup.php if --connection is omitted.
• APP_NAME Sensitivity: Must match the backup folder name (e.g., APP_NAME=myapp_backup).