Symfony Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require backup-manager/symfony
   

   For Symfony Flex projects, the bundle auto-enables. For non-Flex, add to config/bundles.php:

   BM\BackupManagerBundle\BMBackupManagerBundle::class => ['all' => true],
   

2. Configuration: Define databases and storage in config/packages/bm_backup_manager.yml:

   bm_backup_manager:
       database:
           production:
               dsn: '%env(resolve:DATABASE_URL)%'
       storage:
           s3:
               type: AwsS3
               key: '%env(AWS_KEY)%'
               secret: '%env(AWS_SECRET)%'
               bucket: 'my-backups'
   

3. First Backup: Use the CLI to back up the production database to S3:

   php bin/console backup-manager:backup production s3 --filename=backup_$(date +%F).sql.gz -c gzip
   

Where to Look First

• Configuration: config/packages/bm_backup_manager.yml (default location).
• CLI Commands: backup-manager:backup and backup-manager:restore for quick testing.
• Service: BackupManager (injectable via dependency injection).

First Use Case

Automate Nightly Backups:

1. Configure a cron job to run:

   php bin/console backup-manager:backup production s3 --filename=nightly_$(date +%F).sql.gz -c gzip
   

2. Store credentials in environment variables (e.g., .env or a secrets manager).

Implementation Patterns

Usage Patterns

1. Programmatic Backups:

   use BM\BackupManagerBundle\BackupManager;
   
   public function __construct(private BackupManager $backupManager) {}
   
   public function backupDatabase()
   {
       $this->backupManager->makeBackup()
           ->run('production', [new Destination('s3', 'backups/prod_'.date('Y-m-d').'.sql.gz')], 'gzip');
   }
   

2. Restoring from Storage:

   public function restoreDatabase()
   {
       $this->backupManager->makeRestore()
           ->run('s3', 'backups/prod_2023-10-01.sql.gz', 'production', 'gzip');
   }
   

3. Conditional Backups: Use events or commands to trigger backups (e.g., pre-deployment):

   php bin/console backup-manager:backup staging s3 --filename=pre_deploy_$(date +%F).sql.gz -c gzip
   

Workflows

1. Multi-Environment Backups: Configure separate database/storage entries for development, staging, and production in bm_backup_manager.yml.

2. Incremental Backups: Use --ignore-tables in CLI or ignoreTables in config to exclude large tables (e.g., logs):

   ignoreTables: ['logs', 'sessions']
   

3. Compression and Encryption: Chain compression (gzip) and encryption (openssl) in the CLI:

   php bin/console backup-manager:backup production s3 --filename=backup.sql.gz -c gzip,openssl
   

Integration Tips

1. Laravel-Specific:

   • Use Laravel’s Artisan facade to call commands:

     Artisan::call('backup-manager:backup', [
         'database' => 'production',
         'storage' => 's3',
         '--filename' => 'custom_backup.sql.gz',
         '--compression' => 'gzip'
     ]);
     

   • Bind the BackupManager service to Laravel’s container for DI:

     $this->app->bind(BackupManager::class, function ($app) {
         return new BackupManager($app['bm_backup_manager']);
     });
     

2. Event-Driven Backups: Listen to Laravel events (e.g., deploying) to trigger backups:

   public function handle(Deploying $event)
   {
       $this->backupManager->makeBackup()->run('production', [...], 'gzip');
   }
   

3. Storage Fallbacks: Configure multiple storage backends (e.g., s3 and local) and use a fallback strategy:

   storage:
       s3:
           type: AwsS3
           # ...
       local:
           type: Local
           root: '/backups'
   

   Then handle failures in code:

   try {
       $this->backupManager->makeBackup()->run('production', [new Destination('s3', 'backup.sql.gz')], 'gzip');
   } catch (Exception $e) {
       $this->backupManager->makeBackup()->run('production', [new Destination('local', 'backup.sql.gz')], 'gzip');
   }
   

Gotchas and Tips

Pitfalls

1. DSN vs. Manual Config:

   • If both dsn and manual config (e.g., host, user) are provided, the dsn takes precedence. Omit manual fields if using dsn:

     dsn: '%env(resolve:DATABASE_URL)%'  # Overrides host/user/pass
     

2. Command-Line Dependencies:

   • Ensure mysqldump, pg_dump, and gzip are installed on the server. Test with:

     which mysqldump gzip
     

3. File Permissions:

   • For Local storage, ensure the root directory is writable by the PHP process:

     chmod -R 755 /path/to/working/directory
     

4. Database Compatibility:

   • No cross-database restores: A MySQL dump cannot be restored to PostgreSQL. Ensure database and storage types match your workflow.

5. Compression Chaining:

   • Not all compression methods support chaining (e.g., gzip + openssl). Test combinations in a staging environment.

Debugging

1. Verbose Output: Use -v or -vv flags in CLI commands to debug:

   php bin/console backup-manager:backup production s3 -vv
   

2. Dry Runs: Simulate backups without executing them:

   php bin/console backup-manager:backup production s3 --dry-run
   

3. Logging: Enable Symfony’s monolog to capture backup events:

   # config/packages/monolog.yaml
   handlers:
       backup:
           type: stream
           path: "%kernel.logs_dir%/backup.log"
           level: debug
   

Config Quirks

1. Environment Variables: Use %env() syntax for sensitive data (e.g., AWS_KEY):

   key: '%env(AWS_KEY)%'
   secret: '%env(AWS_SECRET)%'
   

2. Default Values: The bundle provides default configs in config/packages/bm_backup_manager.yml. Override only what’s necessary.

3. Storage Root: For Local storage, root must be an absolute path. Relative paths may fail silently.

Extension Points

1. Custom Destinations: Extend the Destination class to support additional storage backends (e.g., Google Cloud Storage):

   class GoogleCloudDestination extends Destination {
       public function __construct(string $bucket, string $path) {
           parent::__construct('google_cloud', $bucket . '/' . $path);
       }
   }
   

2. Pre/Post Backup Hooks: Use Symfony events to run logic before/after backups:

   // src/EventListener/BackupListener.php
   public function onBackup(BackupEvent $event) {
       if ($event->getDatabase() === 'production') {
           // Pre-backup logic
       }
   }
   

   Register the listener in services.yaml:

   services:
       App\EventListener\BackupListener:
           tags:
               - { name: kernel.event_listener, event: backup.manager.backup, method: onBackup }
   

3. Custom Compression: Implement a new compression strategy by extending BM\BackupManager\Compression\CompressionStrategy:

   class CustomCompression implements CompressionStrategy {
       public function compress(string $source, string $destination): void {
           // Custom logic
       }
   }
   

   Register it in config:

   bm_backup_manager:
       compression:
           custom:
               class: App\CustomCompression
   

Performance Tips

1. Ignore Large Tables: Exclude tables like logs or sessions to speed up backups:

   ignoreTables: ['logs', 'sessions']
   

2. Batch Backups: For large databases, use --batch-size in CLI or set batchSize