Pro 版本

NextPDF Pro 快速入门

概览

你手中已有一份 NextPDF Pro 授权信封。本教程用四个简短步骤，把它变成你的第一个已校验成果。你从私有仓库安装 nextpdf/pro、激活你的授权、确认运行时解析出的授权权益，然后渲染一个模板化的 PDF 并为其签名。每一步都会展示你应当看到的输出。

此能力随 NextPDF Pro（nextpdf/pro）交付，并通过 Pro 层级的授权信封激活。没有该授权权益的部署不会加载此能力的类。比较各版本并获取授权。

先决条件

PHP 8.4 与 Composer 2。 premium 包要求 PHP >=8.4 <9.0。
私有仓库凭据。 你的门户会签发一个仓库 URL、用户名和令牌。设置过程见安装与认证。
你的授权信封。 登录你在 app.getnextpdf.com 的账户，签署授权协议，并为你的部署下载已签名的信封。请像对待 API key 一样对待它。
ionCube Loader（仅编码构建需要）。 Pro 试用版和付费的、 ionCube 编码的 Pro 构建需要适用于 PHP 8.4 的 Loader——参见 ionCube 设置。

1. 安装并激活

将 Composer 指向你的私有仓库、进行认证，并 require 该包：

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、全局 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. 校验你的授权权益

向授权权益评估器（entitlement evaluator）——授权决策的唯一权威——询问你的信封解析出的结果。$license 是你集成的授权引导所暴露的、已校验的 NextPDF\Enterprise\Licensing\LicenseKey；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

在试用或评估授予（grant）下，预期改为 channel: evaluation 和 branding: evaluation。每一项 Pro 能力仍然运行，且渲染的输出按设计带有可见的评估水印。付费授权无需改动任何代码即可移除它——参见试用与评估品牌标识。

3. 第一个成果

现在到了有趣的部分：解析一个 JSON 模板、以类型感知的格式绑定你的数据、渲染绑定后的值，并为文档签名。把它保存为紧邻你 vendor/ 目录的 quickstart.php，然后运行 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

在 PDF 阅读器中打开 welcome-letter-signed.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`

composer require 期间出现 401/403，或 “could not be found”，意味着私有仓库或其凭据未为此项目配置。auth.json 中的 host 键必须与仓库 URL 的 host 完全匹配。请逐步完成安装与认证。

运行时报告无授权

第 2 步打印 status: no_license、runtime: disabled 以及评估器的警告——原始的 premium 运行时消息（两个版本共用）是：No license configured. Enterprise runtime is disabled. Install a license or purchase one at https://nextpdf.dev/pricing。没有已校验的信封时， premium 特性会 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 验证。

接下来去哪里

Template —— 完整的模板定义与绑定参考。
用 PAdES B-B 为 PDF 签名，再扩展到 PAdES B-T —— 为你的签名添加 RFC 3161 时间戳。
NextPDF Pro 能力 —— 你的 Pro 授权所包含的一切。
两个交付通道 —— ionCube 在线租约与完全离线的 signed source。
试用与评估品牌标识 —— 评估水印长什么样，以及付费授权如何移除它。