ข้อมูลอ้างอิง API สำหรับ Laravel

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

แพ็กเกจ nextpdf/laravel เชื่อมต่อ NextPDF core ที่เป็นอิสระจากเฟรมเวิร์กเข้ากับแอปพลิเคชัน Laravel คุณสามารถเรียกใช้จุดเข้าใช้งานสี่จุดได้โดยตรง ได้แก่ facade Pdf สำหรับขั้นตอนการสร้างเอกสารแบบสั้น binding ของคอนเทนเนอร์ PdfDocumentInterface สำหรับสร้างเอกสารผ่าน injection ตัวช่วย PdfResponse สำหรับส่งการตอบสนอง HTTP จากเอกสารที่สร้างเสร็จแล้ว และ queue job GeneratePdfJob สำหรับสร้างเอกสารนอกวงจรคำขอ NextPdfServiceProvider จะลงทะเบียน binding แต่ละรายการ และตัว provider จะถูกค้นพบโดยอัตโนมัติ คุณจึงไม่ต้องตั้งค่าด้วยตนเอง การกำหนดค่าใน config/nextpdf.php ควบคุมค่าเริ่มต้น ฟอนต์ คิว และคุณลักษณะการลงนามกับ time-stamp authority (TSA) ซึ่งเป็นทางเลือก

หากต้องการส่งไฟล์ Portable Document Format (PDF) จากคอนโทรลเลอร์โดยตรง ให้เริ่มจากการสร้างเอกสาร แล้วคืนค่า PdfResponse::download($document, 'file.pdf') ตัวอย่างแรกด้านล่างแสดงกระบวนการนี้

งานที่พบบ่อย

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

คืนค่า PDF ที่ดาวน์โหลดได้จากคอนโทรลเลอร์ นี่คืองานที่พบบ่อยที่สุด:

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

สิ่งที่ตัวอย่างนี้ทำ: inject เอกสารใหม่ เขียนข้อความหนึ่งบรรทัด และคืนค่าการตอบสนองแบบ attachment พร้อม Content-Type: application/pdf และส่วนหัวด้านความปลอดภัยของ Open Worldwide Application Security Project (OWASP) ใช้ inline() แทน download() เมื่อต้องการแสดงตัวอย่างในเบราว์เซอร์

สร้างและบันทึกด้วย facade Pdf นี่คือวิธีที่สั้นที่สุดสำหรับสคริปต์และกระบวนการขนาดสั้น:

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

สิ่งที่ตัวอย่างนี้ทำ: facade resolve เอกสารใหม่จากคอนเทนเนอร์ เขียนหนึ่งเซลล์ และบันทึก PDF ที่สร้างเสร็จแล้วลงดิสก์

สร้าง PDF นอกเธรดของคำขอด้วย 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),
);

สิ่งที่ตัวอย่างนี้ทำ: จัดคิวการสร้างเอกสารบน worker โดย closure ของ builder รับเอกสารที่ resolve จากคอนเทนเนอร์และคืนค่าเอกสารนั้น job จะตรวจสอบเส้นทางผลลัพธ์ .pdf ก่อนบันทึก ชื่อคิว ค่าหมดเวลา และการเชื่อมต่อทั้งหมดมาจาก config('nextpdf.queue.*')

ฟาซาด (Facade)

