การอ้างอิง API ของ CodeIgniter

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

แพ็กเกจ CodeIgniter มีส่วนต่อประสานโปรแกรมประยุกต์ (application programming interface หรือ API) ขนาดเล็กสำหรับ controller แพ็กเกจนี้ประกอบด้วย library wrapper Pdf สำหรับเอกสารหนึ่งฉบับ (Services::pdf() และตัวช่วยส่วนกลาง pdf()) ตัวช่วยจัดการ response ที่แปลงเอกสารที่สร้างแล้วให้เป็น DownloadResponse (PdfResponse) factory ภายใน Services (registry ของฟอนต์และรูปภาพ, document factory, signer และไคลเอนต์สำหรับหน่วยงานออกตราประทับเวลา (time-stamping authority หรือ TSA) แบบเลือกได้) คลาสการกำหนดค่า NextPdf และ GeneratePdfJob สำหรับการสร้างแบบอะซิงโครนัสจาก builder callable แบบ static

เริ่มจากเส้นทางหลักใน controller: เรียก Services::pdf() (หรือตัวช่วย pdf()) เพิ่มเนื้อหาลงใน $pdf->document() แล้วคืนค่า $pdf->download('file.pdf') เส้นทางนี้ครอบคลุมกรณีที่ใช้กันทั่วไป ตารางอ้างอิงจัดเรียงตามส่วนการใช้งานของ API โดยส่วนงานที่พบบ่อยจะแสดงรูปแบบที่รันได้จริงก่อน

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

รายการต่อไปนี้คือกระแสงานในระบบจริงที่พบบ่อยที่สุด ตัวอย่างแต่ละชุดได้รับการตรวจสอบกับซอร์สโค้ดของ nextpdf/codeigniter โดยตรง

ใช้เส้นทางการเรนเดอร์มาตรฐานเพื่อคืนค่าไฟล์ Portable Document Format (PDF) ที่ดาวน์โหลดได้จาก controller:

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;
use NextPDF\CodeIgniter\Config\Services;

final class InvoiceController extends BaseController
{
    public function download(int $id): DownloadResponse
    {
        $pdf = Services::pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, "Invoice #{$id}");

        return $pdf->download("invoice-{$id}.pdf");
    }
}

การทำงาน: สร้าง Pdf ตัวใหม่ที่ครอบ Document ตัวใหม่ เขียน cell หนึ่งรายการ แล้วคืนค่า DownloadResponse ที่มี disposition แบบ attachment พร้อมส่วนหัวความปลอดภัยของแพ็กเกจ

แสดงตัวอย่าง PDF แบบ inline ในเบราว์เซอร์ด้วย wrapper เดียวกันและใช้ inline() แทน download():

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;

final class ReportController extends BaseController
{
    public function preview(): DownloadResponse
    {
        $pdf = pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, 'Monthly Report');

        return $pdf->inline('report.pdf');
    }
}

การทำงาน: ใช้ตัวช่วยส่วนกลาง pdf() (เทียบเท่ากับ Services::pdf()) และคืนค่า DownloadResponse ที่มี disposition แบบ inline เพื่อให้เบราว์เซอร์แสดง PDF แทนที่จะดาวน์โหลด

สร้าง PDF แบบอะซิงโครนัสบน queue ด้วย GeneratePdfJob และ builder แบบ static:

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Jobs\GeneratePdfJob;

service('queue')->push('pdf', GeneratePdfJob::class, [
    'builder'    => 'App\PdfBuilders\InvoiceBuilder::build',
    'outputPath' => WRITEPATH . 'pdfs/invoice-42.pdf',
    'context'    => ['invoice_id' => 42],
]);

การทำงาน: นำงานสร้างเอกสารเข้าคิว worker จะตรวจสอบความถูกต้องของ builder (ต้องเป็น static callable แบบ App\PdfBuilders\...::method) และเส้นทางเอาต์พุต (ต้องถูกตีความให้อยู่ภายใต้ WRITEPATH/pdfs/ และลงท้ายด้วย .pdf) จากนั้นสร้างเอกสารตัวใหม่และบันทึก

ตัวครอบไลบรารี (Library wrapper)

