NextPDF สำหรับ CodeIgniter 4

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

nextpdf/codeigniter เชื่อมต่อเอนจิน NextPDF Portable Document Format (PDF) เข้ากับแอปพลิเคชัน CodeIgniter 4 ผ่านชั้น Services ของเฟรมเวิร์ก คุณสามารถสร้างเอกสาร PDF ในคอนโทรลเลอร์ งาน หรือคำสั่ง แล้วส่งกลับเป็นการตอบสนอง Hypertext Transfer Protocol (HTTP) แบบเนทีฟของ CodeIgniter

การติดตั้ง

composer require nextpdf/codeigniter

ไฟล์ composer.json ของแพ็กเกจกำหนดให้ใช้ php >=8.4 <9.0 nextpdf/core ^3.0 || ^5.2 และ codeigniter4/framework ^4.6 นอกจากนี้ยัง แนะนำ nextpdf/artisan, nextpdf/premium และ codeigniter4/queue สำหรับตารางข้อกำหนดฉบับเต็ม แพ็กเกจเสริม และขั้นตอนการตรวจสอบ ดู /integrations/codeigniter/install/.

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

NextPDF เป็นเอนจิน PDF 2.0 สำหรับ PHP 8.4 เอนจินหลัก (nextpdf/core) ไม่ผูกกับเฟรมเวิร์กใด และไม่รับรู้เกี่ยวกับ HTTP การกำหนดเส้นทาง หรือการเดินสายการพึ่งพา nextpdf/codeigniter เป็นอะแดปเตอร์ที่เชื่อมต่อเอนจินเข้ากับแอปพลิเคชัน CodeIgniter 4 เมื่อใช้อะแดปเตอร์นี้ คุณไม่ต้องเดินสายรีจิสทรี แฟกทอรี หรือการจัดการการตอบสนองด้วยตนเอง

แพ็กเกจเพิ่มสี่สิ่งให้กับแอปพลิเคชัน CodeIgniter 4:

• คลาส Services (NextPDF\CodeIgniter\Config\Services) ที่ CodeIgniter ค้นพบโดยอัตโนมัติ คลาสนี้เปิดให้ใช้บริการที่มีชื่อพร้อมใช้งาน ได้แก่ fontRegistry, imageRegistry, documentFactory, pdfDocument, pdf, tsaClient และ pdfSigner
• ไลบรารี Pdf (NextPDF\CodeIgniter\Libraries\Pdf) — application programming interface (API) สำหรับคอนโทรลเลอร์ระดับสูง ไลบรารีนี้ห่อหุ้มเอกสารแบบใช้ครั้งเดียวหนึ่งฉบับ และแปลงเป็นการตอบสนองได้ในการเรียกครั้งเดียว
• ตัวช่วย PdfResponse (NextPDF\CodeIgniter\Http\PdfResponse) ที่สร้าง DownloadResponse ของ CodeIgniter สำหรับการแสดงตัวอย่างแบบอินไลน์หรือการดาวน์โหลด ตัวช่วยนี้แนบชุดส่วนหัวการตอบสนองด้านความปลอดภัยที่กำหนดไว้ตายตัว
• ฟังก์ชันตัวช่วยส่วนกลางสองตัว ได้แก่ pdf() และ pdf_document() ฟังก์ชันเหล่านี้ลงทะเบียนผ่านรายการ autoload files ของ Composer และ Registrar ของแพ็กเกจ

นอกจากนี้แพ็กเกจยังตรวจหาส่วนขยาย NextPDF ที่เป็นทางเลือกขณะสร้างเอกสาร เมื่อติดตั้ง nextpdf/artisan และกำหนดค่าไบนารี Chrome ไว้ เอกสารจะได้รับตัวเรนเดอร์ Chrome เมื่อติดตั้ง NextPDF Pro ไว้ เอาต์พุต PDF/A และการลงลายเซ็นดิจิทัลจะพร้อมใช้งานผ่านพื้นผิว Services เดียวกัน การตรวจหานี้ทำงานตามเงื่อนไขและไม่รบกวนการทำงาน แพ็กเกจจะไม่บังคับใช้ส่วนขยายที่ไม่มีอยู่

ทำไมจึงใช้คลาส Services แทนที่จะเป็นการผูกคอนเทนเนอร์

