เริ่มต้นใช้งาน NextPDF Laravel อย่างรวดเร็ว

ภาพรวมโดยย่อ

ในบทช่วยสอนนี้ คุณจะสร้างไฟล์ Portable Document Format (PDF) ที่ดาวน์โหลดได้จากคอนโทรลเลอร์ จากนั้นย้ายงานเดียวกันไปยังงานในคิว โค้ดตัวอย่างแต่ละส่วนสอดคล้องกับพฤติกรรมที่ชุดทดสอบของแพ็กเกจตรวจสอบยืนยันไว้

การติดตั้ง

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

ภาพรวมเชิงแนวคิด

จุดเริ่มต้นการใช้งานสามจุดครอบคลุมกรณีการใช้งาน Laravel เกือบทั้งหมด facade ช่วยให้เริ่มต้นได้เร็วที่สุด PdfResponse แปลงเอกสารเป็นการตอบกลับ Hypertext Transfer Protocol (HTTP) งานในคิวย้ายการสร้างที่ใช้ทรัพยากรมากออกจากเธรดของคำขอ ดังนั้นคุณจึงไม่ต้องรอ บทช่วยสอนนี้อธิบายจุดเริ่มต้นการใช้งานแต่ละจุดตามลำดับ เวอร์ชันระดับโปรดักชันซึ่งเพิ่มการจัดการข้อผิดพลาดอยู่ที่ /integrations/laravel/production-usage/

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

1. Facade (เฟซาด)

facade จะรีโซลฟ์เอกสารใหม่จากคอนเทนเนอร์ทุกครั้งที่เรียกใช้ คอนเทนเนอร์คือรีจิสทรีของบริการใน Laravel โค้ดตัวอย่างนี้สอดคล้องกับพฤติกรรมที่ tests/Unit/Laravel/Facades/PdfTest.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'));

2. การตอบกลับสำหรับดาวน์โหลดจากคอนโทรลเลอร์

PdfResponse::download() คืนค่า Illuminate\Http\Response พร้อม Content-Type: application/pdf การจัดวางแบบ attachment และส่วนหัวความปลอดภัยตาม Open Worldwide Application Security Project (OWASP) tests/Unit/Laravel/Http/PdfResponseTest.php ตรวจสอบรหัสสถานะ ชนิดเนื้อหา คำนำหน้าการจัดวาง และส่วนหัว

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

หากต้องการแสดงตัวอย่างแบบอินไลน์ในเบราว์เซอร์ ให้เปลี่ยนจาก download() เป็น inline() สำหรับเอกสารขนาดใหญ่ ให้ใช้ streamInline() หรือ streamDownload() ฟังก์ชันเหล่านี้ส่ง PDF เป็นชิ้นส่วนขนาด 64 KB ที่กำหนดแน่นอน

3. การสร้างผ่านคิว

GeneratePdfJob สร้างและบันทึก PDF บน queue worker โดย closure สำหรับสร้างเอกสารจะรับเอกสารที่รีโซลฟ์จากคอนเทนเนอร์ แล้วคืนค่าเอกสารที่กำหนดค่าแล้ว tests/Unit/Laravel/Jobs/GeneratePdfJobTest.php ยืนยันว่างานสร้างไฟล์ที่พาธเอาต์พุตตรงตามที่ระบุ

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

พาธเอาต์พุตต้องลงท้ายด้วย .pdf งานจะตรวจสอบความถูกต้องของพาธบน worker ก่อนเขียน

ตัวอย่างโค้ด — โปรดักชัน

เวอร์ชันโปรดักชันเพิ่มการจัดการข้อผิดพลาดที่ชัดเจน callback สำหรับกรณีสำเร็จและล้มเหลวของงาน และกลยุทธ์ exception ที่กำหนดชนิดไว้ รายละเอียดทั้งหมดมีเอกสารอยู่ที่ /integrations/laravel/production-usage/

กรณีขอบและข้อควรระวัง

facade คืนค่าอินสแตนซ์เอกสารคนละตัวในการรีโซลฟ์แต่ละครั้ง อย่าแคช Pdf::getFacadeRoot() ข้ามเอกสารเชิงตรรกะหลายฉบับ
หากคุณส่งชื่อไฟล์ว่างให้ factory ใดๆ ของ PdfResponse จะใช้ค่าเริ่มต้นเป็น document.pdf ชุดทดสอบการตอบกลับตรวจสอบยืนยันค่าเริ่มต้นนี้
ชื่อไฟล์ที่ไม่ใช่ ASCII จะได้รับพารามิเตอร์ RFC 5987 filename*= โดยอัตโนมัติ ส่วนชื่อแบบ ASCII จะไม่ได้รับ
GeneratePdfJob ปฏิเสธ path traversal, stream wrapper, ไบต์ว่าง (null byte) และนามสกุลใดๆ ที่ไม่ใช่ .pdf โดยจะโยน InvalidArgumentException บน worker

ประสิทธิภาพ

เอกสารหน้าเดียวสร้างเสร็จภายในงบประมาณเวลาต่อหน้าที่ระบุไว้ใน front matter ได้อย่างเหลือเฟือ การย้ายการสร้างไปยัง GeneratePdfJob ทำให้เวลาสร้าง PDF ไม่อยู่ในคำขอ HTTP อีกต่อไป คำขอจะคืนค่าทันทีที่ส่งงานเข้าคิว

หมายเหตุด้านความปลอดภัย

PdfResponse factory ใช้ชุดส่วนหัวตาม OWASP แบบตายตัว และทำความสะอาดชื่อไฟล์ที่ดาวน์โหลดด้วย งานในคิวจะตรวจสอบความถูกต้องของพาธเอาต์พุตของงานเอง รายละเอียดการครอบคลุมภัยคุกคามอยู่ที่ /integrations/laravel/security-and-operations/

ความสอดคล้องตามมาตรฐาน

ไม่มีมาตรฐานเชิงบรรทัดฐานที่กำกับบทช่วยสอนนี้ โค้ดตัวอย่างทุกชิ้นได้รับการตรวจสอบเทียบกับซอร์สของแพ็กเกจและการทดสอบในไดเรกทอรี tests/ ที่เกี่ยวข้อง

บริบทเชิงพาณิชย์

เอาต์พุตที่ลงนามแล้วและ PDF/A มีให้ใช้งานกับ nextpdf/premium ในฐานะความสามารถระดับ Enterprise เสริม แพ็กเกจ Core ที่อธิบายไว้ในที่นี้ไม่จำเป็นต้องเปลี่ยนโค้ดเพื่อนำไปใช้ ดู https://nextpdf.dev/get-license/?intent=laravel-signing สำหรับรายละเอียด

ดูเพิ่มเติม

/integrations/laravel/install/ — ติดตั้งและเผยแพร่การกำหนดค่า
/integrations/laravel/production-usage/ — คอนโทรลเลอร์และงานที่เชื่อมต่อด้วย dependency injection และการจัดการข้อผิดพลาด
/integrations/laravel/configuration/ — คีย์การกำหนดค่าที่ใช้ในที่นี้
/integrations/laravel/overview/ — สถาปัตยกรรมและอายุการใช้งานของ binding