เริ่มต้นใช้งาน 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 key
• 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, การยืนยันตัวตนแบบ global) อธิบายไว้ใน ติดตั้งและยืนยันตัวตน

ต่อไป วางซองใบอนุญาตที่ลงลายเซ็นแล้วไว้ในตำแหน่งที่การติดตั้งของคุณโหลด ตาม ธรรมเนียมการกำหนดค่าของคุณ และเรียกใช้ขั้นตอนการเปิดใช้งานของการผสานรวมของคุณ — เฟรมเวิร์กส่วนใหญ่จะเปิดเผยเป็นคำสั่งคอนโซล เบื้องหลังนั้น การเปิดใช้งานออนไลน์คือ การเรียกหนึ่งครั้งบนพื้นผิวการออกใบอนุญาต:

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) แบบ self-signed ก็ใช้ได้สำหรับบทเรียนนี้ การลงลายเซ็นในการใช้งานจริงต้องการคีย์ส่วนตัวที่ได้รับการปกป้องอย่างเหมาะสม ห่วงโซ่ใบรับรองจริง และนโยบายความน่าเชื่อถือที่ผู้รับของคุณยอมรับ — ลายเซ็นแบบ self-signed ไม่เหมาะสำหรับเวิร์กโฟลว์ที่ผู้รับต้องเชื่อถือ

<?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 เมื่อ linearization เปิดใช้งานอยู่แล้ว (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” หมายความว่า ที่เก็บส่วนตัวหรือข้อมูลรับรองของมันยังไม่ได้ตั้งค่าสำหรับโปรเจกต์นี้ คีย์ host ใน auth.json ต้องตรงกับ host ของ URL ที่เก็บพอดี ทำตาม ติดตั้งและยืนยันตัวตน

รันไทม์รายงานว่าไม่มีใบอนุญาต

ขั้นตอนที่ 2 พิมพ์ status: no_license, runtime: disabled และคำเตือน ของตัวประเมิน — ข้อความ premium-runtime ดิบ (ใช้ร่วมกันทั้งสองรุ่น) คือ: No license configured. Enterprise runtime is disabled. Install a license or purchase one at https://nextpdf.dev/pricing คุณสมบัติพรีเมียมจะล้มเหลว แบบปิดหากไม่มีซองที่ผ่านการตรวจสอบ ไฟล์ซองที่มีอยู่แต่เสียหายจะไม่ถูก ปฏิบัติเสมือนว่าไม่มีอยู่ — มันจะยก 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 — เพิ่ม timestamp ตาม RFC 3161 ให้กับลายเซ็นของคุณ
• ความสามารถของ NextPDF Pro — ทุกอย่างที่ใบอนุญาต Pro ของคุณรวมไว้
• สองช่องทางการส่งมอบ — การเช่าออนไลน์ ผ่าน ionCube เทียบกับ signed source แบบออฟไลน์เต็มรูปแบบ
• การสร้างแบรนด์สำหรับรุ่นทดลองและประเมินผล — ลายน้ำ ประเมินผลมีลักษณะอย่างไรและใบอนุญาตแบบชำระเงินลบมันออกอย่างไร