การผสานรวม NextPDF กับ CodeIgniter

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

เมื่อติดตั้งแพ็กเกจแล้ว CodeIgniter 4 จะลงทะเบียนการผสานรวมให้โดยอัตโนมัติ ใช้หน้านี้เพื่อตรวจสอบยืนยันการผสานรวม ได้แก่ การค้นพบ โมเดลการผูก การพับลิชค่ากำหนด และ smoke test แบบเมท็อดเดียวที่พิสูจน์ว่าการผสานรวมทำงานได้

การติดตั้ง

composer require nextpdf/codeigniter

ไม่ต้องแก้ไข service provider หรือเปลี่ยนไฟล์ bootstrap ใดๆ ดู /integrations/codeigniter/install/ สำหรับข้อจำกัดเวอร์ชันที่ได้รับการตรวจสอบยืนยันแล้ว

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

CodeIgniter 4 ค้นหาแพ็กเกจผ่านการค้นพบแพ็กเกจของ Composer เมื่อ Config\Modules::$discoverInComposer มีค่าเป็น true ซึ่งเป็นค่าเริ่มต้นของเฟรมเวิร์ก พรีฟิกซ์ของ PHP Standard Recommendation 4 (PSR-4) คือ NextPDF\CodeIgniter\ และแมปไปยัง src/CodeIgniter/ ดังนั้นเฟรมเวิร์กจึงรีโซลฟ์ NextPDF\CodeIgniter\Config\Services ไปยังไฟล์คลาสได้ (PSR-4 §x1.x3) /integrations/codeigniter/boot-and-discovery/ อธิบายลำดับทั้งหมดและพร็อพเพอร์ตีของ Config\Modules ที่ควบคุมขั้นตอนเหล่านี้

การผูกคอนเทนเนอร์

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

ชื่อเซอร์วิส	คืนค่า	อายุการใช้งานเริ่มต้น
`fontRegistry`	`FontRegistryInterface`	ใช้ร่วมกัน
`imageRegistry`	`ImageRegistry`	ใช้ร่วมกัน
`documentFactory`	`DocumentFactoryInterface`	ใช้ร่วมกัน
`pdfDocument`	`Document`	สร้างใหม่
`pdf`	`Pdf`	สร้างใหม่
`tsaClient`	`?TsaClient`	ใช้ร่วมกัน
`pdfSigner`	`?SignerInterface`	สร้างใหม่

เลือกใช้จุดเริ่มต้นจุดใดก็ได้ ทั้งสองจุดเทียบเท่ากัน:

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Config\Services;

$a = Services::pdf(false);   // direct
$b = \service('pdf');        // helper → Services::pdf()

เฮลเปอร์ส่วนกลาง pdf() และ pdf_document() ห่อหุ้ม Services::pdf(false) และ Services::pdfDocument(false) ตามลำดับ

การพับลิชค่ากำหนด

การกำหนดค่าของแพ็กเกจอยู่ใน NextPDF\CodeIgniter\Config\NextPdf ซึ่งเป็น BaseConfig ที่ไม่ใช่ final คุณสามารถเขียนทับค่ากำหนดได้ด้วยวิธีที่รองรับสองวิธีต่อไปนี้:

1. ขยายคลาส (มีไทป์และควบคุมเวอร์ชันได้) สร้าง app/Config/NextPdf.php:

<?php

declare(strict_types=1);

namespace Config;

use NextPDF\CodeIgniter\Config\NextPdf as BaseNextPdf;

final class NextPdf extends BaseNextPdf
{
    public int $imageCacheMb = 100;
}

CodeIgniter จะโหลดคลาสของแอปพลิเคชันของคุณแทนค่าเริ่มต้นของแพ็กเกจ

2. เขียนทับด้วย .env (แยกตามสภาพแวดล้อม) ใช้ชื่อคลาสแบบสั้นตัวพิมพ์เล็ก nextpdf เป็นพรีฟิกซ์:

nextpdf.imageCacheMb = 100
nextpdf.signature.enabled = true
nextpdf.signature.certificate = /etc/nextpdf/cert.pem

/integrations/codeigniter/configuration/ อธิบายคีย์แต่ละรายการและกฎการเขียนทับอาร์เรย์

Smoke test ของ service-provider / bundle

