การติดตั้ง NextPDF สำหรับ CodeIgniter 4

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

ติดตั้งแพ็กเกจด้วย Composer แล้ว CodeIgniter 4 จะค้นหาคลาส Services และฟังก์ชันตัวช่วยโดยอัตโนมัติ จึงไม่จำเป็นต้องลงทะเบียนด้วยตนเอง

ข้อกำหนด

ไฟล์ composer.json ของแพ็กเกจเป็นแหล่งข้อมูลอย่างเป็นทางการสำหรับข้อกำหนดเหล่านี้ ตารางต่อไปนี้แสดงข้อกำหนดดังกล่าวซ้ำเพื่อใช้อ้างอิงอย่างรวดเร็ว

ดีเพนเดนซี	ข้อจำกัดเวอร์ชัน	หมายเหตุ
PHP	`>=8.4 <9.0`	มุ่งเป้าไปที่ PHP 8.4
`nextpdf/core`	`^3.0 \|\| ^5.2`	เอนจิน NextPDF
`codeigniter4/framework`	`^4.6`	ตรวจสอบยืนยันกับ CodeIgniter 4.7.0
`ext-mbstring`	จำเป็นต้องใช้ขณะรันไทม์	ตรวจสอบหนึ่งครั้งต่อโปรเซส
`ext-zlib`	จำเป็นต้องใช้ขณะรันไทม์	ตรวจสอบหนึ่งครั้งต่อโปรเซส

แพ็กเกจเสริมที่ประกาศไว้ภายใต้ suggest จะเพิ่มความสามารถต่อไปนี้

แพ็กเกจ	เพิ่ม
`nextpdf/artisan`	ตัวเรนเดอร์ HTML ผ่าน Chrome DevTools Protocol (CDP) ซึ่งตรวจหาโดยอัตโนมัติเมื่อสร้างเอกสาร
`nextpdf/premium`	ความสามารถของ NextPDF Pro และ Enterprise รวมถึงการลงนาม PDF/A และ Factur-X
`codeigniter4/queue`	การสร้าง PDF แบบอะซิงโครนัสด้วย `GeneratePdfJob`

การติดตั้ง

ติดตั้งแพ็กเกจด้วย Composer:

composer require nextpdf/codeigniter

Composer จะเลือกเวอร์ชันของดีเพนเดนซี nextpdf/core และ codeigniter4/framework ตามข้อจำกัดเวอร์ชันด้านบน ไม่จำเป็นต้องแก้ไข service provider, bundle หรือไฟล์ bootstrap

การค้นพบทำงานอย่างไร

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

รายการโหลดอัตโนมัติแบบ files ของ Composer สำหรับแพ็กเกจ (src/CodeIgniter/Helpers/pdf_helper.php) จะลงทะเบียนฟังก์ชันตัวช่วยสองฟังก์ชัน ได้แก่ pdf() และ pdf_document() นอกจากนี้ Registrar ของแพ็กเกจยังประกาศตัวช่วย pdf ให้กับตัวโหลดตัวช่วยของ CodeIgniter ด้วย ดูลำดับการทำงานทั้งหมดได้ที่ /integrations/codeigniter/boot-and-discovery/

ตรวจสอบการติดตั้ง

ยืนยันว่า Composer เลือกเวอร์ชันและติดตั้งแพ็กเกจเรียบร้อยแล้ว:

composer show nextpdf/codeigniter

ยืนยันว่า CodeIgniter ค้นพบคลาส Services แล้ว โดยเรียกใช้เซอร์วิสในคอนโทรลเลอร์ใดก็ได้ หรือในเราต์ php spark สั้น ๆ แล้วตรวจสอบชนิดของเซอร์วิสนั้น:

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Config\Services;
use NextPDF\Core\Document;

$document = Services::pdfDocument(false);

// $document is a fresh NextPDF\Core\Document instance.
\assert($document instanceof Document);

หาก Services::pdfDocument() คืนค่า Document แสดงว่าการค้นพบทำงานได้ หากคืนค่า null แสดงว่าการค้นพบไม่ทำงาน ดูเพิ่มเติมที่ /integrations/codeigniter/troubleshooting/

กรณีพิเศษและข้อควรระวัง

หากแอปพลิเคชันโฮสต์ตั้งค่า Config\Modules::$discoverInComposer เป็น false ให้เพิ่ม nextpdf/codeigniter เข้าไปในรายการ $composerPackages['only'] มิฉะนั้น CodeIgniter จะข้ามแพ็กเกจนี้
ตัวโหลดอัตโนมัติของ Composer ที่ล้าสมัยอาจทำให้คลาส Services ไม่ถูกมองเห็น ให้รัน composer dump-autoload หลังจากอัปเกรด
แพ็กเกจประกาศ codeigniter4/queue เป็นดีเพนเดนซีสำหรับการพัฒนาเท่านั้น แอปพลิเคชันโปรดักชันที่ส่งงาน GeneratePdfJob ต้องประกาศ codeigniter4/queue เป็นดีเพนเดนซีโดยตรง

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

ติดตั้งจาก Packagist ผ่าน HTTPS และตรึงเวอร์ชันที่ Composer เลือกแล้วไว้ใน composer.lock แพ็กเกจไม่เพิ่มสคริปต์ใด ๆ ระหว่างการติดตั้ง ดูเพิ่มเติมที่ /integrations/codeigniter/security-and-operations/

ความสอดคล้องตามมาตรฐาน

การค้นพบของ Composer ขึ้นอยู่กับการโหลดอัตโนมัติแบบ PSR-4

ดูเพิ่มเติม

/integrations/codeigniter/overview/ — ความสามารถของแพ็กเกจ
/integrations/codeigniter/quickstart/ — สร้าง PDF ฉบับแรกในคอนโทรลเลอร์
/integrations/codeigniter/configuration/ — คีย์การกำหนดค่าและการเขียนทับค่า
/integrations/codeigniter/boot-and-discovery/ — ลำดับการค้นพบโดยละเอียด