Alt generator PHP library: integration with your application

The dockcodes/dockaccess-alt-generator library is the PHP client used by alt generator integrations. It validates files, prepares images for upload and returns texts and identifiers. It does not create a CMS form, save alts in your database or register a synchronization endpoint.

Requirements and installation

You need 64-bit PHP 7.4+ with cURL and JSON. GD with JPEG, PNG, GIF and WebP support is recommended. Install the package from the Composer repository in which it is available to your project:

composer require dockcodes/dockaccess-alt-generator
Copy text

For a framework application, use the dedicated Laravel or Symfony package. This guide covers the standalone PHP library without framework-specific services.

Connection and account key

In your verified DockAccess account, add or select a site, check its domain and enable ALT Generator. Copy the site token. The connection client, available since version 1.1, obtains the account key and secret:

use Dock\AltGenerator\Config;
use Dock\AltGenerator\Connection\ConnectionClient;
use Dock\AltGenerator\Connection\ConnectRequest;

$connector = new ConnectionClient(Config::anonymous());
$connection = $connector->connect(ConnectRequest::create(
    $siteToken,
    $email,
    $password,
    'php',
    'https://example.com'
));

$accountKey = $connection->accountKey()->reveal();
$connectionSecret = $connection->secret()->reveal();
// Store the key, secret and site token in protected server configuration; do not store the password.
Copy text

$email and $password come from secure connection handling in your application; do not hardcode them. The application address must match the token’s domain. Before generating, check $connector->verify($siteToken, new Dock\AltGenerator\Secret($connectionSecret))->isActive(). After disconnection, the client throws ConnectionException; stop using the old connection. See the API guide for the protocol.

Generate one description

require __DIR__ . '/vendor/autoload.php';

use Dock\AltGenerator\AltGenerator;
use Dock\AltGenerator\Config;
use Dock\AltGenerator\GenerateOptions;
use Dock\AltGenerator\Image\ImageSource;
use Dock\AltGenerator\Tone;

$accountKey = getenv('DOCKACCESS_ALT_KEY');
$siteToken = getenv('DOCKACCESS_ALT_SITE_TOKEN');
if (!$accountKey || !$siteToken) {
    throw new RuntimeException('Missing DockAccess configuration');
}

$generator = new AltGenerator(Config::create($accountKey));
$uploadsDirectory = __DIR__ . '/public/uploads';
$image = ImageSource::fromFile(
    $uploadsDirectory . '/backpack.jpg',
    [$uploadsDirectory]
);
$options = GenerateOptions::create()
    ->withLanguage('en_GB')
    ->withTone(Tone::NEUTRAL)
    ->withContext('Product page: city backpack, front view')
    ->withVariants(1)
    ->withSetRef($siteToken);

$result = $generator->generate($image, $options);
$alt = $result->alt()->text();
$imageUuid = $result->imageUuid();
$setUuid = $result->setUuid();
// Save $alt, language, $imageUuid and $setUuid with the local image.
echo htmlspecialchars($alt, ENT_QUOTES, 'UTF-8');
Copy text

Allow only the narrowest directory holding your images. Do not allow the entire filesystem or an unchecked user-provided path. In Laravel use the media disk’s real path, such as Storage::disk('public')->path(''); in Symfony use your configured upload directory. Run generation in a job or an editor action, rather than on every page view.

Formats and options

The client recognizes actual content and refuses invalid or unsupported files before uploading. The prepared image is re-encoded or stripped. Do not assume identical format support to the online tool: the library refuses SVG and some formats need an appropriate GD decoder. Start with JPEG, PNG or WebP.

withLanguage() accepts language codes and locales, withContext() up to 500 characters and withVariants() 1–3 alternatives. Use one alternative when the CMS stores one alt. To validate and prepare without generating, use $generator->prepare($image).

Errors and batches

• InvalidImageException: correct the file or path; nothing was uploaded.
• AuthenticationException: check the key and connection.
• DailyLimitReachedException: stop the batch. The exception name is historical; use getPeriod() to identify a monthly allowance.
• RateLimitedException: defer the job by getRetryAfter() seconds.
• TransportException: retry automatically only when isRetryable() confirms the request did not reach the service; otherwise check the set first.

$generator->usage() exposes usage, limit and remaining allowance, plus period(), isMonthly() and resetsAt(). An older service version may not provide a renewal time. Do not convert a monthly allowance into a fixed daily amount.

Storage and synchronization

Store plain text with the language and local image identifier. Apply HTML escaping when rendering the alt attribute. Editorial changes and signed incoming updates require implementing the synchronization contract; the generation library alone does not add those features to your application.

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.

Before production, try one image and review the result using the user guide.