Flysystem Process Bundle Laravel Package

Getting Started

Install via Composer:

composer require cleverage/flysystem-process-bundle

Register the bundle in your Symfony config/bundles.php:

return [
    // ...
    Clevage\FlysystemProcessBundle\FlysystemProcessBundle::class => ['all' => true],
];

Configure in config/packages/cleverage_flysystem_process.yaml (if needed). First use case: Process files in a Flysystem adapter (e.g., local, S3) with Symfony’s Process component integration. Example:

use Clevage\FlysystemProcessBundle\Process\ProcessAdapter;
use League\Flysystem\Filesystem;

$filesystem = new Filesystem($adapter);
$processAdapter = new ProcessAdapter($filesystem);
$processAdapter->run('ls -la'); // Execute shell commands on remote storage

Implementation Patterns

Core Workflow

1. Adapter Integration: Wrap any Flysystem adapter with ProcessAdapter to execute shell commands on remote storage (e.g., sftp://, aws.s3://).
2. Symfony Process Integration: Leverage Symfony’s Process component for command execution, with Flysystem handling file I/O.
3. Command Patterns:
   • Use ProcessAdapter::run() for one-off commands.
   • Chain with Flysystem methods (e.g., read(), write()) for pre/post-processing:

     $processAdapter->write('file.txt', 'content');
     $processAdapter->run('chmod +x file.txt');
     

Common Use Cases

• Remote File Processing: Execute ffmpeg, imagemagick, or custom scripts on files stored in cloud/SFTP.
• CI/CD Pipelines: Run build tools (e.g., npm, docker) against files in object storage.
• Hybrid Local/Remote Workflows: Combine local processing with remote execution (e.g., generate a file locally, then process it remotely).

Dependency Injection

Register the adapter as a service in Symfony:

# config/services.yaml
services:
    Clevage\FlysystemProcessBundle\Process\ProcessAdapter:
        arguments:
            $filesystem: '@oneup_flysystem.my_adapter'

Gotchas and Tips

Breaking Changes (v3.0)

• PHP/Symfony Version Drop: Requires PHP 8.2+ and Symfony 7.4+ (PR #23).
  • Action: Update your php and symfony/* packages in composer.json:

    "require": {
        "php": "^8.2",
        "symfony/*": "^7.4"
    }
    

  • Impact: If using PHP 8.1/Symfony 7.3, migrate to supported versions or fork the package.

Debugging

• Command Failures: Use Symfony’s Process error output:

  $process = $processAdapter->run('invalid_command');
  if (!$process->isSuccessful()) {
      echo $process->getErrorOutput(); // Debug here
  }
  

• Permission Issues: Remote commands (e.g., SFTP) may fail due to user permissions. Test with whoami or pwd first:

  $processAdapter->run('whoami'); // Verify remote user context
  

Performance Tips

• Batch Processing: For large files, stream input/output to avoid memory issues:

  $processAdapter->run('cat largefile.txt | gzip > largefile.gz', null, ['input' => fopen('php://input', 'r')]);
  

• Caching: Cache frequent commands (e.g., ls) to avoid repeated remote calls.

Extension Points

• Custom Adapters: Extend ProcessAdapter to add domain-specific logic:

  class MyProcessAdapter extends ProcessAdapter {
      public function optimizeImages(string $path): void {
          $this->run("convert {$path} -quality 80 optimized_{$path}");
      }
  }
  

• Event Listeners: Hook into Symfony’s kernel.terminate to clean up temporary files created by commands.

Configuration Quirks

• Environment Variables: Pass environment vars to remote commands via Process constructor:

  $processAdapter->run('echo $MY_VAR', null, ['env' => ['MY_VAR' => 'value']]);
  

• Timeouts: Set command timeouts to avoid hanging:

  $processAdapter->run('long_running_command', null, ['timeout' => 30]);