Imagine Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require avalanche123/imagine-bundle
   

   Add the bundle to AppKernel.php:

   new Avalanche\Bundle\ImagineBundle\AvalancheImagineBundle(),
   

   Register routes in routing.yml:

   _imagine:
       resource: .
       type:     imagine
   

2. Basic Configuration: Define a filter in config.yml (e.g., thumbnail):

   avalanche_imagine:
       filters:
           my_thumb:
               type:    thumbnail
               options: { size: [120, 90], mode: outbound }
   

3. First Use Case: Apply the filter in a Twig template:

   <img src="{{ '/path/to/image.jpg' | apply_filter('my_thumb') }}" />
   

   The bundle caches the result in web/media/cache/my_thumb/path/to/image.jpg.

Implementation Patterns

Common Workflows

1. Dynamic Filter Application: Use Twig logic to conditionally apply filters:

   {% set filter = image_type == 'product' ? 'product_thumb' : 'default_thumb' %}
   <img src="{{ image_path | apply_filter(filter) }}" />
   

2. Controller Integration: Resolve cached paths programmatically:

   $cachedPath = $this->get('imagine.cache.path.resolver')
       ->getBrowserPath('/path/to/image.jpg', 'my_thumb');
   

3. Batch Processing: Generate thumbnails for a collection of images in a controller:

   $cacheManager = $this->get('imagine.cache.manager');
   foreach ($images as $image) {
       $cacheManager->cacheImage(
           $this->getRequest()->getBaseUrl(),
           $image->getPath(),
           'my_thumb'
       );
   }
   

Integration Tips

• Asset Management: Use the cache_prefix to organize cached images by filter (e.g., media/cache/thumbnail/).
• Twig Extensions: Extend Twig with custom filters for reusable logic:

  // services.yml
  twig.extension.imagine:
      class: AppBundle\Twig\ImagineExtension
      tags: ['twig.extension']
  

• Symfony Forms: Dynamically generate image paths for form fields:

  {{ form_widget(form.image, {'attr': {'src': image_path|apply_filter('preview')}}) }}
  

Gotchas and Tips

Pitfalls

1. Twig Filter Order: Parentheses are required for complex paths:

   {{ ('/path/' ~ variable ~ '.jpg') | apply_filter('filter') }}  # Correct
   {{ '/path/' ~ variable ~ '.jpg' | apply_filter('filter') }}   # Incorrect (filters '.jpg')
   

2. Cache Path Collisions: Override cache_prefix per filter to avoid conflicts:

   filters:
       custom_thumb:
           type:    thumbnail
           options: { size: [200, 200] }
           path:    media/cache/custom_thumbs
   

3. Driver Dependencies: Ensure gd, imagick, or gmagick is installed system-wide. Test with:

   php -m | grep -E 'gd|imagick'
   

Debugging

• Missing Cached Images: Verify web_root and cache_prefix paths are writable. Check Symfony logs for Imagine\Exception\RuntimeException.
• Filter Not Applied: Confirm the filter name matches exactly in Twig and config.yml. Use:

  $this->get('imagine.cache.manager')->getFilters();
  

  to list registered filters.

Extension Points

1. Custom Filters: Implement LoaderInterface for new filter types. Example:

   class MyFilterLoader implements LoaderInterface {
       public function load($name, FilterManager $filterManager) {
           return $filterManager->filter(new MyFilter());
       }
   }
   

   Register the service:

   services:
       my_filter_loader:
           class: AppBundle\Imagine\MyFilterLoader
           tags:
               - { name: imagine.filter.loader, filter: my_filter }
   

2. Event Listeners: Hook into imagine.filter.post_generate to modify cached images:

   $event->getImage()->draw()->text('Watermark', new Point(10, 10));
   

3. HTTP Cache Headers: Configure cache_type and cache_expires in filters to leverage browser caching:

   filters:
       my_thumb:
           type:    thumbnail
           options:
               size: [120, 90]
               cache_type: public
               cache_expires: '+1 year'
   

   Add Apache/Nginx rules to enforce cache headers for the media/cache directory.

Performance Tips

• Pre-Generate Thumbnails: Use a command to batch-process images during deployment:

  // app/console imagine:cache:generate
  

• Lazy Loading: Defer image processing until the first request to reduce server load.
• CDN Integration: Serve cached images via CDN by configuring web_root to point to the CDN’s local cache directory.