Tổng quan tích hợp Laravel của NextPDF

Tổng quan nhanh

Gói nextpdf/laravel kết nối engine PDF của NextPDF với ứng dụng Laravel 12 của bạn và đăng ký sẵn các ràng buộc container. Gói này cung cấp facade Pdf, trình trợ giúp HTTP PdfResponse và GeneratePdfJob chạy qua hàng đợi. Laravel tự động phát hiện gói, nên bạn không cần đăng ký thủ công.

Cài đặt

composer require nextpdf/laravel

Ràng buộc Composer là nextpdf/core: ^3.0 || ^5.2. Gói này cũng yêu cầu laravel/framework: ^12.0 và php: >=8.4 <9.0. Để xem quy trình đầy đủ, bao gồm xuất bản cấu hình và các tiện ích mở rộng tùy chọn, hãy xem /integrations/laravel/install/.

Tổng quan khái niệm

Gói này nằm giữa service container của Laravel và phần lõi NextPDF độc lập với framework. Gói không triển khai lại việc tạo PDF; thay vào đó, nó điều chỉnh mô hình lõi NextPDF\Core\Document để phù hợp với vòng đời, cấu hình, hàng đợi và lớp HTTP của Laravel.

Sơ đồ bên dưới cho thấy một yêu cầu đi từ mã ứng dụng của bạn, qua gói này, rồi vào các registry lõi dùng chung.

NextPDF Laravel request and render flow

Bản đồ autoload có một mục PSR-4. PSR-4 là Khuyến nghị Tiêu chuẩn PHP cho autoload; tiền tố NextPDF\Laravel\ của gói ánh xạ tới src/Laravel/. Theo PSR-4, một tiền tố namespace tương ứng với một thư mục gốc, còn phần tên lớp còn lại ánh xạ tới đường dẫn tệp bên trong thư mục đó (PSR-4 §3). Bốn lớp sản phẩm nằm dưới tiền tố này:

• NextPDF\Laravel\NextPdfServiceProvider — đăng ký các ràng buộc và xuất bản cấu hình.
• NextPDF\Laravel\Facades\Pdf — proxy tĩnh phân giải một tài liệu mới từ container.
• NextPDF\Laravel\Http\PdfResponse — tạo phản hồi PDF dạng inline, tải xuống và truyền luồng với một bộ header bảo mật cố định.
• NextPDF\Laravel\Jobs\GeneratePdfJob — job có thể đưa vào hàng đợi để dựng và lưu tệp PDF trên worker.

Service provider triển khai DeferrableProvider, nên chỉ đăng ký các ràng buộc khi bạn phân giải một trong các mục đã công bố. Cơ chế trì hoãn này giúp đường khởi động của framework gọn nhẹ. Phương thức provides() của provider liệt kê các mục được trì hoãn, và container đọc danh sách này để ánh xạ từng khóa trở lại provider.

Việc phân giải tuân theo hợp đồng của container: khi có ràng buộc, phân giải định danh sẽ trả về mục đã đăng ký. PSR-11 là Khuyến nghị Tiêu chuẩn PHP cho khả năng tương tác của container, và tiêu chuẩn này lưu ý rằng hai lần gọi get() liên tiếp với cùng một định danh có thể trả về các giá trị khác nhau, tùy theo chiến lược ràng buộc (PSR-11 §1.1.2). NextPDF chủ động dựa vào hành vi này. Các registry là singleton, nên mỗi lần phân giải trả về cùng một instance. Tài liệu được ràng buộc theo factory, nên mỗi lần phân giải trả về một instance mới. Để xem bảng đầy đủ về vòng đời ràng buộc, hãy xem /integrations/laravel/boot-and-discovery/.

Kiến trúc này được thiết kế cho các worker tồn tại lâu dài, chẳng hạn như Octane, RoadRunner và Swoole. Font registry là singleton tồn tại suốt vòng đời tiến trình: gói làm nóng nó một lần rồi khóa lại, nên không yêu cầu nào có thể thay đổi trạng thái phông chữ dùng chung. Image registry là singleton tồn tại suốt vòng đời tiến trình với bộ nhớ đệm ít được dùng gần đây nhất (LRU) có giới hạn. Vì gói luôn tạo từng tài liệu từ DocumentFactory, trạng thái có thể thay đổi theo từng yêu cầu sẽ không bao giờ rò rỉ sang yêu cầu khác.

