Câu hỏi thường gặp về NextPDF

Tổng quan nhanh

Trang này trả lời những câu hỏi nảy sinh đầu tiên khi bạn đánh giá NextPDF hoặc bắt đầu một dự án mới. Mỗi câu trả lời ngắn gọn và liên kết đến trang bao quát nó đầy đủ. NextPDF là một engine PHP 8.4 tạo và kiểm tra các tài liệu Portable Document Format (PDF) 2.0, định dạng tệp do ISO 32000-2 định nghĩa.

Nếu bạn hoàn toàn mới, hãy đọc Bắt đầu trước, rồi quay lại đây để biết các chi tiết cụ thể.

Bắt đầu

Tôi cần phiên bản nào: Core, Pro, hay Enterprise?

Hãy bắt đầu với Core. Lõi mã nguồn mở (nextpdf/core) tạo đầu ra PDF, kết xuất HTML được hỗ trợ thành PDF, và kiểm tra PDF dưới giấy phép Apache-2.0 và miễn phí. Core đã tạo các chữ ký CMS SignedData cho các mức cơ sở PDF Advanced Electronic Signatures (PAdES) B-B và B-T. Hãy chọn Pro khi bạn cần khả năng tạo nâng cao và các thao tác trên tài liệu, đầu ra hóa đơn điện tử (Factur-X / ZUGFeRD), hoặc các quy trình ký nâng cao như ký từ xa, ký bằng cloud-KMS, và ký tuần tự. Hãy chọn Enterprise khi bạn cần các quy trình tạo lưu trữ PDF/A, các mức dài hạn PAdES (B-LT / B-LTA) với một Document Security Store và các dấu thời gian tài liệu, ký được hỗ trợ bằng phần cứng qua một hardware security module (HSM), hoặc các chữ ký điện tử đủ điều kiện. Pro và Enterprise là hai phiên bản được cấp phép của NextPDF Premium, dòng sản phẩm trả phí; xem Chọn lộ trình của bạn.

Nó thực sự là Apache-2.0 chứ?

Đúng vậy, với lõi. nextpdf/core khai báo "license": "Apache-2.0" và đi kèm toàn văn Apache License 2.0 trong tệp LICENSE của nó. Bạn có thể dùng, sửa đổi, phân phối lại, và thương mại hóa lõi, tùy thuộc vào các yêu cầu ghi công và NOTICE (Apache-2.0 §4). NextPDF Pro và NextPDF Enterprise là các phiên bản thương mại độc quyền và không được giấy phép đó bao phủ. Tên và logo NextPDF là nhãn hiệu, tách biệt với giấy phép mã. Xem Cấp phép sản phẩm.

Phiên bản PHP tối thiểu là gì?

PHP 8.4. Ràng buộc gói là >=8.4 <9.0, nên Composer từ chối cài đặt trên PHP 8.3 trở xuống, hoặc trên PHP 9. NextPDF nhắm vào một runtime hiện đại duy nhất và dùng các tính năng ngôn ngữ của nó trực tiếp. Xem Cài đặt NextPDF.

Nó có cần một binary bên ngoài hay một trình duyệt headless không?

Không, không cần cho engine lõi. Engine native được hiện thực bằng PHP và các extension PHP chuẩn, không cần binary PDF bên ngoài và không cần trình duyệt headless bắt buộc: API trôi chảy và pipeline HTML writeHtml() tích hợp sẵn chạy trong tiến trình mà không có trình duyệt và không có lệnh gọi mạng. Một binary Chrome hoặc Chromium là tùy chọn và chỉ cần cho bộ kết xuất Artisan (writeHtmlChrome()), mà bạn cài riêng dưới dạng nextpdf/artisan. Các cầu nối Cloudflare và Gotenberg cũng tùy chọn và gọi ra một dịch vụ. Xem Chọn lộ trình của bạn.

Nó yêu cầu các extension PHP nào?

composer.json của lõi yêu cầu các extension chuẩn ext-mbstring, ext-zlib, ext-intl, ext-gd, ext-curl, và ext-openssl, vốn là các extension PHP phổ biến; hãy đảm bảo chúng được cài đặt và bật trong runtime của bạn. ext-curl đứng sau các vòng mạng tùy chọn — đóng dấu thời gian RFC 3161 và lấy tài nguyên từ xa — nên việc tạo native ngoại tuyến không dùng đến nó, nhưng Composer vẫn liệt kê nó như một yêu cầu cứng. Các tích hợp kiểm tra những cái chúng cần lúc khởi động và dừng lại với một thông báo rõ ràng nếu thiếu cái nào. Danh sách đầy đủ nằm trong composer.json của gói; xem Cài đặt NextPDF.

Làm sao để tôi tạo PDF đầu tiên của mình?

