Tài liệu tham khảo API Laravel

Tổng quan nhanh

Gói nextpdf/laravel kết nối lõi NextPDF độc lập với framework vào ứng dụng Laravel. Bạn gọi trực tiếp bốn điểm vào: facade Pdf cho các luồng soạn thảo ngắn, ràng buộc container PdfDocumentInterface để tạo tài liệu có thể tiêm, helper PdfResponse cho phản hồi HTTP từ tài liệu đã hoàn tất, và job hàng đợi GeneratePdfJob để tạo tài liệu ngoài chu kỳ request. NextPdfServiceProvider đăng ký từng ràng buộc và được tự động phát hiện, nên bạn không cần thiết lập thủ công. Cấu hình trong config/nextpdf.php kiểm soát các giá trị mặc định, phông chữ, hàng đợi, cùng các tính năng tùy chọn về chữ ký và đơn vị cấp dấu thời gian (TSA).

Bắt đầu tại đây: để gửi trực tiếp một tệp Định dạng tài liệu di động (PDF) từ controller, hãy dựng tài liệu rồi trả về PdfResponse::download($document, 'file.pdf'). Ví dụ đầu tiên bên dưới minh họa luồng này.

Tác vụ thường gặp

Các đoạn mã bên dưới bao quát ba luồng bạn thường dùng trước tiên. Mỗi đoạn mã đã được kiểm chứng dựa trên mã nguồn của gói; bảng đầy đủ theo từng ký hiệu nằm ở phần sau.

Trả về một tệp PDF có thể tải xuống từ controller. Đây là tác vụ thường gặp nhất:

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

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

