Sylius Media Alt Text: Technical details

Technical details of the Sylius Media Alt Text plugin: architecture diagram, directory structure, tables and columns, migrations, and the integration into the admin image forms and Twig hooks.

Deutsche Version

Back to overview

Sylius Media Alt Text: Technical details

This documentation always describes the latest published version.

Architecture

graph TD
    A["Image form in the admin"] --> B["Form extension altText"]
    B --> C["AltTextManager"]
    D["Admin API PUT or POST"] --> E["AltTextPersistProcessor"]
    E --> C
    F["Backfill command"] --> C
    C --> G[("Alt text tables")]
    G --> H["AltTextResolver"]
    I["Fallback providers"] --> H
    H --> J["Twig mmd_image_alt"]
    H --> K["ImageAltTextNormalizer"]
    K --> L["Shop and Admin API"]

Every write goes through the AltTextManager, which validates languages and lengths. The AltTextResolver reads the rows of an image (remembered once per request) and applies the order requested language, default language, fallback providers.

Structure

src/
  Api/            provider of the settings endpoint
  Backfill/       AltTextBackfiller, BackfillResult
  Command/        SetupCommand, BackfillCommand
  Controller/Admin/  settings page
  DependencyInjection/  bundle extension (mapping, migrations, overrides)
  Entity/         alt text entities, registry, settings
  Form/           extension for the image forms, form types
  Manager/        AltTextManager, AltTextValidationException
  Menu/           admin menu entry and the "MMKreativ Plugins" group
  Migrations/     two Doctrine migrations
  Repository/     read access to alt texts and settings
  Resolver/       AltTextResolver, fallback providers
  Serializer/     normalizer, payload, persist processor
  Settings/       MediaAltTextSettingsProvider
  Twig/           Twig functions
config/           services.php, routes, Twig hooks
templates/        own templates and overrides
translations/     messages.de.yaml, messages.en.yaml

Tables

erDiagram
    SYLIUS_PRODUCT_IMAGE ||--o{ MMD_ALT_TEXT_PRODUCT_IMAGE : "has"
    SYLIUS_TAXON_IMAGE ||--o{ MMD_ALT_TEXT_TAXON_IMAGE : "has"
    SYLIUS_AVATAR_IMAGE ||--o{ MMD_ALT_TEXT_AVATAR_IMAGE : "has"

Table	Content
`mmd_sylius_media_alt_text_product_image`	Texts of product images
`mmd_sylius_media_alt_text_taxon_image`	Texts of category images
`mmd_sylius_media_alt_text_avatar_image`	Texts of admin avatars
`mmd_sylius_media_alt_text_settings`	The setting, exactly one row with ID 1

The three alt text tables have the same columns: id, image_id (foreign key with ON DELETE CASCADE), locale (up to 12 characters), alt (up to 255 characters) and decorative (default false). There is at most one row per image and language (unique index over image_id and locale). If you delete an image, its texts disappear with it.

The settings table has the field active (no database default). The migration creates the row with active = 1, and the entity also starts with true.

Migrations

There are two migrations in the namespace Mmd\SyliusMediaAltTextPlugin\Migrations: the first creates the three alt text tables, the second the settings table including its initial row. Both abort on databases that are not MySQL or MariaDB.

Admin integration

A form extension attaches the unmapped field altText to the image forms for product, category and avatar. If the output is turned off, the field is not added at all.
The taxon editor attaches to the Twig hooks sylius_admin.taxon.create.content.sections.form.images.image#right and sylius_admin.taxon.update.content.sections.form.images.image#right. The product form has no suitable hook, so a template override replaces the image list there.
The settings page is neither a Sylius resource nor a grid. Its Twig hooks carry the prefix sylius_admin.mmd_sylius_media_alt_text_admin_settings.
The plugin ships no JavaScript or Stimulus assets of its own.