Remote Assets Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require billhance/remote-assets-bundle
   

   Enable the bundle in config/bundles.php (Symfony) or config/app.php (Laravel via bridge):

   Billhance\RemoteAssetsBundle\RemoteAssetsBundle::class => ['all' => true],
   

2. First Use Case Run the console command to fetch a remote asset (e.g., a CSS file):

   php artisan remote:assets:copy https://example.com/path/to/asset.css public/assets/asset.css
   

   (Note: Laravel users may need to alias remote:assets:copy in artisan config.)

3. Where to Look First

   • Command Reference: Check vendor/billhance/remote-assets-bundle/Command/CopyRemoteAssetsCommand.php for arguments/options.
   • Configuration: Look for remote_assets config in config/packages/billhance_remote_assets.php (Symfony) or config/remote-assets.php (if auto-generated).

Implementation Patterns

Usage Patterns

1. Fetching Assets Programmatically Use the service container to call the command logic directly:

   $command = $this->get('remote_assets.copy_command');
   $command->run(new ArrayInput(['command' => 'copy', 'remote' => 'https://example.com/file.js', 'local' => 'public/js/file.js']), new NullOutput());
   

2. Batch Processing Loop through an array of remote assets and process them sequentially:

   $assets = [
       'https://cdn.example.com/style.css' => 'public/css/style.css',
       'https://cdn.example.com/script.js' => 'public/js/script.js',
   ];
   
   foreach ($assets as $remote => $local) {
       $this->call('remote:assets:copy', ['remote' => $remote, 'local' => $local]);
   }
   

3. Integration with Asset Pipelines Hook into Laravel’s assets:compile or Symfony’s assets:install events to auto-fetch remote assets:

   // Laravel Example (Event Service Provider)
   public function boot()
   {
       Event::listen('assets.compiled', function () {
           $this->call('remote:assets:copy', [
               'remote' => 'https://example.com/remote.css',
               'local' => 'public/build/remote.css'
           ]);
       });
   }
   

4. Customizing Headers/Authentication Pass HTTP headers or auth tokens via command options:

   php artisan remote:assets:copy \
       --remote=https://auth-protected.com/file.zip \
       --local=public/uploads/file.zip \
       --header="Authorization: Bearer TOKEN"
   

Workflows

• Development Workflow: Use the command to mirror remote assets locally during development, then override them in production.
• Production Workflow: Schedule the command via Laravel’s schedule or Symfony’s cron to periodically sync assets:

  // Laravel Task Scheduling
  $schedule->command('remote:assets:copy https://example.com/prod.css public/css/prod.css')->daily();
  

Gotchas and Tips

Pitfalls

1. File Overwrites The command overwrites local files by default. Use --backup to preserve existing files:

   php artisan remote:assets:copy --remote=... --local=... --backup
   

2. Permission Issues Ensure the public/ directory is writable by the web server user (e.g., chmod -R 755 public).

3. SSL/TLS Warnings If fetching from HTTP (non-HTTPS), suppress SSL warnings with --insecure (not recommended for production):

   php artisan remote:assets:copy --remote=http://example.com/file --insecure
   

4. Large Files The command does not stream files by default, which may cause memory issues. For large files, extend the command to use fopen() with streaming:

   // Example extension (override the command's handle() method)
   $stream = fopen($remoteUrl, 'r');
   file_put_contents($localPath, $stream);
   fclose($stream);
   

Debugging

• Verbose Output: Use -v or -vv flags to debug:

  php artisan remote:assets:copy -vv https://example.com/file public/file
  

• Check HTTP Status: The command logs HTTP status codes. A 404 or 403 indicates a fetch failure.

Config Quirks

• Default Local Directory: The default local directory is public/assets/. Override it in config:

  'default_local_dir' => 'storage/app/public/remote_assets',
  

• Allowed Domains: Restrict remote domains to trusted sources in config:

  'allowed_domains' => ['example.com', 'cdn.example.com'],
  

Extension Points

1. Custom Storage Handlers Extend the command to support cloud storage (S3, GCS) by overriding the storeFile() method:

   // Example: Store in S3
   use Aws\S3\S3Client;
   $s3 = new S3Client([...]);
   $s3->putObject(['Body' => file_get_contents($localPath), 'Bucket' => 'my-bucket', 'Key' => 'remote/file']);
   

2. Pre/Post-Processing Hook into the command’s onPreCopy() or onPostCopy() events (if supported in future versions) to transform files (e.g., minify CSS).

3. Caching Add caching logic to avoid re-downloading unchanged files:

   if (file_exists($localPath) && filesize($localPath) === $remoteFileSize) {
       return true; // Skip download
   }