final class ReportController extends Controller
{
    public function download(PdfDocumentInterface $document): Response
    {
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

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

Tác dụng: tiêm một tài liệu mới, ghi một dòng và trả về phản hồi attachment kèm Content-Type: application/pdf cùng các tiêu đề bảo mật của Dự án bảo mật ứng dụng nguồn mở toàn cầu (OWASP). Dùng inline() thay cho download() để xem trước trong trình duyệt.

Soạn thảo và lưu bằng facade Pdf. Đây là cách gọn nhất cho script và các luồng ngắn:

<?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'));

Tác dụng: facade phân giải một tài liệu mới từ container, ghi một ô và lưu tệp PDF đã hoàn tất xuống ổ đĩa.

Tạo một tệp PDF ngoài luồng request bằng GeneratePdfJob:

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Jobs\GeneratePdfJob;

GeneratePdfJob::dispatch(
    storage_path('app/reports/january-2026.pdf'),
    static fn (PdfDocumentInterface $document): PdfDocumentInterface => $document
        ->addPage()
        ->cell(0, 10, 'January report', newLine: true),
);

Tác dụng: đưa việc tạo tài liệu vào hàng đợi trên một worker. Closure builder nhận tài liệu do container phân giải và trả về chính tài liệu đó. Job xác thực đường dẫn xuất .pdf trước khi lưu. Tên hàng đợi, thời gian chờ và kết nối lấy từ config('nextpdf.queue.*').

Facade

Facade Pdf ủy quyền tĩnh cho một lõi Document mới. Hãy dùng facade này trong các luồng controller ngắn khi kiểu tĩnh đã rõ ràng. Mỗi hàng liệt kê một phương thức tài liệu được ủy quyền.

Ký hiệu	Tham số	Hành vi mặc định	Giá trị trả về	Ném ra hoặc thất bại với	Ghi chú
`NextPDF\Laravel\Facades\Pdf`	không có; bộ truy cập facade tĩnh phân giải `NextPDF\Contracts\PdfDocumentInterface`	Laravel phân giải ràng buộc container hiện tại cho giao diện tài liệu.	API fluent của tài liệu lõi nền tảng.	Lỗi ràng buộc container của Laravel nếu provider chưa được đăng ký.	Hãy dùng facade này cho các luồng controller ngắn. Ưu tiên tiêm qua hàm khởi tạo cho service và job.
`Pdf::setTitle(string $title)`	`title`: tiêu đề tài liệu.	Thay thế mọi tiêu đề hiện có.	`static`	Lỗi xác thực lõi hoặc lỗi tại thời điểm ghi.	Ủy quyền cho lõi `Document`.
`Pdf::setAuthor(string $author)`	`author`: siêu dữ liệu tác giả của tài liệu.	Thay thế mọi tác giả trước đó.	`static`	Lỗi xác thực siêu dữ liệu lõi.	Hãy ưu tiên các giá trị mặc định đã cấu hình cho siêu dữ liệu áp dụng trên toàn ứng dụng.
`Pdf::addPage(?PageSize $size = null, Orientation $orientation = Portrait)`	`size`: kích thước trang tùy chọn; `orientation`: `Portrait` theo mặc định.	Dùng kích thước trang đã cấu hình hoặc mặc định khi bỏ qua `size`.	`static`	Lỗi xác thực trang lõi.	Hãy chỉ định `PageSize` rõ ràng khi kích thước đầu ra quan trọng.
`Pdf::setFont(string $family, string $style = '', float $size = 12.0)`	Họ phông chữ, kiểu chữ và cỡ điểm.	Dùng kiểu chữ rỗng và cỡ 12 pt.	`static`	Lỗi sổ đăng ký phông chữ hoặc lỗi mã hóa.	Hãy nạp trước các phông chữ dùng trong môi trường sản xuất qua `nextpdf.preload_fonts` khi độ trễ là yếu tố quan trọng.
`Pdf::cell(float $width, float $height, string $text = '', bool $border = false, bool $newLine = false, Alignment $align = Left)`	Hộp ô, văn bản, cờ viền, cờ xuống dòng và canh lề.	Dùng văn bản rỗng, không viền, không xuống dòng và canh lề trái.	`static`	Lỗi bố cục hoặc lỗi mã hóa văn bản.	Dùng cho đầu ra có bố cục cố định đơn giản.
`Pdf::multiCell(float $width, float $height, string $text, bool $border = false, Alignment $align = Left)`	Chiều rộng ô, chiều cao dòng, văn bản, cờ viền, canh lề.	Không viền và canh lề trái.	`static`	Lỗi bố cục hoặc lỗi mã hóa văn bản.	Dùng khi văn bản cần tự xuống dòng trong một chiều rộng cố định.
`Pdf::writeHtml(string $html)`	`html`: đoạn HTML.	Kết xuất trên trang hiện tại và tạo thêm trang khi cần.	`static`	Lỗi kết xuất HTML lõi.	Hãy áp dụng chính sách về kích thước đầu vào và tài nguyên trước khi chấp nhận HTML không đáng tin cậy.
`Pdf::image(string $file, ?float $x = null, ?float $y = null, ?float $width = null, ?float $height = null)`	Đường dẫn tệp và hình chữ nhật vị trí tùy chọn.	Khi bỏ qua tọa độ, để tài liệu lõi tự chọn vị trí hiện tại và kích thước nội tại.	`static`	Lỗi giải mã ảnh, lỗi đường dẫn hoặc lỗi bố cục.	Hãy xác thực chính sách về nguồn ảnh trước khi chấp nhận đường dẫn do người dùng cung cấp.
`Pdf::output(?string $filename = null, OutputDestination $dest = Inline)`	`filename`: tên tùy chọn; `dest`: đích xuất.	Xuất nội tuyến khi bỏ qua đích.	`string`	Lỗi tuần tự hóa lõi.	Hãy ưu tiên `PdfResponse` cho các phản hồi HTTP của Laravel.
`Pdf::save(string $path)`	`path`: đích trên hệ thống tệp.	Ghi tệp PDF đã hoàn tất xuống ổ đĩa.	`void`	Lỗi hệ thống tệp hoặc lỗi ghi lõi.	Hãy xác thực các thư mục đầu ra trong mã ứng dụng.
`Pdf::getPdfData()`	không có.	Hiện thực hóa các byte PDF trong bộ nhớ.	`string`	Lỗi tuần tự hóa lõi.	Dùng khi một đối tượng framework khác cần sở hữu phần thân phản hồi.

Service provider và các ràng buộc

Hãy dùng bảng này khi bạn cần phân giải hoặc ghi đè trực tiếp một mục trong container, chẳng hạn như tiêm DocumentFactoryInterface vào service hoặc kiểm tra những gì provides() trì hoãn.

Ký hiệu	Tham số	Hành vi mặc định	Giá trị trả về	Ném ra hoặc thất bại với	Ghi chú
`NextPdfServiceProvider::register()`	không có.	Hợp nhất `config/nextpdf.php`; đăng ký các sổ đăng ký, document factory, ràng buộc tài liệu, HTTP client, TSA client, signer và các contract hóa đơn điện tử tùy chọn.	`void`	Lỗi phân giải container hoặc lỗi phân giải lớp tùy chọn khi một tính năng được dùng.	`FontRegistryInterface` và `ImageRegistry` được dùng chung; tài liệu luôn là bản mới.
`NextPdfServiceProvider::boot()`	không có.	Xác thực các phần mở rộng PHP bắt buộc và phát hành `nextpdf-config` ở chế độ console.	`void`	`RuntimeException` nếu một phần mở rộng bắt buộc không khả dụng.	Các phần mở rộng bắt buộc là `mbstring` và `zlib`.
`NextPdfServiceProvider::provides()`	không có.	Báo cáo các ID service được trì hoãn.	`array<string>`	không kỳ vọng có lỗi nào.	Bao gồm `PdfDocumentInterface`, `DocumentFactoryInterface`, `FontRegistryInterface`, `SignerInterface`, `TsaClient`, `ClientInterface` và `nextpdf`.
`PdfDocumentInterface` / `nextpdf`	được phân giải từ container của Laravel.	Tạo một `Document` dùng một lần qua `DocumentFactoryInterface`, sau đó áp dụng các giá trị mặc định đã cấu hình cùng thiết lập PDF/A hoặc Artisan tùy chọn.	`NextPDF\Core\Document`	Lỗi phần mở rộng tùy chọn khi đã cấu hình nhưng không khả dụng.	Hãy phân giải một tài liệu mới cho mỗi request hoặc job.
`DocumentFactoryInterface`	được phân giải từ container của Laravel.	Factory singleton dùng chung các sổ đăng ký phông chữ và ảnh có vòng đời bằng tiến trình.	`DocumentFactoryInterface`	Lỗi thiết lập sổ đăng ký.	Dùng mục này để tiêm phụ thuộc một cách tường minh.
`SignerInterface`	được phân giải từ container của Laravel.	Trả về `null` trừ khi `nextpdf.signature.enabled` được đặt và các đường dẫn chứng chỉ đã được cấu hình.	`SignerInterface	null`	Lỗi tải chứng chỉ hoặc lỗi xác thực ở cấp chữ ký.

Cấu hình

Hãy dùng bảng này để tra cứu các khóa nextpdf.* hướng tới thời gian chạy mà các ràng buộc đọc. Tài liệu tham khảo đầy đủ theo từng khóa, bao gồm biến môi trường và giá trị mặc định, nằm tại /integrations/laravel/configuration/.

Khóa	Kiểu	Hành vi mặc định	Ghi chú
`nextpdf.fonts_path`	`string`	Dùng phông chữ tài nguyên của Laravel khi bỏ qua.	Thư mục cho phông chữ tùy chỉnh và nạp khởi động.
`nextpdf.cache_path`	`string`	Đường dẫn cache của ứng dụng.	Hãy bảo đảm worker PHP có thể ghi vào đó.
`nextpdf.preload_fonts`	`list<string>`	Danh sách rỗng.	Được nạp trong lúc tạo sổ đăng ký; sau đó sổ đăng ký bị khóa.
`nextpdf.image_cache_mb`	`int`	Kích thước cache ảnh có giới hạn.	Giới hạn bộ nhớ cache ảnh có vòng đời theo tiến trình.
`nextpdf.defaults.*`	`array`	Creator `NextPDF`, ngôn ngữ `en`, các giá trị mặc định tùy chọn về tác giả và bố cục.	Áp dụng cho từng tài liệu mới.
`nextpdf.artisan.*`	`array`	Trình kết xuất Chrome bị tắt trừ khi được cài đặt và cấu hình.	Ánh xạ tới `ChromeRendererConfig::fromArray()`.
`nextpdf.signature.*`	`array`	Tính năng chữ ký bị tắt theo mặc định.	Chứng chỉ, khóa riêng tư, mật khẩu, các chứng chỉ bổ sung và cấp chữ ký.
`nextpdf.tsa.*`	`array`	TSA bị tắt khi Định vị tài nguyên thống nhất (URL) để trống.	Hỗ trợ thông tin xác thực, tệp Bảo mật tầng giao vận tương hỗ (mTLS), thời gian chờ, ghim khóa công khai và chính sách HTTP.
`nextpdf.ocsp_cache.*`	`array`	Cache Giao thức trạng thái chứng chỉ trực tuyến (OCSP) được bật với TTL đã cấu hình.	Được các luồng xác thực chữ ký sử dụng khi có sẵn.

Phản hồi HTTP

Hãy dùng bảng này khi bạn trả về một tài liệu đã hoàn tất qua HTTP và cần chọn hiển thị nội tuyến, tải xuống dưới dạng đính kèm hoặc đầu ra dạng luồng.

Ký hiệu	Tham số	Hành vi mặc định	Giá trị trả về	Ném ra hoặc thất bại với	Ghi chú
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: tài liệu đã dựng; `filename`: tên tệp Content-Disposition.	Chuẩn hóa tên tệp rỗng thành `document.pdf`.	`Illuminate\Http\Response`	Lỗi tuần tự hóa lõi hoặc lỗi dựng phản hồi.	Đặt kiểu nội dung PDF và các tiêu đề phòng vệ.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	Giống như `inline`; disposition là attachment.	Trả về phản hồi tải xuống cho trình duyệt.	`Illuminate\Http\Response`	Giống như `inline`.	Dùng cho các trường hợp tải tệp xuống một cách tường minh.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	Giống như `inline`.	Hiện thực hóa các byte PDF, sau đó phát ra các khối 64 KB.	`Symfony\Component\HttpFoundation\StreamedResponse`	Giống như `inline`.	Đây là đầu ra HTTP dạng luồng, không phải kết xuất sao chép bằng không (zero-copy).
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	Giống như `streamInline`; disposition là attachment.	Phản hồi luồng tải xuống.	`StreamedResponse`	Giống như `streamInline`.	Hãy áp dụng giới hạn kích thước đầu vào và đầu ra trước khi kết xuất.

Job hàng đợi

Hãy dùng bảng này khi bạn chuyển việc tạo tài liệu ra ngoài luồng request. Bảng bao quát việc khởi tạo, điều phối và các callback thành công hoặc thất bại cho GeneratePdfJob.

Ký hiệu	Tham số	Hành vi mặc định	Giá trị trả về	Ném ra hoặc thất bại với	Ghi chú
`new GeneratePdfJob(string $outputPath, callable $builder, ?callable $onSuccess = null, ?callable $onFailure = null)`	`outputPath`: đích `.pdf`; `builder`: nhận một `PdfDocumentInterface`; các callback là tùy chọn.	Tên hàng đợi, thời gian chờ và kết nối được đọc từ `config('nextpdf.queue.*')`.	Thực thể job.	Lỗi tuần tự hóa nếu builder hoặc các callback không thể tuần tự hóa.	Builder phải trả về tài liệu đã được cấu hình.
`GeneratePdfJob::handle()`	không có.	Phân giải `PdfDocumentInterface`, áp dụng builder, xác thực đường dẫn đầu ra, rồi lưu.	`void`	`InvalidArgumentException` cho các đường dẫn đầu ra không an toàn; lỗi ghi lõi.	Từ chối các stream wrapper, byte null, các đoạn `..` và các đường dẫn không phải `.pdf`.
`GeneratePdfJob::failed(Throwable $exception)`	`exception`: nguyên nhân thất bại.	Gọi callback thất bại đã cấu hình khi có.	`void`	Lỗi callback.	Hãy giữ cho các callback có tính lũy đẳng.
`GeneratePdfJob::then(callable $callback)`	`callback`: nhận đường dẫn đầu ra.	Thay thế callback thành công.	`self`	Lỗi closure có thể tuần tự hóa.	Helper fluent cho việc thiết lập điều phối.
`GeneratePdfJob::catch(callable $callback)`	`callback`: nhận `Throwable` được ném ra.	Thay thế callback thất bại.	`self`	Lỗi closure có thể tuần tự hóa.	Dùng để cảnh báo hoặc dọn dẹp bù trừ.

Ghi chú phát triển

PdfResponse luôn gọi getPdfData() trước khi dựng phản hồi. Đây không phải là trình dựng tài liệu lười.
Tải trọng hàng đợi có thể bị giả mạo trên các phương tiện truyền dùng chung; hãy giữ đường dẫn đầu ra trong thư mục do ứng dụng sở hữu.
Hãy dùng một tài liệu mới cho mỗi request hoặc job. Đừng tái sử dụng tài liệu giữa các request.