Vì sao tài liệu được tạo mới cho mỗi yêu cầu

Ràng buộc theo factory trả về một Document mới trên mỗi lần phân giải, trong khi font registry và image registry dùng chung vẫn tồn tại trên toàn tiến trình. Sự phân tách này giúp các tiến trình worker tồn tại lâu dài (Octane, RoadRunner, Swoole) không rò rỉ trạng thái giữa các yêu cầu, đồng thời vẫn phân bổ chi phí phân tích phông chữ qua nhiều yêu cầu.

Bề mặt API

Lớp	Điểm vào công khai	Trả về	Mục đích
NextPdfServiceProvider	register(), boot(), provides()	void / array	Ràng buộc container, xuất bản cấu hình, danh sách mục được trì hoãn
Facades\Pdf	proxy tĩnh (addPage(), cell(), save(), …)	static / mixed	Phân giải PdfDocumentInterface mỗi lần gọi
Http\PdfResponse	inline(), download(), streamInline(), streamDownload()	Response / StreamedResponse	Các phản hồi HTTP với header của Open Worldwide Application Security Project (OWASP)
Jobs\GeneratePdfJob	dispatch(), handle(), then(), catch(), failed()	PendingDispatch / void / self	Tạo PDF qua hàng đợi

Các khóa container được provider ràng buộc:

Khóa	Vòng đời	Phân giải thành
NextPDF\Contracts\FontRegistryInterface (bí danh FontRegistry)	singleton, đã khóa	NextPDF\Typography\FontRegistry
NextPDF\Graphics\ImageRegistry	singleton, giới hạn theo LRU	ImageRegistry
NextPDF\Contracts\DocumentFactoryInterface (bí danh DocumentFactory)	singleton	NextPDF\Core\DocumentFactory
Psr\Http\Client\ClientInterface	singleton	SecurityAwareHttpClient bọc quanh CurlHttpClient
NextPDF\Security\Timestamp\TsaClient	scoped	TsaClient hoặc null khi không có URL của tổ chức cấp dấu thời gian (TSA)
NextPDF\Contracts\SignerInterface	factory	DigitalSigner hoặc null khi tính năng ký bị tắt
NextPDF\Contracts\PdfDocumentInterface (bí danh nextpdf)	factory	NextPDF\Core\Document
NextPDF\Contracts\EInvoice\{Embedder,Validator,Profile,SchematronRunner}Interface	factory	chỉ phân giải khi nextpdf/premium được cài đặt

Mẫu mã — bắt đầu nhanh

resource: README.md Quick Start (verified against src/Laravel/Facades/Pdf.php)

<?php

declare(strict_types=1);

use NextPDF\Laravel\Facades\Pdf;

Pdf::addPage();
Pdf::cell(0, 10, 'Hello from Laravel', newLine: true);
Pdf::save(storage_path('app/hello.pdf'));

Để xem ví dụ có thể chạy được và giới hạn trong phạm vi một controller, hãy xem /integrations/laravel/quickstart/.

Mẫu mã — sản phẩm

Mẫu dành cho sản phẩm phân giải hợp đồng tài liệu từ container thay vì từ facade, giúp điểm gọi rõ ràng và có thể kiểm thử. Để xem controller đầy đủ, bao gồm tiêm phụ thuộc (DI) và xử lý lỗi, hãy xem /integrations/laravel/production-usage/.

resource: src/Laravel/Http/PdfResponse.php (download factory)

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

$document = app(PdfDocumentInterface::class);
$document->addPage();
$document->cell(0, 10, 'Invoice', newLine: true);

return PdfResponse::download($document, 'invoice.pdf');

Trường hợp đặc biệt & lưu ý

