Developer corner

Architecture overview

ai3-alttext follows the capability pattern introduced by wegewerk/ai3_core . The central pieces are:

Class	Responsibility
`ZakAiAlttext`	Extends `AbstractZakAiEndpoint`; resizes the image and calls the `/alttexts` REST endpoint
`AlttextCapability`	Registers the alt text capability under the key `alttext` so the core task queue can dispatch jobs to it
`AlttextController` (Ajax)	Manages the generation task lifecycle: create, poll status, review, and select a suggestion
`FilelistController` (Ajax)	Lists files in a folder and saves approved alt texts back to `sys_file_metadata`
`FolderController` (Ajax)	Lists sub-folders and bulk-accepts suggestions recursively
`Ai3AlttextAddToBatch`	FormEngine `AbstractNode` that renders the batch button in the file metadata edit form
`AfterFormEnginePageInitializedEventListener`	Loads the extension language labels whenever a FormEngine page is initialised

ZakAiAlttext API class

Wegewerk\Ai3Alttext\Api\ZakAiAlttext extends Wegewerk\Ai3Core\Api\AbstractZakAiEndpoint (implementing ZakAiEndpointInterface) and exposes a single public method:

Classes/Api/ZakAiAlttext.php (signature)

public function generate(array $options = []): string

The method accepts an options array:

imagePath (string, required): Absolute local path to the image file.
caption (string, optional): Contextual text / caption for the image.
language (string, optional): Target language code.
previous (mixed, optional): Previous suggestions to avoid duplication.

The generation flow:

Verifies the image file exists on disk (in preparePayload()).
Resizes the image to a maximum of 512 × 512 px using ImageService and ImageProcessingService to keep API payload sizes small.
Base64-encodes the resized image into the image payload field and POSTs it to the /alttexts endpoint via ZakAiClient::postJson().
Returns the alttext string from the API response, or an empty string if the API reports an error.

Ajax routes

All Ajax endpoints are registered in Configuration/Backend/AjaxRoutes.php:

Route identifier	Target
`ai3_alttext_generation_create_task`	`AlttextController::addAlttextGenerationTaskAction`
`ai3_alttext_generation_review`	`AlttextController::reviewAlttextAction`
`ai3_alttext_generation_select`	`AlttextController::selectAlttextAction`
`ai3_alttext_generation_status`	`AlttextController::checkAlttextGenerationStatusAction`
`ai3_filelist`	`FilelistController::listFiles`
`ai3_filelist_save_file`	`FilelistController::saveFile`
`ai3_filelist_create_task_alttext`	`FilelistController::addAlttextTaskForFile`
`ai3_folders`	`FolderController::listFolders`
`ai3_folders_acceptAll_recursive`	`FolderController::acceptAllSuggestionsRecursive`

Capability registration

AlttextCapability is registered as a DI-tagged service so that the wegewerk/ai3_core capability registry picks it up automatically:

Configuration/Services.yaml

Wegewerk\Ai3Alttext\Domain\Capabilities\AlttextCapability:
    autowire: false
    arguments:
        $key: 'alttext'
        $title: 'Alt Text'
        $endpoint: '@Wegewerk\Ai3Alttext\Api\ZakAiAlttext'
    tags:
        - name: ai3.capability

FormEngine field control

The field control is registered as a custom FormEngine node in ext_localconf.php:

ext_localconf.php

$GLOBALS['TYPO3_CONF_VARS']['SYS']['formEngine']['nodeRegistry'][1759225979] = [
    'nodeName' => 'ai3AlttextAddToBatch',
    'priority' => 30,
    'class' => \Wegewerk\Ai3Alttext\FormEngine\FieldControl\Ai3AlttextAddToBatch::class,
];

The TCA override in Configuration/TCA/Overrides/sys_file_metadata.php attaches this node to the alternative field of sys_file_metadata as a fieldControl.

Event listener

AfterFormEnginePageInitializedEventListener listens to AfterFormEnginePageInitializedEvent and injects the extension language labels into the page renderer so that the JavaScript modules can use them via the TYPO3 inline label API.