facade Pdf ทำหน้าที่เป็น proxy แบบ static ไปยัง core Document ใหม่ ใช้ในกระบวนการคอนโทรลเลอร์ขนาดสั้นเมื่อรูปแบบ static อ่านเข้าใจได้ชัดเจน แต่ละแถวแสดงเมท็อดเอกสารหนึ่งรายการที่ถูก proxy

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	ข้อยกเว้นหรือสาเหตุที่ล้มเหลว	หมายเหตุ
`NextPDF\Laravel\Facades\Pdf`	ไม่มี; accessor ของ facade แบบ static จะ resolve `NextPDF\Contracts\PdfDocumentInterface`	Laravel resolve binding ปัจจุบันของคอนเทนเนอร์สำหรับอินเทอร์เฟซเอกสาร	fluent API ของเอกสาร core ที่อยู่เบื้องหลัง	binding ของคอนเทนเนอร์ Laravel จะล้มเหลวหากยังไม่ได้ลงทะเบียน provider	ใช้สำหรับกระบวนการคอนโทรลเลอร์ขนาดสั้น แนะนำให้ใช้ constructor injection สำหรับเซอร์วิสและ job
`Pdf::setTitle(string $title)`	`title`: ชื่อเอกสาร	แทนที่ชื่อที่มีอยู่เดิม	`static`	ข้อผิดพลาดการตรวจสอบความถูกต้องหรือข้อผิดพลาดขณะเขียนของ core	ทำหน้าที่ proxy ไปยัง core `Document` ที่อยู่เบื้องหลัง
`Pdf::setAuthor(string $author)`	`author`: เมทาดาทาผู้เขียนเอกสาร	แทนที่ผู้เขียนก่อนหน้า	`static`	ข้อผิดพลาดการตรวจสอบเมทาดาทาของ core	แนะนำให้ใช้ค่าเริ่มต้นที่กำหนดค่าไว้สำหรับเมทาดาทาทั้งแอปพลิเคชัน
`Pdf::addPage(?PageSize $size = null, Orientation $orientation = Portrait)`	`size`: ขนาดหน้าซึ่งเป็นทางเลือก; `orientation`: `Portrait` โดยค่าเริ่มต้น	ใช้ขนาดหน้าที่กำหนดค่าไว้หรือขนาดหน้าเริ่มต้นเมื่อละ `size`	`static`	ข้อผิดพลาดการตรวจสอบหน้าของ core	ใช้ `PageSize` อย่างชัดเจนเมื่อขนาดผลลัพธ์มีความสำคัญ
`Pdf::setFont(string $family, string $style = '', float $size = 12.0)`	ตระกูลฟอนต์ สไตล์ และขนาดเป็นพอยต์	ใช้สไตล์ว่างและขนาด 12 pt	`static`	ข้อผิดพลาด font registry หรือการเข้ารหัส	โหลดฟอนต์สำหรับการใช้งานจริงล่วงหน้าผ่าน `nextpdf.preload_fonts` เมื่อความหน่วงมีความสำคัญ
`Pdf::cell(float $width, float $height, string $text = '', bool $border = false, bool $newLine = false, Alignment $align = Left)`	กล่องเซลล์ ข้อความ แฟล็กเส้นขอบ แฟล็กขึ้นบรรทัดใหม่ และการจัดแนว	ใช้ข้อความว่าง ไม่มีเส้นขอบ ไม่ขึ้นบรรทัดใหม่ และจัดแนวชิดซ้าย	`static`	ข้อผิดพลาดเค้าโครงหรือการเข้ารหัสข้อความ	ใช้สำหรับผลลัพธ์เค้าโครงคงที่อย่างง่าย
`Pdf::multiCell(float $width, float $height, string $text, bool $border = false, Alignment $align = Left)`	ความกว้างเซลล์ ความสูงบรรทัด ข้อความ แฟล็กเส้นขอบ และการจัดแนว	ไม่มีเส้นขอบและจัดแนวชิดซ้าย	`static`	ข้อผิดพลาดเค้าโครงหรือการเข้ารหัสข้อความ	ใช้เมื่อข้อความควรตัดบรรทัดภายในความกว้างคงที่
`Pdf::writeHtml(string $html)`	`html`: ส่วนย่อยของ HTML	เรนเดอร์บนหน้าปัจจุบันและสร้างหน้าใหม่เมื่อจำเป็น	`static`	ข้อผิดพลาดการเรนเดอร์ HTML ของ core	ใช้นโยบายขนาดอินพุตและทรัพยากรก่อนรับ HTML ที่ไม่น่าเชื่อถือ
`Pdf::image(string $file, ?float $x = null, ?float $y = null, ?float $width = null, ?float $height = null)`	เส้นทางไฟล์และสี่เหลี่ยมระบุตำแหน่งซึ่งเป็นทางเลือก	ให้เอกสาร core เลือกตำแหน่งปัจจุบันและขนาดจริงเมื่อละพิกัด	`static`	ข้อผิดพลาดการถอดรหัสภาพ เส้นทาง หรือเค้าโครง	ตรวจสอบนโยบายแหล่งที่มาของภาพก่อนรับเส้นทางที่ผู้ใช้ระบุ
`Pdf::output(?string $filename = null, OutputDestination $dest = Inline)`	`filename`: ชื่อซึ่งเป็นทางเลือก; `dest`: ปลายทางผลลัพธ์	ส่งออกแบบ inline เมื่อละปลายทาง	`string`	ข้อผิดพลาดการ serialize ของ core	แนะนำให้ใช้ `PdfResponse` สำหรับการตอบสนอง HTTP ของ Laravel
`Pdf::save(string $path)`	`path`: เป้าหมายในระบบไฟล์	เขียน PDF ที่สร้างเสร็จแล้วลงดิสก์	`void`	ข้อผิดพลาดระบบไฟล์หรือข้อผิดพลาดขณะเขียนของ core	ตรวจสอบไดเรกทอรีผลลัพธ์ในโค้ดของแอปพลิเคชัน
`Pdf::getPdfData()`	ไม่มี	สร้างไบต์ของ PDF ในหน่วยความจำ	`string`	ข้อผิดพลาดการ serialize ของ core	ใช้เมื่ออ็อบเจ็กต์เฟรมเวิร์กอื่นต้องเป็นเจ้าของเนื้อหาการตอบสนอง

