Events

ModifyProcessingInstructionsEvent

\LIA\LiaImageserver\Event\ModifyProcessingInstructionsEvent fires once per rendering call: before the processing instructions are transformed or routed to a delivery backend, and on every exit path (image server URL, skip, passThrough, local core processing). Listeners can modify the instruction set, for example add an abstract overlay instruction that delivery backends map to their own mechanism, see The overlay contract.

The event exposes:

Method	Description
`getImage()`	The (unwrapped) `FileInterface` being rendered.
`getInstructions()` / `setInstructions(array)`	The processing instructions (read / replace).
`getContext()`	Read-only opaque context from the `liaContext` ViewHelper argument. `_maxRenderWidth` carries the largest requested width of the call.

Important

Listeners MUST be idempotent (set or overwrite keys, never append): the event can fire more than once for the same rendering. The liaContext key itself never reaches a backend. It is stripped before dispatch and only available via getContext().

EXT:my_extension/Classes/EventListener/AddOverlayToProcessingInstructions.php

<?php

declare(strict_types=1);

namespace Vendor\MyExtension\EventListener;

use LIA\LiaImageserver\Event\ModifyProcessingInstructionsEvent;
use LIA\LiaImageserver\Processing\Overlay;
use LIA\LiaImageserver\Processing\OverlayAlignment;
use TYPO3\CMS\Core\Attribute\AsEventListener;

#[AsEventListener]
final class AddOverlayToProcessingInstructions
{
    public function __invoke(ModifyProcessingInstructionsEvent $event): void
    {
        if (($event->getContext()['aiBadge'] ?? null) === '0') {
            return;
        }
        $instructions = $event->getInstructions();
        $instructions[Overlay::INSTRUCTION_NAME] = (new Overlay(
            imageIdentifier: '/_badges/example.png',
            alignment: OverlayAlignment::BottomLeft,
        ))->toInstruction();
        $event->setInstructions($instructions);
    }
}

Register custom instruction classes

Every key of the instruction set is processed by an Instruction class. The defaults cover width, height, crop, maxWidth and maxHeight; unknown keys are passed through. Register a class for a custom key in ext_localconf.php. External registrations win over the defaults.

EXT:my_extension/ext_localconf.php

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['lia_imageserver']['instructionRegister']['myKey']
    = \Vendor\MyExtension\Processing\MyInstruction::class;