ใช้ตารางนี้เมื่อมี wrapper Pdf และต้องการเมท็อด response หรือ save

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนข้อยกเว้นหรือล้มเหลวด้วย	หมายเหตุ
`NextPDF\CodeIgniter\Libraries\Pdf` / `new Pdf(Document $document)`	`document`: เอกสาร core ตัวใหม่	ครอบเอกสารที่ส่งเข้ามาสำหรับการสร้าง response หรือการบันทึกหนึ่งครั้ง	`Pdf`	ไม่คาดว่าจะเกิดขึ้น	อย่านำ wrapper กลับมาใช้ซ้ำหลังจากส่งเอาต์พุตแล้ว
`Pdf::document()`	ไม่มี	คืนค่าเอกสารที่ครอบไว้	`NextPDF\Core\Document`	ไม่คาดว่าจะเกิดขึ้น	ใช้เมท็อดนี้เพื่อเรียก API การสร้างเนื้อหาของ core
`Pdf::inline(string $filename = 'document.pdf')`	`filename`: ชื่อไฟล์ของ response	ใช้ disposition แบบ inline ของเบราว์เซอร์	`CodeIgniter\HTTP\DownloadResponse`	ข้อผิดพลาดด้านการทำให้เป็นอนุกรมของ core	มอบหมายงานต่อไปยัง `PdfResponse::inline()` โดยตรง
`Pdf::download(string $filename = 'document.pdf')`	`filename`: ชื่อไฟล์ของ response	ใช้ disposition แบบ attachment ของเบราว์เซอร์	`DownloadResponse`	ข้อผิดพลาดด้านการทำให้เป็นอนุกรมของ core	มอบหมายงานต่อไปยัง `PdfResponse::download()` โดยตรง
`Pdf::streamInline(string $filename = 'document.pdf')`	`filename`: ชื่อไฟล์ของ response	ให้ความเท่าเทียมของ API กับแพ็กเกจของเฟรมเวิร์กอื่น	`DownloadResponse`	ข้อผิดพลาดด้านการทำให้เป็นอนุกรมของ core	CodeIgniter จัดการเอาต์พุตแบบไบนารีได้ในตัว
`Pdf::streamDownload(string $filename = 'document.pdf')`	`filename`: ชื่อไฟล์ของ response	ให้ความเท่าเทียมของ API กับแพ็กเกจของเฟรมเวิร์กอื่น	`DownloadResponse`	ข้อผิดพลาดด้านการทำให้เป็นอนุกรมของ core	ใช้การควบคุมขนาดแบบเดียวกับ response ที่ไม่ได้สตรีม
`Pdf::save(string $path)`	`path`: ปลายทางบนระบบไฟล์	เขียนเอกสารที่ครอบไว้	`void`	ข้อผิดพลาดของระบบไฟล์หรือการเขียนของ core	ตรวจสอบ storage root ให้ถูกต้องก่อนบันทึก

Service และตัวช่วย

