การกำหนดค่าแพ็กเกจ NextPDF สำหรับ Laravel

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

config/nextpdf.php เผยแพร่ได้ด้วย php artisan vendor:publish --tag=nextpdf-config ทุกคีย์มีค่าทดแทน (fallback) จากตัวแปรสภาพแวดล้อมและค่าเริ่มต้นที่กำหนดไว้ตายตัว หน้านี้แสดงรายการแต่ละคีย์ตามที่ปรากฏใน config/nextpdf.php ของแพ็กเกจ

การติดตั้ง

php artisan vendor:publish --tag=nextpdf-config

ระหว่างการทำงานของ register() ผู้ให้บริการ (provider) ยังผสานค่าเริ่มต้นของแพ็กเกจไว้ภายใต้คีย์ config ชื่อ nextpdf ด้วย คีย์ที่ไม่ได้กำหนดค่าจะย้อนกลับไปใช้ค่าด้านล่าง แม้คุณยังไม่ได้เผยแพร่ไฟล์ config

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

ตัวแปรสภาพแวดล้อมส่วนใหญ่รองรับได้ทั้งชื่อแบบ NEXTPDF_* หรือชื่อรูปแบบเดิม TCPDF_* คำนำหน้ารูปแบบเดิมใช้ได้ในช่วงการเปลี่ยนผ่านตามที่ระบุไว้ใน UPGRADE.md ใช้ NEXTPDF_* สำหรับการใช้งานใหม่ ไฟล์ config เลือกใช้ค่าตามลำดับนี้: ตัวแปรสภาพแวดล้อม → ค่าจากไฟล์ที่เผยแพร่ → ค่าเริ่มต้นของแพ็กเกจ

พื้นผิว API — คีย์การกำหนดค่า

เค้าโครงเอกสาร

คีย์	Env (หลัก)	ค่าเริ่มต้น	ผล
page_format	NEXTPDF_PAGE_FORMAT	A4	รูปแบบหน้าเริ่มต้น: A4, A3, A5, Letter, Legal หรือ Tabloid
orientation	NEXTPDF_ORIENTATION	P	แนวตั้ง (P) หรือแนวนอน (L)
unit	NEXTPDF_UNIT	mm	หน่วยวัด: pt, mm, cm หรือ in
defaults.creator	NEXTPDF_CREATOR	NextPDF	เมตาดาตาผู้สร้างเอกสาร นำไปใช้กับ PdfDocumentInterface ระหว่างการผูก
defaults.author	NEXTPDF_AUTHOR	(ว่าง)	เมตาดาตาผู้แต่ง ใช้เฉพาะเมื่อมีค่าไม่ว่างเท่านั้น
defaults.language	NEXTPDF_LANG	en	ภาษาของเอกสาร ใช้กับการผูกเอกสาร
defaults.margin_top / _right / _bottom / _left	—	10	ระยะขอบเริ่มต้น
defaults.font_family	—	dejavusans	ตระกูลฟอนต์เริ่มต้น
defaults.font_size	—	12	ขนาดฟอนต์เริ่มต้น
defaults.trim_box	—	null	TrimBox [left, bottom, right, top] เป็นหน่วยพอยต์ หรือ null
defaults.bleed_box	—	null	BleedBox [left, bottom, right, top] เป็นหน่วยพอยต์ หรือ null

ผู้ให้บริการจะนำ defaults.creator, defaults.language และ (เมื่อกำหนดค่าไว้) defaults.author ไปใช้กับเอกสารใหม่แต่ละรายการที่ได้จากการผูก ผู้ให้บริการจะไม่ใช้ defaults.author เมื่อค่าเป็นค่าว่าง

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

