Imagine Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require liip/imagine-bundle
   

   Add to config/bundles.php (Symfony Flex handles this automatically).

2. Configure Filter Sets: Define a filter set in config/packages/liip_imagine.yaml:

   liip_imagine:
       filter_sets:
           my_thumbnail:
               filters:
                   thumbnail: { size: [100, 100], mode: outbound }
   

3. First Use Case: Generate a thumbnail in a controller:

   use Liip\ImagineBundle\Imagine\Cache\CacheManager;
   use Liip\ImagineBundle\Imagine\Filter\FilterManager;
   
   public function show(Image $image, CacheManager $cacheManager, FilterManager $filterManager)
   {
       $filter = $filterManager->getFilter('my_thumbnail');
       $path = $cacheManager->getBrowserPath($image->getPath(), $filter);
       return new Response(file_get_contents($path));
   }
   

Key Files to Review

• config/packages/liip_imagine.yaml (default config)
• src/Controller/ImageController.php (example usage)
• src/Entity/Image.php (if using Doctrine)

Implementation Patterns

Common Workflows

1. Dynamic Filter Application

Use the FilterManager to apply filters dynamically based on user input or business logic:

$filter = $filterManager->getFilter('thumbnail_large');
if ($user->isPremium()) {
    $filter = $filterManager->getFilter('thumbnail_premium');
}

2. Responsive Images

Generate multiple filter sets for different breakpoints and serve the appropriate one:

liip_imagine:
    filter_sets:
        responsive_small: { filters: { thumbnail: { size: [300, 300] } } }
        responsive_large: { filters: { thumbnail: { size: [1200, 1200] } } }

Use in Twig:

{% for filter in ['responsive_small', 'responsive_large'] %}
    <source srcset="{{ asset(app.liip_imagine.filter(filter).getBrowserPath(image.path)) }}"
            media="(min-width: {{ loop.index0 * 300 + 300 }}px)">
{% endfor %}

3. Doctrine Integration

Annotate entities to auto-generate paths:

use Liip\ImagineBundle\Annotation\Filter;

/**
 * @ORM\Entity
 * @Filter("my_thumbnail")
 */
class ProductImage {
    // ...
}

Access the filtered path:

$productImage->getFilteredPath('my_thumbnail');

4. Command-Line Processing

Process images in bulk via console:

php bin/console liip:imagine:cache:remove --filter=my_thumbnail
php bin/console liip:imagine:cache:generate --filter=my_thumbnail

Integration Tips

• Symfony Forms: Use LiipImagineBundle\Form\Type\ImagineType for file uploads with auto-filtering.
• APIs: Return filtered image paths in JSON responses:

  return $this->json([
      'original' => $image->getPath(),
      'thumbnail' => $cacheManager->getBrowserPath($image->getPath(), $filter),
  ]);
  

• Varnish/Nginx: Cache filtered images at the web server level using X-Sendfile or X-Accel-Redirect.

Gotchas and Tips

Pitfalls

1. Cache Invalidation:

   • Manually clear cache after changing filter configurations:

     php bin/console cache:clear
     php bin/console liip:imagine:cache:remove --filter=*
     

   • Use cache:generate to rebuild all filtered images.

2. File Permissions: Ensure the cache directory (e.g., var/cache/liip_imagine) is writable by the web server user.

3. Memory Limits: Large images may hit PHP’s memory_limit. Adjust in php.ini or use gd/imagick optimizations:

   liip_imagine:
       driver: gd
       # or
       driver: imagick
   

4. Filter Chaining: Filters execute in order. Place thumbnail before watermark to avoid scaling artifacts.

5. Doctrine Proxy Issues: If using annotations, ensure LiipImagineBundle is loaded before Doctrine ORM in config/bundles.php.

Debugging

• Check Generated Paths:

  $path = $cacheManager->getBrowserPath($originalPath, $filter);
  file_exists($path); // Verify file exists
  

• Log Filter Execution: Enable debug mode to see filter stack traces:

  liip_imagine:
      debug: true
  

• Inspect Filter Sets: Dump available filters in a controller:

  dump($filterManager->getFilterNames());
  

Extension Points

1. Custom Filters: Create a custom filter by implementing Liip\ImagineBundle\Imagine\Filter\FilterInterface:

   use Liip\ImagineBundle\Imagine\Filter\FilterConfigurationInterface;
   
   class CustomFilter implements FilterInterface {
       public function apply(FilterConfigurationInterface $configuration) {
           // Modify $configuration->getImagineObject()
       }
   }
   

   Register in config/packages/liip_imagine.yaml:

   liip_imagine:
       filters:
           custom:
               custom_filter: ~
   

2. Dynamic Filter Sets: Generate filter sets programmatically:

   $filterManager->createFilter('dynamic_'.uniqid(), [
       'thumbnail' => ['size' => [$width, $height]],
   ]);
   

3. Event Listeners: Listen to liip_imagine.filter.post_generate to post-process images:

   use Liip\ImagineBundle\Imagine\Event\FilterEvent;
   
   $eventDispatcher->addListener(
       'liip_imagine.filter.post_generate',
       function (FilterEvent $event) {
           // $event->getImagineObject() is the processed image
       }
   );
   

4. Storage Backends: Extend Liip\ImagineBundle\Imagine\Cache\CacheManager to support custom storage (e.g., S3):

   class S3CacheManager extends CacheManager {
       protected function getCachePath($path) {
           return 's3://bucket/' . $path;
       }
   }