Быстрый старт NextPDF Pro

Кратко

У вас есть лицензионный конверт NextPDF Pro. Этот учебник превращает его в первый проверенный результат за четыре коротких шага. Вы устанавливаете nextpdf/pro из приватного репозитория, активируете лицензию, подтверждаете право, которое разрешил рантайм, затем рендерите PDF по шаблону и подписываете его. Каждый шаг показывает вывод, который вы должны увидеть.

Эта возможность поставляется в составе NextPDF Pro (nextpdf/pro) и активируется лицензионным конвертом уровня Pro. Развёртывание без этого права не загружает классы данной возможности. Сравните редакции и получите лицензию.

Требования

• PHP 8.4 и Composer 2. Премиум-пакеты требуют PHP >=8.4 <9.0.
• Учётные данные приватного репозитория. Портал выдаёт URL репозитория, имя пользователя и токен. Настройка описана в разделе Установка и аутентификация.
• Ваш лицензионный конверт. Войдите в аккаунт на app.getnextpdf.com, подпишите лицензионное соглашение и загрузите подписанный конверт для вашего развёртывания. Обращайтесь с ним как с API-ключом.
• ionCube Loader (только для кодированных сборок). Пробная версия Pro и платная сборка Pro с кодировкой ionCube требуют Loader для PHP 8.4 — см. Настройка ionCube.

1. Установка и активация

Укажите Composer на ваш приватный репозиторий, аутентифицируйтесь и подключите пакет:

composer config repositories.nextpdf composer https://repo.example.com/nextpdf
composer config --auth http-basic.repo.example.com your-username your-token
composer require nextpdf/pro:^3

Подставьте URL репозитория и учётные данные из вашего портала. Все три метода аутентификации (проектный auth.json, COMPOSER_AUTH, глобальная аутентификация) описаны в разделе Установка и аутентификация.

Далее поместите подписанный лицензионный конверт туда, откуда его загружает ваше развёртывание, следуя вашему соглашению о конфигурации, и выполните шаг активации вашей интеграции — большинство фреймворков предоставляют его в виде консольной команды. Под капотом онлайн-активация — это один вызов лицензионного интерфейса:

public function activate(string $licenseJws, string $deploymentId, ?string $machineFingerprintHash = null, ?string $expectedLicenseId = null, ?string $clientNonce = null): StatusResponse

Выбрасывает или завершается ошибкой с: NextPDF\Enterprise\Licensing\LicenseClientException при сбое транспорта, статусе, отличном от 200, или неверном переданном nonce, и NextPDF\Accelerator\Exception\SpectrumAuthenticationException при любом сбое проверки подписанного статуса. На канале ionCube лицензия также периодически проверяется онлайн; канал signed-source проверяет локально — см. Два канала доставки.

2. Проверка вашего права

Спросите оценщик прав — единственный авторитет в решениях по лицензии — во что разрешился ваш конверт. $license — это проверенный NextPDF\Enterprise\Licensing\LicenseKey, который предоставляет лицензионный bootstrap вашей интеграции; null показывает fail-closed результат «нет лицензии».

use NextPDF\Enterprise\Licensing\EntitlementEvaluator;

$result = (new EntitlementEvaluator())->evaluate($license);

printf("status:   %s\n", $result->status->value);
printf("edition:  %s\n", $result->edition?->value ?? '(none)');
printf("channel:  %s\n", $result->channel->value);
printf("branding: %s\n", $result->brandingMode->value);
printf("runtime:  %s\n", $result->runtimeAllowed ? 'allowed' : 'disabled');

Метод, стоящий за этим (он не выбрасывает исключений):

public function evaluate(?LicenseKey $license, ?DateTimeImmutable $now = null): EntitlementResult

С активной платной лицензией Pro ожидайте:

status:   active
edition:  pro
channel:  paid
branding: none
runtime:  allowed

При пробном или ознакомительном гранте вместо этого ожидайте channel: evaluation и branding: evaluation. Все возможности Pro по-прежнему работают, а отрендеренный вывод по замыслу несёт видимый водяной знак ознакомительной версии. Платная лицензия убирает его без изменений в коде — см. Брендинг пробной и ознакомительной версий.

3. Первый результат

Теперь самое интересное: разобрать JSON-шаблон, привязать ваши данные с типозависимым форматированием, отрендерить привязанные значения и подписать документ. Сохраните это как quickstart.php рядом с каталогом vendor/ и запустите php quickstart.php. Вам нужен сертификат для подписи в виде файла PKCS#12 (signing-cert.p12); для этого учебника подойдёт самоподписанный. Промышленная подпись требует должным образом защищённого приватного ключа, реальной цепочки сертификатов и политики доверия, приемлемой для ваших получателей — самоподписанные подписи не подходят для доверенных рабочих процессов с получателями.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;
use NextPDF\Pro\Template\TemplateDataBinder;
use NextPDF\Pro\Template\TemplateParser;
use NextPDF\Security\Signature\CertificateInfo;
use NextPDF\Security\Signature\SignatureLevel;

// Parse a JSON template: one A4 page, three positioned placeholders.
$template = (new TemplateParser())->parse(<<<'JSON'
{
    "name": "welcome-letter",
    "pageSize": "A4",
    "orientation": "P",
    "placeholders": [
        {"name": "customer", "type": "text",     "x": 25, "y": 60, "width": 160, "height": 10},
        {"name": "issued",   "type": "date",     "x": 25, "y": 72, "width": 80,  "height": 10},
        {"name": "total",    "type": "currency", "x": 25, "y": 84, "width": 80,  "height": 10, "format": "EUR "}
    ]
}
JSON);

