Flysystem Process Bundle Laravel Package

Technical Evaluation

Architecture Fit The flysystem-process-bundle (v3.2) remains well-aligned with Laravel/PHP ecosystems using Flysystem for file storage abstraction, particularly for file processing pipelines (image/video manipulation, PDF generation). Its Symfony Process integration makes it a strong fit for Laravel applications that shell out to CLI tooling inside queue workers or Artisan commands. The bundle's task-based design (FileFetchTask, ListContentTask, RemoveFileTask) abstracts "fetch → process → store → clean up" behind a unified API, reducing vendor lock-in and custom glue code.

v3.2 does not alter the architectural surface. It is a correctness release: the changes are confined to the FileFetchTask and RemoveFileTask implementations plus expanded test coverage (bundle wiring, DI extension, local storage). No new extension points, no API removals, and no new dependencies. From an architecture standpoint the only signal is a positive one — the previously untested DI/extension layer is now covered, which reduces the risk of service wiring subtly breaking across Laravel container bindings.

Integration Feasibility

• Laravel Compatibility: Unchanged. The bundle is still a Symfony bundle consumable via Composer, with Laravel's Symfony-derived components (symfony/process, symfony/filesystem) providing the bridge. Flysystem adapter support keeps it compatible with Laravel's Storage facade and third-party adapters (S3, GCS).
• Dependency Overlap: Still requires PHP 8.5+ and Symfony 8.x. Laravel 10+ on PHP 8.5 satisfies this; older stacks carry the same friction as before.
• Customization: The modular design (configurable process wrappers, event listeners) is unchanged. Because v3.2 fixes FileFetchTask semantics rather than its signature, existing custom task subclasses continue to work — but any subclass overriding fetch behaviour should be re-validated against the corrected input-iteration logic.
• Version Constraint: A ^3.0 constraint already admits v3.2. Adoption requires only a Composer update and regression run — no code changes.

Technical Risk

• Breaking Changes (v3.2): None in the API sense. However, three fixes change observable runtime behaviour and should be treated as behavioural changes for pipelines that compensated for the old bugs:
  • ignore_missing is now honoured for input files; previously a missing input threw UnableToReadFile. Pipelines that relied on that exception as a signal (e.g., a try/catch used for detection) will now silently skip.
  • A path supplied twice as input is no longer skipped; with file_pattern, every input is now processed rather than only the first. Expect higher volume and longer task runtimes where duplicate inputs were previously (accidentally) suppressed.
  • A file literally named 0 is no longer treated as "no file" by FileFetchTask/RemoveFileTask.
• Breaking Changes (v3.0 lineage): The PHP 8.5 / Symfony 8.x floor introduced in v3.0 still forces upgrades for teams on Laravel 9.x / PHP 8.1.
• Dependency Bloat: Unchanged — Symfony 8.x stricter typing may require service-provider refactoring.
• Testing Overhead: Reduced. v3.2's added coverage for local-storage tasks, the bundle class and the DI extension is exactly the surface that is hardest to exercise from a Laravel app. Validate integration points at the Laravel boundary (container bindings, Storage disk handoff) rather than the task internals.
• Observability: RemoveFileTask now logs a missing file as not found rather than deleted, and the deletion-failure message is corrected. Any dashboard, alert rule, or log-based metric keyed on the old message text must be updated — this is the most likely silent breakage in a mature deployment.

Key Questions

1. Stack Alignment:
   • Is the application on PHP 8.5+ and Symfony 8.x components (symfony/process v8.x)?
   • Are custom Flysystem adapters or Process-based services in place that could conflict with Symfony 8.x changes?
2. Workflow Impact:
   • Does any pipeline depend on UnableToReadFile being thrown for missing inputs (now suppressed by ignore_missing)?
   • Are input lists ever passed with duplicates, or is the same path intentionally supplied twice? Runtime and throughput estimates may need revision.
   • Are any log scrapers, dashboards, or alerts keyed to the old "deleted" / deletion-failure strings from RemoveFileTask?
3. Performance:
   • Because duplicate inputs are now processed rather than skipped, have queue timeouts and worker concurrency been re-baselined for affected jobs?
4. Fallback Strategy:
   • If the PHP 8.5 upgrade is not feasible, can the bundle be patched for PHP 8.2–8.4, and is that fork intended to absorb the v3.2 task fixes?

Integration Approach

Stack Fit

• Laravel Integration Path:
  1. Dependency Injection: Register the bundle via Composer (cleverage/flysystem-process-bundle:^3.0, resolving to v3.2) and bind Symfony services to Laravel's container (e.g., ProcessRunner as a singleton). v3.2's DI-extension tests make this wiring materially safer to rely on.
  2. Flysystem Bridge: Use Laravel's Storage facade to build Flysystem adapters, then wrap them with the bundle's processed filesystem.
  3. Artisan/Commands: Extend Artisan commands to drive the bundle's tasks for CLI-based batch work (image resizing, document conversion, cache warming).
