การกำหนดค่า NextPDF สำหรับ CodeIgniter 4

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

การกำหนดค่า NextPDF อยู่ใน NextPDF\CodeIgniter\Config\NextPdf ซึ่งเป็นคลาสย่อยของ BaseConfig ของ CodeIgniter คุณสามารถแทนที่ค่าได้ด้วยการขยายคลาสใน app/Config/ หรือตั้งคีย์ .env ที่มีคำนำหน้า nextpdf. ค่าเริ่มต้นใช้งานได้โดยไม่ต้องกำหนดค่าเพิ่มเติม

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

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

เส้นทางฟอนต์และแคชเริ่มต้นอ้างอิงค่าคงที่ WRITEPATH ของ CodeIgniter ได้แก่ WRITEPATH . 'fonts' และ WRITEPATH . 'cache/nextpdf'

คีย์การกำหนดค่า

แต่ละคีย์ด้านล่างเป็นพร็อพเพอร์ตี้สาธารณะของ NextPdf ค่าเริ่มต้นผ่านการตรวจสอบเทียบกับซอร์สโค้ดของแพ็กเกจแล้ว

ค่าเริ่มต้นของหน้าและเอกสาร

คีย์	ชนิด	ค่าเริ่มต้น	คำอธิบาย
pageFormat	string	A4	รูปแบบหน้า
orientation	string	P	P คือแนวตั้ง หรือ L คือแนวนอน
unit	string	mm	หน่วยวัด
defaults.creator	string	NextPDF	เมทาดาทาของผู้สร้าง Portable Document Format (PDF)
defaults.author	string	''	เมทาดาทาของผู้เขียน ข้ามเมื่อค่าว่างเปล่า
defaults.language	string	en	แท็กภาษาของเอกสาร
defaults.margin_top	float	10.0	ระยะขอบบน
defaults.margin_right	float	10.0	ระยะขอบขวา
defaults.margin_bottom	float	10.0	ระยะขอบล่าง
defaults.margin_left	float	10.0	ระยะขอบซ้าย
defaults.font_family	string	dejavusans	ตระกูลฟอนต์เริ่มต้น
defaults.font_size	float	12.0	ขนาดฟอนต์เริ่มต้น
defaults.trim_box	list<float>|null	null	กล่องตัดเจียน (trim box) เมื่อกำหนดค่าไว้
defaults.bleed_box	list<float>|null	null	กล่องเผื่อตัดตก (bleed box) เมื่อกำหนดค่าไว้

แพ็กเกจจะใช้ defaults.creator และ defaults.language กับ ทุกเอกสาร และใช้ defaults.author เฉพาะเมื่อค่า ไม่ว่างเปล่าเท่านั้น

เส้นทางและแคช

คีย์	ชนิด	ค่าเริ่มต้น	คำอธิบาย
fontsPath	string	WRITEPATH/fonts	ไดเรกทอรีไฟล์ฟอนต์
cachePath	string	WRITEPATH/cache/nextpdf	ไดเรกทอรีแคช
preloadFonts	list<string>	[]	เส้นทางฟอนต์แบบสัมบูรณ์ที่อุ่นเครื่องไว้ระหว่างบูต
imageCacheMb	int	50	งบประมาณแคชรูปภาพแบบ least recently used (LRU) เป็นเมกะไบต์ (MB)
fontCacheLocking	bool	true	ล็อกแคชฟอนต์หลังอุ่นเครื่อง

