Перейти к содержанию
13 минут чтения
Тема: Практика Laravel · PDF · Telegram Bot API

Как сформировать PDF-документ в Laravel и отправить его через Telegram-бота

Для примера сервис принимает заявку на консультацию и отправляет клиенту PDF с номером, датой и темой обращения. Сначала подготовим отдельный шаблон для печати и проверим кириллицу. Затем воркер соберёт PDF и отправит его в подтверждённый личный чат.

Устанавливаем генератор и готовим данные

Для Blade-шаблона используем barryvdh/laravel-dompdf. Пример рассчитан на Laravel 13 с PHP 8.3+ и обычным воркером Laravel. Установите пакет в приложении, где будет генерироваться документ.

Bash · установка пакета
composer require barryvdh/laravel-dompdf

После регистрации заявки сохраните снимок для PDF. В нашем примере это номер, дата в часовом поясе клиента, имя и тема. Снимок нужен, чтобы повторная генерация по той же версии заявки давала те же данные. Если заявка изменилась и клиенту нужно новое подтверждение, создайте отдельную версию документа.

Числа, даты и статусы форматируйте до передачи в шаблон. Для коммерческого предложения подготовьте строки с количеством, ценой, валютой и итогами из серверного расчёта. Данные из полей клиента подставляйте через экранирование Blade {{ … }}. Логотипы и шрифты поставляйте с приложением, а загрузку внешних ресурсов Dompdf оставьте выключенной.

Определяем состав и версию документа

Подтверждение заявки должно отвечать на несколько вопросов. Какую заявку приняли, кто её отправил, когда она создана и что произойдёт дальше. Добавьте контакт для уточнений и понятную подпись документа. Если время показано в часовом поясе сервиса, укажите его рядом с датой.

Для коммерческого предложения потребуется более строгий набор данных. Сохраните название каждой позиции, единицу измерения, количество, цену и сумму строки, а также валюту, условия и срок действия предложения. Округляйте деньги в одном месте на сервере. Шаблон получает готовые значения для отображения.

Например, первая версия предложения содержит два монитора по согласованной цене. Через неделю цена каталога изменилась. При повторном скачивании первой версии клиент должен получить прежние условия. Новую цену оформляйте новой версией с собственной датой и номером.

Храните номер версии рядом со снимком, ID адресата и состоянием отправки. Это позволит восстановить документ после сбоя без обращения к изменившимся данным каталога. При изменении самого шаблона учитывайте и его версию, если требуется воспроизводить внешний вид старых документов.

Делаем отдельный Blade-шаблон для PDF

Сохраните шаблон в resources/views/pdf/application-confirmation.blade.php. Укажите UTF-8 и DejaVu Sans: Dompdf поставляется с этим семейством, в котором есть кириллица. Обычный шаблон кабинета часто использует CSS, который Dompdf обрабатывает иначе. Для документа используйте простой блоковый поток и таблицы.