// Bind data. Keys match placeholder names case-insensitively.
$binding = (new TemplateDataBinder())->bind($template, [
    'customer' => 'Aurora Paper Co.',
    'issued'   => '2026-07-03',
    'total'    => 1249.5,
]);

printf(
    "Bound %d of %d placeholders (%d missing, %d warnings)\n",
    $binding->count(),
    count($template->placeholders),
    count($binding->missingFields),
    count($binding->warnings),
);

// Render the bound values with the Core document API.
$doc = Document::createStandalone();
$doc->setTitle('Welcome letter');
$doc->addPage();
$doc->setFont('helvetica', '', 12);

foreach ($binding->bindings as $bound) {
    $doc->text($bound->placeholder->x, $bound->placeholder->y, $bound->formattedValue);
}

// Apply a PAdES B-B baseline signature, then save once.
$doc->setSignature(
    CertificateInfo::fromPkcs12(__DIR__ . '/signing-cert.p12', (string) getenv('NEXTPDF_P12_PASSWORD')),
    SignatureLevel::PAdES_B_B,
);

$doc->save(__DIR__ . '/welcome-letter-signed.pdf');

echo "Created: welcome-letter-signed.pdf\n";

Ожидаемый вывод:

Bound 3 of 3 placeholders (0 missing, 0 warnings)
Created: welcome-letter-signed.pdf

Откройте welcome-letter-signed.pdf в PDF-ридере: три привязанных значения появляются на позициях из шаблона (issued отформатировано как Y-m-d, total как EUR 1,249.50), а панель подписей ридера показывает одну подпись. Формируемая структура следует базовому профилю PAdES B-B; NextPDF документирует это как возможность, а не как сертификацию — область охвата и позиция по соответствию описаны на странице уровней PAdES. Если JSON шаблона некорректен, TemplateParser::parse() выбрасывает InvalidArgumentException с сообщением, начинающимся с Template validation failed:.

Ключевые сигнатуры, которые вы только что использовали, дословно:

public function parse(string $json): TemplateDefinition
public function bind(TemplateDefinition $template, array $data): BindingResult
public static function fromPkcs12(string $p12Path, #[SensitiveParameter] string $password = ''): self
public function setSignature(CertificateInfo $certInfo, SignatureLevel $level = SignatureLevel::PAdES_B_B, ?TsaClient $tsaClient = null, ?ClientInterface $httpClient = null): static
public function save(string $path): void

Выбрасывает или завершается ошибкой с: parse() — InvalidArgumentException, когда JSON невалиден или не соответствует ожидаемой структуре; fromPkcs12() — NextPDF\Exception\SignatureException, когда файл не удаётся прочитать или разобрать; setSignature() — NextPDF\Exception\InvalidConfigException, когда линеаризация уже включена (PAdES и Fast Web View взаимоисключающи); save() — NextPDF\Exception\InvalidConfigException, NextPDF\Exception\PageLayoutException или NextPDF\Exception\CompressionException, когда файл не удаётся записать. bind() не выбрасывает исключений; вместо этого он сообщает о missingFields и warnings.

4. Когда что-то идёт не так

Composer не может найти или загрузить nextpdf/pro

Ошибка 401/403 во время composer require или «could not be found» означает, что приватный репозиторий или его учётные данные не настроены для этого проекта. Ключ хоста в auth.json должен точно совпадать с хостом URL репозитория. Разберитесь с этим по разделу Установка и аутентификация.

Рантайм сообщает об отсутствии лицензии

Шаг 2 печатает status: no_license, runtime: disabled и предупреждение оценщика — исходное сообщение премиум-рантайма (общее для обеих редакций): No license configured. Enterprise runtime is disabled. Install a license or purchase one at https://nextpdf.dev/pricing. Премиум-функции завершаются безопасно (fail closed) без проверенного конверта. Присутствующий, но повреждённый файл конверта никогда не считается отсутствующим — он вызывает NextPDF\Enterprise\Licensing\Storage\LicenseStorageException с сообщениями вроде License file is present but unreadable: ... или License file is present but empty: .... Поместите конверт по настроенному пути и сделайте его читаемым для пользователя процесса PHP.

Сертификат для подписи не загружается

CertificateInfo::fromPkcs12() выбрасывает NextPDF\Exception\SignatureException, когда файл .p12 не удаётся прочитать или разобрать. Обычные причины — неверный путь, неверный пароль (проверьте NEXTPDF_P12_PASSWORD) или файл, который на самом деле не является PKCS#12. Проверьте командой openssl pkcs12 -info -in signing-cert.p12 -noout.

Что дальше

• Шаблон — полный справочник по определению шаблона и привязке данных.
• Подпишите PDF с PAdES B-B, затем расширьте до PAdES B-T — добавьте к подписи метку времени RFC 3161.
• Возможности NextPDF Pro — всё, что включает ваша лицензия Pro.
• Два канала доставки — онлайн-аренда ionCube против полностью офлайновой подписи по исходному коду.
• Брендинг пробной и ознакомительной версий — как выглядит ознакомительный водяной знак и как платная лицензия его убирает.