CodeIgniter ไม่มีคลาส service provider หรือ bundle สำหรับให้ทดสอบโดยตรง ใช้ smoke test ที่เทียบเท่ากันเพื่อตรวจสอบสองสิ่ง ได้แก่ กลไกการค้นพบรีโซลฟ์เซอร์วิสได้สำเร็จ และอายุการใช้งานทำงานตามที่ระบุไว้ แอ็กชันของคอนโทรลเลอร์ด้านล่างนี้รันได้จริงและสะท้อนการยืนยันเชิงฟังก์ชันของแพ็กเกจเอง

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\ResponseInterface;
use NextPDF\CodeIgniter\Config\Services;
use NextPDF\CodeIgniter\Libraries\Pdf;
use NextPDF\Core\Document;

final class NextPdfSmokeController extends BaseController
{
    public function check(): ResponseInterface
    {
        // Discovery resolved the services.
        $document = Services::pdfDocument(false);
        $library = Services::pdf(false);

        // Documents are fresh per call (no cross-request leakage).
        $freshIsolated = Services::pdfDocument(false) !== $document;

        // Registries are shared singletons.
        $registrySingleton = Services::fontRegistry() === Services::fontRegistry();

        // Optional services degrade to null without Premium / TSA config.
        $signerOptional = Services::pdfSigner(false) === null;

        $ok = $document instanceof Document
            && $library instanceof Pdf
            && $freshIsolated
            && $registrySingleton
            && $signerOptional;

        return $this->response
            ->setStatusCode($ok ? 200 : 500)
            ->setJSON([
                'discovery' => $document instanceof Document,
                'document_fresh_per_call' => $freshIsolated,
                'registry_shared' => $registrySingleton,
                'signer_optional_null' => $signerOptional,
            ]);
    }
}

แมปเส้นทางไปยังแอ็กชันนี้ แล้วส่งคำขอไปยังเส้นทางนั้น การตอบกลับ 200 ที่มีแฟล็กทั้งหมดเป็น true ยืนยันว่าการผสานรวมทำงานได้ การยืนยันแต่ละข้อในที่นี้ตรงกับพฤติกรรมที่ตรวจสอบยืนยันไว้ในชุดทดสอบเชิงฟังก์ชันของแพ็กเกจ

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

หากแอปพลิเคชันโฮสต์ปิดการค้นพบผ่าน Composer ให้เพิ่ม nextpdf/codeigniter ลงใน Config\Modules::$composerPackages['only'] ด้วยตนเอง
Services::pdfDocument(true) คืนค่าเอกสารที่ใช้ร่วมกัน เอกสารนี้มีไว้สำหรับการรีเซ็ตในการทดสอบเท่านั้น ห้ามร้องขอเอกสารที่ใช้ร่วมกันในโค้ดที่ประมวลผลคำขอหรือโค้ด job โดยเด็ดขาด
Services::pdfSigner() และ Services::tsaClient() คืนค่า null จนกว่าจะมีการกำหนดค่าการลงนามหรือเอนด์พอยต์ของ Time-Stamping Authority (TSA) นี่คือการลดระดับแบบนุ่มนวลที่ตั้งใจไว้ ไม่ใช่ความล้มเหลว

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

การแมปคลาสกับพาธสำหรับการค้นพบโมดูล (PSR-4 Autoloader §x1.x3)
แนวทาง service-locator สำหรับโมเดลการผูก (PSR-11 Container §1.3)

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

NextPDF core ใช้สัญญาอนุญาต Apache-2.0 หลังจากติดตั้ง Pro หรือ Enterprise แล้ว เซอร์วิสของรุ่นนั้นจะปรากฏใน Services เดียวกัน แพ็กเกจ CodeIgniter เปิดให้ใช้เมท็อดของเซอร์วิสที่ตรงกัน แต่ละเมท็อดคืนค่า null จนกว่าคุณจะติดตั้งแพ็กเกจ Premium ที่ตรงกัน ดู </get-license/?intent=codeigniter> เพื่อดูรายละเอียด

ดูเพิ่มเติม

/integrations/codeigniter/boot-and-discovery/ — กลไกภายในของการค้นพบ
/integrations/codeigniter/install/ — ข้อจำกัดเวอร์ชันและการตรวจสอบยืนยัน
/integrations/codeigniter/quickstart/ — PDF แรก
/integrations/codeigniter/production-usage/ — คอนโทรลเลอร์ที่เชื่อมต่อผ่าน dependency injection และ job ของคิว
/integrations/codeigniter/configuration/ — ทุกคีย์ของการกำหนดค่า