DomPDF PHP: методы, примеры, установка

Введение в DomPDF: что это и зачем нужно

DomPDF — это мощная и популярная библиотека для языка PHP, предназначенная для генерации PDF-документов из HTML-разметки. Основная идея библиотеки заключается в том, чтобы позволить разработчикам создавать PDF-файлы, используя привычные технологии веб-верстки: HTML, CSS и JavaScript (ограниченно). Вместо того чтобы изучать сложные низкоуровневые API для работы с PDF (как, например, в FPDF или TCPDF), вы можете просто написать HTML-шаблон, оформить его с помощью CSS и передать его DomPDF для конвертации.

Библиотека использует движок рендеринга, основанный на DOMPDF (отсюда и название), который парсит HTML и CSS, создавая визуальное представление страницы, а затем экспортирует его в формат PDF. DomPDF поддерживает большинство стандартных CSS-свойств, включая позиционирование, float, flexbox (частично), работу со шрифтами, изображениями и таблицами.

Зачем нужна эта библиотека?

Автоматизация отчетов: Создание счетов, актов, накладных, коммерческих предложений на основе данных из базы данных.
Генерация сертификатов и дипломов: Быстрая выгрузка персонализированных документов с уникальными данными (имя, дата, курс).
Создание электронных книг и мануалов: Конвертация HTML-контента в хорошо отформатированный PDF для скачивания.
Сохранение веб-страниц: Функция "Сохранить как PDF" для любого контента на сайте.
Интеграция с CMS: WordPress, Laravel, Symfony и другие фреймворки активно используют DomPDF для генерации документов.

Главное преимущество DomPDF перед аналогами — это простота использования. Если вы знаете HTML и CSS, вы уже умеете работать с DomPDF на 80%.

Установка DomPDF

Установка DomPDF в современный PHP-проект выполняется через менеджер зависимостей Composer. Это стандартный способ для PHP-библиотек.

Убедитесь, что у вас установлен Composer. Затем выполните команду в корне вашего проекта:

composer require dompdf/dompdf

После успешной установки в вашем проекте появится папка vendor, а в файле composer.json добавится строка зависимости. Если вы используете фреймворк (Laravel, Symfony), установка может немного отличаться (например, через сервис-провайдеров), но базовая команда остается той же.

Важно: DomPDF требует PHP версии 7.1 или выше. Также рекомендуется установить расширение PHP mbstring для корректной работы с многобайтовыми кодировками (UTF-8).

Для проверки установки создайте файл test.php и добавьте в него следующий код:

<?php
require_once 'vendor/autoload.php'; // Подключаем автозагрузчик Composer

use Dompdf\Dompdf;

$dompdf = new Dompdf();
$dompdf->loadHtml('<h1>Hello World</h1>');
$dompdf->render();
$dompdf->stream("test.pdf");

?>

Если при открытии файла в браузере у вас скачался PDF с надписью "Hello World", установка прошла успешно.

Быстрый старт: первый PDF-документ

Давайте создадим простой, но полноценный пример. Мы сгенерируем PDF-файл с таблицей и стилями.

<?php
require_once 'vendor/autoload.php';

use Dompdf\Dompdf;
use Dompdf\Options;

// 1. Настройка опций (опционально)
$options = new Options();
$options->set('defaultFont', 'DejaVu Sans'); // Шрифт с поддержкой кириллицы
$options->set('isRemoteEnabled', true); // Разрешить загрузку внешних изображений

// 2. Создаем экземпляр Dompdf
$dompdf = new Dompdf($options);

