PHP

Именованные аргументы, понятные исключения, повторы при перегрузке. Без сторонних зависимостей — нужно только расширение curl.

Установка#

composer require pdfapi/pdfapi

Ключ берётся из переменной окружения PDFAPI_KEY — выпустите его в кабинете:

export PDFAPI_KEY=pdf_live_...

Первый PDF#

use PdfApi\Client;

$client = new Client();   // ключ из PDFAPI_KEY

$pdf = $client->html('<h1>Счёт №42</h1>', marginTop: '20mm');
$pdf->save('invoice.pdf');

echo $pdf->pages, ' стр., осталось ', $pdf->quota?->remaining;

Методы#

У каждого метода есть timeout: — секунд на этот вызов.

Параметры страницы#

Именованные аргументы, все необязательные. Что они значат — в разделе Параметры страницы.

$pdf = $client->url('https://example.com/report', landscape: true, waitDelay: '1s');

Размер — число и единица pt, px, in, mm, cm или pc без пробела. '20' и '20 mm' вызовут InvalidArgumentException сразу, без запроса к API.

Документы Office#

$pdf = $client->office('report.docx');                                    // с диска
$pdf = $client->officeFromString($data, 'table.xlsx', landscape: true);   // из памяти — имя с расширением

Файл — до 3,7 МБ: в base64 он вырастает на треть, а тело запроса ограничено 5 МБ. Библиотека проверяет, что файл — настоящий ZIP-архив, поэтому старый .doc или PDF, переименованный в .docx, отклоняется до отправки.

Результат#

Result:

• content — байты PDF, строка;
• pages — сколько страниц списано;
• quota — Quota с полями limit, used и remaining после этой конвертации;
• save($path) — записать в файл и вернуть путь.

save пишет атомарно: сначала во временный файл рядом, потом переименовывает поверх. Оборвётся запись или кончится место — останется прежний файл, а не обрезанный PDF.

Аккаунт и квота#

$me = $client->me();
echo "{$me->plan}: осталось {$me->pagesRemaining} из {$me->pagesLimit}, обнулится ",
    $me->periodEnd?->format(DATE_ATOM) ?? 'неизвестно когда', "\n";

Account: userId, plan, periodStart, periodEnd (DateTimeImmutable в UTC или null), pagesUsed, pagesLimit, pagesRemaining, requestsPerSecond, burst. Запрос страниц не тратит. Как встроить проверку в cron — в руководстве Контроль квоты.

Ошибки#

Все ошибки API — наследники PdfApi\Exception\PdfApiException с полями errorCode, status и сообщением по-русски.

use PdfApi\Exception\{QuotaExceededException, RateLimitException, RenderException, PdfApiException};

try {
    $pdf = $client->html($html);
} catch (QuotaExceededException $e) {
    // страницы кончились
} catch (RateLimitException $e) {
    sleep((int) ceil($e->retryAfter ?? 1));
} catch (RenderException $e) {          // и RenderTimeoutException тоже
    // разметка не отрендерилась
} catch (PdfApiException $e) {
    error_log("{$e->errorCode} {$e->status}: {$e->getMessage()}");
}

Неверные аргументы — пустой HTML, адрес без https://, файл .pdf вместо .docx — \InvalidArgumentException до запроса; лимит частоты на них не тратится. Все коды API — в разделе Ошибки и повторы.

Повторы#

Библиотека сама повторяет запрос, когда это безопасно, — по умолчанию до двух раз (maxRetries):

• 429 — через Retry-After, но не дольше минуты;
• 503 или нет соединения — первый повтор примерно через 0,5 секунды, второй — примерно через 1 секунду.

Настройки клиента#

$client = new Client(
    apiKey: 'pdf_live_...',               // иначе PDFAPI_KEY
    baseUrl: 'https://pdfapi.ru/api',     // иначе PDFAPI_BASE_URL
    timeout: 40.0,                        // секунд на запрос
    maxRetries: 2,
    transport: $myTransport,              // свой PdfApi\Http\Transport: прокси, PSR-18
);

• Неверные настройки — таймаут не больше нуля или отрицательное число повторов — \InvalidArgumentException сразу.
• Ключ не утекает — его нет в var_dump и print_r клиента, а в трассировках исключений он помечен #[\SensitiveParameter].

PDF в веб-приложении#

PDF уже в памяти — отдавайте байты, на диск сохранять незачем:

return response($pdf->content, 200, [
    'Content-Type' => 'application/pdf',
    'Content-Disposition' => 'inline; filename="invoice.pdf"',
]);

Данные пользователя в HTML — только через htmlspecialchars или шаблоны с автоэкранированием (Blade, Twig), иначе это HTML-инъекция в документ — см. Безопасность и данные.

Примеры#

В папке examples/ библиотеки; запуск — composer install && PDFAPI_KEY=pdf_live_... php examples/<файл>.