คู่มือสำหรับนักพัฒนา CodeIgniter

ภาพรวมโดยสรุป

แพ็กเกจ CodeIgniter มี service factory ฟังก์ชันตัวช่วย และ wrapper ไลบรารี Pdf ขนาดเล็กสำหรับเอกสาร Portable Document Format (PDF) หนึ่งฉบับ ใช้ wrapper นี้ภายใน controller ส่วนงานคิวจะใช้ static builder callable เนื่องจาก payload ของคิว CodeIgniter ต้องเป็นข้อมูลที่ serialize ได้

ใช้คู่มือนี้เพื่อออกแบบ flow ของ controller บริการ queue builder และการทดสอบที่เกี่ยวข้องกับ nextpdf/codeigniter

ขอบเขตของสถาปัตยกรรม

เลเยอร์	เป็นเจ้าของโดย	ความรับผิดชอบ	อย่าใส่ไว้ที่นี่
Controller	แอปพลิเคชัน	ตรวจสอบสิทธิ์ เรียก builder หรือบริการ และคืนค่า DownloadResponse	ตรรกะเค้าโครงที่ใช้ร่วมกัน
Wrapper ไลบรารี	nextpdf/codeigniter	ห่อหุ้ม Document หนึ่งรายการ และเตรียมตัวช่วยสำหรับ response และการบันทึก	ที่จัดเก็บเอกสารระยะยาว
Service factory	nextpdf/codeigniter	สร้าง registry ที่ใช้ร่วมกันและเอกสารใหม่	รากที่จัดเก็บเฉพาะตามธุรกิจ
Queue builder	แอปพลิเคชัน	สร้างเอกสารจากอินพุต static callable	ออบเจ็กต์ของ request หรือสถานะที่ serialize ไม่ได้
เอนจินหลัก	nextpdf/nextpdf	สร้างและ serialize ไฟล์ PDF	นโยบาย response หรือคิวของ CodeIgniter

วงจรชีวิตขณะรันไทม์

ขั้นตอน	พฤติกรรม	การดำเนินการของนักพัฒนา
การลงทะเบียน autoload	Registrar::Autoload() ลงทะเบียนการโหลดตัวช่วยสำหรับโมดูล	โหลดโมดูลผ่านการกำหนดค่าของ CodeIgniter
การ resolve บริการ	Services::pdf() คืนค่า wrapper รอบเอกสารใหม่เป็นค่าเริ่มต้น	resolve หนึ่งครั้งต่อ request
การสร้างเนื้อหา	โค้ดแอปพลิเคชันใช้ Pdf::document() สำหรับการเรียกใช้เอกสารหลัก	เก็บโค้ดสำหรับสร้างเอกสารไว้ในบริการหรือ builder
Response	PdfResponse คืนค่า DownloadResponse	ให้แพ็กเกจกำหนด header ของ PDF
การประมวลผลคิว	GeneratePdfJob::process() ตรวจสอบความถูกต้องของ builder และพาธเอาต์พุต แล้วจึงบันทึก	วาง queue builder ไว้ภายใต้ App\PdfBuilders

โครงสร้างแอปพลิเคชันที่แนะนำ

