Biblioteka PHP generatora altów: integracja z aplikacją

Biblioteka dockcodes/dockaccess-alt-generator jest klientem PHP używanym przez integracje generatora altów. Sprawdza pliki, przygotowuje obraz do wysłania i zwraca teksty oraz identyfikatory. Nie tworzy formularza CMS-a, nie zapisuje automatycznie altu w Twojej bazie i nie rejestruje endpointu synchronizacji.

Wymagania i instalacja

Wymagane są 64-bitowe PHP 7.4+ oraz rozszerzenia cURL i JSON. Zalecane jest GD z obsługą JPEG, PNG, GIF i WebP. Pakiet instaluj z repozytorium Composer, w którym jest udostępniony Twojemu projektowi:

composer require dockcodes/dockaccess-alt-generator
Skopiuj tekst

W aplikacji opartej na frameworku wybierz gotowy pakiet dla Laravel albo Symfony. Ten poradnik dotyczy samodzielnej biblioteki PHP, bez mechanizmów konkretnego frameworka.

Połączenie i klucz konta

Na zweryfikowanym koncie DockAccess dodaj lub wybierz stronę, sprawdź jej domenę i włącz Generator ALT. Skopiuj token strony. Klient połączenia dostępny od wersji 1.1 pozwala uzyskać klucz konta i sekret:

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();
// Zapisz klucz, sekret i token w chronionej konfiguracji serwera; nie zapisuj hasła.
Skopiuj tekst

Zmienne $email i $password pochodzą z bezpiecznej obsługi połączenia w Twojej aplikacji; nie wpisuj ich na stałe w kodzie. Adres aplikacji musi pasować do domeny tokenu. Przed generowaniem sprawdzaj $connector->verify($siteToken, new Dock\AltGenerator\Secret($connectionSecret))->isActive(). Po rozłączeniu klient zgłasza ConnectionException; nie kontynuuj pracy na starym połączeniu. Szczegóły protokołu opisuje instrukcja API.

Generowanie jednego opisu

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('pl_PL')
    ->withTone(Tone::NEUTRAL)
    ->withContext('Karta produktu: plecak miejski, widok z przodu')
    ->withVariants(1)
    ->withSetRef($siteToken);

$result = $generator->generate($image, $options);
$alt = $result->alt()->text();
$imageUuid = $result->imageUuid();
$setUuid = $result->setUuid();
// Zapisz $alt, język, $imageUuid i $setUuid przy lokalnym obrazie.
echo htmlspecialchars($alt, ENT_QUOTES, 'UTF-8');
Skopiuj tekst

Wskaż najwęższy katalog zawierający obrazy. Nie dopuszczaj całego systemu plików ani ścieżki pobranej bez sprawdzenia od użytkownika. Dla Laravel użyj rzeczywistej ścieżki dysku mediów, np. Storage::disk('public')->path(''), a dla Symfony skonfigurowanego katalogu uploadów. Generowanie uruchamiaj w zadaniu lub akcji redaktora, nie przy każdym wyświetleniu strony.

Formaty i ustawienia

Klient rozpoznaje rzeczywistą zawartość i odrzuca nieprawidłowe lub nieobsługiwane pliki przed wysłaniem. Przygotowany obraz jest ponownie kodowany lub oczyszczany. Nie zakładaj identycznej obsługi formatów jak w narzędziu online: biblioteka odrzuca SVG, a część formatów wymaga odpowiedniego dekodera GD. Zacznij od JPEG, PNG lub WebP.

withLanguage() obsługuje kody języka i locale, withContext() maksymalnie 500 znaków, a withVariants() od 1 do 3. Jeżeli zapisujesz jeden alt w CMS-ie, użyj jednej propozycji. Do samego sprawdzenia i przygotowania pliku bez generowania służy $generator->prepare($image).

Obsługa błędów i partii

• InvalidImageException: popraw plik lub jego ścieżkę; nic nie zostało wysłane.
• AuthenticationException: sprawdź klucz i połączenie.
• DailyLimitReachedException: zatrzymaj partię. Nazwa wyjątku jest historyczna; limit może być miesięczny, co sprawdzisz przez getPeriod().
• RateLimitedException: przełóż zadanie o getRetryAfter() sekund.
• TransportException: automatycznie ponawiaj tylko wtedy, gdy isRetryable() potwierdza, że żądanie nie dotarło do usługi; w przeciwnym razie najpierw sprawdź zestaw.

$generator->usage() udostępnia zużycie, limit i pozostałą pulę oraz period(), isMonthly() i resetsAt(). Starsza wersja usługi może nie podawać terminu odnowienia. Nie przeliczaj miesięcznej puli na sztywną stawkę dzienną.

Zapis i synchronizacja

Zapisuj tekst jako zwykły tekst z językiem i lokalnym identyfikatorem obrazu. Przy renderowaniu atrybutu alt stosuj escapowanie HTML. Zmiany redakcyjne i odbiór podpisanych aktualizacji wymagają implementacji kontraktu synchronizacji; sama biblioteka generująca nie dodaje tej funkcji do aplikacji.

Standardowy plan bezpłatny obejmuje 10 generowań opisów obrazów na dobę UTC i 1 stronę z włączonym Generatorem ALT. Gotowe integracje CMS działają również w planie bezpłatnym.

Płatne plany generatora altów mają limit na miesiąc kalendarzowy, dostępny w całości, bez podziału na dni. Limit stron jest niezależny od limitu generowania. Aktualny limit i wykorzystanie sprawdzisz na pulpicie konta. Sprawdź aktualne plany

Limit generowania jest wspólny dla całego konta: narzędzie online, połączone strony i API korzystają z tej samej puli. Ponowne wygenerowanie opisu też zużywa limit; ręczna edycja zapisanego tekstu nie generuje nowego opisu.

Limit dobowy odnawia się o 00:00 UTC, a miesięczny o 00:00 UTC pierwszego dnia kolejnego miesiąca kalendarzowego. Nie zależy to od daty płatności za subskrypcję. W Polsce 00:00 UTC przypada o 01:00 zimą i o 02:00 latem. Usługa zużycia zwraca dokładny termin odnowienia w polu resets_at.

Generowanie zbiorcze przetwarza obrazy kolejno. Po wyczerpaniu limitu konta gotowe opisy pozostają zapisane, a partia się zatrzymuje. Pozostałe obrazy przetwórz po odnowieniu limitu lub zmianie planu. Chwilowy limit częstotliwości powoduje oczekiwanie i ponowienie próby. Starsze wersje wtyczek mogą opisywać miesięczny licznik jako „dzienny”; sprawdzaj okres i termin odnowienia na koncie DockAccess.

Przed uruchomieniem produkcyjnym przeprowadź próbę na jednym obrazie i sprawdź wynik według poradnika obsługi.