คีย์	Env (หลัก)	ค่าเริ่มต้น	ผล
pdfa	NEXTPDF_PDFA	null	ระดับการจัดเก็บถาวร PDF/A: null, 4, 4e หรือ 4f ค่าที่ไม่ใช่ null จะเปิดใช้ PDF/A ในการผูกเอกสารและต้องใช้ nextpdf/premium
fonts_path	NEXTPDF_FONTS_PATH	resource_path('fonts')	ไดเรกทอรีสำหรับฟอนต์ TrueType เพิ่มเติม กำหนดเส้นทางค้นหาของรีจิสทรีฟอนต์
cache_path	NEXTPDF_CACHE_PATH	storage_path('framework/cache/tcpdf')	ไดเรกทอรีแคชสำหรับฟอนต์ที่แปลงแล้วและไฟล์ชั่วคราว
icc_profile.rgb	NEXTPDF_ICC_PROFILE_RGB	null	เส้นทางโปรไฟล์ ICC แบบ RGB จำเป็นสำหรับ PDF/A
icc_profile.cmyk	NEXTPDF_ICC_PROFILE_CMYK	null	โปรไฟล์ ICC แบบ CMYK สำหรับเวิร์กโฟลว์งานพิมพ์ที่เลือกใช้ได้
font_cache_locking	NEXTPDF_FONT_CACHE_LOCKING	true	ใช้ flock กับแคชฟอนต์เพื่อป้องกันข้อมูลเสียหายเมื่อ queue worker หลายตัวเขียนพร้อมกัน

ค่า pdfa ที่ไม่ใช่ null ต้องใช้ระดับ Premium หากไม่มี nextpdf/premium การแปลงค่าการผูกเอกสารที่ตั้งค่า pdfa ไว้ จะเกิดข้อผิดพลาด class-not-found สำหรับชนิดเวอร์ชัน PDF/A หน้านี้ ไม่ได้อธิบายพฤติกรรมการจัดเก็บถาวรของ Premium โปรดดูเอกสาร Premium ประกอบ

หน่วยความจำของ worker (รันไทม์ที่ทำงานต่อเนื่อง)

คีย์	Env (หลัก)	ค่าเริ่มต้น	ผล
preload_fonts	—	[]	เส้นทางไฟล์ฟอนต์แบบสัมบูรณ์ที่จะแปลงเมื่อ worker เริ่มทำงาน รีจิสทรีฟอนต์จะถูกล็อกหลังการอุ่นเครื่อง (warmup)
image_cache_mb	NEXTPDF_IMAGE_CACHE_MB	50	งบประมาณแคชภาพแบบ least recently used (LRU) เป็นเมกะไบต์ (MB) 0 ปิดใช้งานการแคช ผู้ให้บริการไม่บังคับขีดจำกัดสูงสุด

งบประมาณแคชภาพไม่มีขีดจำกัดสูงสุดที่ผู้ให้บริการบังคับใช้ ใช้ขีดจำกัดหน่วยความจำของคอนเทนเนอร์หรือ php.inimemory_limit เพื่อควบคุมค่านี้ ไฟล์ config แนะนำค่าสูงสุดที่ใช้ได้จริงไว้ที่ 256 MB

ลายเซ็นดิจิทัล (Premium)

คีย์	Env (หลัก)	ค่าเริ่มต้น	ผล
signature.enabled	NEXTPDF_SIGN_ENABLED	false	เมื่อเป็น false หรือเมื่อใบรับรองว่างเปล่า SignerInterface จะแปลงค่าเป็น null
signature.certificate	NEXTPDF_SIGN_CERT	null	เส้นทางใบรับรองสำหรับลงนาม
signature.private_key	NEXTPDF_SIGN_KEY	null	เส้นทางคีย์ส่วนตัว
signature.password	NEXTPDF_SIGN_PASSWORD	(ว่าง)	วลีรหัสผ่านของคีย์
signature.extra_certs	—	[]	เส้นทางใบรับรอง CA ตัวกลาง
signature.level	NEXTPDF_SIGN_LEVEL	B-B	ระดับพื้นฐาน (baseline) ของ PDF Advanced Electronic Signatures (PAdES) ที่ส่งต่อให้ตัวลงนาม

แพ็กเกจ Core ที่อธิบายในหน้านี้ไม่ได้มาพร้อม implementation ของตัวลงนาม SignerInterface จะแปลงค่าเป็น null จนกว่า nextpdf/premium จะจัดหาให้ เมื่อมี Premium ติดตั้งอยู่ level: B-B จะสร้างลายเซ็นพื้นฐาน PAdES B-B ระดับพื้นฐาน PAdES ที่สูงกว่านั้นขึ้นอยู่กับผู้ออกตราเวลา (timestamp authority) ที่กำหนดค่าไว้และความสามารถของ Premium หน้านี้ไม่ได้อธิบายระดับเหล่านั้น