พาธ	วัตถุประสงค์
app/PdfBuilders/*	static builder ที่ปลอดภัยสำหรับคิวซึ่ง GeneratePdfJob ยอมรับ
app/Libraries/*	wrapper เสริมของแอปพลิเคชันรอบ ๆ เวิร์กโฟลว์เอกสารที่ทำซ้ำ
app/Services/*	การดึงข้อมูลโดเมนและนโยบายการจัดเก็บ
app/Config/NextPdf.php	การ override ระดับแอปพลิเคชันสำหรับค่ากำหนดแพ็กเกจ
tests/app/PdfBuilders/*	การทดสอบ builder และ payload ของคิว

ใช้ตัวช่วยของแพ็กเกจสำหรับ flow สั้น ๆ และเรียกบริการอย่างชัดเจนเมื่อควรวางการสร้างเอกสารไว้ในคลาสที่ทดสอบได้โดยตรง

<?php

namespace App\Controllers;

final class InvoiceController extends BaseController
{
    public function download(int $id)
    {
        $pdf = pdf();
        $pdf->document()
            ->setTitle('Invoice ' . $id)
            ->addPage()
            ->writeHtml('<h1>Invoice ' . $id . '</h1>');

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

รูปแบบ queue builder

queue builder ควรเป็น static ให้ผลลัพธ์ที่คาดเดาได้ และอยู่ภายใต้ App\PdfBuilders เก็บอาร์เรย์ context ให้เรียบง่ายพอที่จะ serialize และตรวจสอบได้

<?php

namespace App\PdfBuilders;

use NextPDF\Core\Document;

final class InvoiceBuilder
{
    public static function build(Document $document, array $context): Document
    {
        $document->setTitle((string) $context['title'])
            ->addPage()
            ->writeHtml((string) $context['html']);

        return $document;
    }
}

งานนี้จำกัดเอาต์พุตให้อยู่เฉพาะในไดเรกทอรี PDF ของแอปพลิเคชันตามค่าที่กำหนดไว้ หากแอปพลิเคชันของคุณต้องการที่จัดเก็บเฉพาะตาม tenant ให้วางนโยบายนั้นไว้ในบริการเดียว และทดสอบก่อน dispatch งาน

จุดขยายความสามารถ

จุดขยายความสามารถ	ใช้สำหรับ	ข้อจำกัด
Services::pdfDocument()	ปรับแต่งการสร้างเอกสาร	ต้องคืนค่าเอกสารใหม่
Services::fontRegistry()	วอร์มอัปฟอนต์และเข้าถึง registry	ปฏิเสธพาธที่ไม่ปลอดภัย และล็อก registry ไว้หลังวอร์มอัป
Services::pdfSigner()	เปิดใช้การลงลายเซ็นดิจิทัลแบบเสริม	คืนค่า null เมื่อปิดการลงลายเซ็น
NextPDF\CodeIgniter\Libraries\Pdf	ห่อหุ้มงานเอกสารที่ใช้งานผ่าน controller	หนึ่ง wrapper จับคู่กับหนึ่งเอกสาร
App\PdfBuilders::*	builder เอกสารที่ปลอดภัยสำหรับคิว	ต้องเป็นสตริง static callable
app/Config/NextPdf.php	ค่าเริ่มต้นของแอปพลิเคชันและการตั้งค่าการผสานรวม	ระบุค่าสำหรับ production อย่างชัดเจน

เวิร์กโฟลว์การพัฒนา

1. เริ่มต้นด้วย controller ที่เรียก pdf() หรือ service('pdf')
2. ย้ายการสร้างเอกสารที่ทำซ้ำไปไว้ใน app/PdfBuilders หรือบริการของแอปพลิเคชัน
3. ใช้ GeneratePdfJob เมื่อการสร้างเอกสารช้าเกินไปสำหรับเส้นทาง request
4. เก็บ context ของคิวให้ serialize ได้และมีขนาดเล็ก
5. จัดเก็บเอาต์พุตไว้ภายใต้รากที่จัดเก็บ PDF ที่ได้รับอนุมัติ เว้นแต่คุณจะตั้งใจขยายนโยบาย
6. เพิ่มการทดสอบสำหรับตัวช่วย บริการ payload ของคิว และพาธที่ไม่ปลอดภัยต่าง ๆ

การจัดการความล้มเหลว

ความล้มเหลว	ควรจัดการที่ใด	การตอบสนองที่แนะนำ
ส่วนขยายขาดหายไปหรือพาธฟอนต์ไม่ปลอดภัย	Service factory	ล้มเหลวอย่างรวดเร็วระหว่างการ resolve บริการ
builder callable ไม่ถูกต้อง	การตรวจสอบความถูกต้องของงานคิว	ปฏิเสธงานและบันทึกสตริงของ builder โดยไม่รวมข้อมูลลับ
พาธเอาต์พุตที่ไม่ปลอดภัย	บริการจัดเก็บและงานคิว	ปฏิเสธก่อน dispatch และคงการตรวจสอบความถูกต้องของงานไว้
ข้อผิดพลาดในการ serialize response	การจัดการข้อผิดพลาดของ controller หรือเฟรมเวิร์ก	อย่าส่งเนื้อหา response body ที่ไม่สมบูรณ์
คลาส Premium แบบเสริมไม่พร้อมใช้งาน	ค่าที่เมธอดของบริการคืนกลับมา	จัดการ null อย่างชัดเจนก่อนใช้ฟีเจอร์ e-invoice แบบเสริม

ค่าเริ่มต้นที่ปลอดภัย

ประเด็น	ค่าเริ่มต้น	เมื่อใดควร override
เนมสเปซของ queue builder	App\PdfBuilders	คงค่าเริ่มต้นไว้ เว้นแต่คุณจะอัปเดตนโยบายความปลอดภัยด้วย
รากของเอาต์พุต	WRITEPATH/pdfs	override เฉพาะเมื่อมี allowlist ที่เข้มงวดกว่าเท่านั้น
ชื่อไฟล์ของ response	document.pdf	ใช้ชื่อไฟล์เชิงธุรกิจที่ผ่านการ sanitize แล้ว
เมธอดสตรีม	ความเท่าเทียมกันของ Application programming interface (API) กับเฟรมเวิร์กอื่น ๆ	อย่าพึ่งพาการสตรีมเป็นขอบเขตของหน่วยความจำใน CodeIgniter
บริการเอกสาร	เป็นเอกสารใหม่ตามค่าเริ่มต้น	อย่าร้องขอเอกสารที่ใช้ร่วมกันจากโค้ดในเส้นทาง request

รายการตรวจสอบสำหรับการทดสอบ

• การทดสอบบริการตรวจสอบว่าการ resolve Services::pdf() แต่ละครั้งคืนค่าเอกสารที่เป็นอิสระต่อกัน
• การทดสอบตัวช่วยตรวจสอบว่า pdf() และ pdf_document() คืนค่าออบเจ็กต์ใหม่
• การทดสอบ response ตรวจสอบ header และการ normalize ชื่อไฟล์ให้เป็นมาตรฐาน
• การทดสอบคิวครอบคลุมสตริง builder ที่ไม่ถูกต้องและพาธเอาต์พุตที่ไม่ปลอดภัย
• การทดสอบ builder ใช้ข้อมูล context ที่เป็นตัวแทน
• การทดสอบ config ครอบคลุมพาธฟอนต์ พาธแคช สถานะปิดการลงลายเซ็น และสถานะปิดการใช้งาน Time-Stamp Authority (TSA)