Image Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require aferrandini/image-bundle
   

   Register it in config/bundles.php:

   return [
       // ...
       Aferrandini\ImageBundle\AferrandiniImageBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console aferrandini:image:install
   

   Update config/packages/aferrandini_image.yaml to define:

   • default_driver (e.g., gd, imagick).
   • storage (e.g., local, s3).
   • directories (input/output paths).

3. First Use Case Resize an image in a controller:

   use Aferrandini\ImageBundle\Manager\ImageManager;
   
   public function resize(ImageManager $imageManager)
   {
       $image = $imageManager->read('path/to/input.jpg');
       $image->resize(300, 200);
       $imageManager->save($image, 'path/to/output.jpg');
   }
   

Implementation Patterns

Core Workflows

1. Dynamic Resizing Use named presets (defined in config) for reusable transformations:

   # config/packages/aferrandini_image.yaml
   aferrandini_image:
       presets:
           thumbnail: { width: 150, height: 150, mode: 'outbound' }
   

   Apply in code:

   $image->applyPreset('thumbnail');
   

2. Batch Processing Loop through files in a directory:

   $files = glob('uploads/*.jpg');
   foreach ($files as $file) {
       $image = $imageManager->read($file);
       $image->resize(800, null); // Auto-height
       $imageManager->save($image, "resized/{$image->getFilename()}");
   }
   

3. Integration with Symfony Forms Use Aferrandini\ImageBundle\Form\Type\ImageType for file uploads:

   $builder->add('image', ImageType::class, [
       'label' => 'Profile Picture',
       'required' => false,
       'preset' => 'thumbnail', // Optional preset
   ]);
   

Advanced Patterns

• Custom Drivers: Extend Aferrandini\ImageBundle\Driver\DriverInterface for cloud storage (e.g., S3).
• Event Listeners: Hook into image.pre_save/image.post_save events for logging/validation.
• Twig Filters: Use {{ image('path/to/file.jpg', 'thumbnail') }} in templates (requires AferrandiniImageTwigExtension).

Gotchas and Tips

Pitfalls

1. Driver Compatibility

   • imagick requires PHP Imagick extension (not gd).
   • Fallback to gd in config if imagick fails:

     aferrandini_image:
         drivers:
             imagick: ~
             gd: { fallback: true }
     

2. File Permissions Ensure output directories (e.g., public/uploads/resized) are writable:

   chmod -R 775 var/cache var/log public/uploads
   

3. Memory Limits Large images may hit PHP’s memory_limit. Increase in php.ini or use imagick (more efficient):

   memory_limit = 256M
   

Debugging Tips

• Log Errors: Enable debug mode and check var/log/dev.log for driver failures.
• Validate Config: Run:

  php bin/console debug:config aferrandini_image
  

• Test Locally: Use local storage first before deploying to cloud.

Extension Points

1. Custom Filters Add filters (e.g., watermark) by extending Aferrandini\ImageBundle\Filter\FilterInterface:

   class WatermarkFilter implements FilterInterface {
       public function apply(ImageInterface $image) { /* ... */ }
   }
   

   Register in services.yaml:

   services:
       App\Filter\WatermarkFilter:
           tags: { name: aferrandini_image.filter, alias: 'watermark' }
   

2. Override Templates Copy vendor/aferrandini/image-bundle/Resources/views/ to templates/aferrandini_image/ for custom Twig templates.

3. Command-Line Tools Use php bin/console aferrandini:image:resize for CLI batch processing:

   php bin/console aferrandini:image:resize input.jpg output.jpg 300x200