Hãy cài lõi, rồi dựng một tài liệu bằng API trôi chảy:

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$document = Document::createStandalone();
$document->addPage();
$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello, NextPDF!', newLine: true);
$document->save(__DIR__ . '/first.pdf');

Hãy đi qua nó từng bước trong PDF đầu tiên của bạn.

Phiên bản và cấp phép

Core có giới hạn tính năng hay watermark nào không?

Không. Core là engine mã nguồn mở cho tập tính năng Core không có watermark và không có màn hình nhắc. Với tập tính năng Core — tạo, kiểm tra, mã hóa, các nguyên hàm đầu ra PDF/A và PDF/UA, và ký B-B/B-T bằng khóa phần mềm (không có các quy trình xác thực dài hạn và lưu giữ khóa của Premium) — Core là đầy đủ. Watermark đánh giá chỉ áp dụng cho một quyền đánh giá Premium, nơi bạn thử nghiệm toàn bộ tập tính năng Pro và Enterprise đằng sau một dấu có thể gỡ bỏ; một giấy phép trả phí gỡ nó mà không cần thay đổi mã ứng dụng nào. Xem Cấp phép và kích hoạt.

Tôi có cần thay đổi mã để nâng cấp lên Pro hay Enterprise không?

Hầu hết là không. Khi bạn cài nextpdf/premium, các tích hợp framework và máy chủ tự động phát hiện nó và phơi bày các năng lực bổ sung. Hầu hết ứng dụng giữ cùng các điểm tích hợp ở mức cao; một số quy trình Premium có thể đòi hỏi cấu hình hoặc các lệnh gọi đặc thù theo tính năng. Bạn kích hoạt một phong bì giấy phép đã ký một lần cho mỗi lần triển khai. Xem Cấp phép và kích hoạt.

Tôi có thể dùng lõi trong một sản phẩm thương mại mã nguồn đóng không?

Được. Apache License 2.0 không có hạn chế phi-thương-mại. Bạn có thể dùng lõi trong các sản phẩm thương mại mã nguồn đóng, trả phí, hoặc nội bộ, miễn là bạn tôn trọng các nghĩa vụ ghi công và NOTICE và không coi giấy phép mã là sự cho phép dùng thương hiệu NextPDF. Xem Cấp phép sản phẩm và Nhãn hiệu và sử dụng thương hiệu.

Năng lực

Nó có thể đọc và phân tích PDF không, hay chỉ ghi chúng?

Cả hai, với một lưu ý. NextPDF ghi PDF và cũng đọc chúng: module Inspect đọc một tệp hiện có thành một InspectResult có cấu trúc với dữ liệu về độ phức tạp, phông chữ, hình ảnh, và rủi ro, và bạn có thể gộp và tách các tài liệu hiện có. Inspect được đánh dấu experimental, nên hình dạng kết quả của nó có thể thay đổi giữa các phiên bản minor — hãy dùng nó cho chẩn đoán và kiểm soát cổng, không phải như một hợp đồng lâu dài. Xem module Inspect.

Nó có tạo ra văn bản chọn được, tìm kiếm được không?

Có. Cả API trôi chảy lẫn pipeline writeHtml() tích hợp sẵn phát ra nội dung văn bản thật, không phải hình ảnh raster hóa, nên đầu ra chọn được và tìm kiếm được. writeHtmlChrome() của bộ kết xuất Artisan cũng giữ văn bản chọn được. Xem PDF đầu tiên của bạn.

Việc kết xuất HTML và CSS hoạt động như thế nào?

Engine lõi bao gồm một pipeline HTML thuần PHP. writeHtml() kết xuất một đoạn HTML với một tập con CSS được hỗ trợ trực tiếp vào trang, không có trình duyệt và không có lệnh gọi mạng. Khi một bố cục cần độ chân thực đầy đủ của trình duyệt — như flexbox, grid, hoặc web font — hãy cài bộ kết xuất Artisan và gọi writeHtmlChrome(). Trước khi bạn dựa vào một thuộc tính, hãy kiểm tra ma trận hỗ trợ CSS.

Phông chữ hoạt động như thế nào?

Các alias phông chữ chuẩn tích hợp sẵn như Helvetica hoạt động không cần thiết lập cho văn bản WinAnsi đơn giản, nên tài liệu đầu tiên của bạn không cần tệp phông chữ nào. Các phông chữ chuẩn Latin tích hợp sẵn phù hợp cho văn bản WinAnsi cơ bản; Symbol và ZapfDingbats dùng các mã hóa riêng của chúng; để kết xuất các chữ viết khác, bạn đăng ký và nhúng một phông chữ mà bản đồ ký tự và đường tạo hình của nó hỗ trợ chữ viết đó. Xem ma trận hỗ trợ phông chữ và module Font.

