Bắt đầu nhanh với NextPDF Laravel

Tổng quan nhanh

Trong hướng dẫn này, bạn sẽ tạo một tệp Portable Document Format (PDF) có thể tải xuống từ một controller. Sau đó, bạn chuyển cùng tác vụ đó sang một job trong hàng đợi. Mỗi đoạn mã đều khớp với hành vi mà bộ kiểm thử của gói xác nhận.

Cài đặt

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

Tổng quan khái niệm

Ba điểm vào bao phủ hầu như mọi trường hợp sử dụng Laravel. Facade là cách nhanh nhất để bắt đầu. PdfResponse biến một tài liệu thành phản hồi Hypertext Transfer Protocol (HTTP). Một job trong hàng đợi chuyển phần tạo tài liệu nặng ra khỏi luồng xử lý yêu cầu, nên bạn không phải chờ quá trình đó. Hướng dẫn này lần lượt đi qua từng điểm vào. Các phiên bản cấp sản xuất có bổ sung xử lý lỗi và nằm tại /integrations/laravel/production-usage/.

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

1. Facade

Facade phân giải một tài liệu mới từ container cho mỗi lần gọi. Container là nơi đăng ký dịch vụ của Laravel. Đoạn mã này khớp với hành vi mà tests/Unit/Laravel/Facades/PdfTest.php xác nhậ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'));

2. Phản hồi tải xuống từ một controller

PdfResponse::download() trả về một Illuminate\Http\Response với Content-Type: application/pdf, kiểu disposition attachment, cùng các tiêu đề bảo mật Open Worldwide Application Security Project (OWASP). tests/Unit/Laravel/Http/PdfResponseTest.php kiểm tra mã trạng thái, kiểu nội dung, tiền tố disposition và các tiêu đề.

<?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(): Response
    {
        $document = app(PdfDocumentInterface::class);
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

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

Để hiển thị bản xem trước nội tuyến trong trình duyệt, hãy thay download() bằng inline(). Với tài liệu lớn, hãy dùng streamInline() hoặc streamDownload(). Các phương thức này gửi PDF theo từng khối 64 KB xác định.

3. Tạo bằng hàng đợi

GeneratePdfJob tạo và lưu một PDF trên một queue worker. Closure builder nhận tài liệu đã được phân giải từ container và trả về tài liệu đã cấu hình. tests/Unit/Laravel/Jobs/GeneratePdfJobTest.php xác nhận rằng job tạo tệp tại đúng đường dẫn đầu ra.

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

Đường dẫn đầu ra phải kết thúc bằng .pdf. Job xác thực đường dẫn trên worker trước khi ghi tệp.

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

Các phiên bản sản xuất bổ sung cách xử lý lỗi rõ ràng, callback thành công và thất bại trên job, cùng một chiến lược exception có kiểu. Chúng được ghi chép đầy đủ tại /integrations/laravel/production-usage/.

Trường hợp biên và lưu ý

Facade trả về một thực thể tài liệu khác cho mỗi lần phân giải. Đừng lưu Pdf::getFacadeRoot() vào bộ nhớ đệm để dùng qua nhiều tài liệu logic.
Nếu bạn truyền một tên tệp trống vào bất kỳ factory PdfResponse nào, nó sẽ mặc định là document.pdf. Bộ kiểm thử phản hồi khẳng định giá trị mặc định này.
Tên tệp không phải ASCII tự động nhận tham số RFC 5987 filename*=. Tên ASCII thì không.
GeneratePdfJob từ chối path traversal, stream wrapper, byte null và mọi phần mở rộng không phải .pdf. Nó ném InvalidArgumentException trên worker.

Hiệu năng

Một tài liệu một trang được tạo trong giới hạn thời gian thực thi cho mỗi trang được liệt kê trong front matter. Việc chuyển quá trình tạo sang GeneratePdfJob loại bỏ hoàn toàn thời gian dựng PDF khỏi yêu cầu HTTP. Yêu cầu trả về ngay khi job được dispatch.

Ghi chú bảo mật

PdfResponse factory áp dụng một bộ tiêu đề OWASP cố định. Các factory này cũng làm sạch tên tệp tải xuống. Job trong hàng đợi xác thực đường dẫn đầu ra của nó. Thông tin chi tiết về các mối đe dọa có tại /integrations/laravel/security-and-operations/.

Tuân thủ

Không có tiêu chuẩn quy chuẩn nào chi phối hướng dẫn này. Mỗi đoạn mã đều được kiểm chứng đối chiếu với mã nguồn của gói và bài kiểm thử tương ứng trong tests/.

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

Đầu ra có chữ ký và PDF/A có sẵn với nextpdf/premium dưới dạng một năng lực Enterprise tùy chọn. Gói Core được ghi chép ở đây không cần thay đổi mã nào để áp dụng năng lực đó. Xem https://nextpdf.dev/get-license/?intent=laravel-signing.

Xem thêm

/integrations/laravel/install/ — cài đặt và publish cấu hình
/integrations/laravel/production-usage/ — controller và job được kết nối với dependency injection và cơ chế xử lý lỗi
/integrations/laravel/configuration/ — các khóa cấu hình được dùng ở đây
/integrations/laravel/overview/ — kiến trúc và vòng đời của binding