Paging Seal Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require cubemage/paging-seal-bundle
   

   Ensure gd PHP extension is enabled for image processing.

2. Enable Bundle: Add to config/bundles.php if not auto-loaded by Flex:

   CubeMage\PagingSealBundle\CubeMagePagingSealBundle::class => ['all' => true],
   

3. First Use Case: Inject PagingSealGenerator into a controller/service and call generate() with:

   • Input PDF path (required)
   • Seal image path (optional; falls back to default_seal_path if configured)
   • Position ('right', 'left', 'top', 'bottom')
   • Seal size (mm)
   • Margin (mm)

   Example:

   $this->sealGenerator->generate(
       $pdfPath,
       $sealPath,
       'right',
       30, // size
       5  // margin
   );
   

Implementation Patterns

Core Workflow

1. File Handling:

   • Upload PDF and seal image via Symfony UploadedFile.
   • Use getPathname() to get temporary paths for processing.
   • Clean up files post-download with deleteFileAfterSend(true).

2. Service Integration:

   • Controller: Inject PagingSealGenerator and call generate() in action methods.
   • Service Layer: Reuse the service for batch processing (e.g., queue jobs for bulk PDF sealing).

3. Configuration:

   • Set default_seal_path in config/packages/cube_mage_paging_seal.yaml to avoid passing seal paths repeatedly.
   • Customize pdf_path for temporary file storage (default: %kernel.project_dir%/var/cubemage/paging-seal).

4. Response Handling:

   • Return processed PDF as BinaryFileResponse for downloads:

     return $this->file($generatedPdfPath, 'sealed-document.pdf')->deleteFileAfterSend(true);
     

Advanced Patterns

• Dynamic Seal Selection: Use a database-backed service to fetch seal paths based on user/role (e.g., company-specific seals). Example:

  $sealPath = $this->sealRepository->getSealPathForUser($userId);
  

• Validation: Validate PDF/seal files before processing:

  if (!$documentFile->isValid() || !$documentFile->getClientOriginalExtension() === 'pdf') {
      throw $this->createNotFoundException('Invalid PDF file.');
  }
  

• Asynchronous Processing: Dispatch a Symfony Messenger message to process PDFs in the background:

  $this->messageBus->dispatch(new ProcessPdfSealMessage($pdfPath, $sealPath, 'right'));
  

Gotchas and Tips

Pitfalls

1. File Permissions:

   • Ensure the pdf_path directory is writable by the web server (e.g., chmod -R 775 var/cubemage).

2. GD Extension:

   • If seal images fail to render, verify gd is enabled (php -m | grep gd). Common issue on shared hosting.

3. Memory Limits:

   • Large PDFs may hit PHP’s memory_limit. Increase if needed:

     # config/packages/framework.yaml
     framework:
         php:
             memory_limit: 512M
     

4. Seal Image Requirements:

   • Seal images must be transparent PNGs for proper overlay. Non-PNGs may render with white backgrounds.

Debugging

• Log Temporary Files: Add logging to track file paths:

  $this->logger->debug('Generated PDF:', ['path' => $generatedPdfPath]);
  

• Check Config Overrides: Verify cube_mage_paging_seal.yaml is loaded (Symfony Flex may auto-configure it).

Extension Points

1. Custom Seal Logic: Extend PagingSealGenerator to support:

   • Multi-page seals (e.g., alternating seals per page).
   • Dynamic seal positioning (e.g., center-align seals).

2. Event Listeners: Trigger events before/after sealing (e.g., log processing time):

   // src/EventListener/PdfSealListener.php
   public function onPdfSealed(PdfSealedEvent $event) {
       $this->logger->info('PDF sealed', ['path' => $event->getPath()]);
   }
   

3. Seal Templates: Use Symfony’s templating to generate seals dynamically (e.g., add timestamps):

   {# templates/seal/seal.html.twig #}
   <img src="{{ asset('images/seal.png') }}" style="opacity: 0.8; filter: drop-shadow(0 0 2px #000);">
   

Tips

• Performance: Cache frequently used seals in memory (e.g., with Symfony’s CacheInterface).

• Testing: Mock PagingSealGenerator in PHPUnit:

  $mockGenerator = $this->createMock(PagingSealGenerator::class);
  $mockGenerator->method('generate')->willReturn('/path/to/mocked-pdf.pdf');
  

• Localization: Support multi-language seals by storing them in public/seals/{locale}.png and routing dynamically.