Настройка NextPDF и рендеринг первого PDF

NextPDF — это PHP-библиотека, которая создаёт файлы PDF (Portable Document Format). В этом руководстве вы установите её в пустую папку и отрендерите свой первый одностраничный документ. Вам понадобится терминал и около десяти минут.

Что вы создадите

Вы создадите крошечный проект с одним скриптом — 01-hello.php. Скрипт рендерит одну страницу с жирным заголовком и одним абзацем. Результат сохраняется в out/hello.pdf. По ходу дела вы узнаете две команды, подтверждающие, что установка работает исправно.

На этой странице показан один способ установки: пустая папка плюс пакет движка. Существуют и другие способы — адаптеры фреймворков, рендереры на основе браузера и клиент для Python. Они описаны в разделах Установка и Выберите свой путь. Сегодня они вам не нужны.

Шаг 1. Создание проекта и установка NextPDF

Composer — это менеджер пакетов для PHP. Он загружает библиотеки в ваш проект и генерирует автозагрузчик. Автозагрузчик — это небольшой PHP-файл, который сам находит классы библиотек, поэтому вам не придётся писать длинные списки подключений.

Откройте терминал и выполните эти три команды:

mkdir hello-nextpdf
cd hello-nextpdf
composer require nextpdf/core

Composer выводит информацию о ходе работы, пока разрешает зависимости и загружает пакеты. Точные строки зависят от версии Composer и вашего локального кэша. Успешная установка завершается без сообщений об ошибках и выглядит примерно так:

./composer.json has been created
Running composer update nextpdf/core
Loading composer repositories with package information
Updating dependencies
Lock file operations: ... installs, 0 updates, 0 removals
...
Generating autoload files

Что только что произошло

Composer создал в вашей папке три вещи. composer.json фиксирует, что ваш проект зависит от движка. composer.lock закрепляет точную установленную версию, чтобы последующая установка получила тот же код. Папка vendor/ содержит загруженные пакеты, включая vendor/autoload.php. Ваш скрипт подключает этот единственный файл — и все классы движка становятся доступны.

Во время установки Composer также проверил вашу конфигурацию PHP. Движок объявляет нужные ему расширения PHP. Расширения — это необязательные модули, встроенные в PHP. Если какого-то не хватает, Composer останавливается и называет его, вместо того чтобы оставить вас с нерабочей установкой.

Шаг 2. Рендеринг первого PDF

Создайте файл 01-hello.php рядом с composer.json. Вставьте в него эту полную программу:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Hello from NextPDF');
$document->addPage();

$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello from NextPDF', newLine: true);

$document->setFont('helvetica', '', 12);
$document->cell(0, 10, 'This page came from a short PHP script and the built-in fonts.', newLine: true);

$document->save(__DIR__ . '/out/hello.pdf');

echo "Wrote out/hello.pdf\n";

Запустите его:

php 01-hello.php

Вы должны увидеть ровно одну строку:

Wrote out/hello.pdf

Откройте out/hello.pdf в любом просмотрщике PDF. Вы увидите жирный заголовок с абзацем под ним, а большинство просмотрщиков покажут “Hello from NextPDF” в заголовке окна.

Что только что произошло

Разберём скрипт сверху вниз:

• require подключает автозагрузчик Composer, благодаря чему класс Document становится доступен.
• @mkdir создаёт папку out/. Ведущий символ @ заставляет скрипт молчать, когда папка уже существует, чтобы вы могли запустить его повторно.
• Document::createStandalone() возвращает новый документ. Он предназначен именно для коротких скриптов командной строки, таких как этот.
• setTitle() задаёт заголовок документа, который просмотрщики показывают в заголовке окна.
• addPage() добавляет одну пустую страницу и помещает курсор в левый верхний угол.
• setFont() выбирает семейство шрифта, начертание и размер в пунктах. Пункты — стандартная единица измерения размера шрифта в печати. 'B' означает жирное начертание, а '' — обычное. Семейство helvetica встроено, поэтому файлы шрифтов вам не нужны.
• cell() пишет одну строку текста в позиции курсора. Ширина 0 означает “растянуть до правого поля”. newLine: true затем сдвигает курсор вниз, как нажатие Enter.
• save() собирает готовый PDF и записывает его на диск.

Один документ создаёт один файл. Когда вам нужен второй PDF, создайте новый документ, а не используйте старый повторно.

Шаг 3. Проверка установки

Две быстрые проверки подтверждают, что эта установка будет работать не только для одного скрипта.

Сначала выведите список расширений, которые есть в вашем PHP:

php -m

Найдите в списке curl, gd, intl, mbstring, openssl и zlib. Движок полагается на эти шесть. Composer уже проверил их на шаге 1, поэтому все они должны присутствовать.

Затем запустите собственную проверку работоспособности движка:

vendor/bin/nextpdf doctor

В Windows вместо этого вызовите vendor\bin\nextpdf doctor. Команда проверяет версию PHP, расширения, временную папку и конфигурацию. Каждая проверка выводит [OK], [WARN] или [FAIL], а в конце — один общий вердикт.

Что только что произошло

Сначала прочитайте блок Extensions. Шесть строк [OK] с именами curl, gd, intl, mbstring, openssl и zlib означают, что ваша установка готова к каждому из следующих руководств.

Отчёт также перечисляет возможности движка. При бесплатной установке Core возможности, относящиеся к коммерческим пакетам, выводятся как [FAIL] с сообщением, называющим пакет, который их предоставляет. Здесь это ожидаемо и может изменить общий вердикт на UNHEALTHY, хотя ваша установка Core в порядке. Для этих руководств важен именно блок Extensions.

Если что-то пошло не так

Сначала сопоставьте свой симптом с этими распространёнными случаями:

• composer: command not found означает, что Composer отсутствует или не добавлен в PATH. Установите его с getcomposer.org, затем повторите шаг 1.
• Failed opening required '.../vendor/autoload.php' означает, что скрипт запущен вне папки проекта или установка не завершилась. Перейдите в папку из шага 1 и выполните composer install.
• Если Composer останавливается на шаге 1 и называет отсутствующее расширение PHP, включите это расширение в php.ini. Подтвердите его командой php -m, затем повторите установку.
• Строка [FAIL] в блоке Extensions утилиты doctor называет отсутствующее PHP- расширение. Включите его в php.ini, подтвердите командой php -m и снова запустите doctor. Строки [FAIL] о возможностях, называющие коммерческий пакет, ожидаемы при установке Core и не требуют действий здесь.

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

Далее

У вас есть рабочая установка и первый отрендеренный файл. Продолжите с Текст, шрифты и основы страниц, чтобы управлять размерами страниц, встроенными шрифтами, цветами и выравниванием.