Blade · application-confirmation.blade.php
<!doctype html>
<html lang="ru">
<head>
    <meta charset="UTF-8">
    <title>Подтверждение заявки</title>
    <style>
        @page { margin: 18mm; }
        body { font: 11pt "DejaVu Sans", sans-serif; color: #18212c; }
        h1 { font-size: 18pt; margin: 0 0 12pt; }
        h2 { font-size: 12pt; page-break-after: avoid; }
        table { width: 100%; border-collapse: collapse; }
        th, td { padding: 6pt; border-bottom: 1px solid #d6dde5; }
        th { width: 28%; text-align: left; }
        td, .subject { overflow-wrap: break-word; }
        .subject { white-space: pre-wrap; }
    </style>
</head>
<body>
    <h1>Подтверждение заявки</h1>
    <table>
        <tr><th>Номер</th><td>{{ $number }}</td></tr>
        <tr><th>Дата</th><td>{{ $submittedAt }}</td></tr>
        <tr><th>Клиент</th><td>{{ $customerName }}</td></tr>
    </table>
    <h2>Тема обращения</h2>
    <p class="subject">{{ $subject }}</p>
</body>
</html>

Длинная тема вынесена из таблицы: Dompdf размещает строку таблицы на одной странице. Для многостраничного предложения используйте thead и короткие строки, а подробные условия выводите отдельными блоками. Проверяйте переносы по готовому PDF. Если нужна фирменная гарнитура, проверьте лицензию на встраивание, подготовьте локальные начертания и укажите их через @font-face. Каталог кэша шрифтов должен быть доступен пользователю воркера для записи.

Сначала проверяем документ на фиктивной заявке

Пока настраиваете шаблон, соберите PDF локально с помощью команды Tinker, если она установлена. Этот пример записывает файл во внутренний каталог storage/app. Используйте вымышленные данные.

PHP · команда для Tinker
use Barryvdh\DomPDF\Facade\Pdf;

$snapshot = [
    'number' => 'K-142',
    'submittedAt' => '10 ноября 2026, 14:30 МСК',
    'customerName' => 'Алёна Ковалёва',
    'subject' => "Консультация по подключению.\nПросьба связаться после 16:00.",
];

Pdf::loadView('pdf.application-confirmation', $snapshot)
    ->setPaper('a4')
    ->save(storage_path('app/preview-application.pdf'));

Откройте документ и скопируйте из него имя в текстовый редактор. Так можно заметить проблемы со шрифтом и кодировкой. Прогоните длинную тему, длинное слово и пустые необязательные поля. Сверьте поля, переносы, размер страницы и итоговый объём файла. Для коммерческого предложения добавьте тест с позициями на две страницы и проверьте читаемость итогов.

PDF-подтверждение заявки K-142: дата, имя Алёна Ковалёва и тема обращения с переносом строки.
PDF-подтверждение заявки K-142: дата, имя Алёна Ковалёва и тема обращения с переносом строки.
Результат генерации Dompdf из Blade-шаблона и данных Tinker из статьи. Показаны фрагменты PDF; на телефоне реквизиты и тема увеличены для чтения.

Исправляем проблемы шрифта и разбиения на страницы

Если вместо русских букв появились квадраты, сначала проверьте UTF-8 в исходных данных и имя выбранного шрифта. Затем убедитесь, что шрифт доступен процессу генерации и содержит нужные символы. Проверьте обычное и полужирное начертания отдельно. Эмодзи из имени клиента тоже требуют поддержки шрифта, поэтому их отображение нужно проверить на реальном PDF.

Если строка таблицы уходит за нижнюю границу, сократите содержимое ячеек. Длинное описание позиции вынесите под таблицу или на отдельную страницу. Запрет разрыва для большого блока может только переместить его целиком и оставить пустое место. Используйте page-break-inside: avoid для небольшого блока итогов, который заведомо помещается на страницу.

Если текст налезает на поля, проверьте ширину таблицы, отступы ячеек и длинные последовательности без пробелов. Для телефона, адреса и артикула задайте реалистичные тестовые значения. Проверяйте не только пример из трёх строк, но и максимально длинную заявку, которую разрешает форма.

Если пропал логотип, проверьте локальный путь и ограничения доступа Dompdf к файлам. Изображение должно входить в набор ресурсов приложения. Укажите его размеры в шаблоне, чтобы крупный оригинал не вытеснил текст. Для печати подберите достаточное разрешение и проверьте, что оно не делает небольшой документ неоправданно тяжёлым.

Создайте два контрольных документа. Первый с короткими полями должен помещаться на одну страницу. Второй с большим числом строк должен корректно переходить на следующие страницы. Откройте оба в просмотрщике PDF и проверьте текст у нижнего края, повторяемые заголовки таблиц и итоговую сумму.

Генерируем PDF в очереди и отправляем в личный чат

Поставьте задачу на отправку после фиксации заявки, например вызовом dispatch(...)->afterCommit(). Если потеря задачи при аварии недопустима, сохраняйте отдельную исходящую операцию вместе с заявкой и выбирайте её воркером. В очередь передавайте ID операции. По нему воркер загрузит снимок и адресата. Для таймаутов и повторов используйте настройки вашего драйвера очереди.

Берите ID личного чата из сохранённой привязки, полученной от Telegram. Перед отправкой проверьте, что заявка принадлежит владельцу этой привязки. Вызов ниже предполагает, что проверка пройдена, операция захвачена воркером, а токен получен из серверной конфигурации. tmpfile() создаёт временный файл для текущей задачи.

PHP · функция для задания очереди
use Barryvdh\DomPDF\Facade\Pdf;
use Illuminate\Http\Client\ConnectionException;
use Illuminate\Support\Facades\Http;

/**
 * @param array{number: string, submittedAt: string, customerName: string, subject: string} $snapshot
 * @return array{status: string, message_id?: int, error_code?: int, retry_after?: int}
 */
function sendApplicationPdf(string $token, string $chatId, array $snapshot): array
{
    $pdf = Pdf::loadView('pdf.application-confirmation', $snapshot)
        ->setPaper('a4')
        ->output();

    if (!str_starts_with($pdf, '%PDF-') || strlen($pdf) > 8 * 1024 * 1024) {
        throw new RuntimeException('PDF не прошёл локальную проверку.');
    }

    $file = tmpfile();
    if ($file === false) {
        throw new RuntimeException('Временный файл недоступен.');
    }

    try {
        if (fwrite($file, $pdf) !== strlen($pdf) || !rewind($file)) {
            throw new RuntimeException('Не удалось подготовить файл к отправке.');
        }

        try {
            $response = Http::connectTimeout(5)->timeout(25)
                ->attach('document', $file, 'application.pdf', ['Content-Type' => 'application/pdf'])
                ->post('https://api.telegram.org/bot'.$token.'/sendDocument', [
                    'chat_id' => $chatId,
                    'caption' => 'Подтверждение заявки',
                ]);
        } catch (ConnectionException) {
            return ['status' => 'unknown'];
        }

        $messageId = $response->json('result.message_id');
        if ($response->successful() && $response->json('ok') === true && is_int($messageId)) {
            return ['status' => 'sent', 'message_id' => $messageId];
        }

        $errorCode = $response->json('error_code');
        if ($response->clientError() && $response->json('ok') === false && is_int($errorCode)) {
            $result = ['status' => 'rejected', 'error_code' => $errorCode];
            $delay = $response->json('parameters.retry_after');
            if ($errorCode === 429 && is_int($delay) && $delay > 0) {
                $result['retry_after'] = $delay;
            }
            return $result;
        }

        return ['status' => 'unknown'];
    } finally {
        if (is_resource($file)) {
            fclose($file);
        }
    }
}

Лимит 8 МиБ выбран для примера. При генерации PDF хранится в памяти до записи во временный файл. Учитывайте это в лимите памяти воркера. При штатном завершении или исключении fclose() закрывает и удаляет файл. Проверьте права и свободное место во временном каталоге. После аварийного завершения процесса остатки временных файлов могут потребовать очистки.

Функция показывает генерацию и multipart-загрузку. В приложении ведите журнал отправки с ключом по версии документа и адресату. В случае успеха сохраните message_id. Явный отказ Telegram разбирайте по коду ответа и при 429 учитывайте retry_after. При потере ответа повторная отправка может прислать второй PDF. Отмечайте исход как неизвестный и решайте повтор отдельно. В журнале достаточно ID операции, типа ошибки и безопасных полей ответа.

Используйте тестовый чат и сначала проверьте сам PDF. Затем убедитесь, что Telegram прислал его нужному получателю и что сохранённый ID сообщения связан с версией документа. Сымитируйте таймаут и проверьте состояние исходящей операции. Если документ нужен нескольким задачам, храните его на приватном диске и задайте срок удаления.

Для подключения функции к заданию очереди разместите её в сервисе приложения и вызывайте из handle(). Передаваемый в очередь ID должен вести к одной исходящей операции. После её захвата загрузите снимок, проверьте получателя и вызовите генерацию. Сохраните возвращённое состояние sent, rejected или unknown до завершения задания.

При rejected с retry_after запланируйте новую попытку после указанной паузы. При unknown сохраните задачу для проверки результата. Ошибка генерации до HTTP-запроса допускает повтор после устранения причины, поскольку файл ещё не передавался. Разделяйте эти этапы в журнале, чтобы оператор видел, где произошёл сбой.

Для обычных драйверов Laravel согласуйте время HTTP-запроса, таймаут воркера и retry_after очереди. Таймаут воркера должен быть меньше срока повторной выдачи задания. Для SQS эту роль выполняет visibility timeout. В расчёт времени включайте генерацию PDF, которая может занимать больше времени на длинном документе.

Dompdf для Laravel · Документация Dompdf · Очереди Laravel · Telegram sendDocument · Отправка файлов ботом