Imgproxy Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require 3brs/imgproxy-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       ImgproxyBundle::class => ['all' => true],
   ];
   

2. Configure config/packages/liip_imagine.yaml Replace imagine driver with imgproxy:

   liip_imagine:
       driver: imgproxy
       imgproxy:
           endpoint: 'http://localhost:8080'
           key: 'your_imgproxy_key'
   

3. First Use Case: Replace Liip Imagine Filters Update your twig templates to use liip_imagine_path as before:

   <img src="{{ liip_imagine_path(image, 'thumbnail') }}">
   

   Ensure your Imagine filter is defined in config/packages/liip_imagine.yaml:

   filter_sets:
       cache: ~
       thumbnail:
           quality: 75
           filters:
               thumbnail: { size: [200, 200], mode: outbound }
   

Implementation Patterns

Workflow: Migrating from Liip Imagine

1. Replace Driver Configuration Update liip_imagine.yaml to use imgproxy driver and configure the endpoint:

   liip_imagine:
       driver: imgproxy
       imgproxy:
           endpoint: 'https://your-imgproxy-instance.com'
           key: '%env(IMGPROXY_KEY)%'
           signature_secret: '%env(IMGPROXY_SIGNATURE_SECRET)%'  # Optional for signed URLs
   

2. Leverage URL Signing (Security) Enable signed URLs to prevent unauthorized transformations:

   imgproxy:
       signature_secret: 'your_secure_secret'
       signature_expiry: 3600  # 1 hour expiry
   

   Generate signed URLs in templates:

   <img src="{{ liip_imagine_path(image, 'thumbnail', {'signed': true}) }}">
   

3. Cloud Storage Integration Use imgproxy with S3/CDN by configuring the source URL:

   imgproxy:
       source_url: 'https://your-cdn-bucket.s3.amazonaws.com'
   

   Reference images via full URLs in templates:

   <img src="{{ liip_imagine_path('https://cdn.example.com/original.jpg', 'thumbnail') }}">
   

4. Dynamic Filter Sets Define reusable filter sets in liip_imagine.yaml:

   filter_sets:
       responsive:
           quality: 80
           filters:
               thumbnail: { size: [null, 400], mode: outbound }
               background: { color: '#ffffff' }
   

   Use them in templates:

   <img src="{{ liip_imagine_path(image, 'responsive') }}">
   

Gotchas and Tips

Pitfalls

1. Filter Compatibility

   • Only 13/17 Liip Imagine filters are supported (e.g., seamcarving and interlace are unsupported).
   • Workaround: Use alternative filters (e.g., thumbnail instead of seamcarving for resizing).
   • Debug: Check the imgproxy documentation for supported filters.

2. URL Signing Overhead

   • Signed URLs add latency. Disable if not critical:

     imgproxy:
         signature_secret: null  # Disables signing
     

3. Caching Headers

   • imgproxy relies on HTTP caching. Ensure your CDN/S3 has proper Cache-Control headers:

     imgproxy:
         cache_control: 'public, max-age=31536000'  # 1 year
     

4. Endpoint Configuration

   • Hardcoded Endpoints: Avoid hardcoding endpoint in liip_imagine.yaml. Use environment variables:

     imgproxy:
         endpoint: '%env(IMGPROXY_ENDPOINT)%'
     

Debugging

1. Validate imgproxy Response Use browser dev tools to inspect the imgproxy endpoint URL. A malformed URL (e.g., missing key) will return a 403 or 404.

2. Check Filter Syntax imgproxy uses a different syntax for some filters. For example:

   • Liip Imagine: filters: { thumbnail: { size: [200, 200] } }
   • imgproxy: filters: { thumbnail: { width: 200, height: 200 } }
   • Fix: Adjust filter definitions in liip_imagine.yaml.

3. Log imgproxy Requests Enable debug mode in config/packages/dev/liip_imagine.yaml:

   imgproxy:
       debug: true
   

   Logs will appear in var/log/dev.log.

Extension Points

1. Custom Filters Extend the bundle by creating a custom filter class:

   // src/Filter/CustomFilter.php
   namespace App\Filter;
   
   use Liip\ImagineBundle\Filter\FilterConfiguration;
   use Liip\ImagineBundle\Filter\FilterInterface;
   
   class CustomFilter implements FilterInterface {
       public function applyFilter(FilterConfiguration $config, $image) {
           // Custom logic (e.g., call imgproxy API directly)
           return $image;
       }
   }
   

   Register it in services.yaml:

   services:
       App\Filter\CustomFilter:
           tags: [liip_imagine.filter]
   

2. Override imgproxy Client Replace the default ImgproxyClient for custom logic (e.g., retry logic):

   imgproxy:
       client: '@app.imgproxy.client.custom'
   

   Define the service:

   services:
       app.imgproxy.client.custom:
           class: App\Imgproxy\CustomImgproxyClient
           arguments: ['@imgproxy.client']
   

3. Dynamic Endpoint Routing Use a dynamic endpoint based on environment (e.g., staging/production):

   imgproxy:
       endpoint: '%kernel.environment% == "prod" ? "%env(IMGPROXY_PROD_ENDPOINT)" : "%env(IMGPROXY_STAGING_ENDPOINT)"%'