Bỏ qua để đến nội dung
NextPDF
getnextpdf.com

Pro phiên bản

Bắt đầu nhanh với NextPDF Pro

Tổng quan nhanh

Phần tiêu đề “Tổng quan nhanh”

Bạn có một license envelope NextPDF Pro. Hướng dẫn này biến nó thành kết quả đã xác minh đầu tiên qua bốn bước ngắn. Bạn cài đặt nextpdf/pro từ kho lưu trữ riêng tư, kích hoạt license của bạn, xác nhận quyền dùng mà runtime đã phân giải, rồi kết xuất một PDF theo mẫu và ký nó. Mỗi bước cho thấy kết quả mà bạn nên thấy.

Khả năng này được cung cấp trong NextPDF Pro (nextpdf/pro) và kích hoạt bằng một license envelope bậc Pro. Một triển khai không có quyền dùng đó sẽ không nạp các lớp của khả năng này. So sánh các phiên bản và nhận license.

Điều kiện tiên quyết

Phần tiêu đề “Điều kiện tiên quyết”
  • PHP 8.4 và Composer 2. Các gói premium yêu cầu PHP >=8.4 <9.0.
  • Thông tin đăng nhập kho riêng tư. Cổng của bạn cấp một URL kho lưu trữ, tên đăng nhập và token. Việc thiết lập được trình bày trong Cài đặt và xác thực.
  • License envelope của bạn. Đăng nhập vào tài khoản của bạn tại app.getnextpdf.com, ký thỏa thuận license, và tải xuống envelope đã ký cho triển khai của bạn. Hãy xem nó như một API key.
  • ionCube Loader (chỉ với các bản dựng mã hóa). Bản dùng thử Pro và bản dựng Pro trả phí, mã hóa bằng ionCube cần Loader cho PHP 8.4 — xem Thiết lập ionCube.

1. Cài đặt và kích hoạt

Phần tiêu đề “1. Cài đặt và kích hoạt”

Trỏ Composer đến kho riêng tư của bạn, xác thực, và require gói:

Terminal window
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

Thay thế URL kho lưu trữ và thông tin đăng nhập bằng thông tin từ cổng của bạn. Cả ba phương thức xác thực (project auth.json, COMPOSER_AUTH, global auth) đều được mô tả trong Cài đặt và xác thực.

Tiếp theo, đặt license envelope đã ký vào nơi mà triển khai của bạn nạp nó, theo quy ước cấu hình của bạn, và chạy bước kích hoạt của tích hợp của bạn — hầu hết các framework đều phơi bày nó dưới dạng một lệnh console. Ở bên dưới, việc kích hoạt trực tuyến là một lệnh gọi trên bề mặt licensing:

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

Ném hoặc thất bại với: NextPDF\Enterprise\Licensing\LicenseClientException khi có lỗi truyền tải, một trạng thái không phải 200, hoặc một nonce cung cấp sai, và NextPDF\Accelerator\Exception\SpectrumAuthenticationException khi bất kỳ việc xác minh trạng thái đã ký nào thất bại. Trên kênh ionCube license cũng xác minh trực tuyến định kỳ; kênh signed-source xác minh cục bộ — xem Hai kênh phân phối.

2. Xác minh quyền dùng của bạn

Phần tiêu đề “2. Xác minh quyền dùng của bạn”

Hỏi bộ đánh giá quyền dùng — thẩm quyền duy nhất cho các quyết định về license — xem envelope của bạn đã phân giải thành gì. $license là NextPDF\Enterprise\Licensing\LicenseKey đã xác minh mà quá trình khởi động licensing của tích hợp của bạn phơi bày; null cho thấy kết quả không-license 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');

Phương thức đằng sau nó (nó không ném):

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

Với một license Pro trả phí đang hoạt động, hãy mong đợi:

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

Trên một cấp phép dùng thử hoặc đánh giá, hãy mong đợi channel: evaluation và branding: evaluation thay vào đó. Mọi khả năng Pro vẫn chạy, và kết xuất đầu ra mang một watermark đánh giá hiển thị theo thiết kế. Một license trả phí loại bỏ nó mà không cần thay đổi mã — xem Thương hiệu dùng thử và đánh giá.

3. Kết quả đầu tiên

Phần tiêu đề “3. Kết quả đầu tiên”

