README

Liip Imagine Template Symfony Bundle

Liip Integration for Symfony

Getting started

This bundle helps you to use Liip Imagine Bundle

Installation

$ composer requ daddl3/liip_imagine_template_bundle

Config

you have to config liip_imagine like this

liip_imagine:

  resolvers:
    data:
      web_path:
        web_root: "%kernel.project_dir%/public"
        cache_prefix: media/cache/resolve

  loaders:
    data:
      filesystem:
        data_root: "%kernel.project_dir%/data" // important

Encrypted Messenger transports

The transports of this bundle use EncryptedTransportSerializer, which encrypts every message body with Symfony KeyManagement (envelope encryption, AES-256-GCM). Requires Symfony 8.2 and the KeyManagementBundle:

// config/bundles.php
Symfony\Component\KeyManagement\KeyManagementBundle::class => ['all' => true],

# config/packages/key_management.yaml
key_management:
    clients:
        # e.g. sodium://?keys[app]=<base64url, 32 bytes> or a cloud KMS DSN
        default: '%env(KEY_MANAGEMENT_DSN)%'
    # optional: data keys in the database, "messenger" is then the scope of the data key
    store:
        key_id: app

Without a store, the key messenger must be a master key of the KMS (e.g. keys[messenger]=...). Change the key with:

parameters:
    daddl3_liip_imagine_template.messenger_encryption_key: 'my-key'

Messages that cannot be decrypted (e.g. still queued from before a key change) are rejected with a MessageDecodingFailedException. The former MESSENGER_ENCRYPT_SECRET env var is no longer used.

The transports async, image and failed are signed (sign: true, Symfony 8.2): every message is signed with an HMAC after encryption, and messages without a valid signature are refused before their type is read. The failure transport of your application must therefore sign as well:

framework:
    messenger:
        serializer:
            # own secret instead of kernel.secret; list several to rotate (first signs, all verify)
            signing_secret: ['%env(MESSENGER_SIGNING_SECRET)%']
        transports:
            failed:
                dsn: 'doctrine://default?queue_name=failed'
                sign: true

Messages queued before signing was enabled are refused: let the queues run empty before deploying.

Queue names are prefixed per project (<prefix>_email, <prefix>_modern_image_generation, <prefix>_failed), so projects sharing a broker or schema keep their queues apart:

parameters:
    daddl3_liip_imagine_template.queue_prefix: '%env(CACHE_KEY)%'   # default: app

queue_name/table_name are Doctrine transport options. For AMQP, isolate projects with a vhost each.

Avif and Webp

to enable one of them just add those

    parameters:
        daddl3_liip_imagine_template.avif: true
        daddl3_liip_imagine_template.webp: true

Manual Image Generation

To manually generate images (to avoid slow automatic generation), use the provided command.

How it works:

Applies Liip Imagine filters (resize, crop, etc.) to create filtered JPG/PNG images
Creates WebP/AVIF versions of filtered images using GD (if enabled in config)

Important: The command respects your configuration parameters:

If daddl3_liip_imagine_template.webp: true is set, WebP images will be generated automatically using GD
If daddl3_liip_imagine_template.avif: true is set, AVIF images will be generated automatically using GD
You can override these settings using command flags

# Generate images using config parameters (webp/avif based on your config)
php bin/console daddl3:liip:generate-images news_pics/folder --all-filters

# Generate standard JPG/PNG images for a single file with specific filters
php bin/console daddl3:liip:generate-images news_pics/folder/image.jpg -f meta -f meta_tablet -f meta_mobile

# Force WebP generation (overrides config)
php bin/console daddl3:liip:generate-images news_pics/folder --all-filters --webp

# Force AVIF generation (overrides config)
php bin/console daddl3:liip:generate-images news_pics/folder --all-filters --avif

# Generate ALL formats (JPG/PNG + WebP + AVIF) - overrides config
php bin/console daddl3:liip:generate-images news_pics/folder --all-filters --all-formats

# Generate with custom filters and force WebP
php bin/console daddl3:liip:generate-images news_pics/folder -f slider_image -f slider_image_tablet --webp

# Show available options
php bin/console daddl3:liip:generate-images --help

Command Options:

path (required): Path to image or directory relative to data root
--filters or -f: Specify filter names (can be used multiple times)
--webp or -w: Force WebP generation (overrides config parameter)
--avif: Force AVIF generation (overrides config parameter)
--all-formats: Generate all formats (JPG/PNG, WebP, AVIF) - overrides config
--all-filters or -a: Apply common filters (meta, meta_tablet, meta_mobile)

Note: If you don't specify --webp, --avif, or --all-formats, the command will use your configuration parameters (daddl3_liip_imagine_template.webp and daddl3_liip_imagine_template.avif).

Examples:

# Pre-generate all images for a news article with all formats (override config)
php bin/console daddl3:liip:generate-images news_pics/article-123 --all-filters --all-formats

# Pre-generate slider images using config settings
php bin/console daddl3:liip:generate-images news_pics/slider -f slider_image -f slider_image_tablet -f slider_image_mobile

# Pre-generate with only WebP, even if config has avif enabled
php bin/console daddl3:liip:generate-images news_pics/slider --all-filters --webp

Asynchronous Image Generation

For the same work as the command, but off the request cycle, dispatch the GenerateImagesMessage. This avoids the slow, synchronous on-demand generation that LiipImagine would otherwise perform during template rendering (which can exceed PHP's max_execution_time and make the page hang).

How it works (one job per image): GenerateImagesMessage carries the path and all filters. Its handler does no generation — it only lists the image files under the path and dispatches one GenerateImageMessage per image. Each GenerateImageMessage then builds that single image's filtered base images (all filters) plus their WebP/AVIF variants. So the worker processes one image at a time, memory stays bounded no matter how many images a folder holds, and the web request never blocks. You only ever dispatch GenerateImagesMessage.

Both messages are routed to the bundle's image transport. Make sure a worker consumes it — add a memory limit so it recycles between jobs:

php bin/console messenger:consume image --memory-limit=256M

Dispatch it — for example after creating or editing an entity that owns images:

use daddl3\LiipImagineTemplateBundle\Message\GenerateImagesMessage;
use Symfony\Component\Messenger\MessageBusInterface;

public function __construct(private readonly MessageBusInterface $messageBus) {}

// path is relative to the LiipImagine data root, just like the command
$this->messageBus->dispatch(new GenerateImagesMessage(
    path: 'news_pics/article-123',
    filters: ['meta', 'meta_tablet', 'meta_mobile', 'slider_image', 'slider_image_tablet', 'slider_image_mobile'],
    // generateWebp / generateAvif default to null = use the bundle config parameters
));

Generation is idempotent: already existing cache files are skipped, only missing/deleted ones are (re)built — so it is safe to dispatch on every save.

Message Parameters:

path (required): Path to image or directory relative to data root
filters (required): array<string> of Liip Imagine filter names to generate
generateWebp (optional, default null): true/false to force, null = use config
generateAvif (optional, default null): true/false to force, null = use config

Information

Some functions are just for my infrastructure

daddl3 / liip_imagine_template_bundle

Package info

Security

Statistics