CodeIgniter 4 ไม่ได้มาพร้อมคอนเทนเนอร์การฉีดการพึ่งพา PSR-11 แต่ใช้ตัวระบุตำแหน่ง Services แทน ตัวระบุตำแหน่ง Services คือคลาสที่เฟรมเวิร์กค้นพบ ซึ่งมีเมธอดแฟกทอรีแบบสแตติก แต่ละเมธอดส่งคืนอินสแตนซ์ที่ใช้ร่วมกันหรืออินสแตนซ์ใหม่ PSR-11 §1.3 ใช้กริยาช่วย SHOULD NOT เพื่อไม่สนับสนุนรูปแบบตัวระบุตำแหน่งบริการ — การส่งคอนเทนเนอร์เข้าไปในออบเจกต์เพื่อให้ออบเจกต์ดึงการพึ่งพาของตนเอง แพ็กเกจปฏิบัติตามแบบแผนตัวระบุตำแหน่งของ CodeIgniter และยังทำให้พื้นผิวตัวระบุตำแหน่งกระชับและชัดเจน: ทุกบริการเป็นเมธอดแฟกทอรีที่มีชื่อพร้อมพารามิเตอร์ bool $getShared และผู้เรียกได้รับออบเจกต์ที่เป็นรูปธรรมแทนที่จะเป็นแฮนเดิลของคอนเทนเนอร์

การออกแบบนี้ทำให้การผสานรวม CodeIgniter สอดคล้องกับการผสานรวม Laravel และ Symfony การผสานรวมแต่ละแบบเปิดให้ใช้ชุดบริการเชิงตรรกะเดียวกันผ่านสำนวนของเฟรมเวิร์กนั้น ๆ

พื้นผิว API

จุดเริ่มต้น	ประเภท	ส่งคืน	อายุการใช้งาน
Services::fontRegistry()	บริการ	FontRegistryInterface	ใช้ร่วมกัน (อุ่นเครื่องแล้วล็อก)
Services::imageRegistry()	บริการ	ImageRegistry	ใช้ร่วมกัน (แคชแบบ least recently used (LRU) ที่จำกัดขอบเขต)
Services::documentFactory()	บริการ	DocumentFactoryInterface	ใช้ร่วมกัน (ไร้สถานะ)
Services::pdfDocument(false)	บริการ	NextPDF\Core\Document	ใหม่ในแต่ละการเรียก
Services::pdf(false)	บริการ	NextPDF\CodeIgniter\Libraries\Pdf	ใหม่ในแต่ละการเรียก
Services::tsaClient()	บริการ	?TsaClient	ใช้ร่วมกัน; null เมื่อไม่มี URL ของหน่วยงานประทับเวลา (TSA)
Services::pdfSigner(false)	บริการ	?SignerInterface	ใหม่; null เมื่อปิดใช้งานการลงลายเซ็น
pdf()	ตัวช่วย	Pdf	ใหม่ในแต่ละการเรียก
pdf_document()	ตัวช่วย	Document	ใหม่ในแต่ละการเรียก
PdfResponse::inline() / download()	สแตติก	DownloadResponse	ต่อการเรียก
GeneratePdfJob	งานคิว	—	หนึ่งครั้งต่อการจัดส่ง

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

คอนโทรลเลอร์ส่งคืน PDF ได้ในสามบรรทัด Services::pdf() ส่งคืนไลบรารี Pdf ใหม่ที่ห่อหุ้มเอกสารใหม่ จากนั้น download() จะสร้าง DownloadResponse ของ CodeIgniter

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

คู่มือการใช้งานที่รันได้ครบถ้วนอยู่ใน /integrations/codeigniter/quickstart/. และครอบคลุมการกำหนดเส้นทาง การแสดงตัวอย่างแบบอินไลน์ รวมถึงรูปแบบต่าง ๆ ของตัวช่วย pdf() และ pdf_document()

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

ในการใช้งานจริง ให้ขออินสแตนซ์ที่ไม่ใช้ร่วมกันด้วย Services::pdf(false) และจับข้อยกเว้นฐานเพียงตัวเดียวคือ NextPDF\Exception\NextPdfException; ความล้มเหลวจากแกนหลักและส่วนขยายทุกตัวสืบทอดจากข้อยกเว้นนี้ ให้บันทึกความล้มเหลวพร้อมบริบทแทนการกลืนข้อผิดพลาด

try {
    $pdf = Services::pdf(false);
    $pdf->document()->addPage();
    $pdf->document()->cell(0, 10, "Invoice #{$id}");

    return $pdf->download("invoice-{$id}.pdf");
} catch (NextPdfException $e) {
    $logger->error('pdf.invoice.failed', [
        'invoice_id' => $id,
        'exception' => $e::class,
        'message' => $e->getMessage(),
    ]);

    return $this->response
        ->setStatusCode(ResponseInterface::HTTP_INTERNAL_SERVER_ERROR)
        ->setJSON(['error' => 'pdf_generation_failed', 'invoice_id' => $id]);
}

คอนโทรลเลอร์สำหรับการใช้งานจริงแบบสมบูรณ์อยู่ใน /integrations/codeigniter/production-usage/. โดยเพิ่มการจับเวลาเพื่อการสังเกตการณ์ อายุการใช้งานที่ปลอดภัยสำหรับเวิร์กเกอร์ และการสร้างแบบอะซิงโครนัส

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