Giờ đến phần thú vị: phân tích một mẫu JSON, ràng buộc dữ liệu của bạn với việc định dạng nhận biết kiểu, kết xuất các giá trị đã ràng buộc, và ký tài liệu. Lưu tệp này thành quickstart.php cạnh thư mục vendor/ của bạn và chạy php quickstart.php. Bạn cần một chứng chỉ ký dưới dạng tệp PKCS#12 (signing-cert.p12); một chứng chỉ tự ký là đủ cho hướng dẫn này. Việc ký trong môi trường sản xuất cần một khóa riêng được bảo vệ đúng cách, một chuỗi chứng chỉ thực, và một chính sách tin cậy mà người nhận của bạn chấp nhận — chữ ký tự ký không phù hợp cho các quy trình người nhận đáng tin cậy.

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

Đầu ra mong đợi:

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

Mở welcome-letter-signed.pdf trong một trình đọc PDF: ba giá trị đã ràng buộc xuất hiện tại các vị trí trong mẫu của chúng (issued được định dạng Y-m-d, total là EUR 1,249.50), và bảng chữ ký của trình đọc cho thấy một chữ ký. Cấu trúc được phát ra tuân theo hồ sơ cơ sở PAdES B-B; NextPDF ghi nhận điều này như một khả năng, không phải một chứng nhận — phạm vi và tư thế tuân thủ nằm trên trang các mức PAdES. Nếu mẫu JSON không hợp lệ, TemplateParser::parse() ném InvalidArgumentException với một thông báo có tiền tố Template validation failed:.

Các chữ ký khóa mà bạn vừa dùng, nguyên văn:

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

Ném hoặc thất bại với: parse() — InvalidArgumentException khi JSON không hợp lệ hoặc không tuân theo cấu trúc mong đợi; fromPkcs12() — NextPDF\Exception\SignatureException khi không thể đọc hoặc phân tích tệp; setSignature() — NextPDF\Exception\InvalidConfigException khi việc tuyến tính hóa đã được bật (PAdES và Fast Web View loại trừ lẫn nhau); save() — NextPDF\Exception\InvalidConfigException, NextPDF\Exception\PageLayoutException, hoặc NextPDF\Exception\CompressionException khi không thể ghi tệp. bind() không ném; thay vào đó nó báo cáo missingFields và warnings.

4. Khi có thứ gì đó thất bại

Phần tiêu đề “4. Khi có thứ gì đó thất bại”

Composer không thể tìm hoặc lấy nextpdf/pro

Phần tiêu đề “Composer không thể tìm hoặc lấy nextpdf/pro”

Một 401/403 trong lúc composer require, hoặc “could not be found”, nghĩa là kho riêng tư hoặc thông tin đăng nhập của nó chưa được cấu hình cho dự án này. Khóa host trong auth.json phải khớp chính xác với host của URL kho lưu trữ. Hãy làm theo Cài đặt và xác thực.

Runtime báo không có license

Phần tiêu đề “Runtime báo không có license”

Bước 2 in ra status: no_license, runtime: disabled, và cảnh báo của bộ đánh giá — thông báo runtime premium thô (dùng chung bởi cả hai phiên bản) là: No license configured. Enterprise runtime is disabled. Install a license or purchase one at https://nextpdf.dev/pricing. Các tính năng premium thất bại đóng khi không có envelope đã xác minh. Một tệp envelope hiện diện nhưng hỏng không bao giờ được xem như vắng mặt — nó phát sinh NextPDF\Enterprise\Licensing\Storage\LicenseStorageException với các thông báo như License file is present but unreadable: ... hoặc License file is present but empty: .... Đặt envelope tại đường dẫn đã cấu hình và làm cho nó đọc được bởi người dùng tiến trình PHP.

Chứng chỉ ký không nạp được

Phần tiêu đề “Chứng chỉ ký không nạp được”

CertificateInfo::fromPkcs12() ném NextPDF\Exception\SignatureException khi không thể đọc hoặc phân tích tệp .p12. Các nguyên nhân thường gặp là sai đường dẫn, sai mật khẩu (kiểm tra NEXTPDF_P12_PASSWORD), hoặc một tệp không thực sự là PKCS#12. Xác minh bằng openssl pkcs12 -info -in signing-cert.p12 -noout.

Đi tiếp đến đâu

Phần tiêu đề “Đi tiếp đến đâu”