Backup Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bastsys/backup-bundle
   

   Add to config/bundles.php (Symfony):

   return [
       // ...
       Bastsys\BackupBundle\BastsysBackupBundle::class => ['all' => true],
   ];
   

2. Configuration Edit config/packages/bastsys_backup.yaml (Symfony) or publish defaults:

   php bin/console bastsys:backup:dump --help
   

   Key config fields:

   bastsys_backup:
       storage:
           type: 'local' # or 's3', 'ftp', etc.
           path: '%kernel.project_dir%/backups'
       databases: ['%env(DATABASE_URL)%']
       files: ['%kernel.project_dir%/storage', '%kernel.project_dir%/public/uploads']
   

3. First Backup

   php bin/console bastsys:backup:dump
   

   Outputs to backups/[timestamp]_backup.zip.

First Use Case: Scheduled Backups

1. Cron Job Add to crontab (Linux):

   0 3 * * * cd /path/to/project && php bin/console bastsys:backup:dump >> /dev/null 2>&1
   

   (Runs daily at 3 AM.)

2. Verify Backup

   php bin/console bastsys:backup:list
   

   Lists all backups with timestamps.

Implementation Patterns

Workflow: Database + Files Backup

1. Define Backup Scope In config/packages/bastsys_backup.yaml:

   bastsys_backup:
       databases:
           - '%env(DATABASE_URL)%'
           - 'mysql://user:pass@localhost/secondary_db'
       files:
           - '%kernel.project_dir%/storage/app'
           - '%kernel.project_dir%/public/media'
       storage:
           type: 's3'
           bucket: 'my-backup-bucket'
           credentials:
               key: '%env(AWS_ACCESS_KEY_ID)%'
               secret: '%env(AWS_SECRET_ACCESS_KEY)%'
   

2. Customize Backup Command Extend the bundle’s command (e.g., add pre-backup checks):

   // src/Command/CustomBackupCommand.php
   namespace App\Command;
   
   use Bastsys\BackupBundle\Command\BackupCommand;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Output\OutputInterface;
   
   class CustomBackupCommand extends BackupCommand
   {
       protected function execute(InputInterface $input, OutputInterface $output)
       {
           // Pre-backup logic (e.g., validate DB connections)
           $this->validateEnvironment($output);
   
           parent::execute($input, $output);
       }
   
       private function validateEnvironment(OutputInterface $output)
       {
           // Custom validation
       }
   }
   

   Register in services.yaml:

   services:
       App\Command\CustomBackupCommand:
           tags: ['console.command']
   

3. Post-Backup Actions Use events to trigger actions after backup:

   # config/packages/bastsys_backup.yaml
   bastsys_backup:
       events:
           post_backup: ['App\EventListener\BackupListener']
   

   Listener example:

   // src/EventListener/BackupListener.php
   namespace App\EventListener;
   
   use Bastsys\BackupBundle\Event\BackupEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class BackupListener implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               'bastsys.backup.post' => 'onBackupComplete',
           ];
       }
   
       public function onBackupComplete(BackupEvent $event)
       {
           $backupPath = $event->getBackupPath();
           // Send Slack notification, log, etc.
       }
   }
   

Integration Tips

1. Laravel-Specific Setup

   • For Laravel (Symfony-based), ensure DATABASE_URL is in .env:

     DATABASE_URL="mysql://user:pass@localhost/db_name"
     

   • Override bundle config in config/backup.php (if using Laravel’s config system).

2. Excluding Files Use .gitignore-style patterns in config:

   bastsys_backup:
       files:
           - '%kernel.project_dir%/storage/app'
           - '!%kernel.project_dir%/storage/app/logs' # Exclude logs
   

3. Remote Storage Configure S3/FTP in config/packages/bastsys_backup.yaml:

   storage:
       type: 's3'
       bucket: 'my-backup-bucket'
       credentials:
           key: '%env(AWS_ACCESS_KEY_ID)%'
           secret: '%env(AWS_SECRET_ACCESS_KEY)%'
       region: 'eu-west-1'
   

4. Backup Retention Use the bastsys:backup:prune command to clean old backups:

   php bin/console bastsys:backup:prune --days=7
   

   Keeps only backups from the last 7 days.

Gotchas and Tips

Pitfalls

1. Database Connection Issues

   • Symptom: Backup fails silently or creates empty files.
   • Fix: Ensure DATABASE_URL is correct and the user has SELECT permissions on all tables.
   • Debug: Run php bin/console bastsys:backup:dump --verbose to see SQL errors.

2. File Permissions

   • Symptom: Backup fails with "Permission denied" for local storage.
   • Fix: Ensure the web server user (e.g., www-data) has write access to the backup directory:

     chmod -R 775 %kernel.project_dir%/backups
     chown -R www-data:www-data %kernel.project_dir%/backups
     

3. Large File Backups

   • Symptom: Backup hangs or times out for large directories (e.g., storage/app/public with 100K files).
   • Fix:
     • Exclude unnecessary files (e.g., cache, logs).
     • Increase PHP memory limit in php.ini:

       memory_limit = 2G
       

     • Use --chunk-size flag (if supported):

       php bin/console bastsys:backup:dump --chunk-size=100
       

4. Symfony vs. Laravel Quirks

   • Issue: Laravel’s DATABASE_URL format may not work out-of-the-box.
   • Workaround: Use the full DSN format:

     databases:
         - 'mysql://user:pass@127.0.0.1/db_name?unix_socket=/var/run/mysqld/mysqld.sock'
     

Debugging Tips

1. Enable Verbose Output

   php bin/console bastsys:backup:dump -v
   

   Shows detailed logs for each step (database dump, file archiving, storage upload).

2. Check Backup Contents Extract a backup to verify:

   unzip backups/2023-01-01_120000_backup.zip -d /tmp/backup_test
   

   Inspect /tmp/backup_test/database/ and /tmp/backup_test/files/.

3. Log Backup Events Enable monolog in config/packages/monolog.yaml:

   handlers:
       backup:
           type: stream
           path: "%kernel.logs_dir%/backup.log"
           level: debug
   

   Then check var/log/backup.log (Symfony) or storage/logs/backup.log (Laravel).

Extension Points

1. Custom Backup Format Override the BackupService to change ZIP compression or add encryption:

   // src/Service/CustomBackupService.php
   namespace App\Service;
   
   use Bastsys\BackupBundle\Service\BackupService as BaseBackupService;
   
   class CustomBackupService extends BaseBackupService
   {
       protected function createArchive(string $sourceDir, string $destination): void
       {
           // Custom logic (e.g., use Phar instead of ZipArchive)
       }
   }
   

   Bind in services.yaml:

   services:
       Bastsys\BackupBundle\Service\BackupService:
           alias: App\Service\CustomBackupService
   

2. Add Pre/Post Hooks Use the BackupEvent to inject logic:

   // src/EventListener/EncryptBackupListener.php
   namespace App\EventListener;
   
   use Bastsys\BackupBundle\Event\BackupEvent;
   
   class EncryptBackupListener
   {
       public function onBackupComplete(BackupEvent $event)
       {
           $backupPath = $event->getBackupPath();
           // Encrypt $backupPath using Open