ใช้ตารางนี้เมื่อต้องการ service factory หรือฟังก์ชันตัวช่วยส่วนกลางที่เจาะจง รวมถึงพฤติกรรมการแชร์และชนิดของค่าที่คืนกลับ

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนข้อยกเว้นหรือล้มเหลวด้วย	หมายเหตุ
`Services::fontRegistry(bool $getShared = true)`	`getShared`: ค่าธงสำหรับ service แบบ shared ของ CodeIgniter	คืนค่า registry แบบ shared ที่โหลดฟอนต์ตามการกำหนดค่าไว้ล่วงหน้าแล้วล็อก	`FontRegistryInterface`	`RuntimeException` เมื่อขาดส่วนขยายหรือเส้นทางฟอนต์ไม่ปลอดภัย	ปฏิเสธ stream wrapper และไบต์ว่าง (null byte) ใน `fontsPath` ทั้งหมด
`Services::imageRegistry(bool $getShared = true)`	`getShared`: ค่าธงสำหรับ service แบบ shared	คืนค่า registry รูปภาพแบบ shared ที่จำกัดขนาดด้วยกลไก least recently used (LRU)	`ImageRegistry`	ไม่คาดว่าจะเกิดขึ้น	ขนาดแคชถูกควบคุมโดย `imageCacheMb` โดยตรง
`Services::documentFactory(bool $getShared = true)`	`getShared`: ค่าธงสำหรับ service แบบ shared	คืนค่า factory แบบ shared ที่ใช้ registry แบบ shared	`DocumentFactoryInterface`	ข้อผิดพลาดจากการกำหนดค่า registry	factory สามารถนำกลับมาใช้ซ้ำได้ แต่เอกสารทำไม่ได้
`Services::tsaClient(bool $getShared = true)`	`getShared`: ค่าธงสำหรับ service แบบ shared	คืนค่า `null` เมื่อ `tsa.url` ว่าง	`TsaClient	null`	ข้อผิดพลาดของไคลเอนต์ Hypertext Transfer Protocol (HTTP) หรือการกำหนดค่า TSA
`Services::pdfSigner(bool $getShared = false)`	`getShared`: ค่าธงสำหรับ service แบบ shared	คืนค่า `null` เมื่อปิดใช้งานการลงนาม	`SignerInterface	null`	ข้อผิดพลาดด้านใบรับรองหรือระดับลายเซ็น
`Services::pdfDocument(bool $getShared = false)`	`getShared`: ค่าธงสำหรับ service แบบ shared	สร้างเอกสารตัวใหม่ ใช้ค่าเริ่มต้น และกำหนดค่า PDF/A หรือ Artisan แบบเลือกได้	`Document`	ข้อผิดพลาดด้านส่วนขยายแบบเลือกได้หรือการกำหนดค่าเอกสาร	คงค่าเริ่มต้น `false` ไว้เพื่อความปลอดภัยระดับ request
`Services::pdf(bool $getShared = false)`	`getShared`: ค่าธงสำหรับ service แบบ shared	สร้าง wrapper `Pdf` ตัวใหม่ที่ครอบเอกสารตัวใหม่	`NextPDF\CodeIgniter\Libraries\Pdf`	ข้อผิดพลาดในการตั้งค่าเอกสาร	service หลักสำหรับ controller
`Services::eInvoiceEmbedder()`	ไม่มี	คืนค่า `null` เว้นแต่มีคลาส e-invoice embedder ของ Premium Pro อยู่	`EmbedderInterface	null`	ข้อผิดพลาดในการสร้างแพ็กเกจเสริมแบบเลือกได้
`Services::eInvoiceValidator()`	ไม่มี	คืนค่า `null` เว้นแต่มีคลาส validator ของ Premium Enterprise อยู่	`ValidatorInterface	null`	ข้อผิดพลาดในการสร้างแพ็กเกจเสริมแบบเลือกได้
`Services::eInvoiceProfile()`	ไม่มี	คืนค่าโปรไฟล์ EN16931 เมื่อมีการติดตั้ง Premium Pro	`ProfileInterface	null`	ข้อผิดพลาดของแพ็กเกจเสริมแบบเลือกได้
`Services::schematronRunner()`	ไม่มี	คืนค่า `null` เว้นแต่มี Schematron validator ของ Premium Enterprise อยู่	`SchematronRunnerInterface	null`	ข้อผิดพลาดในการสร้างแพ็กเกจเสริมแบบเลือกได้
`Registrar::Autoload()`	ไม่มี	เพิ่มตัวช่วยของแพ็กเกจลงในการกำหนดค่า autoload ของ CodeIgniter	`array`	ไม่คาดว่าจะเกิดขึ้น	เปิดใช้งาน `pdf()` และ `pdf_document()` เมื่อมีการโหลดโมดูล
`pdf()`	ไม่มี	เรียก `Services::pdf(false)` โดยตรง	`Pdf`	ข้อผิดพลาดในการตั้งค่าเอกสาร	ตัวช่วยเพื่อความสะดวกสำหรับ controller
`pdf_document()`	ไม่มี	เรียก `Services::pdfDocument(false)` โดยตรง	`Document`	ข้อผิดพลาดในการตั้งค่าเอกสาร	ตัวช่วยเพื่อความสะดวกเมื่อต้องการใช้ API เอกสารของ core

response ของ HTTP

ใช้ตารางนี้เมื่อมี Document ที่สร้างแล้วและต้องการสร้าง DownloadResponse ด้วยตนเองแทนการใช้ wrapper Pdf โดยตรง

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนข้อยกเว้นหรือล้มเหลวด้วย	หมายเหตุ
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: เอกสารที่สร้างแล้ว; `filename`: ชื่อไฟล์ของ response	รับประกันนามสกุล `.pdf` และ disposition แบบ inline	`DownloadResponse`	ข้อผิดพลาดด้านการทำให้เป็นอนุกรมของ core	เพิ่มชนิดเนื้อหา PDF และส่วนหัวป้องกัน
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	เหมือนกับ `inline` แต่ disposition เป็นแบบ attachment	รับประกันนามสกุล `.pdf` เสมอ	`DownloadResponse`	เหมือนกับ `inline` ทุกประการ	ใช้สำหรับการดาวน์โหลดผ่านเบราว์เซอร์
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	เหมือนกับ `inline` ทุกประการ	พฤติกรรมเหมือนกับ `inline` ใน CodeIgniter 4 (CI4)	`DownloadResponse`	เหมือนกับ `inline` ทุกประการ	มีไว้เพื่อความเท่าเทียมของ API ข้ามเฟรมเวิร์ก
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	เหมือนกับ `download` ทุกประการ	พฤติกรรมเหมือนกับ `download` ใน CI4	`DownloadResponse`	เหมือนกับ `download` ทุกประการ	มีไว้เพื่อความเท่าเทียมของ API ข้ามเฟรมเวิร์ก

งาน queue

