Archive Process Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Require the package via Composer:

   composer require cleverage/archive-process-bundle
   

   Enable the bundle in config/bundles.php:

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

2. Configuration Publish the default config:

   php bin/console cleverage:archive-process:install
   

   Review config/packages/cleverage_archive_process.yaml for storage paths, archive formats, and process integrations.

3. First Use Case Trigger an archive for a process instance:

   use Cleverage\ProcessBundle\Model\ProcessInstanceInterface;
   use Cleverage\ArchiveProcessBundle\Service\ArchiveService;
   
   $archiveService = $this->container->get(ArchiveService::class);
   $archive = $archiveService->archiveProcessInstance($processInstance);
   

Implementation Patterns

Core Workflows

1. Process Instance Archiving

   • Hook into ProcessInstance lifecycle events (e.g., postExecute) to auto-archive completed processes:

     # config/packages/cleverage_process.yaml
     cleverage_process:
         events:
             post_execute: ['Cleverage\ArchiveProcessBundle\EventListener\ArchiveProcessListener']
     

   • Customize archive content via ArchiveContentProvider:

     class CustomArchiveContentProvider implements ArchiveContentProviderInterface {
         public function getContent(ProcessInstanceInterface $instance): array {
             return [
                 'metadata' => $instance->getMetadata(),
                 'custom_data' => $this->fetchCustomData($instance),
             ];
         }
     }
     

2. Storage Backends

   • Configure multiple storage adapters (e.g., local filesystem, S3):

     cleverage_archive_process:
         storage:
             default: 'local'
             adapters:
                 local:
                     type: 'local'
                     path: '%kernel.project_dir%/var/archives'
                 s3:
                     type: 'aws_s3'
                     bucket: 'my-archive-bucket'
                     key: 'process-archives'
     

3. Archive Formats

   • Generate archives in ZIP, TAR, or custom formats:

     cleverage_archive_process:
         formats:
             default: 'zip'
             custom_format:
                 type: 'custom'
                 class: 'App\Custom\ArchiveFormat'
     

Integration Tips

• Symfony Workflows Use the bundle’s archive transition in workflows:

  # config/packages/workflows/process_workflow.yaml
  transitions:
      archive:
          from: [completed]
          to: archived
          action: archive_process_instance
  

• API Endpoints Expose archiving via API:

  // src/Controller/ArchiveController.php
  #[Route('/processes/{id}/archive', name: 'archive_process', methods: ['POST'])]
  public function archive(ProcessInstanceInterface $instance, ArchiveService $archiveService): JsonResponse {
      $archive = $archiveService->archiveProcessInstance($instance);
      return $this->json(['archive_id' => $archive->getId()]);
  }
  

Gotchas and Tips

Pitfalls

1. Storage Permissions

   • Ensure the configured storage path (var/archives) is writable by the web server user.
   • For S3/AWS, validate IAM permissions and bucket policies.

2. Circular Dependencies

   • Avoid circular references in ArchiveContentProvider implementations (e.g., fetching data from the same process instance recursively).

3. Large Archives

   • For processes with large payloads, implement chunked archiving or streaming to avoid memory issues:

     $archiveService->archiveProcessInstance($instance, [
         'chunk_size' => 1024 * 1024, // 1MB chunks
         'stream' => true,
     ]);
     

Debugging

• Log Archive Events Enable debug logging for archive operations:

  # config/packages/monolog.yaml
  handlers:
      archive:
          type: stream
          path: '%kernel.logs_dir%/archive.log'
          level: debug
          channels: ['archive']
  

• Validate Archive Contents Use the ArchiveService::validateArchive() method to check integrity:

  $isValid = $archiveService->validateArchive($archive->getPath());
  

Extension Points

1. Custom Archive Formats Extend Cleverage\ArchiveProcessBundle\Format\ArchiveFormatInterface:

   class PDFArchiveFormat implements ArchiveFormatInterface {
       public function generate(array $content, string $outputPath): void {
           // Custom PDF generation logic
       }
   }
   

   Register in config:

   cleverage_archive_process:
       formats:
           pdf:
               type: 'pdf'
               class: 'App\PDFArchiveFormat'
   

2. Pre/Post Archive Hooks Subscribe to events:

   // src/EventListener/CustomArchiveListener.php
   class CustomArchiveListener implements EventSubscriberInterface {
       public static function getSubscribedEvents(): array {
           return [
               ArchiveEvents::PRE_ARCHIVE => 'onPreArchive',
               ArchiveEvents::POST_ARCHIVE => 'onPostArchive',
           ];
       }
   }
   

3. Metadata Enrichment Override default metadata with a subscriber:

   class ArchiveMetadataSubscriber implements EventSubscriberInterface {
       public static function getSubscribedEvents(): array {
           return [
               ArchiveEvents::BUILD_METADATA => 'enrichMetadata',
           ];
       }
   
       public function enrichMetadata(ArchiveMetadataEvent $event): void {
           $event->addMetadata('custom_field', 'value');
       }
   }
   

Configuration Quirks

• Default Format Fallback If no format is specified, the bundle defaults to zip. Explicitly set a default in config:

  cleverage_archive_process:
      formats:
          default: 'zip'
  

• Process Instance Filtering Use the archive_filter config to limit archiving to specific processes:

  cleverage_archive_process:
      archive_filter:
          class: 'App\Filter\ProcessFilter'
          method: 'isArchivable'