รีจิสทรีฟอนต์จะปฏิเสธ fontsPath ใดๆ ที่มี stream wrapper (://) หรือ null byte และจะโยนข้อผิดพลาดขณะรันไทม์ ดู /integrations/codeigniter/security-and-operations/

การจัดเก็บถาวรและสี (NextPDF Pro)

คีย์	ชนิด	ค่าเริ่มต้น	คำอธิบาย
pdfa	string|null	null	เวอร์ชัน PDF/A: 4, 4e, 4f
iccProfile.rgb	string|null	null	เส้นทางโปรไฟล์ International Color Consortium (ICC) สำหรับแดง เขียว และน้ำเงิน (RGB)
iccProfile.cmyk	string|null	null	เส้นทางโปรไฟล์ ICC สำหรับฟ้า ม่วงแดง เหลือง และดำ (CMYK)

pdfa จะมีผลเฉพาะเมื่อมีการติดตั้ง NextPDF Pro และ ความสามารถการจัดเก็บถาวรพร้อมใช้งาน เมื่อใช้เฉพาะเวอร์ชัน core คีย์นี้จะถูกละเว้น

ลายเซ็นดิจิทัล (NextPDF Pro / Enterprise)

คีย์	ชนิด	ค่าเริ่มต้น	คำอธิบาย
signature.enabled	bool	false	เปิดใช้งานบริการลงนาม
signature.certificate	string|null	null	เส้นทางไฟล์ใบรับรอง
signature.private_key	string|null	null	เส้นทางไฟล์คีย์ส่วนตัว
signature.password	string	''	รหัสผ่านคีย์ส่วนตัว
signature.extra_certs	list<string>	[]	เส้นทางใบรับรองในสายโซ่เพิ่มเติม
signature.level	string	B-B	ตัวระบุระดับลายเซ็น

Services::pdfSigner() จะคืนค่า null เว้นแต่ signature.enabled เป็น true และ signature.certificate ไม่ว่างเปล่า ระดับเริ่มต้น คือ B-B NextPDF Pro จัดเตรียมลายเซ็นพื้นฐานระดับ B-B ระดับการตรวจสอบ ความถูกต้องระยะยาวเป็นความสามารถของ Enterprise แยกต่างหาก และ มีบันทึกไว้ในเอกสารอ้างอิงของ Premium ไม่ใช่ที่นี่

PDF Advanced Electronic Signatures (PAdES) B-T ถูกสร้างโดยเอนจิน Core การผสานรวมกับ CodeIgniter ไม่ได้เพิ่ม B-T ด้วยตัวเอง และ Pro มาพร้อมเฉพาะลายเซ็นพื้นฐานระดับ B-B เท่านั้น เอกสารนี้จะได้รับการปรับปรุงหาก และเมื่อมีการเปิดตัว Pro B-T

หน่วยงานประทับเวลา (Time Stamp Authority)

คีย์	ชนิด	ค่าเริ่มต้น	คำอธิบาย
tsa.url	string|null	null	URL ของปลายทางหน่วยงานประทับเวลา (TSA)
tsa.username	string	''	ชื่อผู้ใช้สำหรับการยืนยันตัวตนพื้นฐานของ TSA
tsa.password	string	''	รหัสผ่านสำหรับการยืนยันตัวตนพื้นฐานของ TSA
tsa.cert	string|null	null	เส้นทางใบรับรองไคลเอนต์
tsa.key	string|null	null	เส้นทางคีย์ไคลเอนต์
tsa.timeout	int	30	ระยะหมดเวลาของคำขอเป็นวินาที
tsa.pinned_public_keys	list<string>	[]	คีย์สาธารณะของ TSA ที่ปักหมุดไว้
tsa.warn_on_key_rotation	bool	true	เตือนเมื่อมีการหมุนเวียนคีย์ของ TSA
tsa.allow_insecure_http	bool	false	อนุญาตให้ใช้ HTTP แบบข้อความธรรมดาไปยัง TSA

Services::tsaClient() จะคืนค่า null เมื่อ tsa.url เป็น null หรือเป็น สตริงว่างเปล่า เมื่อเลือกระดับลายเซ็นที่ต้องใช้ การประทับเวลา ตัวลงนามจะแนบไคลเอนต์ TSA ให้โดยอัตโนมัติ

แคช OCSP

คีย์	ชนิด	ค่าเริ่มต้น	คำอธิบาย
ocspCache.enabled	bool	true	เปิดใช้งานแคชการตอบกลับ Online Certificate Status Protocol (OCSP)
ocspCache.ttl	int	86400	อายุของแคช (time to live, TTL) เป็นวินาที
ocspCache.directory	string|null	null	ไดเรกทอรีแคช ใช้ค่าเริ่มต้นของเอนจินเมื่อเป็น null

ตัวเรนเดอร์ HTML ของ Chrome (NextPDF Artisan)

คีย์	ชนิด	ค่าเริ่มต้น	คำอธิบาย
artisan.chrome_binary	string|null	null	เส้นทางไบนารีของ Chrome/Chromium
artisan.render_timeout	int	30	ระยะหมดเวลาของการเรนเดอร์เป็นวินาที
artisan.default_css	string	''	สไตล์ชีตเริ่มต้น
artisan.no_sandbox	bool	false	ส่งผ่าน --no-sandbox ไปยัง Chrome
artisan.max_html_size	int	5000000	ขนาด HTML ที่นำเข้าสูงสุดเป็นไบต์

ตัวเรนเดอร์ Chrome จะถูกกำหนดค่าสำหรับเอกสารเฉพาะเมื่อ มีการตั้งค่า artisan.chrome_binary และ ติดตั้ง nextpdf/artisan แล้วเท่านั้น

แทนที่ด้วย .env

BaseConfig นำค่าที่แทนที่จากสภาพแวดล้อมมาใช้เป็นรายพร็อพเพอร์ตี้ คีย์การค้นหาคือชื่อคลาสสั้นแบบตัวพิมพ์เล็ก nextpdf ตามด้วยเส้นทางพร็อพเพอร์ตี้ ใช้จุดเพื่อระบุคีย์อาร์เรย์ที่ซ้อนกัน ยอมรับทั้งรูปแบบจุดและรูปแบบขีดล่าง

.env

nextpdf.fontsPath = /var/www/writable/fonts
nextpdf.imageCacheMb = 100
nextpdf.signature.enabled = true
nextpdf.signature.certificate = /etc/nextpdf/cert.pem
nextpdf.signature.private_key = /etc/nextpdf/key.pem
nextpdf.tsa.url = https://tsa.example.com/timestamp
nextpdf.artisan.chrome_binary = /usr/bin/chromium
nextpdf.defaults.creator = Acme Billing
nextpdf.defaults.language = zh-TW

คำนำหน้าคือชื่อคลาสสั้นแบบตัวพิมพ์เล็ก ค่านี้ยังคงเป็น nextpdf แม้ชื่อคลาสจะเขียนเป็น NextPdf และยังใช้รูปแบบชื่อเต็มได้ (NextPDF\CodeIgniter\Config\NextPdf.fontsPath)

แทนที่โดยขยายคลาส

สำหรับการกำหนดค่าแบบมีชนิดและควบคุมเวอร์ชันได้ ให้ขยายคลาสของแพ็กเกจใน app/Config/ CodeIgniter จะโหลดคลาสของแอปพลิเคชันแทนค่าเริ่มต้นของแพ็กเกจ ไฟล์นี้ประกาศคลาสและไม่ก่อให้เกิดผลข้างเคียง แนวทางนี้สอดคล้องกับความคาดหวังของ PSR-1 ที่ว่าไฟล์ควรประกาศสัญลักษณ์หรือรันตรรกะที่ก่อผลข้างเคียง แต่ไม่ควรทำทั้งสองอย่าง (PSR-1 §x1.x1.p3)

<?php

declare(strict_types=1);

namespace Config;

use NextPDF\CodeIgniter\Config\NextPdf as BaseNextPdf;

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

    public string $fontsPath = WRITEPATH . 'fonts';

    /** @var array{creator: string, author: string, language: string, margin_top: float, margin_right: float, margin_bottom: float, margin_left: float, font_family: string, font_size: float, trim_box: list<float>|null, bleed_box: list<float>|null} */
    public array $defaults = [
        'creator' => 'Acme Billing',
        'author' => 'Acme, Inc.',
        'language' => 'en',
        'margin_top' => 12.0,
        'margin_right' => 12.0,
        'margin_bottom' => 12.0,
        'margin_left' => 12.0,
        'font_family' => 'dejavusans',
        'font_size' => 11.0,
        'trim_box' => null,
        'bleed_box' => null,
    ];
}

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