Nó có hỗ trợ PDF/A và khả năng tiếp cận (PDF/UA) không?

Có, với một ranh giới rõ ràng: hỗ trợ một hồ sơ không phải là tuân thủ. Lõi đi kèm bộ phân biệt tuân thủ và các nguyên hàm gắn thẻ — enableTaggedPdf() bật đầu ra cấu trúc tagged-PDF dùng cho các quy trình PDF/UA, và enablePdfA() chọn một hồ sơ đầu ra PDF/A trong Core; các phiên bản Premium thêm các quy trình tạo lưu trữ và công cụ ở mức cao hơn (xác thực, chính sách, và các thao tác vận hành) lên trên. NextPDF phát ra các hiện vật cấu trúc mà một hồ sơ đòi hỏi; một bộ xác thực độc lập như veraPDF quyết định liệu một tệp nhất định có thực sự tuân thủ hay không. Xem Tuân thủ và module Accessibility.

Làm sao để tôi ký một PDF?

Lõi có thể tạo các chữ ký Cryptographic Message Syntax (CMS) SignedData và có thể áp các dấu thời gian RFC 3161 (mức B-T), dùng các thuật toán khóa phần mềm được hỗ trợ qua nhà cung cấp ký đã cấu hình. Mã của bạn phụ thuộc vào hợp đồng SignerInterface, nên cùng một lệnh gọi hoạt động trên các phiên bản. Các mức dài hạn PAdES B-LT và B-LTA, lưu giữ khóa HSM và PKCS#11, và các chữ ký đủ điều kiện là các năng lực Enterprise; còn các quy trình ký được hỗ trợ bằng cloud và KMS được cung cấp trong Pro. Core tạo các cấu trúc cơ sở B-B và B-T. Xem module Signing.

Môi trường thực tế

Nó có an toàn với worker và an toàn với luồng không?

Một Document là dùng-một-lần: một khi bạn đã ghi xong một cái, hãy tạo một thực thể mới cho tài liệu tiếp theo thay vì tái sử dụng nó. Điều này khiến nó tự nhiên phù hợp với mô hình theo-từng-yêu-cầu, theo-từng-công-việc mà PHP-FPM, các queue worker, và các framework dùng — mỗi đơn vị công việc dựng tài liệu riêng của nó. Khi bạn phân tích hoặc soạn đầu vào không đáng tin, hãy chạy công việc đó trong một worker bị ràng buộc và giữ các bảo vệ tài nguyên (maxFiles, maxTotalBytes, maxBytes) chặt. Xem module Document và mô hình mối đe dọa của engine.

Đầu ra có tất định không?

Nó tất định về cấu trúc, nhưng không giống hệt nhau từng byte theo mặc định. Hai lần chạy của cùng đầu vào tạo ra các PDF bằng nhau về cấu trúc, nhưng mỗi cái mang một trailer và /ID tài liệu mới, nên các byte khác nhau. Việc ký và đóng dấu thời gian thêm sự biến thiên theo từng-lần-chạy nữa theo thiết kế. Hãy lập kế hoạch so sánh quanh sự bằng nhau về cấu trúc, hoặc chuẩn hóa các trường dễ biến động, thay vì kỳ vọng các byte giống hệt qua các lần chạy.

Làm sao để tôi triển khai nó?

Hãy commit composer.lock để mọi worker đã triển khai giải quyết cùng phiên bản engine, rồi triển khai như bạn triển khai bất kỳ thư viện PHP nào — việc tạo native không cần daemon, trình duyệt, hay mạng; đóng dấu thời gian (B-T), tài nguyên từ xa, hoặc cầu nối trình duyệt tùy chọn đòi hỏi truy cập mạng đã cấu hình. Nếu các dịch vụ không-PHP cần engine, hãy chạy NextPDF Server, vốn phơi bày nó qua Model Context Protocol (MCP), REST, và gRPC. Với Premium, hãy đặt phong bì giấy phép đã ký ở nơi mà bản triển khai nạp nó và chạy bước kích hoạt một-lần; trạng thái giấy phép được cache nghĩa là việc xử lý thông thường không cần một dịch vụ giấy phép, nên các bản triển khai cách ly mạng được hỗ trợ. Xem Cài đặt NextPDF và Cấp phép và kích hoạt.

Tôi đem một thất bại đi đâu khi có gì đó sai?

NextPDF báo cáo lỗi theo lớp ngoại lệ PHP, không phải theo một mã lỗi dạng chuỗi, và các ngoại lệ nhận biết ngữ cảnh mang các trường chẩn đoán có cấu trúc. Cơ sở tri thức khắc phục sự cố ánh xạ các thất bại phổ biến về chữ ký, PDF/A, PDF/UA, phông chữ, gắn thẻ, và mã hóa tới nguyên nhân và giải pháp của chúng.