• Provider được trì hoãn, nên việc phân giải một khóa container không liên quan sẽ không khởi động NextPDF. Các ràng buộc chỉ xuất hiện khi bạn yêu cầu một trong các mục provides().
• SignerInterface và TsaClient được thiết kế để phân giải thành null khi bạn chưa cấu hình tính năng ký hoặc tổ chức cấp dấu thời gian. Mã của bạn phải kiểm tra null trên kết quả; đừng giả định luôn có instance.
• Các ràng buộc hợp đồng hóa đơn điện tử luôn được đăng ký, nhưng chúng phân giải thành các lớp cụ thể của Premium, vốn chỉ tồn tại khi nextpdf/premium được cài đặt. Việc phân giải chúng khi không có Premium sẽ gây lỗi không tìm thấy lớp, và lỗi này xuất hiện ở lần phân giải đầu tiên, không phải lúc khởi động.
• Facade trả về một tài liệu mới cho mỗi lần phân giải. Hãy xét hai lần gọi tĩnh Pdf:: trong cùng một yêu cầu, được phân tách bằng Pdf::clearResolvedInstances(): các lần gọi đó thao tác trên những tài liệu khác nhau.

Kiểm tra null cho các dịch vụ ký tùy chọn

SignerInterface và TsaClient là null cho đến khi bạn cấu hình tính năng ký và một tổ chức cấp dấu thời gian, nên bất kỳ mã nào phân giải các khóa này đều phải xử lý trường hợp null. Thiếu kiểm tra null sẽ gây lỗi lúc chạy, không phải lúc khởi động.

Hiệu năng

Việc đăng ký provider chạy trong thời gian O(1). Provider ràng buộc các closure và không khởi tạo đối tượng nặng, nên chi phí khởi tạo được trì hoãn đến lần phân giải đầu tiên. Việc làm nóng font registry chạy trong thời gian O(f), trong đó f là số tệp phông chữ được nạp sẵn, và chỉ chạy một lần cho mỗi tiến trình worker. Điều này phân bổ độ trễ của yêu cầu đầu tiên trong các worker tồn tại lâu dài. Ngân sách bộ nhớ mỗi trang cho phần tổng quan này được ghi trong trường front-matter performance_budget.

Lưu ý về bảo mật

PdfResponse áp dụng một bộ header cố định của Open Worldwide Application Security Project (OWASP). Bộ này bao gồm X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Content-Security-Policy: default-src 'none', X-Robots-Tag và Referrer-Policy: no-referrer. GeneratePdfJob xác thực đường dẫn đầu ra ở phía worker, giúp giảm thiểu rủi ro từ các payload đã tuần tự hóa bị giả mạo. Để xem mô hình mối đe dọa đầy đủ và cấu hình triển khai, hãy xem /integrations/laravel/security-and-operations/.

Payload của hàng đợi là đầu vào không đáng tin cậy

GeneratePdfJob xác thực lại đường dẫn đầu ra bên trong handle() trên worker, chứ không chỉ tại thời điểm điều phối. Vì payload đã tuần tự hóa có thể bị giả mạo trên kênh truyền tải hàng đợi (Redis hoặc cơ sở dữ liệu) trước khi worker nhận được, kiểm tra ở phía worker sẽ từ chối duyệt đường dẫn (path traversal), trình bao bọc luồng (stream wrapper), byte null và các đích đến không phải PDF.

Tuân thủ

Tuyên bố	Nguồn	Điều khoản	reference_id
Ngữ nghĩa phân giải / vòng đời của container	PSR-11 Container	§1.1.2
Ánh xạ tiền tố autoload của PSR-4	PSR-4 Autoloader	§3

Bối cảnh thương mại

Khi nextpdf/premium được cài đặt, cùng một provider hiển thị thêm nhiều khả năng: ký số (PAdES B-B), lưu trữ PDF/A và các ràng buộc hợp đồng hóa đơn điện tử. Provider hiển thị chúng thông qua cùng các khóa container, nên gói Core được mô tả ở đây không cần thay đổi mã để dùng các khả năng này. Để biết chi tiết, hãy xem https://nextpdf.dev/get-license/?intent=laravel-signing.

Xem thêm

• /integrations/laravel/install/ — quy trình cài đặt và các tiện ích mở rộng tùy chọn
• /integrations/laravel/quickstart/ — ví dụ controller có thể chạy được
• /integrations/laravel/configuration/ — mọi khóa cấu hình, được kiểm chứng đối chiếu với config/nextpdf.php
• /integrations/laravel/production-usage/ — controller được nối dây DI, xử lý lỗi và đưa vào hàng đợi
• /integrations/laravel/boot-and-discovery/ — tự động phát hiện và vòng đời ràng buộc
• /integrations/laravel/security-and-operations/ — mô hình mối đe dọa và cấu hình triển khai