Liip Imagine Template Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer in your Laravel project (Symfony-based):

   composer require daddl3/liip_imagine_template_bundle
   

   Register the bundle in config/app.php under providers:

   Daddl3\LiipImagineTemplateBundle\Daddl3LiipImagineTemplateBundle::class,
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="Daddl3\LiipImagineTemplateBundle\Daddl3LiipImagineTemplateBundle" --tag="config"
   

   Update config/liip_imagine_template.php with your storage paths and template definitions.

3. First Use Case Define a template in config/liip_imagine_template.php:

   templates:
       thumbnail:
           filter: my_thumbnail_filter
           path: /uploads/thumbnails
   

   Use it in a controller:

   use Liip\ImagineBundle\Imagine\Cache\CacheManager;
   use Liip\ImagineBundle\Imagine\Filter\FilterManager;
   
   public function generateThumbnail($path, $filename)
   {
       $cacheManager = $this->get('liip_imagine.cache.manager');
       $filterManager = $this->get('liip_imagine.filter.manager');
   
       $template = $this->get('liip_imagine.template.manager')->get('thumbnail');
       $template->applyFilter($filterManager->get('my_thumbnail_filter'), $path);
       $cacheManager->save($template->getPath(), $filename);
   }
   

Implementation Patterns

Workflows

1. Template-Based Image Processing

   • Define reusable templates for common image transformations (e.g., thumbnails, cropped avatars).
   • Example template for a blog post featured image:

     templates:
         featured_image:
             filter: featured_image_filter
             path: /uploads/blog/featured
             format: jpeg
             quality: 80
     

2. Dynamic Paths Use placeholders in template paths for dynamic storage:

   templates:
       user_avatar:
           filter: avatar_crop
           path: /uploads/avatars/{user_id}
   

   Resolve dynamically in code:

   $template->setParameter('user_id', $user->id);
   

3. Integration with Laravel Storage Use Laravel’s filesystem to handle template paths:

   $path = storage_path('app/uploads/' . $template->getPath());
   

Integration Tips

• Symfony Integration: Leverage Symfony’s dependency injection to inject TemplateManager and CacheManager into controllers/services.

• Laravel Facades: Create a facade for cleaner syntax:

  use Illuminate\Support\Facades\Facade;
  
  class ImagineTemplate extends Facade {
      protected static function getFacadeAccessor() { return 'liip_imagine.template.manager'; }
  }
  

  Usage:

  ImagineTemplate::get('thumbnail')->applyFilter(...);
  

• Event Listeners: Trigger image processing after file uploads:

  public function handle(UploadedFile $file)
  {
      $template = ImagineTemplate::get('thumbnail');
      $template->applyFilter($file->path());
      $template->saveAs($file->hashName());
  }
  

Gotchas and Tips

Pitfalls

1. Cache Invalidation

   • LiipImagine caches generated images. Clear cache manually if templates/config change:

     php artisan cache:clear
     

   • Or programmatically:

     $this->get('liip_imagine.cache.manager')->clear();
     

2. Path Resolution

   • Ensure template paths are absolute (e.g., /uploads/thumbnails) or use Laravel’s storage_path() for consistency.
   • Avoid relative paths like ./uploads—they may break in shared hosting.

3. Filter Configuration

   • Filters must be defined in config/liip_imagine.yaml before use:

     filters:
         my_thumbnail_filter:
             filters:
                 thumbnail: { size: [200, 200], mode: outbound }
     

Debugging

• Check Generated Paths Log template paths to verify they resolve correctly:

  \Log::debug('Template path:', [$template->getPath()]);
  

• Validate Filters Use FilterManager to debug available filters:

  $filters = $this->get('liip_imagine.filter.manager')->getFilters();
  \Log::debug('Available filters:', [$filters]);
  

Extension Points

1. Custom Template Types Extend the Template class to add logic (e.g., auto-resize based on content):

   namespace App\Imagine;
   
   use Daddl3\LiipImagineTemplateBundle\Model\Template;
   
   class ResponsiveTemplate extends Template {
       public function getSize() {
           return $this->getParameter('size', [300, 300]);
       }
   }
   

2. Dynamic Filter Selection Override filter selection in templates:

   templates:
       dynamic_thumbnail:
           filter: { service: 'liip_imagine.filter.manager', method: 'getDynamicFilter' }
   

3. Laravel Service Providers Bind custom template classes in AppServiceProvider:

   public function register() {
       $this->app->bind(
           'app.imagine.template.responsive',
           ResponsiveTemplate::class
       );
   }