Laravel Easy Backups Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aaix/laravel-easy-backups
   php artisan vendor:publish --provider="Aaix\EasyBackups\EasyBackupsServiceProvider" --tag="config"
   

   • Publishes default config to config/easy-backups.php.

2. First Backup

   use Aaix\EasyBackups\Facades\EasyBackups;
   
   EasyBackups::run(); // Creates a backup in storage path (default: `storage/app/backups`)
   

   • Check storage/app/backups/ for generated .sql or .gz files.

3. Key Config

   • Review config/easy-backups.php for:
     • backup_path (default: storage/app/backups)
     • compression (default: gzip)
     • database (default: mysql, but supports pgsql, sqlite)

First Use Case: Scheduled Backups

// app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
    $schedule->command(EasyBackups::class)
             ->dailyAt('2:00') // Runs at 2 AM daily
             ->withoutOverlapping();
}

• Run php artisan schedule:run manually or use Laravel Forge/Forge.

Implementation Patterns

1. Fluent Backup Customization

EasyBackups::run()
    ->database('pgsql') // Override default DB
    ->compress('zip')    // Force ZIP compression
    ->excludeTables(['password_resets', 'sessions'])
    ->withFilename('custom_backup_' . now()->format('Y-m-d'))
    ->run(); // Execute

2. Remote Storage Integration

// Configure in config/easy-backups.php
'storage' => [
    'driver' => 's3',
    'key'    => env('AWS_ACCESS_KEY_ID'),
    'secret' => env('AWS_SECRET_ACCESS_KEY'),
    'bucket' => 'my-backup-bucket',
    'path'   => 'laravel/backups',
],

• Uses Laravel’s built-in filesystem drivers (S3, FTP, etc.).

3. Event-Based Workflows

// Listen for backup completion
EasyBackups::listen(function ($backup) {
    Log::info("Backup created: {$backup->filename}");
    // Send Slack notification, etc.
});

4. Incremental Backups

EasyBackups::run()
    ->incremental() // Only backups changed data (MySQL only)
    ->run();

5. Backup Verification

$backup = EasyBackups::run()->verify();
if ($backup->isValid()) {
    // Proceed with backup
}

Gotchas and Tips

Pitfalls

1. Database-Specific Quirks

   • PostgreSQL: Requires pg_dump CLI tool. Ensure it’s installed on the server.

     EasyBackups::run()->database('pgsql')->withBinary('pg_dump');
     

   • SQLite: Backs up the entire file (no table-level control).
   • MySQL: Incremental backups (--where) may fail on large tables.

2. Permissions

   • Ensure storage/app/backups is writable:

     chmod -R 775 storage/app/backups
     

   • For S3/FTP, verify credentials and bucket permissions.

3. Large Databases

   • Use --quick flag for MySQL to skip table locks (but slower):

     EasyBackups::run()->database('mysql')->withOptions(['quick']);
     

   • For >1GB backups, stream directly to remote storage to avoid disk I/O.

4. Timeouts

   • Long-running backups may hit PHP’s max_execution_time. Use queues:

     EasyBackups::run()->dispatch(); // Dispatches to queue
     

Debugging

• Log Output: Enable debug mode in config:

  'debug' => env('BACKUP_DEBUG', false),
  

• Dry Runs: Test without writing files:

  EasyBackups::run()->dryRun()->run();
  

• Error Handling:

  try {
      EasyBackups::run()->run();
  } catch (\Exception $e) {
      Log::error("Backup failed: " . $e->getMessage());
  }
  

Tips

1. Filename Customization

   EasyBackups::run()
       ->withFilename(fn () => 'backup_' . Str::uuid())
       ->run();
   

2. Backup Retention Policy Combine with Laravel’s filesystem cleanup:

   // app/Console/Commands/CleanBackups.php
   public function handle()
   {
       Storage::disk('backups')->delete(
           Storage::disk('backups')->files('', true)
               ->filter(fn ($file) => now()->diffInDays($file->lastModified()) > 7)
       );
   }
   

3. Multi-Database Backups

   EasyBackups::run()
       ->database('mysql', ['connection' => 'mysql_secondary'])
       ->run();
   

4. Extension Points

   • Pre/Post Hooks: Use events (BackupStarting, BackupCompleted).
   • Custom Drivers: Extend Aaix\EasyBackups\Contracts\BackupDriver for unsupported DBs.

5. CI/CD Integration

   # In GitHub Actions
   - name: Run backups
     run: php artisan easy-backups:run --filename="ci_backup_$(date +%s)"