1. Что такое TCPDF и зачем он нужен?

TCPDF (от англ. "Transparent Communication PDF") — это мощная и широко используемая библиотека для языка PHP, предназначенная для программного создания PDF-документов. Она является одной из старейших и наиболее функциональных библиотек в своей нише, предоставляя разработчикам полный контроль над процессом генерации PDF без необходимости использования внешних инструментов или расширений (за исключением стандартного расширения GD для работы с изображениями).

Зачем нужен TCPDF? В современной веб-разработке часто возникает необходимость генерировать документы в формате PDF на лету: счета, накладные, отчёты, сертификаты, договоры, электронные книги и многое другое. TCPDF позволяет решить эту задачу, работая на серверной стороне. Он поддерживает все основные возможности PDF, включая шрифты (TrueType, Type1, Unicode), изображения (JPEG, PNG, GIF, SVG), HTML-контент, таблицы, аннотации, формы, закладки, шифрование и цифровые подписи. Благодаря поддержке Unicode, библиотека корректно работает с кириллицей, арабским, китайским и другими языками.

Основное преимущество TCPDF перед аналогами (например, FPDF или Dompdf) — это его богатая функциональность "из коробки" и отличная поддержка сложной вёрстки. Он умеет преобразовывать HTML в PDF с высокой точностью, что делает его идеальным выбором для генерации документов на основе готовых шаблонов. Библиотека активно поддерживается сообществом, имеет подробную документацию и огромное количество примеров, что значительно упрощает процесс обучения и решения типовых задач.

2. Установка

Установка TCPDF проще всего выполняется через менеджер зависимостей Composer. Это рекомендуемый способ, так как он автоматически подключает библиотеку и управляет её версиями.

Выполните следующую команду в корне вашего проекта:

composer require tecnickcom/tcpdf

После выполнения этой команды в вашем проекте появится папка vendor, а в файле composer.json — запись о зависимости. Для использования библиотеки в PHP-скрипте необходимо подключить автозагрузчик Composer:

require_once __DIR__ . '/vendor/autoload.php';

Если вы не используете Composer, можно скачать архив с GitHub и вручную подключить главный файл библиотеки:

require_once('/path/to/tcpdf/tcpdf.php');

Однако ручной способ не рекомендуется, так как усложняет обновление библиотеки.

3. Быстрый старт — минимальный рабочий пример

Давайте создадим простейший PDF-документ, который выводит текст "Hello, World!". Этот пример демонстрирует базовый жизненный цикл работы с TCPDF: создание объекта, добавление страницы, вывод текста и сохранение файла.

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

// 1. Создаем новый PDF-документ
// Параметры: ориентация (P - портрет, L - альбом), единицы измерения (mm), формат страницы (A4)
$pdf = new TCPDF('P', 'mm', 'A4', true, 'UTF-8', false);

// 2. Удаляем стандартный заголовок и подвал (для простоты)
$pdf->setPrintHeader(false);
$pdf->setPrintFooter(false);

// 3. Добавляем страницу
$pdf->AddPage();

// 4. Устанавливаем шрифт
$pdf->SetFont('helvetica', 'B', 20);

// 5. Выводим текст (x, y, текст)
$pdf->Text(50, 50, 'Hello, World!');

// 6. Выводим документ в браузер (D - скачать, I - просмотр inline, F - сохранить в файл)
$pdf->Output('hello_world.pdf', 'I');
?>

Этот код создаст PDF-файл с одной страницей, на которой жирным шрифтом Helvetica размером 20pt будет написано "Hello, World!". Файл будет отправлен в браузер для просмотра.

4. Основные методы и классы

TCPDF предоставляет огромное количество методов. Ниже приведены 8 ключевых, которые покроют 90% ваших задач.

4.1. AddPage()

Сигнатура: public function AddPage($orientation='', $format='', $keepmargins=false, $tocpage=false)

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

// Добавляем страницу альбомной ориентации формата A5
$pdf->AddPage('L', 'A5');

// Добавляем страницу с кастомными полями (если были установлены SetMargins)
$pdf->AddPage('', '', true);

4.2. SetFont()

Сигнатура: public function SetFont($family, $style='', $size=null, $fontfile='', $subset='default', $out=true)

Что делает: Устанавливает текущий шрифт, его начертание (жирный, курсив) и размер. Шрифт применяется ко всему последующему тексту до следующего вызова SetFont().

// Устанавливаем шрифт Times New Roman, обычный, размер 12
$pdf->SetFont('times', '', 12);

// Устанавливаем шрифт Helvetica, жирный курсив, размер 16
$pdf->SetFont('helvetica', 'BI', 16);

// Подключаем и используем шрифт DejaVu Sans (поддерживает кириллицу)
$pdf->SetFont('dejavusans', '', 10);

4.3. Cell()