ผู้ออกตราเวลา

คีย์	Env (หลัก)	ค่าเริ่มต้น	ผล
tsa.url	NEXTPDF_TSA_URL	null	ปลายทาง (endpoint) ของผู้ออกตราเวลา (TSA) เมื่อค่าว่าง TsaClient จะแปลงค่าเป็น null
tsa.username / tsa.password	NEXTPDF_TSA_USERNAME / _PASSWORD	(ว่าง)	ข้อมูลรับรอง HTTP ของ TSA
tsa.cert / tsa.key	NEXTPDF_TSA_CERT / _KEY	null	ใบรับรอง / คีย์ของไคลเอนต์สำหรับ mutual Transport Layer Security (mTLS) ไปยัง TSA
tsa.timeout	NEXTPDF_TSA_TIMEOUT	30	การหมดเวลา HTTP เป็นวินาทีสำหรับไคลเอนต์ PSR-18
tsa.pinned_public_keys	—	[]	การปักหมุด (pin) แบบ Base64 SHA-256 SubjectPublicKeyInfo (SPKI) (RFC 7469) ค่าว่างจะปิดใช้งานการปักหมุด
tsa.warn_on_key_rotation	NEXTPDF_TSA_WARN_ROTATION	true	แจ้งเตือนเมื่อ TSA แสดง SPKI ที่ไม่ได้ปักหมุดไว้
tsa.allow_insecure_http	NEXTPDF_TSA_ALLOW_INSECURE_HTTP	false	อนุญาตให้ใช้ HTTP แบบ plaintext ไปยัง TSA คงค่าเป็น false ในระบบที่ใช้งานจริง

แคชการตอบกลับ OCSP

คีย์	Env (หลัก)	ค่าเริ่มต้น	ผล
ocsp_cache.enabled	NEXTPDF_OCSP_CACHE_ENABLED	true	แคชการตอบกลับ Online Certificate Status Protocol (OCSP) ระหว่างการตรวจสอบ
ocsp_cache.ttl	NEXTPDF_OCSP_CACHE_TTL	86400	TTL ของแคชเป็นวินาที
ocsp_cache.directory	NEXTPDF_OCSP_CACHE_DIR	null	ไดเรกทอรีแคช เมื่อเป็น null จะเก็บแคชไว้ในหน่วยความจำเท่านั้น

คิว

คีย์	Env (หลัก)	ค่าเริ่มต้น	ผล
queue.connection	NEXTPDF_QUEUE_CONNECTION	null	การเชื่อมต่อคิว null จะใช้การเชื่อมต่อเริ่มต้น
queue.queue	NEXTPDF_QUEUE_NAME	pdf	คิวที่ใช้ส่ง GeneratePdfJob เข้าไป
queue.timeout	NEXTPDF_QUEUE_TIMEOUT	120	การหมดเวลาต่องานเป็นวินาที

ตัวเรนเดอร์ Chrome CDP (ส่วนขยาย Artisan)

คีย์	Env (หลัก)	ค่าเริ่มต้น	ผล
artisan.chrome_binary	NEXTPDF_ARTISAN_CHROME_BINARY	ค่าจาก env หรือไม่ได้กำหนด	เส้นทางไปยังไบนารี Chrome/Chromium
artisan.render_timeout	NEXTPDF_ARTISAN_RENDER_TIMEOUT	30	การหมดเวลาการเรนเดอร์เป็นวินาที
artisan.default_css	NEXTPDF_ARTISAN_DEFAULT_CSS	(ว่าง)	CSS เริ่มต้นที่แทรกเข้าไปใน HTML ที่เรนเดอร์
artisan.no_sandbox	NEXTPDF_ARTISAN_NO_SANDBOX	false	ปิดใช้งานแซนด์บ็อกซ์ของ Chrome
artisan.max_html_size	NEXTPDF_ARTISAN_MAX_HTML_SIZE	5000000	ขนาดอินพุต HTML สูงสุดเป็นไบต์

ส่วน artisan จะใช้กับการผูกเอกสารเฉพาะเมื่อมีคลาส browser-factory ของ Chrome อยู่เท่านั้น (ส่วนขยาย nextpdf/artisan) เมื่อไม่มีคลาสนั้น ส่วนนี้จะถูกละเว้น

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

