Panduan cepat NextPDF Pro

Sekilas pandang

Anda memiliki license envelope NextPDF Pro. Tutorial ini mengubahnya menjadi hasil pertama yang terverifikasi dalam empat langkah singkat. Anda menginstal nextpdf/pro dari repository privat, mengaktifkan lisensi Anda, mengonfirmasi entitlement yang di-resolve runtime, lalu me-render PDF berbasis template dan menandatanganinya. Setiap langkah menunjukkan output yang seharusnya Anda lihat.

Kapabilitas ini disertakan dalam NextPDF Pro (nextpdf/pro) dan diaktifkan dengan license envelope tier Pro. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitasnya. Bandingkan edisi dan dapatkan lisensi.

Prasyarat

• PHP 8.4 dan Composer 2. Package premium membutuhkan PHP >=8.4 <9.0.
• Kredensial repository privat. Portal Anda menerbitkan URL repository, username, dan token. Penyiapan dibahas di Install and authenticate.
• License envelope Anda. Masuk ke akun Anda di app.getnextpdf.com, tandatangani perjanjian lisensi, dan unduh envelope yang telah ditandatangani untuk deployment Anda. Perlakukan seperti API key.
• ionCube Loader (hanya build ter-encode). Trial Pro dan build Pro berbayar yang di-encode ionCube membutuhkan Loader untuk PHP 8.4 — lihat ionCube setup.

1. Instal dan aktifkan

Arahkan Composer ke repository privat Anda, autentikasi, dan require package tersebut:

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

Ganti URL repository dan kredensial dari portal Anda. Ketiga metode autentikasi (auth.json proyek, COMPOSER_AUTH, auth global) dijelaskan di Install and authenticate.

Selanjutnya, tempatkan license envelope yang telah ditandatangani di lokasi yang dimuat deployment Anda, mengikuti konvensi konfigurasi Anda, dan jalankan langkah aktivasi integrasi Anda — sebagian besar framework mengeksposnya sebagai console command. Di balik layar, aktivasi online adalah satu panggilan pada surface lisensi:

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

Melempar atau gagal dengan: NextPDF\Enterprise\Licensing\LicenseClientException pada kegagalan transport, status non-200, atau nonce yang salah, dan NextPDF\Accelerator\Exception\SpectrumAuthenticationException pada setiap kegagalan verifikasi signed-status. Pada channel ionCube lisensi juga diverifikasi secara berkala online; channel signed-source diverifikasi secara lokal — lihat Two delivery channels.

2. Verifikasi entitlement Anda

Tanyakan pada entitlement evaluator — satu-satunya otoritas untuk keputusan lisensi — apa hasil resolve dari envelope Anda. $license adalah NextPDF\Enterprise\Licensing\LicenseKey terverifikasi yang diekspos oleh bootstrap lisensi integrasi Anda; null menunjukkan hasil fail-closed tanpa lisensi.

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');

Method di baliknya (tidak melempar exception):

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

Dengan lisensi Pro berbayar yang aktif, harapkan:

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

Pada grant trial atau evaluasi, sebagai gantinya harapkan channel: evaluation dan branding: evaluation. Setiap kapabilitas Pro tetap berjalan, dan output yang di-render membawa watermark evaluasi yang terlihat sesuai desain. Lisensi berbayar menghapusnya tanpa perubahan kode — lihat Trial and evaluation branding.

3. Hasil pertama

Sekarang bagian yang menyenangkan: parse template JSON, bind data Anda dengan formatting yang type-aware, render nilai yang telah di-bind, dan tandatangani dokumen. Simpan ini sebagai quickstart.php di sebelah direktori vendor/ Anda dan jalankan php quickstart.php. Anda memerlukan sertifikat penandatanganan berupa file PKCS#12 (signing-cert.p12); sertifikat self-signed cukup untuk tutorial ini. Penandatanganan produksi membutuhkan private key yang dilindungi dengan benar, rantai sertifikat sungguhan, dan trust policy yang diterima penerima Anda — tanda tangan self-signed tidak cocok untuk alur kerja penerima tepercaya.

<?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";

Output yang diharapkan:

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

Buka welcome-letter-signed.pdf di pembaca PDF: ketiga nilai yang di-bind muncul pada posisi template-nya (issued diformat Y-m-d, total sebagai EUR 1,249.50), dan panel tanda tangan pembaca menampilkan satu tanda tangan. Struktur yang dihasilkan mengikuti profil baseline PAdES B-B; NextPDF mendokumentasikan ini sebagai kapabilitas, bukan sertifikasi — cakupan dan posisi konformansi ada di halaman PAdES levels. Jika template JSON malformed, TemplateParser::parse() melempar InvalidArgumentException dengan pesan berawalan Template validation failed:.

Signature kunci yang baru saja Anda gunakan, verbatim:

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

Melempar atau gagal dengan: parse() — InvalidArgumentException ketika JSON invalid atau tidak sesuai dengan struktur yang diharapkan; fromPkcs12() — NextPDF\Exception\SignatureException ketika file tidak dapat dibaca atau di-parse; setSignature() — NextPDF\Exception\InvalidConfigException ketika linearisasi sudah diaktifkan (PAdES dan Fast Web View saling eksklusif); save() — NextPDF\Exception\InvalidConfigException, NextPDF\Exception\PageLayoutException, atau NextPDF\Exception\CompressionException ketika file tidak dapat ditulis. bind() tidak melempar exception; sebagai gantinya ia melaporkan missingFields dan warnings.

4. Ketika sesuatu gagal

Composer tidak dapat menemukan atau mengambil nextpdf/pro

401/403 selama composer require, atau “could not be found”, berarti repository privat atau kredensialnya tidak dikonfigurasi untuk proyek ini. Host key di auth.json harus sama persis dengan host URL repository. Kerjakan langkah-langkah di Install and authenticate.

Runtime melaporkan tidak ada lisensi

Langkah 2 mencetak status: no_license, runtime: disabled, dan warning evaluator — pesan raw premium-runtime (dipakai bersama oleh kedua edisi) adalah: No license configured. Enterprise runtime is disabled. Install a license or purchase one at https://nextpdf.dev/pricing. Fitur premium fail closed tanpa envelope terverifikasi. File envelope yang ada-tapi-rusak tidak pernah diperlakukan sebagai tidak ada — ia memunculkan NextPDF\Enterprise\Licensing\Storage\LicenseStorageException dengan pesan seperti License file is present but unreadable: ... atau License file is present but empty: .... Tempatkan envelope pada path yang dikonfigurasi dan buat agar dapat dibaca oleh user proses PHP.

Sertifikat penandatanganan tidak dapat dimuat

CertificateInfo::fromPkcs12() melempar NextPDF\Exception\SignatureException ketika file .p12 tidak dapat dibaca atau di-parse. Penyebab umumnya adalah path yang salah, password yang salah (periksa NEXTPDF_P12_PASSWORD), atau file yang bukan PKCS#12 sungguhan. Verifikasi dengan openssl pkcs12 -info -in signing-cert.p12 -noout.

Ke mana selanjutnya

• Template — referensi definisi template dan binding lengkap.
• Sign a PDF with PAdES B-B, then extend to PAdES B-T — tambahkan timestamp RFC 3161 ke tanda tangan Anda.
• NextPDF Pro capabilities — semua yang disertakan lisensi Pro Anda.
• Two delivery channels — lease online ionCube versus signed source yang sepenuhnya offline.
• Trial and evaluation branding — seperti apa watermark evaluasi dan bagaimana lisensi berbayar menghapusnya.