การผสานรวม NextPDF ใน Laravel

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

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

การติดตั้ง

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

การบูต/การค้นพบอัตโนมัติ

Laravel ค้นพบ service provider และ facade alias โดยอัตโนมัติจากบล็อก composer.jsonextra.laravel ของแพ็กเกจ คุณไม่จำเป็นต้องแก้ไข config/app.php แมป autoload ใช้รายการ PSR-4 เพียงรายการเดียว คือคำนำหน้า NextPDF\Laravel\ ซึ่งรีโซลฟ์ไปยัง src/Laravel/ ตามกฎการแมปคำนำหน้าไปยังไดเรกทอรีฐานของ PSR-4 (PSR-4 §3) เนื่องจาก provider เป็นแบบเลื่อนการทำงาน (deferred) จึงจะบูตเฉพาะเมื่อมีการรีโซลฟ์รายการใดรายการหนึ่งใน provides() เป็นครั้งแรกเท่านั้น ดูรายละเอียดภายในของการค้นพบทั้งหมดได้ที่ /integrations/laravel/boot-and-discovery/

การผูกบริการในคอนเทนเนอร์

รีโซลฟ์สัญญา (contract) ของเอกสารจากคอนเทนเนอร์ ตัวระบุที่ผูกไว้จะรีโซลฟ์ไปยังรายการที่ลงทะเบียนไว้ (PSR-11 §1.1.2) การผูกบริการของเอกสารเป็นแบบ factory ดังนั้นการรีโซลฟ์แต่ละครั้งจะส่งคืนเอกสารใหม่ รีจิสทรีของฟอนต์และรูปภาพเป็นแบบ singleton ดังนั้นการรีโซลฟ์แต่ละครั้งจะส่งคืนอินสแตนซ์ร่วมตัวเดิม ดูตารางอายุการใช้งานของการผูกบริการทั้งหมดได้ที่ /integrations/laravel/overview/ และ /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);

เผยแพร่ไฟล์การกำหนดค่า

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

คำสั่งนี้จะเขียนไฟล์ config/nextpdf.php เอกสารอ้างอิงการกำหนดค่าอธิบายคีย์ทุกตัว ตัวแปรสภาพแวดล้อม และค่าเริ่มต้นของแต่ละคีย์ไว้ที่ /integrations/laravel/configuration/

Smoke test สำหรับ service provider/bundle

แพ็กเกจมีชุดทดสอบที่ใช้ Testbench ซึ่งทดสอบ provider แบบครบวงจร เพิ่ม smoke test ขั้นต่ำนี้ลงในแอปพลิเคชันที่ใช้งานแพ็กเกจ:

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

การยืนยันสองรายการนี้สอดคล้องกับการตรวจสอบความสอดคล้องแบบครั้งเดียวของแพ็กเกจใน EInvoiceServiceProviderIntegrationTest และยืนยันว่าเอกสารถูกผูกแบบ factory ส่วนรีจิสทรีของฟอนต์เป็น singleton ที่ถูกล็อก

จุดเข้าใช้งาน API สาธารณะ

จุดเข้าใช้งาน	วัตถุประสงค์	เอกสารอ้างอิง
`NextPDF\Laravel\Facades\Pdf`	พร็อกซีแบบ static สำหรับเอกสารใหม่	เริ่มต้นใช้งานอย่างรวดเร็ว — /integrations/laravel/quickstart/
`app(NextPDF\Contracts\PdfDocumentInterface::class)`	เอกสารที่รีโซลฟ์ผ่านคอนเทนเนอร์	การใช้งานในโปรดักชัน — /integrations/laravel/production-usage/
`NextPDF\Laravel\Http\PdfResponse`	การตอบสนอง HTTP แบบ inline, download และ streamed	ความปลอดภัยและการดำเนินงาน — /integrations/laravel/security-and-operations/
`NextPDF\Laravel\Jobs\GeneratePdfJob`	การสร้างแบบเข้าคิว	การใช้งานในโปรดักชัน — /integrations/laravel/production-usage/

ตัวอย่างโค้ด — Production

คอนโทรลเลอร์ฉบับเต็มแสดง dependency injection และการจัดการข้อผิดพลาดอยู่ใน /integrations/laravel/production-usage/ หน้าเดียวกันนี้ยังครอบคลุมงานที่เข้าคิว รวมถึงคอลแบ็กกรณีสำเร็จและกรณีล้มเหลว

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

ให้รีโซลฟ์ PdfDocumentInterface แทนการใช้คลาส Document โดยตรง เพื่อให้การผูกบริการยังคงทดสอบได้และสับเปลี่ยนได้
SignerInterface และ TsaClient จะรีโซลฟ์เป็น null จนกว่าจะมีการกำหนดค่า ต้องตรวจสอบค่า null เสมอ
สัญญา e-invoice ต้องใช้ nextpdf/premium สัญญาเหล่านี้ถูกผูกไว้แล้ว แต่จะเกิดข้อผิดพลาดเมื่อรีโซลฟ์ครั้งแรกหากไม่มีแพ็กเกจดังกล่าว

ประสิทธิภาพ

การผสานรวมแบบครบวงจรไม่เพิ่มต้นทุนการบูต เนื่องจาก provider เป็นแบบเลื่อนการทำงาน (deferred) ต้นทุนการสร้างเมื่อรีโซลฟ์ครั้งแรกและต้นทุนการอุ่นเครื่องฟอนต์อธิบายไว้ใน /integrations/laravel/boot-and-discovery/

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

PdfResponse ใช้ชุดเฮดเดอร์ Open Worldwide Application Security Project (OWASP) แบบตายตัว GeneratePdfJob ตรวจสอบความถูกต้องของพาธเอาต์พุตบน worker ดู threat model ได้ที่ /integrations/laravel/security-and-operations/

ความสอดคล้อง

ข้อกล่าวอ้าง	แหล่งที่มา	ข้อกำหนด	reference_id (รหัสอ้างอิง)
ตัวระบุที่ผูกไว้รีโซลฟ์ไปยังรายการที่ลงทะเบียนไว้	PSR-11 Container	§1.1.2
คำนำหน้า PSR-4 แมปไปยังไดเรกทอรีฐาน	PSR-4 Autoloader	§3

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

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

ดูเพิ่มเติม

/integrations/laravel/overview/ — สถาปัตยกรรมและตารางการผูกบริการ
/integrations/laravel/install/ — การติดตั้งและส่วนขยายที่เป็นตัวเลือก
/integrations/laravel/quickstart/ — ตัวอย่างแรกที่เรียกใช้งานได้
/integrations/laravel/production-usage/ — dependency injection การจัดการข้อผิดพลาด และคิว
/integrations/laravel/boot-and-discovery/ — การค้นพบและอายุการใช้งาน