PHP

The PHP library is spinningcatstudios/lingara on Packagist. It needs PHP 8.2 or later and talks HTTP through PSR-18, so it works with Symfony HttpClient, Guzzle or a client of your own.

How it reads

Calls are synchronous. The only way to cancel is to stop reading: leave the foreach, or call close() on the stream.
A stream is read with foreach, once. Match each event with instanceof.
Errors implement Lingara\Exception\LingaraException. On an API error, errorCode() is the stable code and getCode() is the HTTP status; retryAfter() is a number of seconds, or null.
Choose the HTTP stack with the http argument. With Guzzle, streams need allow_url_fopen enabled. With a PSR-18 client of your own, streaming and timeouts are yours to configure.
Under PHP-FPM every worker starts empty, so give the client a PSR-16 tokenCache. Without one, each worker exchanges its own token, and the token endpoint’s hourly limit is shared by all of them.

The samples below install the package, create a client, stream a vocabulary list and handle an error.

PHP

composer require spinningcatstudios/lingara:0.1.0-alpha.6

PHP

use Lingara\Client;

$client = new Client(clientId: $clientId, clientSecret: $clientSecret);

PHP

use Lingara\Model\VocabRequest;
use Lingara\Stream\GenerateVocabularyEvent;

$request = new VocabRequest(['level' => 2, 'source_lang' => 'en', 'target_lang' => 'zh', 'count' => 8]);
foreach ($client->generateVocabulary($request) as $event) {
    if ($event instanceof GenerateVocabularyEvent\Item) {
        echo $event->data->getWord(), ': ', $event->data->getTranslation(), "\n";
    }
}

PHP

use Lingara\Exception\ApiException;
use Lingara\Exception\LingaraException;
use Lingara\Exception\MaintenanceException;
use Lingara\Exception\OAuthException;
use Lingara\Exception\TransportException;

try {
    $client->getUsage();
} catch (LingaraException $e) {
    if ($e instanceof ApiException) {
        // A refusal from the API: status, errorCode (stable) and message (localised).
        echo $e->status(), ' ', $e->errorCode(), ': ', $e->getMessage(), "\n";
        echo 'retry after: ', $e->retryAfter() ?? 'not given', "\n";
    } elseif ($e instanceof OAuthException) {
        // The token endpoint refused the credentials or the scopes.
        echo $e->status(), ' ', $e->error(), ': ', $e->description(), "\n";
    } elseif ($e instanceof MaintenanceException) {
        echo 'under maintenance; retry after: ', $e->retryAfter() ?? 'not given', "\n";
    } elseif ($e instanceof TransportException) {
        // No usable answer: connect, tls, reset, timeout, and so on.
        echo 'transport: ', $e->kind()->value, "\n";
    }
}

PHP

How it reads

What this page wraps