Service provider และ binding

ใช้ตารางนี้เมื่อคุณต้องการ resolve หรือ override รายการในคอนเทนเนอร์โดยตรง เช่น inject DocumentFactoryInterface เข้าไปในเซอร์วิส หรือตรวจสอบว่า provides() เลื่อนรายการใดออกไป

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	ข้อยกเว้นหรือสาเหตุที่ล้มเหลว	หมายเหตุ
`NextPdfServiceProvider::register()`	ไม่มี	ผสาน `config/nextpdf.php`; ลงทะเบียน registry, document factory, document binding, HTTP client, TSA client, signer และ contract ของ e-invoice ซึ่งเป็นทางเลือก	`void`	ข้อผิดพลาดการ resolve คอนเทนเนอร์หรือคลาสทางเลือกเมื่อมีการใช้คุณลักษณะนั้น	`FontRegistryInterface` และ `ImageRegistry` ถูกใช้ร่วมกัน; เอกสารจะถูกสร้างใหม่เสมอ
`NextPdfServiceProvider::boot()`	ไม่มี	ตรวจสอบส่วนขยาย PHP ที่จำเป็นและเผยแพร่ `nextpdf-config` ในโหมดคอนโซล	`void`	`RuntimeException` หากส่วนขยายที่จำเป็นไม่พร้อมใช้งาน	ส่วนขยายที่จำเป็นคือ `mbstring` และ `zlib` เท่านั้น
`NextPdfServiceProvider::provides()`	ไม่มี	รายงาน ID ของเซอร์วิสที่ถูกเลื่อนออกไป	`array<string>`	ไม่คาดว่าจะเกิดขึ้น	รวมถึง `PdfDocumentInterface`, `DocumentFactoryInterface`, `FontRegistryInterface`, `SignerInterface`, `TsaClient`, `ClientInterface` และ `nextpdf` ด้วย
`PdfDocumentInterface` / `nextpdf`	resolve จากคอนเทนเนอร์ของ Laravel	สร้าง `Document` แบบใช้แล้วทิ้งผ่าน `DocumentFactoryInterface` จากนั้นใช้ค่าเริ่มต้นที่กำหนดค่าไว้ และใช้การตั้งค่า PDF/A หรือ Artisan ซึ่งเป็นทางเลือก	`NextPDF\Core\Document`	ข้อผิดพลาดของส่วนขยายทางเลือกเมื่อกำหนดค่าไว้แต่ไม่พร้อมใช้งาน	resolve เอกสารใหม่สำหรับแต่ละคำขอหรือแต่ละ job
`DocumentFactoryInterface`	resolve จากคอนเทนเนอร์ของ Laravel	factory แบบ singleton ที่ใช้ font registry และ image registry ร่วมกันตลอดอายุของกระบวนการ	`DocumentFactoryInterface`	ข้อผิดพลาดการตั้งค่า registry	ใช้รายการนี้สำหรับ dependency injection อย่างชัดเจน
`SignerInterface`	resolve จากคอนเทนเนอร์ของ Laravel	คืนค่า `null` เว้นแต่มีการตั้งค่า `nextpdf.signature.enabled` และกำหนดค่าเส้นทางใบรับรองไว้	`SignerInterface	null`	ข้อผิดพลาดการโหลดใบรับรองหรือการตรวจสอบความถูกต้องระดับลายเซ็น

