NextPDF FAQ

Кратко

Эта страница отвечает на вопросы, которые возникают первыми, когда вы оцениваете NextPDF или начинаете новый проект. Каждый ответ краток и ведёт на страницу, освещающую его полностью. NextPDF — это движок на PHP 8.4, который генерирует и исследует документы Portable Document Format (PDF) 2.0 — формат файла, определённый ISO 32000-2.

Если вы здесь впервые, сначала прочитайте Начало работы, а затем возвращайтесь сюда за конкретикой.

Начало работы

Какая редакция мне нужна: Core, Pro или Enterprise?

Начните с Core. Открытое ядро (nextpdf/core) генерирует вывод PDF, отрисовывает поддерживаемый HTML в PDF и исследует PDF под лицензией Apache-2.0 и бесплатно. Core уже создаёт подписи CMS SignedData для базовых уровней PDF Advanced Electronic Signatures (PAdES) B-B и B-T. Выбирайте Pro, когда вам нужны продвинутая генерация и операции с документами, вывод электронных счетов (Factur-X / ZUGFeRD) или продвинутые процессы подписания, такие как удалённое, cloud-KMS и последовательное подписание. Выбирайте Enterprise, когда вам нужны рабочие процессы архивного создания PDF/A, долгосрочные уровни PAdES (B-LT / B-LTA) с Document Security Store и метками времени документа, аппаратное подписание через аппаратный модуль безопасности (HSM) или квалифицированные электронные подписи. Pro и Enterprise — две лицензируемые редакции NextPDF Premium, платной линейки; см. Выберите свой путь.

Это действительно Apache-2.0?

Да, для ядра. nextpdf/core объявляет "license": "Apache-2.0" и поставляет полный текст Apache License 2.0 в своём файле LICENSE. Вы можете использовать, модифицировать, перераспространять и коммерциализировать ядро при условии соблюдения требований об указании авторства и NOTICE (Apache-2.0 §4). NextPDF Pro и NextPDF Enterprise — проприетарные коммерческие редакции, и эта лицензия их не покрывает. Название и логотип NextPDF являются товарными знаками, отдельными от лицензии на код. См. Лицензирование продукта.

Какова минимальная версия PHP?

PHP 8.4. Ограничение пакета — >=8.4 <9.0, поэтому Composer отказывается устанавливать на PHP 8.3 или ниже, либо на PHP 9. NextPDF нацелен на одну современную среду выполнения и использует её языковые возможности напрямую. См. Установка NextPDF.

Нужен ли ему внешний бинарник или headless-браузер?

Нет, для движка ядра — нет. Нативный движок реализован на PHP и стандартных расширениях PHP, без внешнего бинарника PDF и без обязательного headless-браузера: fluent-API и встроенный HTML-конвейер writeHtml() работают внутри процесса, без браузера и без сетевого вызова. Бинарник Chrome или Chromium необязателен и нужен только для отрисовщика Artisan (writeHtmlChrome()), который вы устанавливаете отдельно как nextpdf/artisan. Мосты Cloudflare и Gotenberg также необязательны и обращаются к службе. См. Выберите свой путь.

Какие расширения PHP ему нужны?

composer.json ядра требует стандартные расширения ext-mbstring, ext-zlib, ext-intl, ext-gd, ext-curl и ext-openssl — это широко доступные расширения PHP; убедитесь, что они установлены и включены в вашей среде выполнения. ext-curl обеспечивает необязательные сетевые обращения — проставление меток времени по RFC 3161 и загрузку удалённых ресурсов, — поэтому офлайновая нативная генерация его не задействует, но Composer всё равно указывает его как жёсткое требование. Интеграции проверяют нужные им расширения при загрузке и останавливаются с понятным сообщением, если каких-либо не хватает. Полный список находится в composer.json пакета; см. Установка NextPDF.

Как сгенерировать мой первый PDF?

Установите ядро, затем постройте документ с помощью fluent-API:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$document = Document::createStandalone();
$document->addPage();
$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello, NextPDF!', newLine: true);
$document->save(__DIR__ . '/first.pdf');

Пройдите по этому шаг за шагом в Ваш первый PDF.

Редакции и лицензирование

Есть ли у Core ограничения возможностей или водяной знак?

Нет. Core — это движок с открытым исходным кодом для набора возможностей Core без водяного знака и без назойливого экрана. Для набора возможностей Core — генерация, исследование, шифрование, примитивы вывода PDF/A и PDF/UA и подписание B-B/B-T программным ключом (без премиум-процессов долгосрочной проверки и хранения ключей) — Core полон. Оценочный водяной знак применяется только к гранту на оценку Premium, где вы тестируете полный набор возможностей Pro и Enterprise за удаляемой меткой; платная лицензия снимает его без изменения кода приложения. См. Лицензирование и активация.

Нужны ли изменения кода для перехода на Pro или Enterprise?

В основном нет. Когда вы устанавливаете nextpdf/premium, интеграции с фреймворками и сервер обнаруживают его автоматически и предоставляют дополнительные возможности. Большинство приложений сохраняют те же высокоуровневые точки интеграции; некоторые премиум-процессы могут требовать конфигурации или специфичных для возможности вызовов. Вы один раз на развёртывание активируете подписанный конверт лицензии. См. Лицензирование и активация.