• การแทนที่คีย์ที่ซ้อนกันเพียงคีย์เดียวด้วย .env จะเปลี่ยนเฉพาะคีย์นั้น ส่วนที่เหลือของอาร์เรย์จะคงค่าเริ่มต้นไว้
• .env เป็นสตริง CodeIgniter จะแปลง true/false และสตริงตัวเลข ให้ใส่เครื่องหมายคำพูดล้อมรอบค่าที่ต้องคงเป็นสตริงตามตัวอักษร
• การขยายคลาสด้วยอาร์เรย์ defaults เพียงบางส่วนจะแทนที่อาร์เรย์ทั้งหมด ให้ระบุทุกคีย์ตามที่แสดงด้านบน

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

เก็บเส้นทางใบรับรองและคีย์ไว้นอกระบบควบคุมซอร์ส ส่งค่าผ่าน .env หรือตัวจัดการความลับ tsa.allow_insecure_http ต้องคงเป็น false ในการใช้งานจริง ดู /integrations/codeigniter/security-and-operations/

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

• ไฟล์ส่วนขยายการกำหนดค่าของแอปพลิเคชันประกาศคลาสหนึ่งรายการและไม่มีผลข้างเคียง (PSR-1 §x1.x1.p3)

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

NextPDF core เป็น Apache-2.0 คีย์ signature.* และ pdfa จะมีผลเฉพาะเมื่อมีการติดตั้ง NextPDF Pro หรือ Enterprise แพ็กเกจ CodeIgniter เปิดเผยเมธอดบริการที่สอดคล้องกัน เมธอดเหล่านั้นจะคืนค่า null จนกว่าจะติดตั้งแพ็กเกจ Premium ที่ตรงกัน ดู </get-license/?intent=codeigniter-signing>

ดูเพิ่มเติม

• /integrations/codeigniter/install/ — ติดตั้งแพ็กเกจ
• /integrations/codeigniter/quickstart/ — PDF แรก
• /integrations/codeigniter/production-usage/ — คอนโทรลเลอร์ที่เชื่อม DI และงานคิว
• /integrations/codeigniter/security-and-operations/ — การเพิ่มความแข็งแกร่งด้านการลงนามและการกำหนดค่าเส้นทาง