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 金鑰般看待。
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、全域驗證）都描述於安裝與驗證。

接著，依你的組態慣例把已簽署的授權信封放到你的部署會載入的位置，然後執行你整合方案的啟用步驟——多數框架會把它作為主控台指令提供。在底層，線上啟用是授權介面上的一次呼叫：

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

會拋出或失敗於：傳輸失敗、非 200 狀態或提供的 nonce 有誤時拋出 NextPDF\Enterprise\Licensing\LicenseClientException，而任何簽署狀態驗證失敗時拋出 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

在試用或評估授予的情況下，改為預期 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

在 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()——JSON 無效或不符合預期結構時拋出 InvalidArgumentException；fromPkcs12()—— 檔案無法讀取或解析時拋出 NextPDF\Exception\SignatureException； setSignature()——線性化已啟用（PAdES 與 Fast Web View 互斥）時拋出 NextPDF\Exception\InvalidConfigException；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 中的主機索引鍵必須與儲存庫 URL 的主機完全相符。請逐步完成安裝與驗證。

執行期回報沒有授權

步驟 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() 在 .p12 檔案無法讀取或解析時拋出 NextPDF\Exception\SignatureException。常見原因是路徑錯誤、密碼錯誤（檢查 NEXTPDF_P12_PASSWORD），或檔案根本不是 PKCS#12。請以 openssl pkcs12 -info -in signing-cert.p12 -noout 驗證。

接下來可以去哪裡

範本——完整的範本定義與繫結參考。
用 PAdES B-B 簽署 PDF，再擴充到 PAdES B-T ——為你的簽章加上 RFC 3161 時間戳記。
NextPDF Pro 能力——你的 Pro 授權涵蓋的一切。
兩種交付通道——ionCube 線上租約與完全離線的 signed source。
試用與評估品牌標示——評估浮水印長什麼樣子，以及付費授權如何移除它。