Ваш первый PDF

Краткий обзор

В этом руководстве вы создадите два файла PDF. Сначала вы добавите текст напрямую с помощью гибкого API ядра. Затем отрисуете на странице фрагмент HTML с CSS. В итоге у вас будет рабочий скрипт, который можно адаптировать для реального документа, а также ссылки на варианты для фреймворков и сервера.

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

На схеме ниже показаны два подхода к созданию документов и три среды развёртывания, где они применяются.

From your code to a PDF file

Перед началом работы

Вам понадобится установленный движок ядра и среда для запуска скрипта PHP.

1. Убедитесь, что активная среда выполнения — PHP 8.4:

   php --version

2. Установите движок ядра в проект, если он ещё не установлен:

   composer require nextpdf/core

3. Создайте рабочий файл с именем first-pdf.php в корне проекта.

Стандартные 14 шрифтов работают без настройки

Гарнитура основного текста по умолчанию соответствует одному из стандартных 14 шрифтов Type 1, указанных в ISO 32000-2. Для первого документа файлы шрифтов не нужны. Регистрируйте и встраивайте пользовательские шрифты позже, когда этого потребует оформление.

Создание PDF из PHP

Начните с гибкого API. Document::createStandalone() возвращает документ, который сразу готов к работе. Добавьте страницу, задайте шрифт, запишите ячейки, а затем сохраните файл. Каждый метод создания возвращает документ, поэтому цепочка вызовов читается сверху вниз.

1. Поместите этот код в first-pdf.php. Скрипт объявляет строгую типизацию, загружает автозагрузчик и создаёт одну страницу:

   <?php
   
   declare(strict_types=1);
   
   require_once __DIR__ . '/vendor/autoload.php';
   
   use NextPDF\Core\Document;
   
   $document = Document::createStandalone();
   $document->setTitle('My first NextPDF document');
   $document->addPage();
   
   $document->setFont('helvetica', 'B', 24);
   $document->cell(0, 15, 'Hello, NextPDF!', newLine: true);
   
   $document->setFont('helvetica', '', 12);
   $document->cell(0, 10, 'This is the first PDF I generated with PHP.', newLine: true);
   
   $document->save(__DIR__ . '/first-pdf.pdf');
   
   echo "Wrote first-pdf.pdf\n";

2. Запустите скрипт:

   php first-pdf.php

3. Проверьте результат. В стандартном выводе должна появиться эта строка, а рядом со скриптом — новый файл с именем first-pdf.pdf:

   Wrote first-pdf.pdf

Теперь вы создали корректный файл PDF 2.0. Откройте его в любой программе просмотра, чтобы увидеть заголовок и строку под ним.

save или output

save() записывает документ по указанному пути к файлу. Чтобы вместо этого передать байты в браузер потоком, вызовите output(). Чтобы получить байты в памяти, вызовите getPdfData(). Документ предназначен для однократного использования. После записи документа создайте новый экземпляр для следующего файла, а не используйте прежний повторно.

Отрисовка HTML в PDF

Запись ячеек даёт точный контроль. Однако большинство документов быстрее описать с помощью HTML и CSS. Движок ядра включает конвейер обработки HTML на чистом PHP. Метод writeHtml() отрисовывает фрагмент на текущей странице. Он не использует браузер или внешнюю службу.

1. Создайте второй файл, html-pdf.php, который отрисовывает HTML-фрагмент:

   <?php
   
   declare(strict_types=1);
   
   require_once __DIR__ . '/vendor/autoload.php';
   
   use NextPDF\Core\Document;
   
   $document = Document::createStandalone();
   $document->setTitle('HTML to PDF');
   $document->addPage();
   
   $html = <<<'HTML'
   <h1 style="color: #1E3A8A;">HTML rendering in NextPDF</h1>
   <p>NextPDF renders <strong>HTML content</strong> directly into PDF pages.</p>
   <ul>
       <li>Headings, paragraphs, and lists</li>
       <li>Inline <strong>bold</strong> and <em>italic</em></li>
       <li>Inline styles such as color and font-size</li>
   </ul>
   HTML;
   
   $document->writeHtml($html);
   
   $document->save(__DIR__ . '/html-pdf.pdf');
   
   echo "Wrote html-pdf.pdf\n";

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

   php html-pdf.php

3. Проверьте строку вывода и новый файл:

   Wrote html-pdf.pdf

Считайте входной HTML недоверенным

Если HTML поступает от пользователя, из формы или любого внешнего источника, проверьте и очистите его, прежде чем передавать в writeHtml(). В рецепте «Отрисовка HTML на странице PDF» подробно разобраны модель безопасности и потоковая передача.

Движок отрисовывает поддерживаемое подмножество HTML и CSS. Прежде чем полагаться на какое-либо свойство, проверьте матрицу поддержки CSS. Если макету требуется полное соответствие браузеру, например flexbox, grid или веб-шрифты, установите средство отрисовки Artisan и вместо этого вызовите writeHtmlChrome(). Этот метод сохраняет возможность выделять текст.

Из контроллера фреймворка

Возможно, ваше приложение уже работает во фреймворке или через сервер. Те же два вызова можно перенести в эту среду. Движок остаётся прежним. Меняется только способ подключения.

Laravel

Фасад Pdf при каждом вызове создаёт новый документ. PdfResponse преобразует документ в ответ для скачивания:

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Http\Response;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

final class ReportController extends Controller
{
    public function download(): Response
    {
        $document = app(PdfDocumentInterface::class);
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

        return PdfResponse::download($document, 'report.pdf');
    }
}

См. быстрый старт для Laravel.

Symfony

Пакет предоставляет службу PdfFactory. Укажите тип NextPDF\Symfony\Service\PdfFactory в контроллере, создайте документ тем же способом и верните его как HTTP-ответ. См. быстрый старт для Symfony.

Сервер (REST)

Когда NextPDF Server запущен, отправьте методом POST упорядоченный массив операций, и сервер вернёт байты PDF:

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

При ответе 200 тело ответа содержит PDF. См. быстрый старт для Connect.

Дальнейшие действия

Теперь вы создали PDF тремя способами. Эти страницы помогут развить каждый из них.

Отрисовка HTML на странице PDF Полный рецепт по HTML: поддерживаемые элементы, модель потоковой передачи и модель безопасности.

Выберите свой путь Выберите между ядром, фреймворком, сервером и решите, какое средство отрисовки HTML использовать.

Справочник по движку ядра Каждый метод Document, его параметры и возвращаемые значения.

Сборник рецептов Целевые рецепты для оформления, таблиц, разбивки на страницы и не только.