Pro エディション

NextPDF Pro クイックスタート

概要

あなたは NextPDF Pro のライセンスエンベロープを持っています。このチュートリアルは、それを 4 つの短いステップで検証済みの最初の成果物に変えます。プライベートリポジトリから 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 と認証情報は、ポータルから取得したものに置き換えてください。3 つの認証方法（プロジェクトの auth.json、COMPOSER_AUTH、グローバル認証）はすべてインストールと認証で説明しています。

次に、署名済みライセンスエンベロープを、設定の慣例に従ってデプロイがロードする場所に配置し、統合環境のアクティベーション手順を実行します。ほとんどのフレームワークは、これをコンソールコマンドとして公開しています。内部的には、オンラインアクティベーションはライセンシングサーフェス上の 1 回の呼び出しです。

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 つの配信チャネルを参照してください。

2. エンタイトルメントの検証

ライセンス判定の単一の権威であるエンタイトルメント評価器に、あなたのエンベロープが何に解決されたかを尋ねます。$license は、統合環境のライセンシングブートストラップが公開する検証済みの NextPDF\Enterprise\Licensing\LicenseKey です。null はフェイルクローズドのライセンスなし結果を示します。

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 テンプレートを解析し、型を意識したフォーマットでデータをバインドし、バインドした値をレンダリングして、ドキュメントに署名します。これを 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

welcome-letter-signed.pdf を PDF リーダーで開きます。3 つのバインドされた値がテンプレートの位置に表示され（issued は Y-m-d 形式、total は EUR 1,249.50）、リーダーの署名パネルには 1 つの署名が示されます。出力される構造は PAdES ベースライン B-B プロファイルに従います。NextPDF はこれを認証ではなく機能として文書化しています。スコープと適合性の姿勢については PAdES レベルのページに記載しています。テンプレート JSON が不正な場合、TemplateParser::parse() は Template validation failed: を接頭辞とするメッセージとともに InvalidArgumentException をスローします。

今使用した主要なシグネチャを、そのまま示します。

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() — リニアライゼーションがすでに有効な場合は 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 内のホストキーは、リポジトリ 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 機能は、検証済みエンベロープがなければフェイルクローズドになります。存在するが壊れているエンベロープファイルは、決して不在として扱われません。 License file is present but unreadable: ... や License file is present but empty: ... のようなメッセージとともに NextPDF\Enterprise\Licensing\Storage\LicenseStorageException を発生させます。エンベロープを設定されたパスに配置し、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 ライセンスに含まれるすべて。
2 つの配信チャネル — ionCube のオンラインリース対、完全オフラインの signed source。
トライアルと評価版のブランディング — 評価版の透かしがどのように見えるか、そして有償ライセンスがどのようにそれを取り除くか。