การกำหนดค่า

ใช้ตารางนี้เพื่อค้นหาคีย์ nextpdf.* ที่พบขณะ runtime และถูกอ่านโดย binding ข้อมูลอ้างอิงรายคีย์ฉบับครบถ้วน รวมถึงตัวแปรสภาพแวดล้อมและค่าเริ่มต้น อยู่ที่ /integrations/laravel/configuration/

คีย์	ชนิด	พฤติกรรมเริ่มต้น	หมายเหตุ
`nextpdf.fonts_path`	`string`	ใช้ฟอนต์จากทรัพยากรของ Laravel เมื่อละไว้	ไดเรกทอรีสำหรับฟอนต์ที่กำหนดเองและขั้นตอน warmup
`nextpdf.cache_path`	`string`	เส้นทางแคชของแอปพลิเคชัน	คงสิทธิ์ให้ PHP worker เขียนได้
`nextpdf.preload_fonts`	`list<string>`	รายการว่าง	warm ระหว่างการสร้าง registry จากนั้น registry จะถูกล็อก
`nextpdf.image_cache_mb`	`int`	ขนาดแคชภาพที่มีขอบเขตจำกัด	จำกัดหน่วยความจำแคชภาพตลอดอายุของกระบวนการ
`nextpdf.defaults.*`	`array`	ผู้สร้าง `NextPDF` ภาษา `en` ผู้เขียน และค่าเริ่มต้นของเค้าโครงซึ่งเป็นทางเลือก	นำไปใช้กับเอกสารใหม่แต่ละฉบับ
`nextpdf.artisan.*`	`array`	ปิดใช้งานตัวเรนเดอร์ Chrome เว้นแต่มีการติดตั้งและกำหนดค่าไว้	แมปไปยัง `ChromeRendererConfig::fromArray()` โดยตรง
`nextpdf.signature.*`	`array`	ปิดใช้งานการลงนามโดยค่าเริ่มต้น	ใบรับรอง คีย์ส่วนตัว รหัสผ่าน ใบรับรองเพิ่มเติม และระดับลายเซ็น
`nextpdf.tsa.*`	`array`	TSA ถูกปิดใช้งานเมื่อ Uniform Resource Locator (URL) ว่างเปล่า	รองรับข้อมูลรับรอง ไฟล์ mutual Transport Layer Security (mTLS) ค่าหมดเวลา public-key pin และนโยบาย HTTP
`nextpdf.ocsp_cache.*`	`array`	แคช Online Certificate Status Protocol (OCSP) เปิดใช้งานพร้อม TTL ที่กำหนดค่าไว้	ใช้โดยกระบวนการตรวจสอบความถูกต้องของลายเซ็นเมื่อพร้อมใช้งาน

การตอบสนอง HTTP

ใช้ตารางนี้เมื่อคุณคืนค่าเอกสารที่สร้างเสร็จแล้วผ่าน HTTP และต้องเลือกการแสดงผลแบบ inline การดาวน์โหลดแบบ attachment หรือผลลัพธ์แบบ stream

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	ข้อยกเว้นหรือสาเหตุที่ล้มเหลว	หมายเหตุ
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: เอกสารที่สร้างขึ้น; `filename`: ชื่อไฟล์ใน Content-Disposition	ปรับชื่อไฟล์ว่างให้เป็น `document.pdf` เสมอ	`Illuminate\Http\Response`	ข้อผิดพลาดการ serialize ของ core หรือการสร้างการตอบสนอง	ตั้งค่าชนิดเนื้อหา PDF และส่วนหัวเชิงป้องกัน
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	เหมือนกับ `inline`; disposition เป็น attachment	คืนค่าการตอบสนองสำหรับดาวน์โหลดในเบราว์เซอร์	`Illuminate\Http\Response`	เหมือนกับ `inline` ทุกประการ	ใช้สำหรับการดาวน์โหลดไฟล์อย่างชัดเจน
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	เหมือนกับ `inline` ทุกประการ	สร้างไบต์ของ PDF แล้วส่งเป็นชิ้นขนาด 64 KB	`Symfony\Component\HttpFoundation\StreamedResponse`	เหมือนกับ `inline` ทุกประการ	นี่คือผลลัพธ์ HTTP แบบ stream ไม่ใช่การเรนเดอร์แบบ zero-copy
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	เหมือนกับ `streamInline`; disposition เป็น attachment	การตอบสนองแบบ stream สำหรับการดาวน์โหลด	`StreamedResponse`	เหมือนกับ `streamInline` ทุกประการ	บังคับใช้ขีดจำกัดขนาดอินพุตและเอาต์พุตก่อนการเรนเดอร์