• Symfony Interop: Continue leveraging Laravel's Symfony integration rather than reimplementing process management:

  use Cleverage\ProcessBundle\Process\ProcessRunner;
  use Illuminate\Support\Facades\Storage;
  
  $filesystem = Storage::disk('local')->getAdapter()->getFilesystem();
  $processedFs = new ProcessedFilesystem($filesystem, new ProcessRunner());
  

• Task-Level Integration: Prefer the bundle's built-in tasks over hand-rolled fetch/remove logic. The v3.2 fixes cover input iteration, duplicate paths, ignore_missing propagation, falsy filenames, and removal logging — all cases a bespoke implementation would have to handle independently.

Migration Path

1. Pre-Upgrade:
   • Audit composer.json for Symfony 7.x dependencies and PHP version floor.
   • Grep for UnableToReadFile handlers, duplicate-path assumptions, and string matches on RemoveFileTask log messages.
2. Upgrade Steps:
   • Update to cleverage/flysystem-process-bundle v3.2 (no code change required under ^3.0).
   • If still on the v3.0 floor, complete the Laravel 10+ / Symfony 8.x dependency upgrade.
   • Replace remaining direct Process instantiations with the bundle's builder/runner for consistency.
3. Post-Upgrade:
   • Regression-test file-processing pipelines with fixtures covering: missing input with ignore_missing both enabled and disabled, duplicate input paths, file_pattern with multiple inputs, and a file named 0.
   • Update log-based dashboards and alerts for the corrected RemoveFileTask messages.
   • Benchmark affected jobs — the duplicate-input fix can increase work per run.

Compatibility

• Laravel-Specific Considerations:
  • ProcessedFilesystem integrates with Laravel's FilesystemManager for dynamic disk switching.
  • Queued jobs (ShouldQueue) using the bundle should inject ProcessRunner and the bundle's tasks rather than constructing processes inline.
  • If overriding FileFetchTask, re-check subclass behaviour against the corrected per-input iteration.
• Third-Party Risks:
  • Conflicts with packages using deprecated Symfony 7.x Process methods (e.g., mustRun()).
  • Flysystem adapters (e.g., league/flysystem-s3) may need updates for Symfony 8.x StreamWrapper changes.
  • Monitoring/APM tooling that parses task log output may need rule updates.

Sequencing

1. Phase 1: Upgrade Laravel/Symfony dependencies in staging; confirm the ^3.0 constraint resolves to v3.2.
2. Phase 2: Run the new task fixtures against local storage to validate behaviour changes in isolation.
3. Phase 3: Roll v3.2 to non-critical file-processing paths (batch jobs, cache warming), with log-message consumers updated first.
4. Phase 4: Promote to critical media/document pipelines; validate timeouts, large files, and duplicate-input volume; roll back via Composer pin if needed.

Operational Impact

Maintenance

• Pros:
  • v3.2 is a low-risk, drop-in patch that removes four classes of latent bug in fetch/remove tasks, reducing the custom defensive code teams typically write around them.
  • New coverage for the bundle class and DI extension lowers the odds of container-wiring regressions on future upgrades.
  • Symfony 8.x's improved Process stability (signal handling, cleanup) continues to reduce operational overhead.
• Cons:
  • Tighter coupling to Symfony 8.x may complicate future Laravel upgrades if Symfony diverges.
  • Debugging remains a two-framework exercise (Laravel error surfaces, Symfony process error formats).
  • Behavioural change in ignore_missing and log wording means documentation and runbooks need a small but real refresh.

Support

• Tooling:
  • Laravel Telescope can log process execution metrics (runtime, exit codes) via custom listeners.
  • Symfony's Debug component integrates with Laravel's dd() for process inspection.
• Monitoring:
  • Add health checks for file-processing queues (timeouts, disk space).
  • Use Laravel's failed_jobs table to track failed process-based jobs.
  • Re-point any alerting on RemoveFileTask messages: missing files now surface as not found, and deletion failures carry corrected text.

Scaling

• Performance:
  • Symfony 8.x Process optimisations (reduced fork overhead) improve batch throughput.
  • Re-baseline throughput and timeout budgets for jobs that receive duplicate or duplicate-pattern inputs, since v3.2 no longer skips them.
• Resource Management:
  • Configure process memory limits via the bundle's builder to prevent OOM kills.
  • Use Laravel's afterCommit() hooks to clean up temp files post-processing; the corrected RemoveFileTask list-of-paths support allows consolidating cleanup into fewer invocations.

Failure Modes

Ramp-Up

• Training:
  • Document Symfony 8.x Process differences (constructor, event system) for developers.
  • Add a short note on v3.2 task semantics: ignore_missing for inputs, per-input processing with file_pattern, duplicate paths processed, 0-named files valid, removal logging changes.
• Onboarding:
  • Migration checklist for teams coming from PHP 8.1 / Symfony 7.x.
  • Sandbox environment pre-configured with Laravel + Symfony 8.x + bundle v3.2 and the new task fixtures as reference behaviour.
• Documentation Gaps:
  • Clarify extending the bundle via Laravel's ServiceProvider vs. PackageServiceProvider.
  • Add examples of wiring task lifecycle events into Laravel's Events system (e.g., filesystem.processed).
  • Document the exact fetch/remove semantics validated by the new tests, so operators can reason about edge cases without reading source.