// 3. HTML-контент
$html = '
<!DOCTYPE html>
<html>
<head>
    <style>
        body { font-family: DejaVu Sans, sans-serif; }
        h1 { color: #2c3e50; text-align: center; }
        table { width: 100%; border-collapse: collapse; margin-top: 20px; }
        th, td { border: 1px solid #ddd; padding: 8px; text-align: left; }
        th { background-color: #3498db; color: white; }
        .footer { margin-top: 30px; font-size: 12px; text-align: center; color: #7f8c8d; }
    </style>
</head>
<body>
    <h1>Отчет о продажах</h1>
    <table>
        <thead>
            <tr>
                <th>Товар</th>
                <th>Количество</th>
                <th>Цена</th>
                <th>Сумма</th>
            </tr>
        </thead>
        <tbody>
            <tr><td>Ноутбук</td><td>2</td><td>50000</td><td>100000</td></tr>
            <tr><td>Мышь</td><td>5</td><td>1500</td><td>7500</td></tr>
            <tr><td>Клавиатура</td><td>3</td><td>2500</td><td>7500</td></tr>
        </tbody>
    </table>
    <div class="footer">Сгенерировано с помощью DomPDF</div>
</body>
</html>
';

// 4. Загружаем HTML
$dompdf->loadHtml($html);

// 5. Устанавливаем размер бумаги и ориентацию
$dompdf->setPaper('A4', 'portrait');

// 6. Рендерим PDF
$dompdf->render();

// 7. Отправляем PDF в браузер для скачивания
$dompdf->stream('sales_report.pdf', ['Attachment' => 0]); // Attachment = 0 - открыть в браузере, 1 - скачать

?>

Этот код создаст PDF-файл с красиво оформленной таблицей. Обратите внимание на настройку шрифта DejaVu Sans — он необходим для корректного отображения кириллицы, так как стандартный шрифт DomPDF не поддерживает русские буквы.

Основные методы и функции DomPDF

В этом разделе мы подробно разберем ключевые методы библиотеки. Каждый метод будет описан с указанием параметров и рабочим примером.

1. `loadHtml($html, $encoding = null)`

Что делает: Загружает HTML-строку в движок DomPDF для последующей обработки. Это основной метод для передачи контента.

Параметры:

$html (string) — HTML-код, который нужно преобразовать в PDF.
$encoding (string|null) — Кодировка HTML. По умолчанию null (определяется автоматически). Рекомендуется указывать 'UTF-8' для кириллицы.

<?php
$dompdf = new Dompdf();
$html = '<h1>Привет, мир!</h1>';
$dompdf->loadHtml($html, 'UTF-8');
?>

2. `loadHtmlFile($filename)`

Что делает: Загружает HTML-контент из внешнего файла. Удобно, когда шаблон хранится отдельно.

Параметры:

$filename (string) — Путь к HTML-файлу на сервере.

<?php
$dompdf = new Dompdf();
$dompdf->loadHtmlFile('/path/to/template.html');
?>

3. `setPaper($size, $orientation = 'portrait')`

Что делает: Устанавливает формат бумаги и ориентацию страницы.

Параметры:

$size (string|array) — Формат бумаги. Стандартные значения: 'A4', 'A3', 'letter', 'legal'. Можно передать массив [0, 0, 595.28, 841.89] (в пунктах).
$orientation (string) — Ориентация: 'portrait' (книжная) или 'landscape' (альбомная).

<?php
$dompdf = new Dompdf();
$dompdf->setPaper('A4', 'landscape'); // Альбомная ориентация
// Или кастомный размер:
$dompdf->setPaper([0, 0, 400, 600]);
?>

4. `render()`

Что делает: Запускает процесс рендеринга (генерации) PDF-документа из загруженного HTML. Этот метод должен быть вызван перед выводом или сохранением файла.

Параметры: Нет.

<?php
$dompdf = new Dompdf();
$dompdf->loadHtml('<p>Тест</p>');
$dompdf->render(); // Генерируем PDF
?>

5. `stream($filename, $options = [])`

Что делает: Отправляет сгенерированный PDF-файл в браузер пользователя (стриминг). Обычно используется для скачивания или просмотра файла.

Параметры:

$filename (string) — Имя файла, которое будет предложено для скачивания.
$options (array) — Массив опций. Ключ 'Attachment': 0 — открыть в браузере, 1 — принудительное скачивание.

<?php
$dompdf = new Dompdf();
$dompdf->loadHtml('<h1>Документ</h1>');
$dompdf->render();
// Открыть в браузере:
$dompdf->stream('document.pdf', ['Attachment' => 0]);
// Скачать:
$dompdf->stream('document.pdf', ['Attachment' => 1]);
?>

6. `output($options = [])`

Что делает: Возвращает сгенерированный PDF-контент в виде строки (бинарных данных). Это полезно, если вы хотите сохранить PDF в файл на сервере, отправить по email или обработать иначе.

Параметры:

$options (array) — Массив опций (обычно пустой).

<?php
$dompdf = new Dompdf();
$dompdf->loadHtml('<p>Данные для сохранения</p>');
$dompdf->render();
$pdfContent = $dompdf->output();
file_put_contents('my_document.pdf', $pdfContent); // Сохраняем на сервер
?>

7. `setOptions(Options $options)`

Что делает: Устанавливает глобальные опции для экземпляра DomPDF. Позволяет настроить поведение библиотеки (шрифты, кэширование, удаленный доступ и т.д.).

Параметры: