Liip Imagine Pack Laravel Package

Getting Started

Minimal Steps

1. Install the Package Require the package via Composer:

   composer require david-garcia/liip-imagine-pack
   

   Ensure LiipImagineBundle is already installed (Symfony 7.x + PHP 8.x).

2. Enable the Bundle Add to config/bundles.php:

   DavidGarcia\LiipImaginePack\LiipImaginePackBundle::class => ['all' => true],
   

3. Configure Filters Add filter sets to config/packages/liip_imagine.yaml:

   liip_imagine:
       filter_sets:
           blur_example:
               filters:
                   blur_filter:
                       start: [0, 0]
                       size: [100, 100]
           pixelate_example:
               filters:
                   pixelate_filter:
                       start: [0, 0]
                       size: [50, 50]
   

4. First Use Case Generate a blurred/pixelated image in a controller:

   use Liip\ImagineBundle\Service\Filter\FilterConfiguration;
   
   public function applyFilter(FilterConfiguration $filterManager)
   {
       $filter = $filterManager->getFilterConfiguration('blur_example');
       $imagePath = $filter->applyFile('/path/to/image.jpg');
       return new Response(file_get_contents($imagePath), 200, ['Content-Type' => 'image/jpeg']);
   }
   

Implementation Patterns

Common Workflows

1. Dynamic Filter Application Use Twig to apply filters dynamically:

   {% set filter = 'blur_example' %}
   <img src="{{ path('liip_imagine_filter', { filter: filter, path: 'image.jpg' }) }}">
   

2. Conditional Filtering Apply filters based on user input or logic:

   $filterName = $request->get('filter') === 'pixelate' ? 'pixelate_example' : 'blur_example';
   $imagePath = $filterManager->getFilterConfiguration($filterName)->applyFile($originalPath);
   

3. Batch Processing Process multiple images with the same filter:

   $images = ['image1.jpg', 'image2.jpg'];
   foreach ($images as $image) {
       $filteredPath = $filterManager->getFilterConfiguration('blur_example')->applyFile($image);
       // Save or serve $filteredPath
   }
   

4. Integration with Uploads Apply filters to uploaded files:

   $uploadedFile = $request->file('image');
   $filteredPath = $filterManager->getFilterConfiguration('pixelate_example')->applyFile($uploadedFile->getPathname());
   

Integration Tips

• Cache Filtered Images Leverage LiipImagineBundle’s caching to avoid reprocessing:

  blur_example:
      cache: imagick_cache  # Define cache in liip_imagine.yaml
  

• Combine with Existing Filters Chain custom filters with built-in ones (e.g., resize + blur):

  blur_and_resize:
      filters:
          thumbnail: { size: [200, 200], mode: outbound }
          blur_filter: { start: [0, 0], size: [50, 50] }
  

• Use in API Responses Return filtered images as binary responses:

  return new BinaryFileResponse($filteredPath, 200, [], true);
  

Gotchas and Tips

Pitfalls

1. Filter Area Constraints

   • start and size must be within image bounds. Overshooting throws errors or applies partial effects.
   • Fix: Validate coordinates in a custom validator or use max() to clamp values:

     $width = min($image->getWidth(), $start[0] + $size[0]);
     

2. Performance with Large Images

   • Blur/pixelate operations are CPU-intensive. Test on production-sized images.
   • Fix: Use quality (0-100) to balance size/speed or offload to a queue (e.g., Symfony Messenger).

3. GD vs. Imagick/Gmagick

   • GD may produce lower-quality results or lack features. Prefer Imagick/Gmagick for consistency.
   • Fix: Check phpinfo() for installed extensions and adjust liip_imagine.yaml drivers:

     driver: gd  # or gmagick/imagick
     

4. Configuration Overrides

   • Filter sets in liip_imagine.yaml are merged. Later definitions override earlier ones.
   • Fix: Use unique names (e.g., blur_strong, blur_soft) to avoid conflicts.

Debugging

• Verify Filter Application Check if the filter is applied by inspecting the generated image path:

  $filteredPath = $filterManager->getFilterConfiguration('blur_example')->applyFile($path);
  file_exists($filteredPath); // Should return true
  

• Log Filter Errors Enable LiipImagineBundle’s debug mode:

  liip_imagine:
      filter_sets:
          debug:
              debug: true  # Logs filter execution
  

Tips

1. Reusable Filter Presets Create reusable presets in a separate config file (e.g., config/liip_imagine_filters.yaml) and import them:

   imports:
       - { resource: liip_imagine_filters.yaml }
   

2. Custom Filter Parameters Extend the bundle to add parameters (e.g., blur_intensity):

   blur_custom:
       filters:
           blur_filter:
               start: [0, 0]
               size: [100, 100]
               intensity: 0.7  # Hypothetical extension
   

   Requires modifying the bundle’s service or creating a custom filter class.

3. Testing Mock the FilterConfiguration in PHPUnit:

   $filterConfig = $this->createMock(FilterConfiguration::class);
   $filterConfig->method('applyFile')->willReturn('/path/to/filtered.jpg');
   

4. Document Filter Sets Add comments in liip_imagine.yaml to document use cases:

   blur_thumbnail:
       # Applies blur to thumbnails (max 200px). Use for preview images.
       filters:
           thumbnail: { size: [200, 200] }
           blur_filter: { start: [0, 0], size: [100, 100] }