Cài đặt gói NextPDF cho Laravel

Tổng quan nhanh

Cài đặt nextpdf/laravel bằng Composer. Tính năng tự động phát hiện của Laravel sẽ đăng ký service provider cho bạn. Hãy phát hành tệp cấu hình khi bạn muốn chỉnh sửa. Gói này tự động phát hiện các tiện ích mở rộng NextPDF tùy chọn.

Cài đặt

composer require nextpdf/laravel

Gói này khai báo các ràng buộc sau trong composer.json của nó:

Yêu cầu	Ràng buộc
PHP	`>=8.4 <9.0`
`laravel/framework`	`^12.0`
`nextpdf/core`	`^3.0 \|\| ^5.2`
`psr/http-client`	`^1.0`

Gói này được tự động nạp qua một bản đồ PHP Standard Recommendation 4 (PSR-4) duy nhất. Tiền tố NextPDF\Laravel\ ánh xạ tới src/Laravel/. Cách này tuân theo quy tắc ánh xạ tiền tố sang thư mục gốc của PSR-4 (PSR-4 §3).

Tổng quan khái niệm

Sau khi bạn chạy composer require, tính năng tự động phát hiện gói của Laravel sẽ đọc khối extra.laravel trong composer.json của gói này. Sau đó, nó đăng ký provider và facade alias cho bạn, nên bạn không cần chỉnh sửa thủ công config/app.php. Khối đó có dạng như sau:

{
  "extra": {
    "laravel": {
      "providers": [
        "NextPDF\\Laravel\\NextPdfServiceProvider"
      ],
      "aliases": {
        "Pdf": "NextPDF\\Laravel\\Facades\\Pdf"
      }
    }
  }
}

Tài liệu về gói của Laravel giải thích hành vi này. Mảng extra.laravel.providers tự động đăng ký các service provider, còn mảng extra.laravel.aliases tự động đăng ký các facade alias (hướng dẫn phát triển gói cho Laravel 12, https://laravel.com/docs/12.x/packages, truy xuất ngày 2026-05-18).

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

Dùng thẻ nextpdf-config để phát hành tệp cấu hình. Tên thẻ này được định nghĩa trong NextPdfServiceProvider::boot().

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

Lệnh này ghi config/nextpdf.php vào ứng dụng của bạn. Provider cũng hợp nhất cấu hình mặc định của gói dưới khóa nextpdf trong register(), nên gói vẫn hoạt động trước khi bạn phát hành. Việc phát hành giúp bạn có thể chỉnh sửa tệp này trong ứng dụng.

Xác nhận rằng Laravel đã phát hiện provider:

php artisan package:discover --ansi

Mẫu mã — môi trường production

Hãy ghim ràng buộc để các lần triển khai có thể tái lập. Chỉ tắt tính năng tự động phát hiện một cách tường minh nếu bạn tự đăng ký provider:

{
  "extra": {
    "laravel": {
      "dont-discover": [
        "nextpdf/laravel"
      ]
    }
  }
}

Khi tính năng tự động phát hiện bị tắt, hãy tự đăng ký provider trong bootstrap/providers.php:

<?php

declare(strict_types=1);

return [
    App\Providers\AppServiceProvider::class,
    NextPDF\Laravel\NextPdfServiceProvider::class,
];

Tiện ích mở rộng tùy chọn

Gói này liệt kê các gói đồng hành tùy chọn dưới suggest trong composer.json của nó. Gói sẽ phát hiện các gói đồng hành đã cài đặt tại thời điểm chạy:

Gói	Tác dụng khi được cài đặt	Điểm phát hiện
`nextpdf/artisan`	Cấu hình bộ kết xuất Hypertext Markup Language (HTML) qua Chrome DevTools Protocol (CDP) được áp dụng cho document binding khi có lớp factory của Chrome	`NextPdfServiceProvider::register()` kiểm tra lớp browser-factory của Chrome
`nextpdf/premium`	Các khóa container hiện có sẽ phân giải các concrete cho việc ký PDF Advanced Electronic Signatures (PAdES B-B), lưu trữ PDF/A, và contract hóa đơn điện tử	được phân giải trễ trong lần phân giải container đầu tiên

Cài đặt một tiện ích mở rộng theo cùng cách:

composer require nextpdf/artisan

Không cần đấu nối gì thêm. Provider sẽ phát hiện tiện ích mở rộng trong chu kỳ đăng ký tiếp theo.

Trường hợp biên & điểm cần lưu ý

Việc phát hành có tính bất biến (idempotent). Nó không ghi đè lên config/nextpdf.php đang tồn tại. Thêm --force khi bạn muốn chủ động ghi đè.
Provider được trì hoãn (deferred), nên một lần php artisan package:discover thành công là đủ để xác nhận gói. Bản thân các binding chỉ xuất hiện ở lần phân giải đầu tiên.
Gói này hỗ trợ nextpdf/core trên cả hai dòng major ^3.0 và ^5.2. Hãy khớp ràng buộc core với dòng mà ứng dụng của bạn đã ghim. Bề mặt adapter Laravel giống nhau trên cả hai dòng.
Huy hiệu README và composer.json thống nhất ở Apache-2.0. Gói này đã được cấp lại giấy phép từ LGPL-3.0-or-later. Các phiên bản đã gắn thẻ trước khi di chuyển vẫn nằm dưới giấy phép trước đó (xem CHANGELOG.md).

Hiệu năng

Việc phân giải nextpdf/core chiếm phần lớn chi phí của composer require. Việc đăng ký provider không thêm chi phí khởi động nào đo được vì tất cả các binding đều là closure được trì hoãn. Xem /integrations/laravel/boot-and-discovery/ để biết chi phí khởi tạo ở lần phân giải đầu tiên.

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

Hãy cài đặt từ gói Packagist chính thức nextpdf/laravel. Gói này đi kèm các tiêu đề REUSE theo Software Package Data Exchange (SPDX) và tệp NOTICE Apache-2.0. Hãy ghim ràng buộc trong composer.json và commit composer.lock để các worker đã triển khai phân giải đúng cây phụ thuộc đã được xác minh.

Sự tuân thủ

Tuyên bố	Nguồn	Điều khoản	reference_id
Tiền tố PSR-4 ánh xạ tới thư mục gốc	PSR-4 Autoloader	§3

Tên các khóa tự động phát hiện của Laravel đã được xác minh theo tài liệu phát triển gói chính thức cho Laravel 12 (https://laravel.com/docs/12.x/packages, truy xuất ngày 2026-05-18).

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

nextpdf/premium bổ sung các concrete cho việc ký, PDF/A và hóa đơn điện tử như một khả năng Enterprise tùy chọn. Bạn có thể áp dụng mà không cần thay đổi gói Core được mô tả ở đây. Xem https://nextpdf.dev/get-license/?intent=laravel-signing.

Xem thêm

/integrations/laravel/overview/ — kiến trúc gói và bảng binding
/integrations/laravel/quickstart/ — controller chạy được đầu tiên
/integrations/laravel/configuration/ — giải thích mọi khóa cấu hình
/integrations/laravel/boot-and-discovery/ — cơ chế nội bộ của tính năng tự động phát hiện và vòng đời binding