Archive Process Bundle Laravel Package

Getting Started

This package, ArchiveProcessBundle, is a Laravel-compatible Symfony bundle for handling archival and processing workflows. To get started with v2.0, ensure your project meets the updated requirements:

• PHP 8.5 (minimum, replaces PHP 8.1)
• Symfony 8 (minimum, replaces Symfony 7.3)

First Steps:

1. Installation: Require the package via Composer:

   composer require cleverage/archive-process-bundle
   

2. Configuration: Register the bundle in config/bundles.php (Symfony) or config/app.php (Laravel via Symfony integration):

   return [
       // ...
       Cleverage\ArchiveProcessBundle\ClevageArchiveProcessBundle::class => ['all' => true],
   ];
   

3. Basic Usage: Use the bundle’s services (e.g., archive_processor) to define and trigger workflows. Example:

   use Cleverage\ArchiveProcessBundle\Processor\ArchiveProcessorInterface;
   
   public function __construct(private ArchiveProcessorInterface $processor) {}
   
   public function archiveItem($item) {
       $this->processor->process($item);
   }
   

Implementation Patterns

Core Workflows:

1. Workflow Definition: Define archival processes in YAML/XML or via annotations. Example (config/archive_processes.yml):

   my_workflow:
       steps:
           - { service: 'my_service', method: 'process' }
           - { service: 'logger', method: 'log' }
   

   Register the workflow in the bundle’s configuration.

2. Integration with Laravel:

   • Use Symfony’s dependency injection (DI) container via Laravel’s AppServiceProvider:

     public function register() {
         $this->app->register(ClevageArchiveProcessBundle::class);
     }
     

   • Access processors via Laravel’s service container:

     $processor = app(ClevageArchiveProcessBundle::class)->getProcessor();
     

3. Event-Driven Processing: Trigger workflows via events (Symfony) or Laravel’s Event facade:

   event(new ArchiveItemEvent($item));
   

Best Practices:

• Modularity: Split workflows into reusable steps (e.g., validate, transform, archive).
• Error Handling: Wrap processor calls in try-catch blocks to handle step failures gracefully.
• Testing: Mock the ArchiveProcessorInterface in unit tests to isolate logic.

Gotchas and Tips

Breaking Changes (v2.0):

• PHP/Symfony Version Drop:
  • PHP 8.1 and Symfony 7.3 are no longer supported. Update your environment or use v1.x if stuck on older versions.
  • Migration Tip: Test workflows thoroughly after upgrading, as internal changes (e.g., type hints, Symfony components) may affect behavior.

Common Pitfalls:

1. Service Registration:

   • Ensure all custom services used in workflows are properly registered in Symfony’s DI container. Laravel’s bind() or extend() may be needed for legacy services.
   • Example:

     $this->app->bind(MyCustomService::class, function ($app) {
         return new MyCustomService($app->make(OtherDependency::class));
     });
     

2. Configuration Overrides:

   • Bundle configurations (e.g., archive_processes.yml) may not auto-load in Laravel. Manually load them in bootstrap/app.php:

     $app->make(Kernel::class)->loadConfigFrom(__DIR__.'/../config/archive_processes.yml');
     

3. Performance:

   • Complex workflows with many steps can slow down requests. Use Symfony’s Stopwatch or Laravel’s Benchmark to profile performance.

Extension Points:

• Custom Processors: Implement ArchiveProcessorInterface to create domain-specific processors. Example:

  class CustomProcessor implements ArchiveProcessorInterface {
      public function process($item) {
          // Custom logic
      }
  }
  

  Register it as a service:

  services:
      Cleverage\ArchiveProcessBundle\Processor\ArchiveProcessorInterface: '@custom_processor'
  

• Event Listeners: Extend workflow behavior by listening to bundle events (e.g., archive.process.start). Example in Laravel:

  Event::listen(ArchiveProcessEvents::PROCESS_START, function ($event) {
      Log::info('Workflow started for item: '.$event->getItemId());
  });
  

• Database Backend: The bundle supports storing workflow states in a database. Configure doctrine or database options in config/packages/cleverage_archive_process.yaml for persistence.