ใช้ตารางนี้เมื่อเชื่อมต่อการสร้างแบบอะซิงโครนัสและต้องการคีย์ข้อมูลงานที่แน่นอนพร้อมสัญญาของ builder callable

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนข้อยกเว้นหรือล้มเหลวด้วย	หมายเหตุ
`GeneratePdfJob::process()`	คีย์ข้อมูลงาน: `builder`, `outputPath`, และ `context` แบบเลือกได้	ใช้อาร์เรย์ context ว่างเมื่อไม่ได้ระบุ	`void`	`InvalidArgumentException` เมื่อ builder หรือเส้นทางเอาต์พุตไม่ปลอดภัย; ข้อผิดพลาดการเขียนของ core	builder ต้องเป็น `App\PdfBuilders\...\*::method` เท่านั้น
Builder callable	`Document $doc`, `array $context` ตามลำดับ	ไม่มี context เริ่มต้นนอกเหนือจากข้อมูลงาน	`Document`	ข้อยกเว้นที่เจาะจงตาม builder	ต้องใช้ static callable เนื่องจาก payload ของ queue ใน CI4 เป็นข้อมูลที่ผ่านการทำให้เป็นอนุกรมแล้ว

การกำหนดค่า

ใช้ตารางนี้เมื่อต้องเปลี่ยนค่าเริ่มต้นของรูปแบบหน้า เส้นทาง การลงนาม TSA หรือเมทาดาทาของเอกสารในคลาสการกำหนดค่า NextPdf

คุณสมบัติ	ชนิด	พฤติกรรมเริ่มต้น	หมายเหตุ
`pageFormat`	`string`	`A4`	กำหนดรูปแบบหน้าเริ่มต้น
`orientation`	`string`	`P`	กำหนดแนวการวางเริ่มต้น
`unit`	`string`	`mm`	กำหนดหน่วยเริ่มต้น
`pdfa`	`string	null`	`null`
`fontsPath` / `cachePath`	`string`	`WRITEPATH . 'fonts'` และ `WRITEPATH . 'cache/nextpdf'` ตามลำดับ	เก็บเส้นทางไว้ภายในพื้นที่จัดเก็บที่แอปพลิเคชันควบคุม
`signature`	`array`	ปิดใช้งานโดยกำหนดระดับเป็น `B-B` เป็นค่าเริ่มต้น	ใบรับรอง คีย์ รหัสผ่าน ใบรับรองเพิ่มเติม และระดับ
`tsa`	`array`	ปิดใช้งานเมื่อ Uniform Resource Locator (URL) เป็น `null`; ค่า timeout 30 วินาที	ข้อมูลรับรองตัวตน ไฟล์ mutual Transport Layer Security (mTLS) public-key pin และนโยบาย HTTP
`ocspCache`	`array`	เปิดใช้งานโดยมีอายุการเก็บ (time to live หรือ TTL) 86400 วินาที	ใช้โดยกระแสงานตรวจสอบลายเซ็นเมื่อมีให้ใช้งาน
`preloadFonts`	`list<string>`	ว่าง	อุ่นเครื่องก่อนที่ registry จะถูกล็อก
`imageCacheMb`	`int`	`50`	ควบคุมแคชรูปภาพที่มีอายุเท่ากับโปรเซส
`fontCacheLocking`	`bool`	`true`	กันการเปลี่ยนแปลง registry ฟอนต์ออกจากการจัดการ request
`artisan`	`array`	ตัวเรนเดอร์ Chrome ถูกปิดใช้งานเว้นแต่มีการกำหนดค่าและติดตั้งไว้	แมปไปยัง `ChromeRendererConfig::fromArray()` โดยตรง
`defaults`	`array`	creator คือ `NextPDF`, author ว่าง, ภาษา `en`, ระยะขอบเริ่มต้น และฟอนต์เริ่มต้น	`Services::pdfDocument()` ใช้เฉพาะ `creator`, `language`, และ (เมื่อไม่ว่าง) `author` เท่านั้น; ส่วน `margin_top`/`right`/`bottom`/`left`, `font_family`, `font_size`, `trim_box`, และ `bleed_box` เป็นค่าเริ่มต้นที่นิยามไว้ แต่ปัจจุบันยังไม่ได้นำมาใช้

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

GeneratePdfJob จำกัดเอาต์พุตไว้ที่ WRITEPATH . 'pdfs' และต้องลงท้ายด้วย .pdf เสมอ
builder callable ที่อยู่นอก App\PdfBuilders จะถูกปฏิเสธ เพื่อหลีกเลี่ยงการรันโค้ดโดยพลการจาก payload ของ queue ที่ถูกแก้ไข
ใช้ service('pdf') หรือตัวช่วยของแพ็กเกจสำหรับกระแสงานใน controller; ใช้ queue สำหรับการสร้างที่ใช้เวลานาน