Можно ли использовать ядро в коммерческом продукте с закрытым исходным кодом?

Да. У Apache License 2.0 нет некоммерческого ограничения. Вы можете использовать ядро в продуктах с закрытым исходным кодом, платных или внутренних коммерческих продуктах при условии, что соблюдаете обязательства об указании авторства и NOTICE и не трактуете лицензию на код как разрешение использовать бренд NextPDF. См. Лицензирование продукта и Товарный знак и использование бренда.

Возможности

Может ли он читать и разбирать PDF или только записывать их?

И то и другое, с оговоркой. NextPDF записывает PDF, а также читает их: модуль Inspect считывает существующий файл в структурированный InspectResult с данными о сложности, шрифтах, изображениях и рисках, и вы можете объединять и разделять существующие документы. Inspect помечен как экспериментальный, поэтому форма его результата может меняться между минорными версиями — используйте его для диагностики и контроля, а не как долгоживущий контракт. См. Модуль Inspect.

Создаёт ли он выделяемый, доступный для поиска текст?

Да. И fluent-API, и встроенный конвейер writeHtml() выдают настоящее текстовое содержимое, а не растрированные изображения, поэтому вывод выделяемый и доступен для поиска. writeHtmlChrome() отрисовщика Artisan также сохраняет текст выделяемым. См. Ваш первый PDF.

Как работает отрисовка HTML и CSS?

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

Как работают шрифты?

Встроенные стандартные псевдонимы шрифтов, такие как Helvetica, работают без настройки для простого текста WinAnsi, поэтому вашему первому документу не нужны файлы шрифтов. Встроенные латинские стандартные шрифты подходят для базового текста WinAnsi; Symbol и ZapfDingbats используют собственные кодировки; чтобы отрисовать другие письменности, вы регистрируете и встраиваете шрифт, чья карта символов и путь шейпинга поддерживают эту письменность. См. матрицу поддержки шрифтов и модуль Font.

Поддерживает ли он PDF/A и доступность (PDF/UA)?

Да, с чёткой границей: поддержка профиля — это не соответствие. Ядро поставляет дискриминатор соответствия и примитивы тегирования — enableTaggedPdf() включает вывод структуры тегированного PDF, используемой в процессах PDF/UA, а enablePdfA() выбирает профиль вывода PDF/A в Core; редакции Premium добавляют поверх более высокоуровневые процессы и инструменты архивного создания (валидация, политики и производственные операции). NextPDF выдаёт структурные артефакты, которые требует профиль; независимый валидатор, такой как veraPDF, решает, действительно ли данный файл соответствует. См. Соответствие стандартам и модуль Accessibility.

Как мне подписать PDF?

Ядро может создавать подписи Cryptographic Message Syntax (CMS) SignedData и может применять метки времени RFC 3161 (уровень B-T), используя поддерживаемые алгоритмы с программным ключом через настроенного поставщика подписи. Ваш код зависит от контракта SignerInterface, поэтому один и тот же вызов работает во всех редакциях. Долгосрочные уровни PAdES B-LT и B-LTA, хранение ключей в HSM и PKCS#11 и квалифицированные подписи — это возможности Enterprise; процессы облачного и KMS-подкреплённого подписания доступны в Pro. Core создаёт базовые структуры B-B и B-T. См. модуль Signing.

Эксплуатация

Безопасен ли он для воркеров и потоков?

Document одноразовый: записав один документ, создайте новый экземпляр для следующего, а не используйте прежний повторно. Это делает его естественно подходящим для модели «на запрос, на задачу», используемой PHP-FPM, воркерами очередей и фреймворками, — каждая единица работы строит свой собственный документ. Когда вы разбираете или компонуете недоверенный ввод, выполняйте эту работу в ограниченном воркере и держите защитные пределы ресурсов (maxFiles, maxTotalBytes, maxBytes) жёсткими. См. модуль Document и модель угроз движка.

Детерминирован ли вывод?

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

Как мне его развернуть?

Зафиксируйте composer.lock, чтобы каждый развёрнутый воркер разрешал одну и ту же версию движка, затем развёртывайте как любую PHP-библиотеку — нативной генерации не нужны демон, браузер или сеть; проставление меток времени (B-T), удалённые ресурсы или необязательный браузерный мост требуют настроенного доступа к сети. Если движок нужен не-PHP-службам, запустите NextPDF Server, который предоставляет его по Model Context Protocol (MCP), REST и gRPC. Для Premium разместите подписанный конверт лицензии там, где его загружает развёртывание, и выполните одноразовый шаг активации; кэшированное состояние лицензии означает, что обычной обработке не нужна служба лицензий, поэтому изолированные (air-gapped) развёртывания поддерживаются. См. Установка NextPDF и Лицензирование и активация.

Куда обращаться при сбое, когда что-то идёт не так?

NextPDF сообщает об ошибках классом исключения PHP, а не строковым кодом ошибки, и контекстно-зависимые исключения несут структурированные диагностические поля. Устранение неполадок сопоставляет распространённые сбои подписи, PDF/A, PDF/UA, шрифтов, тегирования и шифрования с их причиной и решением.