Сигнатура: public function Cell($w, $h=0, $txt='', $border=0, $ln=0, $align='', $fill=false, $link='', $stretch=0, $ignore_min_height=false, $calign='T', $valign='M')

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

// Ячейка шириной 50мм, высотой 10мм, с текстом, рамкой и выравниванием по центру
$pdf->Cell(50, 10, 'Текст в ячейке', 1, 0, 'C');

// Ячейка без рамки, с выравниванием вправо, после неё - перевод строки
$pdf->Cell(0, 10, 'Текст на всю ширину', 0, 1, 'R');

// Ячейка с заливкой фона
$pdf->SetFillColor(200, 220, 255);
$pdf->Cell(30, 10, 'Заливка', 1, 1, 'C', true);

4.4. MultiCell()

Сигнатура: public function MultiCell($w, $h, $txt, $border=0, $align='J', $fill=false, $ln=1, $x='', $y='', $reseth=true, $stretch=0, $ishtml=false, $autopadding=true, $maxh=0, $valign='T', $fitcell=false)

Что делает: Выводит многострочный текст с автоматическим переносом строк. Незаменим для вывода абзацев, длинных описаний и HTML-контента. Если текст не помещается в ячейку, он переносится на следующую строку внутри той же ячейки.

$text = "Это длинный текст, который будет автоматически перенесён на следующую строку, если не поместится в заданную ширину ячейки. MultiCell - лучший друг верстальщика PDF.";

// Выводим текст в колонку шириной 80мм с выравниванием по ширине
$pdf->MultiCell(80, 10, $text, 1, 'J');

// Выводим HTML-текст (важно установить флаг ishtml в true)
$html = '<h2>Заголовок</h2><p>Абзац с <b>жирным</b> текстом.</p>';
$pdf->MultiCell(0, 0, $html, 0, 'L', false, 1, '', '', true, 0, true);

4.5. Image()

Сигнатура: public function Image($file, $x='', $y='', $w=0, $h=0, $type='', $link='', $align='', $resize=false, $dpi=300, $palign='', $ismask=false, $imgmask=false, $border=0, $fitbox=false, $hidden=false, $fitonpage=false, $alt=false, $altimgs=array())

Что делает: Вставляет изображение в документ. Поддерживает основные форматы (JPEG, PNG, GIF, SVG). Можно задать координаты, размеры, выравнивание и привязать ссылку.

// Вставка PNG-логотипа с прозрачностью
$pdf->Image('/path/to/logo.png', 10, 10, 50, 0, 'PNG', 'https://example.com');

// Вставка JPEG с автоматическим определением размера (указываем только ширину)
$pdf->Image('/path/to/photo.jpg', 100, 50, 80);

// Вставка изображения по центру страницы
$pdf->Image('/path/to/image.png', 0, 0, 0, 0, 'PNG', '', 'C');

4.6. writeHTML()

Сигнатура: public function writeHTML($html, $ln=true, $fill=false, $reseth=false, $cell=false, $align='')

Что делает: Парсит HTML-строку и преобразует её в PDF-контент. Это самый мощный метод для создания сложных макетов, так как позволяет использовать CSS-стили (ограниченно), таблицы, списки и другие HTML-элементы.

$html_content = '
<table border="1" cellpadding="5">
    <tr style="background-color:#cccccc;">
        <th>Имя</th>
        <th>Возраст</th>
        <th>Город</th>
    </tr>
    <tr>
        <td>Иван</td>
        <td>30</td>
        <td>Москва</td>
    </tr>
    <tr>
        <td>Мария</td>
        <td>25</td>
        <td>СПб</td>
    </tr>
</table>';

$pdf->writeHTML($html_content);

4.7. SetY() и SetX()

Сигнатура: public function SetY($y, $resetx=true) и public function SetX($x)

Что делает: Устанавливают текущую позицию курсора (Y — вертикальная, X — горизонтальная координата). SetY() также может сбросить X на левое поле. Используются для перехода к определённому месту на странице.

// Перемещаем курсор на 50мм ниже верхнего края (учитывая верхнее поле)
$pdf->SetY(50);

// Перемещаем курсор на 30мм от левого края
$pdf->SetX(30);

// Комбинируем: переходим в точку (40, 80)
$pdf->SetXY(40, 80);

4.8. Output()

Сигнатура: public function Output($name='doc.pdf', $dest='I')

Что делает: Завершает и выводит PDF-документ. Параметр $dest определяет способ вывода: 'I' — в браузер (inline), 'D' — принудительная загрузка, 'F' — сохранение в файл на сервере, 'S' — возврат в виде строки.

// Сохраняем файл на сервер
$pdf->Output('/var/www/docs/invoice_123.pdf', 'F');

// Отдаём на скачивание
$pdf->Output('report_2024.pdf', 'D');

// Получаем содержимое PDF в переменную
$pdf_content = $pdf->Output('', 'S');

5. Реальный практи