Image Manage Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require creavio/image-manage-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Creavio\ImageManageBundle\CreavioImageManageBundle::class => ['all' => true],
   ];
   

2. Configuration: Publish the default config:

   php bin/console creavio:image-manage:install
   

   Edit config/packages/creavio_image_manage.yaml to define:

   • image_directories (source paths)
   • resize_configs (named presets like thumbnail, large)

3. First Use Case: In a Twig template, reference a resized image:

   <img src="{{ asset('images/product.jpg|resize:thumbnail') }}" alt="Product">
   

   • The |resize:thumbnail filter applies the thumbnail preset from config.

Implementation Patterns

Core Workflow

1. Define Presets: Configure resizing rules in config/packages/creavio_image_manage.yaml:

   resize_configs:
       thumbnail:
           width: 200
           height: 200
           mode: 'outbound'  # or 'inbound', 'exact'
       large:
           width: 800
           height: null
           quality: 80
   

2. Twig Integration:

   • Use the |resize filter in Twig:

     {{ asset('path/to/image.jpg|resize:large') }}
     

   • Chain with other filters (e.g., |crop if supported):

     {{ asset('path/to/image.jpg|resize:thumbnail|crop:50x50') }}
     

3. Dynamic Presets: Pass runtime values via Twig:

   {% set customSize = '400x300' %}
   {{ asset('image.jpg|resize:custom:' ~ customSize) }}
   

   Define in config:

   resize_configs:
       custom: { width: null, height: null }  # Overridden by runtime args
   

4. Asset Pipeline:

   • Cache busting: Append ?v={{ filemtime('path/to/image.jpg') }} to URLs.
   • Use asset() for automatic versioning:

     {{ asset('image.jpg|resize:thumbnail', {'fallback': 'default.jpg'}) }}
     

5. Controller Integration: Generate URLs programmatically:

   use Creavio\ImageManageBundle\Twig\ResizeExtension;
   
   $resizeUrl = $this->get('twig')->getExtension(ResizeExtension::class)
       ->getResizeUrl('/uploads/image.jpg', 'thumbnail');
   

Advanced Patterns

• Conditional Resizing: Use Twig logic to switch presets:

  {% set preset = isMobile ? 'mobile' : 'desktop' %}
  {{ asset('image.jpg|resize:' ~ preset) }}
  

• Fallbacks: Handle missing images:

  {{ asset('image.jpg|resize:thumbnail', {'fallback': 'no-image.png'}) }}
  

• Batch Processing: Use the CLI command to pre-generate resized versions:

  php bin/console creavio:image-manage:resize --dir=/path/to/images --preset=thumbnail
  

Gotchas and Tips

Pitfalls

1. Caching Issues:

   • Resized images are not automatically cached by default. Use a CDN or file_put_contents in a post-resize event to save to disk.
   • Clear cache after config changes:

     php bin/console cache:clear
     

2. Path Configuration:

   • image_directories must include the full server path (e.g., /var/www/html/public/uploads), not a web URL.
   • Trailing slashes in paths can cause 404s.

3. Twig Filter Scope:

   • The |resize filter only works with asset(). Direct URLs (e.g., {{ imageUrl|resize }}) will fail.
   • Example of wrong usage:

     {# ❌ Won't work #}
     <img src="{{ imageUrl|resize:thumbnail }}">
     

4. Quality Settings:

   • Default quality: 75 may produce large files. Adjust in config:

     resize_configs:
         high_quality: { quality: 90 }
     

5. File Permissions:

   • Ensure the web server user (e.g., www-data) has write permissions to the output directory (if saving resized files).

Debugging Tips

1. Check Config: Validate resize_configs syntax. Use:

   php bin/console debug:config creavio_image_manage
   

2. Log Errors: Enable debug mode and check var/log/dev.log for:

   • Missing source files.
   • Invalid preset names.

3. Test CLI Commands: Manually trigger resizing to verify:

   php bin/console creavio:image-manage:resize --dir=/path/to/image.jpg --preset=thumbnail
   

4. Fallback Behavior:

   • If fallback is not set, missing images return a 404. Always specify a fallback in production:

     {{ asset('image.jpg|resize:thumbnail', {'fallback': 'fallback.jpg'}) }}
     

Extension Points

1. Custom Filters: Extend the bundle by adding new Twig filters in a service:

   # config/services.yaml
   services:
       App\Twig\CustomImageExtension:
           tags: ['twig.extension']
   

   Example extension:

   namespace App\Twig;
   use Twig\Extension\AbstractExtension;
   use Twig\TwigFunction;
   
   class CustomImageExtension extends AbstractExtension {
       public function getFunctions() {
           return [
               new TwigFunction('custom_resize', [$this, 'customResize']),
           ];
       }
       public function customResize($path, $preset, $options = []) {
           // Integrate with ImageManageBundle's logic
       }
   }
   

2. Event Listeners: Hook into the resize process to add watermarks or metadata:

   namespace App\EventListener;
   use Creavio\ImageManageBundle\Event\ResizeEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class WatermarkSubscriber implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               ResizeEvent::NAME => 'onResize',
           ];
       }
       public function onResize(ResizeEvent $event) {
           $event->getImage()->addWatermark('watermark.png');
       }
   }
   

3. Override Templates: Customize the Twig template for resize URLs by copying:

   vendor/creavio/image-manage-bundle/Resources/views/
   

   to your project’s templates/creavio_image_manage/ directory.

Performance

• Avoid Runtime Resizing: Pre-generate resized images for static content.
• Use mode: 'exact': Preserves aspect ratio without padding (faster than outbound).
• Limit Presets: Fewer presets reduce config complexity and cache invalidations.