Tích hợp NextPDF vào Laravel

Tổng quan nhanh

Hướng dẫn này thiết lập NextPDF trong ứng dụng Laravel 12. Bạn sẽ đi qua sáu giai đoạn: cài đặt gói, để Laravel tự động khám phá gói, xuất bản tệp cấu hình, phân giải các ràng buộc trong container, trả về phản hồi Hypertext Transfer Protocol (HTTP) và chạy một tác vụ nền. Mỗi giai đoạn đều dẫn đến tài liệu tham khảo chi tiết tương ứng.

Cài đặt

composer require nextpdf/laravel
php artisan vendor:publish --tag=nextpdf-config

Khởi động/tự động khám phá

Laravel tự động khám phá service provider và facade alias từ khối composer.jsonextra.laravel của gói. Bạn không cần chỉnh sửa config/app.php. Bản đồ autoload chỉ dùng một mục PSR-4. Tiền tố NextPDF\Laravel\ phân giải thành src/Laravel/ theo quy tắc ánh xạ tiền tố sang thư mục gốc của PSR-4 (PSR-4 §3). Vì provider được trì hoãn, nó chỉ khởi động khi một trong các mục provides() của nó được phân giải lần đầu. Để xem chi tiết bên trong quá trình khám phá, hãy xem /integrations/laravel/boot-and-discovery/.

Ràng buộc container

Phân giải document contract từ container. Một định danh đã được ràng buộc sẽ phân giải thành mục đã đăng ký của nó (PSR-11 §1.1.2). Ràng buộc document là một factory, nên mỗi lần phân giải sẽ trả về một tài liệu mới. Các registry phông chữ và hình ảnh là singleton, nên mỗi lần phân giải sẽ trả về cùng một thực thể dùng chung. Để xem bảng đầy đủ về vòng đời ràng buộc, hãy xem /integrations/laravel/overview/ và /integrations/laravel/boot-and-discovery/.

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;

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

Xuất bản tệp cấu hình

php artisan vendor:publish --tag=nextpdf-config

Lệnh này ghi ra config/nextpdf.php. Tài liệu tham khảo cấu hình tại /integrations/laravel/configuration/ trình bày từng khóa, biến môi trường tương ứng và giá trị mặc định của khóa đó.

Kiểm tra nhanh service provider/bundle

Gói này bao gồm một bộ kiểm thử dựa trên Testbench để kiểm tra toàn diện provider. Hãy thêm bài kiểm tra nhanh tối thiểu này vào ứng dụng đang sử dụng gói:

<?php

declare(strict_types=1);

namespace Tests\Feature;

use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Typography\FontRegistry;
use Tests\TestCase;

final class NextPdfIntegrationTest extends TestCase
{
    public function test_document_is_factory_bound(): void
    {
        $a = app(PdfDocumentInterface::class);
        $b = app(PdfDocumentInterface::class);

        self::assertNotSame($a, $b);
    }

    public function test_font_registry_is_singleton_and_locked(): void
    {
        $registry = app(FontRegistryInterface::class);

        self::assertInstanceOf(FontRegistry::class, $registry);
        self::assertTrue($registry->isLocked());
    }
}

Hai khẳng định này phản ánh các kiểm tra tuân thủ dùng một lần của gói trong EInvoiceServiceProviderIntegrationTest. Chúng xác nhận rằng tài liệu được ràng buộc theo kiểu factory và registry phông chữ là một singleton đã khóa.

Các điểm vào API công khai

Điểm vào	Mục đích	Tham khảo
`NextPDF\Laravel\Facades\Pdf`	Proxy tĩnh đến một tài liệu mới	/integrations/laravel/quickstart/
`app(NextPDF\Contracts\PdfDocumentInterface::class)`	Tài liệu được phân giải qua container	/integrations/laravel/production-usage/
`NextPDF\Laravel\Http\PdfResponse`	Phản hồi HTTP dạng nội tuyến, tải xuống và truyền luồng	/integrations/laravel/security-and-operations/
`NextPDF\Laravel\Jobs\GeneratePdfJob`	Tạo tệp qua hàng đợi	/integrations/laravel/production-usage/

Mẫu mã — Sản xuất

Controller đầy đủ tại /integrations/laravel/production-usage/ trình bày dependency injection và xử lý lỗi. Trang đó cũng trình bày tác vụ chạy nền cùng các callback thành công và thất bại của tác vụ.

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

Hãy phân giải PdfDocumentInterface, không phải lớp cụ thể Document, để ràng buộc vẫn dễ kiểm thử và có thể thay thế.
SignerInterface và TsaClient phân giải thành null cho đến khi được cấu hình. Luôn kiểm tra giá trị null.
Các contract hóa đơn điện tử yêu cầu nextpdf/premium. Chúng được ràng buộc nhưng sẽ báo lỗi ở lần phân giải đầu tiên nếu thiếu nó.

Hiệu năng

Việc kết nối đầy đủ không làm tăng chi phí khởi động vì provider được trì hoãn. Chi phí khởi tạo ở lần phân giải đầu tiên và chi phí làm nóng phông chữ được trình bày tại /integrations/laravel/boot-and-discovery/.

Lưu ý bảo mật

PdfResponse áp dụng một bộ header cố định của Open Worldwide Application Security Project (OWASP). GeneratePdfJob xác thực đường dẫn đầu ra trên worker. Hãy xem /integrations/laravel/security-and-operations/ để biết mô hình mối đe dọa.

Tuân thủ

Tuyên bố	Nguồn	Điều khoản	reference_id
Định danh đã được ràng buộc phân giải thành mục đã đăng ký của nó	PSR-11 Container	§1.1.2
Tiền tố PSR-4 ánh xạ tới thư mục gốc	PSR-4 Autoloader	§3

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

Khi nextpdf/premium được cài đặt, các contract ký, PDF/A và hóa đơn điện tử đều tích hợp qua cùng một provider. Gói Core được mô tả ở đây không cần thay đổi mã để sử dụng khả năng Enterprise tùy chọn này. Hãy xem https://nextpdf.dev/get-license/?intent=laravel-signing.

Xem thêm

/integrations/laravel/overview/ — kiến trúc và bảng ràng buộc
/integrations/laravel/install/ — cài đặt và các phần mở rộng tùy chọn
/integrations/laravel/quickstart/ — ví dụ chạy được đầu tiên
/integrations/laravel/production-usage/ — dependency injection, xử lý lỗi và hàng đợi
/integrations/laravel/boot-and-discovery/ — khám phá và vòng đời