Download Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require --dev desarrolla2/download-bundle
   

   Register the bundle in AppKernel.php (Symfony) or config/app.php (Laravel) only for dev environment:

   // Laravel (config/app.php)
   if (app()->environment('local')) {
       $provider = new Desarrolla2\DownloadBundle\DownloadServiceProvider();
       if (method_exists($provider, 'register')) {
           $provider->register();
       }
   }
   

2. Configuration Add to .env (Laravel) or config/packages/dev.yml (Symfony):

   DOWNLOAD_USER=deploy_user
   DOWNLOAD_HOST=production_host_or_ip
   DOWNLOAD_TIMEOUT=300
   DOWNLOAD_DB_DIR=/var/data/databases
   DOWNLOAD_DB_REMOTE_HOST=production_database_host
   DOWNLOAD_ONLY_STRUCTURE=mail_history
   

3. First Use Case Trigger a download via Artisan (Laravel) or Symfony CLI:

   php artisan download:fetch
   

   This will:

   • Pull the database dump from the remote host.
   • Copy associated project folders (if configured in download/folders).
   • Restore the database locally (if using Laravel, ensure .env has DB_DATABASE pointing to the restored file).

Implementation Patterns

Workflows

1. Scheduled Syncs Add a cron job (Linux) to sync data nightly:

   0 3 * * * cd /path/to/project && php artisan download:fetch >> /var/log/download.log 2>&1
   

   Log output to debug SSH/DB issues.

2. Conditional Syncs Use a custom command to sync only specific tables/folders:

   php artisan download:fetch --tables=users,products --folders=uploads
   

   (Note: Verify if the package supports CLI flags; extend via custom commands if needed.)

3. Integration with Deployments Hook into Laravel Forge/Envoyer or Symfony Deployer:

   # deployer.php (Symfony)
   task('deploy:post')->after('deploy:update_code')->do(function () {
       run('cd {{release_path}} && php bin/console download:fetch');
   });
   

4. Database-Specific Handling For large databases, split the dump into chunks:

   // Customize the service (if extendable)
   $this->app->make('download')->setChunkSize(100); // Hypothetical method
   

Integration Tips

• SSH Keys: Ensure ~/.ssh/id_rsa.pub is added to authorized_keys on the remote host.
• Database Restore: Post-download, update Laravel’s .env to point to the restored file:

  DB_CONNECTION=mysql
  DB_DATABASE=/var/data/databases/production.sql
  

  (Note: Use DB_SOCKET or DB_HOST if restoring to a local MySQL instance.)
• Folder Permissions: Sync folders with 755 permissions:

  // Post-sync fix (custom command)
  Artisan::call('storage:link');
  chmod('/path/to/folders', 0755);
  

Gotchas and Tips

Pitfalls

1. Linux-Only Limitation

   • The package relies on SSH/SFTP, which may fail on Windows WSL or Docker without proper config.
   • Workaround: Use a Linux VM or CI (GitHub Actions) to run syncs.

2. Database Restore Quirks

   • MySQL/MariaDB may reject large dumps. Test with:

     mysql -u root -p < production.sql
     

   • Fix: Use mysqldump --max_allowed_packet=1G on the remote host.

3. Configuration Overrides

   • Environment variables may not override config/packages/dev.yml in Symfony.
   • Tip: Use config_dev.php to merge settings:

     return [
         'download' => array_merge(
             require __DIR__.'/parameters.yml',
             $_ENV
         ),
     ];
     

4. SSH Timeouts

   • Default timeout: 300 may be too short for large transfers.
   • Debug: Increase to 1800 (30 mins) or monitor with ssh -vvv.

5. Folder Exclusions

   • The package may not handle .git or node_modules by default.
   • Tip: Add to .env:

     DOWNLOAD_EXCLUDE_FOLDERS=.git,node_modules,vendor
     

Debugging

• SSH Errors: Enable verbose mode:

  php artisan download:fetch --verbose
  

• Database Dump Issues: Check the remote dump file exists:

  ssh deploy_user@production_host "ls -lah /path/to/dumps/"
  

• Permission Denied: Ensure the deploy_user has read access to:
  • Database dumps.
  • Project folders (e.g., uploads/).

Extension Points

1. Custom Commands Extend the bundle by creating a custom Artisan command:

   // app/Console/Commands/SyncProduction.php
   class SyncProduction extends Command {
       protected $signature = 'download:sync {--tables=*} {--folders=*}';
       public function handle() {
           $this->call('download:fetch', [
               '--tables' => $this->option('tables'),
               '--folders' => $this->option('folders'),
           ]);
       }
   }
   

2. Pre/Post-Hooks Use Laravel’s registerCommands to add logic before/after sync:

   // DownloadServiceProvider.php
   public function register() {
       $this->app->booted(function () {
           if ($this->app->runningInConsole()) {
               Artisan::extend(function ($artisan) {
                   $artisan->resolving('command.download.fetch', function ($command) {
                       // Pre-sync: Backup local DB
                       Artisan::call('db:backup');
                   });
               });
           }
       });
   }
   

3. Remote Path Customization Override remote paths dynamically:

   // config/packages/dev.yml
   download:
       database:
           remote:
               dump_path: '/custom/path/production_{{ date("Y-m-d") }}.sql'