• รีจิสทรีฟอนต์และรูปภาพเป็นซิงเกิลตันที่มีอายุเท่ากระบวนการ เอกสารไม่เคยถูกใช้ร่วมกัน pdfDocument และ pdf ส่งคืนอินสแตนซ์ใหม่ในทุกการเรียก ดังนั้นคำขอหนึ่งจึงไม่สามารถรั่วไหลเนื้อหาไปยังอีกคำขอหนึ่งได้ Services::pdf(false) และ pdf() ต่างก็ส่งคืนไลบรารีใหม่ที่ห่อหุ้มเอกสารใหม่
• แพ็กเกจต้องการส่วนขยาย PHP mbstring และ zlib รีจิสทรีฟอนต์ตรวจสอบความถูกต้องของส่วนขยายเหล่านี้หนึ่งครั้งต่อกระบวนการ หากส่วนขยายใดขาดหายไป รีจิสทรีฟอนต์จะยกข้อผิดพลาดรันไทม์ที่ระบุชื่อส่วนขยายที่ขาดหายไป
• พฤติกรรมของส่วนขยายที่เป็นทางเลือกขึ้นอยู่กับสิ่งที่ติดตั้งไว้ในแอปพลิเคชันเดียวกัน เมื่อมีเพียง nextpdf/core อยู่ เส้นทางการลงลายเซ็นและ PDF/A จะส่งคืน null หรือถูกข้ามไป เส้นทางเหล่านี้ไม่เคยล้มเหลวแบบแสดงข้อผิดพลาดทันที

ประสิทธิภาพ

การผสานรวมไม่เพิ่มภาระงานที่วัดได้นอกเหนือจากตัวเอนจินเอง รีจิสทรีฟอนต์จะเตรียมข้อมูลครั้งเดียวแล้วล็อก รีจิสทรีรูปภาพเป็นแคชแบบ LRU ที่จำกัดขอบเขตด้วยการตั้งค่า imageCacheMb (50 MB ตามค่าเริ่มต้น) เอนจินหลักและเนื้อหาเอกสารเป็นตัวกำหนดต้นทุนการสร้าง PDF ไม่ใช่อะแดปเตอร์ งบประมาณต่อหน้าสำหรับชุดเอกสารนี้คือ 1500 ms wall / 128 MB peak สูตรจริงกำหนดงบประมาณของตนเองใน front-matter

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

PdfResponse แนบชุดส่วนหัวการตอบสนองที่กำหนดไว้ตายตัวให้กับ PDF ทุกฉบับที่ส่งออก: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Content-Security-Policy: default-src 'none', X-Robots-Tag: noindex, nofollow และ Referrer-Policy: no-referrer ชื่อไฟล์ผ่านการทำให้ปลอดภัย และชื่อที่ไม่ใช่ ASCII จะถูกส่งออกด้วยพารามิเตอร์ขยายตาม Request for Comments (RFC) 5987 งานคิวจำกัดคอลแบ็กตัวสร้างให้อยู่ในเนมสเปซ App\PdfBuilders และจำกัดเส้นทางเอาต์พุตไว้ที่ WRITEPATH/pdfs/ ดู /integrations/codeigniter/security-and-operations/ สำหรับแบบจำลองภัยคุกคามฉบับเต็ม

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

• การค้นพบโมดูลอาศัยการโหลดอัตโนมัติแบบ PSR-4 ของ Composer คำนำหน้าเนมสเปซแมปกับไดเรกทอรีฐาน และชื่อคลาสแบบเต็มแมปกับเส้นทางไฟล์ (PSR-4 §x1.x3)
• การออกแบบ Services ปฏิบัติตามคำแนะนำตัวระบุตำแหน่งที่กล่าวถึงภายใต้ PSR-11 §1.3 ในเอกสารดังกล่าว

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

NextPDF core ใช้สัญญาอนุญาต Apache-2.0 ลายเซ็นดิจิทัล การจัดเก็บถาวรแบบ PDF/A และการฝังใบแจ้งหนี้อิเล็กทรอนิกส์ Factur-X จัดเตรียมโดย NextPDF Pro และ NextPDF Enterprise แพ็กเกจ CodeIgniter เปิดให้ใช้เมธอดบริการที่สอดคล้องกัน เมธอดเหล่านี้ส่งคืน null จนกว่าจะติดตั้งแพ็กเกจ Premium ที่ตรงกันในแอปพลิเคชันเดียวกัน

ดูเพิ่มเติม

• /integrations/codeigniter/install/ — ติดตั้งและตรวจสอบแพ็กเกจ
• /integrations/codeigniter/quickstart/ — PDF แรกในคอนโทรลเลอร์
• /integrations/codeigniter/configuration/ — ทุกคีย์การกำหนดค่า
• /integrations/codeigniter/boot-and-discovery/ — วิธีที่ CodeIgniter ค้นหาคลาส Services
• /integrations/codeigniter/integration/ — เอกสารอ้างอิงการเดินสายและการทดสอบควัน