AI alt text generator for Laravel: installation and configuration

The dockcodes/dockaccess-alt-generator-laravel package adds a DockAccess connection, the AltText facade, file validation, a queued job and Artisan commands to your Laravel application. It generates descriptions for uploads and Storage disks, including S3. Your application remains responsible for saving the result in a model and rendering the alt in its template.

Requirements

You need Laravel 12 or 13, 64-bit PHP 8.2+ with cURL and JSON. GD with JPEG, PNG, GIF and WebP support is recommended. You also need a verified DockAccess account and a site with ALT Generator enabled. The PHP library is installed as a dependency.

Step 1. Install the package

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

Laravel automatically discovers the service provider. If package discovery is disabled in your application, register Dock\AltGenerator\Laravel\AltGeneratorServiceProvider according to your Laravel version’s configuration.

Step 2. Connect the application

1. In DockAccess, open My sites, add or select a site, check its production domain and enable ALT Generator. Copy the site token.
2. Check that APP_URL points to the public application address matching the token’s domain.
3. Run the following command. Enter the site token and the DockAccess account’s email and password. The password is used for connecting and is not stored.

php artisan dockaccess-alt:connect
php artisan dockaccess-alt:status
Copy text

The command writes DOCKACCESS_ALT_KEY, DOCKACCESS_ALT_SITE_TOKEN and DOCKACCESS_ALT_SECRET to the application’s environment configuration. If configuration is cached, run php artisan config:cache after connecting. With a secrets manager, --show returns the values without writing the file; keep that output out of public logs.

--url=https://example.com overrides the application address for the connection request. A local connection does not verify a production domain: reconnect using the correct public address before going live. Use --overwrite only when intentionally replacing an existing installation; it rotates the connection secret.

Step 3. Set generation defaults

php artisan vendor:publish --tag=dockaccess-alt-config
Copy text

config/dockaccess-alt.php contains the language, tone, variants, allowed directories, HTTP and queue settings. Supply image context with the generation call. Language follows the application locale by default, tone is neutral and set_ref uses the site token. Provide the image’s specific context, up to 500 characters, and the content language rather than the administrator language.

Step 4. Generate one description

Example inside an action handling an upload form:

use Dock\AltGenerator\Laravel\Facades\AltText;
use Dock\AltGenerator\Laravel\Rules\GenuineImage;

$request->validate([
    'photo' => ['required', 'file', new GenuineImage],
]);

$result = AltText::generate($request->file('photo'), [
    'language' => 'en',
    'tone' => 'neutral',
    'context' => 'Product page: city backpack, front view',
    'variants' => 1,
]);

$alt = $result->alt()->text();
$imageUuid = $result->imageUuid();
$setUuid = $result->setUuid();
// Save the text, language and identifiers with the correct image in your database.
Copy text

GenuineImage checks actual file content locally, without generating or connecting to an account. For a Storage file use AltText::generateFromDisk('products/42.jpg', 'public'); the disk must exist in your Storage configuration. Absolute paths are restricted to allowed_directories, defaulting to storage/app/public. Avoid generating on every page render.

Step 5. Generate in the background and save the result

use Dock\AltGenerator\Laravel\Jobs\GenerateAltText;

GenerateAltText::dispatch(
    'products/42.jpg',
    'public',
    ['language' => 'en', 'context' => 'Backpack photograph'],
    ['product_id' => 42]
);
Copy text

The final array is context for the result listener; use your own record’s identifier. Configure a persistent queue connection and start a worker with php artisan queue:work. With the sync driver, the job runs within the current request.

Handle Dock\AltGenerator\Laravel\Events\AltTextGenerated. Its alt, locale, imageUuid, setUuid and context fields let you save the result against the correct image. AltTextFailed reports failures. Dispatching the job alone does not persist an alt in your model.

Allowances, verification and errors

AltText::usage() returns an object with used(), limit(), remaining(), isMonthly() and resetsAt(). Before generating, the package verifies the service and caches the answer for 300 seconds by default. A disconnected, disabled or paused service causes GeneratorUnavailableException. If the connector itself is temporarily unreachable, generation can continue; the generator service still enforces the account limit.

An exhausted allowance throws DailyLimitReachedException, including monthly plans; use getPeriod() for the window. The queued job retries temporary failures and respects the delay after a rate limit. It does not endlessly retry an exhausted allowance, rejected file or disconnected 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.

Testing and deployment checks

Use AltText::fake('Green backpack with two front pockets') and assertGenerated(1) in tests. The fake skips network access but still validates the image. In a test environment, generate one real image and check event persistence, the account’s image set and the rendered img alt. Let Blade escape the attribute text. The package does not automatically receive account edits or provide an alt editor; see the REST API guide for custom synchronization.

Disconnect with php artisan dockaccess-alt:disconnect and refresh cached configuration. Restart long-running workers when rotating connection values in a running application. See the general guide for reviewing descriptions.