resource: config/nextpdf.php (subset, verified against the published file)

<?php

declare(strict_types=1);

return [
    'page_format'     => env('NEXTPDF_PAGE_FORMAT', 'A4'),
    'orientation'     => env('NEXTPDF_ORIENTATION', 'P'),
    'unit'            => env('NEXTPDF_UNIT', 'mm'),
    'pdfa'            => env('NEXTPDF_PDFA', null),
    'fonts_path'      => env('NEXTPDF_FONTS_PATH', resource_path('fonts')),
    'preload_fonts'   => [],
    'image_cache_mb'  => env('NEXTPDF_IMAGE_CACHE_MB', 50),
    'queue' => [
        'connection' => env('NEXTPDF_QUEUE_CONNECTION', null),
        'queue'      => env('NEXTPDF_QUEUE_NAME', 'pdf'),
        'timeout'    => env('NEXTPDF_QUEUE_TIMEOUT', 120),
    ],
];

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

• signature.enabled = true ที่มี signature.certificate ว่างเปล่า จะยังคงแปลงค่า SignerInterface เป็น null ต้องกำหนดค่าทั้งสองอย่าง
• tsa.url = null บังคับให้ TsaClient เป็น null แม้ว่าคีย์ tsa.* อื่นจะมีค่าอยู่
• signature.level = null จะย้อนกลับไปใช้ PAdES B-B บนตัวลงนาม
• image_cache_mb ที่ตั้งค่าเป็น null (ไม่ใช่ 0) จะย้อนกลับไปใช้ค่าเริ่มต้น 50 MB ส่วน 0 จะปิดใช้งานการแคชอย่างชัดเจน
• ตัวแปรสภาพแวดล้อมรูปแบบเดิม TCPDF_* ยังอ่านได้แต่เลิกใช้แล้ว ย้ายไปใช้ NEXTPDF_*

ประสิทธิภาพ

การอ่าน config ใช้การเข้าถึงอาร์เรย์แบบ O(1) preload_fonts แลกด้วยการแปลงครั้งเดียวแบบ O(f) เมื่อ worker เริ่มทำงาน เพื่อให้คำขอแรกมีความหน่วงต่ำลง ค่า image_cache_mb ที่มากขึ้นช่วยลดการถอดรหัสภาพซ้ำ โดยแลกกับหน่วยความจำที่กระบวนการครอบครองไว้

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

tsa.allow_insecure_http ลดทอนความน่าเชื่อถือของตราเวลาและต้องคงเป็น false ในระบบที่ใช้งานจริง URL ของ TSA ควรมาจากการกำหนดค่าที่เชื่อถือได้เท่านั้น หากเปิดให้ตั้งค่าผ่านอินเทอร์เฟซผู้ดูแลระบบ ให้ใช้ไฟร์วอลล์ขาออกหรือนโยบาย DNS เพื่อลดความเสี่ยงจากการปลอมแปลงคำขอ ดู /integrations/laravel/security-and-operations/

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

ไม่มีมาตรฐานเชิงบรรทัดฐานที่กำกับรูปแบบไฟล์การกำหนดค่า ทุกคีย์ได้รับการตรวจสอบเทียบกับ config/nextpdf.php ของแพ็กเกจตามรีวิชันที่ระบุไว้ Premium กำกับความหมายของระดับลายเซ็น ซึ่งอยู่นอกขอบเขตของหน้า Core นี้

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

ส่วน signature และ tsa ขับเคลื่อนการลงนามของ Premium เมื่อติดตั้ง nextpdf/premium แล้ว ความสามารถ Enterprise แบบเลือกใช้นี้ไม่จำเป็นต้องแก้ไขโค้ดของแพ็กเกจ Core ดู https://nextpdf.dev/get-license/?intent=laravel-signing

ดูเพิ่มเติม

• /integrations/laravel/install/ — เผยแพร่ไฟล์ config
• /integrations/laravel/production-usage/ — ดูการกำหนดค่าที่ใช้งานในคอนโทรลเลอร์จริง
• /integrations/laravel/security-and-operations/ — เสริมความแข็งแกร่งให้การตั้งค่า TSA และคิว
• /integrations/laravel/boot-and-discovery/ — ดูว่าแต่ละคีย์ขับเคลื่อนการผูกส่วนใด