PDF из плагина Moodle получить просто: в ядре уже лежит библиотека TCPDF и класс-обёртка. Сложности начинаются, когда документ должен выглядеть как в регламенте: нужный шрифт, поля, таблица, повторяющаяся шапка, нумерация страниц, русские буквы без вопросительных знаков. Ниже порядок работы и ошибки, которые я набила, когда делала отчёты для учебного центра ДПО с выгрузкой в PDF, Excel и ZIP. Про готовые печатные формы без разработки читайте в статье про печатные формы в Moodle, а здесь код.
Чем формировать PDF
| Способ | Плюсы | Минусы |
|---|---|---|
Класс pdf в ядре (TCPDF) | Уже есть в Moodle, не нужны внешние программы, работает на любом хостинге | Поддержка HTML и CSS ограничена, вёрстка проще браузерной |
| Внешняя программа или сервис, которая печатает страницу из браузера | Современная вёрстка | Нужен отдельный процесс на сервере, больше места для сбоев и вопросов безопасности |
| Заполнение шаблона Word с конвертацией | Шаблон правят сотрудники | Нужна программа-конвертер на сервере, шрифты и поля плывут |
Для плагина, который должен работать на любом сервере, я выбираю первый вариант. Условие одно: вёрстку документа нужно держать простой.
Минимальный пример
Класс pdf находится в lib/pdflib.php и наследует TCPDF. Создание документа выглядит так.
require_once($CFG->libdir . '/pdflib.php');
$pdf = new pdf('P', 'mm', 'A4', true, 'UTF-8');
$pdf->SetCreator('Moodle');
$pdf->SetTitle($title);
$pdf->setPrintHeader(false);
$pdf->setPrintFooter(false);
$pdf->SetMargins(30, 20, 15);
$pdf->SetAutoPageBreak(true, 20);
$pdf->SetFont('freeserif', '', 14);
$pdf->AddPage();
$pdf->writeHTML($html, true, false, true, false, '');
$pdf->Output('spravka.pdf', 'D');
Поля заданы в миллиметрах: слева 30, сверху 20, справа 15, что часто требуют документы по ГОСТу, снизу 20. Последний аргумент Output задаёт режим: D скачивание, I показ в браузере, S возврат строки, F запись в файл. Для пакетной выгрузки нужны S или F.
Шрифты и кириллица
Самая частая ошибка новичка: шрифт по умолчанию не содержит кириллицы, и вместо букв получаются знаки вопроса или пустые места. В составе TCPDF идут семейства с кириллическими символами: freeserif, freesans, dejavusans. FreeSerif по виду близок к Times New Roman, и для документов, где регламент требует Times, я начинаю с него. Если нужен именно Times New Roman, есть два пути: добавить файл шрифта в библиотеку инструментом преобразования из комплекта TCPDF, либо согласовать с заказчиком замену. Для первого проверьте лицензию на шрифт: это коммерческий продукт, и вшивать его в файл на сервере без права на это нельзя.
Шрифт указывают и в самом HTML через стили, и в вызове SetFont. Если задать только в HTML, а в таблице забыть, получите разные шрифты в тексте и в ячейках.
Таблицы, повторяющиеся шапки, разрывы
Для документа с таблицей удобнее всего HTML с табличной разметкой, как для письма десять лет назад. Современные приёмы вроде display: flex или сеток не поддерживаются.
$html = '<table border="1" cellpadding="4">
<thead><tr style="background-color:#eeeeee;">
<th width="8%">№</th><th width="62%">Дисциплина</th><th width="30%">Оценка</th>
</tr></thead>';
foreach ($rows as $i => $row) {
$html .= '<tr nobr="true"><td>' . ($i + 1) . '</td><td>'
. s($row->subject) . '</td><td>' . s($row->grade) . '</td></tr>';
}
$html .= '</table>';
Две детали. Блок thead повторяется на каждой странице, если таблица длиннее листа. Атрибут nobr="true" у строки не даёт ей разорваться между страницами. Ширину колонок задавайте в процентах: фиксированные пиксели ведут себя непредсказуемо при смене размера страницы. Все данные пользователей пропускайте через s(): фамилия с амперсандом или угловыми скобками иначе ломает разметку, и документ либо не строится, либо выглядит странно.
Колонтитулы и номера страниц
Колонтитулы выводятся методами Header и Footer. Чтобы поставить свои, наследуют класс pdf в своём плагине и переопределяют нужный метод. Номер текущей страницы и их общее число вставляют специальными псевдонимами TCPDF, а не считают сами, потому что число страниц известно только в конце. Не забудьте включить печать колонтитулов в объекте, если вы их определили, иначе они не появятся, а выключенные по привычке вызовы остаются в коде.
Типичные ошибки
| Симптом | Причина | Решение |
|---|---|---|
| Вопросительные знаки вместо букв | Шрифт без кириллицы | Выбрать freeserif, freesans или dejavusans |
| Ошибка вывода: данные уже отправлены | Перед Output что-то уже напечатано, в том числе пробел после закрывающего тега PHP или заголовок страницы Moodle | Формировать PDF до вывода страницы, убрать лишние пробелы в файле |
| Таблица вылезает за поле | Ширина колонок в пикселях | Задать ширину в процентах |
| Пустая страница в конце | Лишний AddPage или отступ после таблицы | Проверить вызовы и убрать завершающие переводы строк |
| Не показывается картинка | Ссылка на файл Moodle, требующая входа | Передавать путь к файлу на диске или данные изображения |
| Документ не строится при странных фамилиях | В разметку попали необработанные символы | Пропускать данные через s() |
| Слова переносятся посреди слова | Нет мягких переносов, мало места в колонке | Расширить колонку или уменьшить кегль, а не ставить неразрывные пробелы везде |
Много документов за раз
Отчёт «по каждому слушателю в отдельном файле» превращается в десятки PDF. Собирать их в одном объекте и отдавать единым ответом нельзя: вы упрётесь в память и время ответа. Я делаю так: для каждого документа создаётся свой объект, результат пишется во временный каталог, который выдаёт make_request_directory, затем файлы упаковываются в ZIP и отдаются одним скачиванием.
$dir = make_request_directory();
$files = [];
foreach ($students as $student) {
$path = $dir . '/' . $student->id . '.pdf';
$pdf = build_student_pdf($student);
$pdf->Output($path, 'F');
$files[$student->id . '.pdf'] = $path;
}
$zip = $dir . '/reports.zip';
get_file_packer('application/zip')->archive_to_pathname($files, $zip);
send_temp_file($zip, 'reports.zip');
Имена внутри архива строятся из идентификаторов, а не из ФИО: в имени файла бывают кавычки, косые черты и слишком длинные строки. Если документов сотни, вынесите формирование в фоновую задачу и сообщите готовность уведомлением. Об отчётах такого рода я писала на странице про отчёты ДПО в Moodle.
Под регламент
Проверка соответствия регламенту
У печатной формы по регламенту есть набор требований, который заказчик редко записывает целиком. Я составляю такую таблицу сама и согласую её до начала кода.
| Требование | Как проверяется |
|---|---|
| Шрифт и кегль | В свойствах PDF и визуально на странице с самым длинным текстом |
| Поля страницы | Линейка в просмотрщике или наложение на эталон |
| Нумерация страниц | Многостраничный документ, а не только короткий пример |
| Реквизиты и подписи | Список полей из регламента против полей формы |
| Длинные ФИО и названия дисциплин | Тестовые записи с самыми длинными значениями из реальных данных |
| Печать на бумаге | Пробная печать, особенно полей и границ таблиц |
Пробная печать на настоящем принтере находит больше замечаний, чем просмотр на экране. Таблица с тонкими линиями, которая на мониторе выглядит аккуратно, на бумаге иногда теряется.
Случай: отчёт по тестам для центра ДПО
Для центра ДПО я делала отчёт о прохождении курса: по каждому слушателю свой PDF с результатами тестов, плюс общая выгрузка в Excel и ZIP со всеми документами. Самым трудоёмким оказался не вывод таблицы, а подготовка данных: у слушателей по нескольку попыток, у тестов разные способы оценивания, а в названиях встречаются длинные строки. Поэтому подготовку данных я отделила от рисования: отдельный класс собирает структуру, отдельный строит документ. Тогда один и тот же набор данных попадает и в PDF, и в Excel, а числа в обоих файлах совпадают. Эта привычка сохраняет нервы: расхождение между документами обнаруживают быстрее, чем исправляют.
Когда документ утверждён регламентом, превращайте требования в проверяемый список до начала кода: шрифт, кегль, интервал, поля, нумерация, реквизиты, место для подписи, формулировки. Затем сверьте PDF с эталоном не глазами, а наложением двух страниц. Любое расхождение в регламенте проще согласовать на втором дне работы, чем на десятом. Если вы готовите форму под приказ или лицензионные требования, расскажите мне, какой документ нужен: подробности есть на странице разработки отчёта под регламент.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.