งานคิว (Queue job)

ใช้ตารางนี้เมื่อคุณย้ายการสร้างเอกสารออกจากเธรดคำขอ ครอบคลุมการสร้างอ็อบเจ็กต์ การ dispatch และ callback เมื่อสำเร็จหรือล้มเหลวสำหรับ GeneratePdfJob โดยเฉพาะ

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	ข้อยกเว้นหรือสาเหตุที่ล้มเหลว	หมายเหตุ
`new GeneratePdfJob(string $outputPath, callable $builder, ?callable $onSuccess = null, ?callable $onFailure = null)`	`outputPath`: เป้าหมาย `.pdf`; `builder`: รับ `PdfDocumentInterface`; callback เป็นทางเลือก	ชื่อคิว ค่าหมดเวลา และการเชื่อมต่อทั้งหมดถูกอ่านจาก `config('nextpdf.queue.*')`	อินสแตนซ์ของ job	ข้อผิดพลาดการ serialize หาก builder หรือ callback ไม่สามารถ serialize ได้	builder ต้องคืนค่าเอกสารที่กำหนดค่าไว้
`GeneratePdfJob::handle()`	ไม่มี	resolve `PdfDocumentInterface` ใช้ builder ตรวจสอบเส้นทางผลลัพธ์ จากนั้นบันทึก	`void`	`InvalidArgumentException` สำหรับเส้นทางผลลัพธ์ที่ไม่ปลอดภัย; ข้อผิดพลาดขณะเขียนของ core	ปฏิเสธ stream wrapper, null byte, ส่วน `..` และเส้นทางที่ไม่ใช่ `.pdf` ทั้งหมด
`GeneratePdfJob::failed(Throwable $exception)`	`exception`: สาเหตุของความล้มเหลว	เรียก callback ความล้มเหลวที่กำหนดค่าไว้เมื่อมีอยู่	`void`	ความล้มเหลวของ callback	คง callback ให้เป็น idempotent
`GeneratePdfJob::then(callable $callback)`	`callback`: รับเส้นทางผลลัพธ์	แทนที่ callback ความสำเร็จ	`self`	ข้อผิดพลาด serializable-closure	ตัวช่วยแบบ fluent สำหรับการตั้งค่าการ dispatch
`GeneratePdfJob::catch(callable $callback)`	`callback`: รับ `Throwable` ที่ถูกโยน	แทนที่ callback ความล้มเหลว	`self`	ข้อผิดพลาด serializable-closure	ใช้สำหรับการแจ้งเตือนหรือการล้างข้อมูลแบบชดเชย

หมายเหตุการพัฒนา

PdfResponse เรียก getPdfData() เสมอก่อนสร้างการตอบสนอง ไม่ใช่ตัวสร้างเอกสารแบบ lazy
เพย์โหลดของคิวอาจถูกดัดแปลงระหว่างส่งผ่าน transport ที่ใช้ร่วมกัน; คงเส้นทางผลลัพธ์ให้อยู่ภายในไดเรกทอรีที่แอปพลิเคชันเป็นเจ้าของ
ใช้เอกสารใหม่ต่อแต่ละคำขอหรือแต่ละ job อย่านำเอกสารกลับมาใช้ซ้ำข้ามคำขอ