AI alt text generator for Symfony: installation and configuration

The dockcodes/dockaccess-alt-generator-symfony package provides a bundle with a DockAccess account connection, AltText service, image validation, Messenger support and console commands. It accepts local files, uploads and Flysystem storages. Your application must save the text against the correct entity and render it as alt.

Requirements

You need Symfony 6.4, 7.4 or 8, and 64-bit PHP 8.2+ with cURL and JSON. PHP must also satisfy the requirements of your chosen Symfony version. GD is recommended. Optional features require their corresponding packages: Validator for validation, Messenger for background jobs and Flysystem for its storages.

Step 1. Install and register the bundle

composer require dockcodes/dockaccess-alt-generator-symfony
Copy text

Check registration in config/bundles.php. If Symfony Flex has not registered the bundle automatically, add this entry to the returned array:

Dock\AltGenerator\Symfony\DockAccessAltGeneratorBundle::class => ['all' => true],
Copy text

Step 2. Connect the application

1. In your verified DockAccess account, add or select a site, check its domain and enable ALT Generator. Copy the site token.
2. Configure the public application address through framework.router.default_uri or pass --url when connecting.
3. Run the command and enter the token and your DockAccess email and password. The password is used for connecting and is not stored.

php bin/console dockaccess:alt:connect --url=https://example.com
php bin/console dockaccess:alt:status
Copy text

The command saves DOCKACCESS_ALT_KEY, DOCKACCESS_ALT_SITE_TOKEN and DOCKACCESS_ALT_SECRET in local environment configuration. In production you can use environment variables or Symfony’s secrets vault; --show returns the values without writing the file. Keep that output out of public logs. Refresh the environment and restart long-running Messenger processes after rotating secrets.

Connect the correct domain before production. A local address does not verify a production domain. --overwrite replaces an existing connection and rotates its secret.

Step 3. Configure the bundle

# config/packages/dockaccess_alt_generator.yaml
dockaccess_alt_generator:
    defaults:
        language: en
        tone: neutral
        variants: 1
    allowed_directories:
        - '%kernel.project_dir%/public/uploads'
    verify:
        enabled: true
        ttl: 300
Copy text

Without an explicit language, the package uses the request locale and then the kernel default locale. set_ref defaults to the site token. Run php bin/console config:dump-reference dockaccess_alt_generator for the complete schema. Allow only directories that actually contain images.

Step 4. Generate through the service

Inject Dock\AltGenerator\Symfony\AltText into a controller or your own service. Example controller action:

use Dock\AltGenerator\Symfony\AltText;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\File\UploadedFile;

final class GenerateImageAltAction
{
    public function __invoke(Request $request, AltText $altText): JsonResponse
    {
        $file = $request->files->get('photo');
        if (!$file instanceof UploadedFile) {
            return new JsonResponse(['error' => 'Image required'], 422);
        }
        $result = $altText->generate($file, [
            'language' => 'en',
            'context' => 'Product page: city backpack',
            'variants' => 1,
        ]);
        // Save the result and identifiers against the correct image in your database.
        return new JsonResponse(['alt' => $result->alt()->text()]);
    }
}
Copy text

Add routing, authorization and persistence appropriate to your application. The description is plain text; let Twig escape it when rendering the alt attribute. Use the Dock\AltGenerator\Symfony\Validator\GenuineImage constraint for form validation. It checks actual file content without sending it to AI.

For Flysystem storage, call $altText->generateFromFilesystem($storage, 'products/42.jpg'), where $storage is your configured FilesystemOperator. S3 files do not need to be publicly accessible: the application reads and uploads them to the generator.

Step 5. Generate with Messenger

use Dock\AltGenerator\Symfony\Message\GenerateAltText;

$bus->dispatch(new GenerateAltText(
    'products/42.jpg',
    'default.storage',
    ['language' => 'en', 'context' => 'Backpack photograph'],
    ['product_id' => 42]
));
Copy text

default.storage is an example Flysystem service ID; replace it with yours. Tag the storage with flysystem.storage or list it in dockaccess_alt_generator.storages. Passing null instead of a storage means an absolute path inside an allowed directory.

# config/packages/messenger.yaml
framework:
    messenger:
        routing:
            Dock\AltGenerator\Symfony\Message\GenerateAltText: async
Copy text

Configure the async transport and run php bin/console messenger:consume async. Handle Dock\AltGenerator\Symfony\Event\AltTextGeneratedEvent: save alt, locale, imageUuid and setUuid against the record identified in context. Dispatching a message alone does not save a description. AltTextFailedEvent reports a final failure.

Allowances and diagnosis

$altText->usage() exposes used(), limit(), remaining(), isMonthly() and resetsAt(). The bundle verifies service state before generation and caches the result for 300 seconds by default. A disconnected, disabled or paused service causes GeneratorUnavailableException. A temporary connector outage can leave generation available; the generator also enforces account limits.

An exhausted allowance, rejected image or disconnected account requires correcting the cause. Messenger can retry temporary failures. On Symfony 7.4 and 8, rate-limit handling supplies the requested delay; on Symfony 6.4, adapt the transport’s retry strategy to Retry-After.

The standard free allowance is 10 image generations per UTC day and 1 site with ALT Generator enabled. Ready-made CMS integrations are available on the free plan.

Paid ALT generator plans use a calendar-month allowance, available in full without a daily split. The site allowance is separate from the generation allowance. Your current allowance and usage are shown in the account dashboard. Check current plans

The generation allowance is shared across the account: the online tool, connected sites and API use the same pool. Generating again also uses the allowance; editing a saved text by hand does not generate a new description.

Daily usage resets at 00:00 UTC; monthly usage resets at 00:00 UTC on the first day of the next calendar month. This is independent of the subscription payment date. In Poland, 00:00 UTC is 01:00 in winter and 02:00 in summer. The usage service returns the exact renewal time as resets_at.

Bulk generation processes images in sequence. When the account allowance is exhausted, completed descriptions stay saved and the batch stops. Continue with the remaining images after renewal or a plan upgrade. A temporary request-rate limit causes a wait and retry instead. Older plugin versions may label a monthly counter “daily”; use the period and renewal time shown in your DockAccess account.

Deployment checks and disconnecting

Check the connection, one image, event persistence, the account’s image set and rendered HTML. Application tests can replace Dock\AltGenerator\Http\TransportInterface with Dock\AltGenerator\Symfony\Testing\FakeTransport; image validation still runs. The bundle does not automatically create an alt editor or receiver for account edits. See the REST API guide for custom synchronization.

Disconnect with php bin/console dockaccess:alt:disconnect or through the DockAccess account. See the general guide for writing useful descriptions.