Imagine Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require braune-digital/imagine-bundle
   

   Register the bundle in config/bundles.php (Symfony):

   return [
       // ...
       BrauneDigital\ImagineBundle\BrauneDigitalImagineBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config (if needed):

   php bin/console braune-digital:imagine:config:dump
   

   Configure config/packages/braune_digital_imagine.yaml:

   braune_digital_imagine:
       driver: 'gd' # or 'imagick'
       cache: 'cache.adapter.system'
   

3. First Use Case Use the service to resize an image in a controller:

   use BrauneDigital\ImagineBundle\Service\ImagineService;
   
   class ImageController extends AbstractController
   {
       public function resize(ImageService $imagineService)
       {
           $path = $this->getParameter('kernel.project_dir') . '/public/uploads/image.jpg';
           $imagine = $imagineService->load($path);
           $imagine->resize(new \Imagine\Gd\Box(200, 200));
   
           return $this->file($imagine->get('jpg'));
       }
   }
   

Implementation Patterns

Common Workflows

1. Dynamic Image Processing Use the service in controllers or services to generate thumbnails on-the-fly:

   $imagine = $imagineService->load($filePath)
       ->resize(new \Imagine\Gd\Box(300, 300))
       ->watermark($watermarkPath, 0.5, 0.5)
       ->save($outputPath);
   

2. Batch Processing Process multiple images in a loop (e.g., for bulk uploads):

   foreach ($uploadedFiles as $file) {
       $imagineService->load($file->getPathname())
           ->resize(new \Imagine\Gd\Box(800, 600))
           ->save($file->getPathname());
   }
   

3. Integration with Symfony Forms Use with VichUploaderBundle or custom file uploads:

   $form = $this->createForm(ImageUploadType::class, $entity);
   $form->handleRequest($request);
   
   if ($form->isSubmitted() && $form->isValid()) {
       $imagineService->load($entity->getImagePath())
           ->resize(new \Imagine\Gd\Box(1024, 768))
           ->save($entity->getImagePath());
   }
   

4. Caching Processed Images Leverage Symfony’s cache system to avoid reprocessing:

   braune_digital_imagine:
       cache: 'cache.adapter.redis'
   

Integration Tips

• Doctrine Entities: Store processed image paths in entities (e.g., thumbnailPath).
• Event Listeners: Trigger image processing after file uploads:

  public function onUpload(FileUploadEvent $event)
  {
      $imagineService->load($event->getFile()->getPathname())
          ->resize(new \Imagine\Gd\Box(400, 400))
          ->save($event->getFile()->getPathname());
  }
  

• API Responses: Return processed images as streams:

  return new BinaryFileResponse($imagine->get('png'), 200, [
      'Content-Type' => 'image/png',
      'Content-Disposition' => 'inline; filename="thumbnail.png"',
  ]);
  

Gotchas and Tips

Pitfalls

1. Driver Dependencies

   • GD/Imagick: Ensure PHP extensions are installed (php-gd or php-imagick).
   • Fallback: Configure a fallback driver in braune_digital_imagine.yaml:

     driver: 'gd'
     fallback_driver: 'imagick'
     

2. File Permissions

   • Ensure the target directory for processed images is writable:

     chmod -R 775 /path/to/public/uploads
     

3. Memory Limits

   • Large images may hit PHP’s memory_limit. Adjust in php.ini or use chunked processing:

     $imagine->resize(new \Imagine\Gd\Box(2000, 2000))->save($outputPath, ['quality' => 80]);
     

4. Cache Invalidation

   • Clear cache after config changes:

     php bin/console cache:clear
     

Debugging

• Log Errors: Enable Imagine’s logger:

  braune_digital_imagine:
       debug: true
  

• Check Loaded Image: Verify paths and formats:

  $imagine = $imagineService->load($path);
  if (!$imagine->valid()) {
      throw new \RuntimeException('Invalid image file');
  }
  

Extension Points

1. Custom Filters Extend the service to add reusable filters:

   $imagine->customFilter(function ($image) {
       $image->rotate(90);
       return $image;
   });
   

2. Event Dispatching Dispatch events before/after processing:

   $dispatcher->dispatch(new ImageProcessEvent($imagine, 'pre_process'));
   $imagine->resize(...);
   $dispatcher->dispatch(new ImageProcessEvent($imagine, 'post_process'));
   

3. Configuration Overrides Override settings per environment (e.g., config/packages/dev/braune_digital_imagine.yaml):

   braune_digital_imagine:
       driver: 'imagick'
       debug: true
   

Pro Tips

• Use Imagine\Image\Box for Aspect Ratio:

  $imagine->resize(new \Imagine\Image\Box(800, null)); // Maintain aspect ratio
  

• Optimize for Web:

  $imagine->resize(new \Imagine\Gd\Box(1200, 800))
      ->save($outputPath, ['quality' => 75]);
  

• Leverage Symfony’s Parameter Bag: Store default paths in config/services.yaml:

  parameters:
      app.upload_dir: '%kernel.project_dir%/public/uploads'