Imgix Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Run composer require apsylone/imgix-bundle in your Symfony 2.8 project. Register the bundle in app/AppKernel.php:

   new Apsylone\ImgixBundle\ApsyloneImgixBundle(),
   

2. Configuration Add imgix configuration to app/config/config.yml:

   apsylone_imgix:
       domain: "your-domain.imgix.net"
       source: "https://your-source.com"
       key: "your-api-key"
   

3. First Use Case Generate an Imgix URL in Twig:

   {{ imgix_url('path/to/image.jpg', {
       'w': 500,
       'h': 300,
       'fit': 'crop'
   }) }}
   

   Or in a controller:

   $imgixUrl = $this->get('apsylone_imgix.imgix')->getUrl(
       'path/to/image.jpg',
       ['w' => 500, 'h' => 300, 'fit' => 'crop']
   );
   

Implementation Patterns

Core Workflows

1. URL Generation Use the Imgix service to generate Imgix URLs with parameters:

   $url = $this->get('apsylone_imgix.imgix')->getUrl(
       'image.jpg',
       ['w' => 800, 'auto' => 'format', 'q' => 80]
   );
   

2. Twig Integration Extend Twig with the imgix_url filter:

   <img src="{{ 'image.jpg'|imgix_url({w: 300, h: 200, fit: 'fill'}) }}" />
   

3. Dynamic Parameter Handling Pass parameters dynamically from controllers or services:

   $params = [
       'w' => $request->query->get('width'),
       'h' => $request->query->get('height'),
       'fit' => 'max'
   ];
   $url = $this->get('apsylone_imgix.imgix')->getUrl('image.jpg', $params);
   

4. Caching URLs Cache generated URLs to avoid redundant API calls:

   $cacheKey = md5('image.jpg' . serialize($params));
   $url = $this->get('apsylone_imgix.imgix.cache')->get($cacheKey);
   if (!$url) {
       $url = $this->get('apsylone_imgix.imgix')->getUrl('image.jpg', $params);
       $this->get('apsylone_imgix.imgix.cache')->set($cacheKey, $url, 3600);
   }
   

Advanced Patterns

1. Parameter Validation Validate Imgix parameters before generating URLs:

   $validator = $this->get('validator');
   $constraints = new Assert\All([
       new Assert\Type('array'),
       new Assert\Expression('value["w"] > 0 && value["h"] > 0', 'Width and height must be positive')
   ]);
   $errors = $validator->validate($params, $constraints);
   

2. Environment-Specific Configs Use Symfony’s parameter bag for environment-specific Imgix configs:

   # app/config/prod.yml
   apsylone_imgix:
       domain: "%imgix_domain_prod%"
       key: "%imgix_key_prod%"
   

3. Event Listeners for URL Generation Hook into kernel events to generate URLs dynamically:

   // src/Acme/ImgixBundle/EventListener/ImgixListener.php
   public function onKernelRequest(GetResponseEvent $event)
   {
       if ($event->isMasterRequest()) {
           $this->generateImgixUrlsForRoute($event->getRequest()->attributes->get('_route'));
       }
   }
   

Gotchas and Tips

Common Pitfalls

1. Missing Configuration Ensure apsylone_imgix is properly configured in config.yml. Missing domain, source, or key will throw exceptions.

2. Parameter Ordering Imgix URLs are sensitive to parameter order. The bundle normalizes parameters, but ensure consistency:

   // Avoid:
   ['w' => 500, 'h' => 300] // May not work if order is critical
   // Use:
   ['w' => 500, 'h' => 300, 'fit' => 'crop']
   

3. Caching Issues If using caching, ensure cache keys are unique and invalidated when configs change:

   $this->get('apsylone_imgix.imgix.cache')->deleteMultiple($this->getCacheKeys());
   

4. Twig Filter Scope The imgix_url filter is only available in Twig templates. For other contexts, use the service directly:

   $this->get('apsylone_imgix.imgix')->getUrl(...);
   

Debugging Tips

1. Enable Imgix Debug Mode Add debug: true to config to log generated URLs:

   apsylone_imgix:
       debug: true
   

2. Validate URLs Manually Test generated URLs in your browser or via curl to ensure they work as expected:

   curl "https://your-domain.imgix.net/path/to/image.jpg?w=500&h=300"
   

3. Check Imgix API Limits Monitor API calls to avoid hitting rate limits. Use auto parameters sparingly:

   // Avoid excessive auto parameters:
   ['auto' => 'format,compress']
   

Extension Points

1. Custom Parameter Transformers Extend the bundle to add custom parameter logic:

   // src/Acme/ImgixBundle/DependencyInjection/Compiler/ImgixPass.php
   public function process(ContainerBuilder $container)
   {
       $definition = $container->findDefinition('apsylone_imgix.imgix');
       $definition->addMethodCall('addParameterTransformer', [new CustomTransformer()]);
   }
   

2. Override Twig Extensions Replace the default Twig extension with a custom one:

   # app/config/config.yml
   twig:
       extensions:
           - Acme\ImgixBundle\Twig\CustomImgixExtension
   

3. Add Custom Cache Backends Implement a custom cache adapter for the ImgixCache service:

   // src/Acme/ImgixBundle/DependencyInjection/AcmeImgixExtension.php
   $container->set('apsylone_imgix.imgix.cache', $this->createCacheService($container));
   

4. Support for Multiple Imgix Instances Configure multiple Imgix instances in Symfony’s parameter bag:

   apsylone_imgix:
       instances:
           primary:
               domain: "primary.imgix.net"
               key: "%imgix_primary_key%"
           secondary:
               domain: "secondary.imgix.net"
               key: "%imgix_secondary_key%"