---
title: "Events"
manual: "LIA Imageserver"
version: "2.3"
permalink: "https://docs.typo3.org/permalink/lia/lia_imageserver:developer-events@2.3"
source: "Developer/Events.rst"
modified: "2026-09-16T09:22:57+00:00"
---

# 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](https://docs.typo3.org/permalink/lia/lia_imageserver:developer-overlay@2.3).

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
<?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**

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