Template — เอกสารอ้างอิงเชิงลึก

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

เอกสารอ้างอิงเชิงลึกนี้บันทึก JSON schema ของ template ที่ยอมรับ กฎการตรวจสอบความถูกต้องทุกข้อ และพฤติกรรมการจัดรูปแบบต่อชนิดที่แม่นยำของ data binder โมดูลนี้แจง (parse) นิยาม template แล้ว bind ข้อมูลจากผู้เรียกเข้ากับ placeholder ที่มีชนิด โมดูลปล่อยสตริงที่จัดรูปแบบแล้ว ไม่ได้วาดออบเจกต์ PDF

ความพร้อมใช้งานและการอนุญาต

ความสามารถนี้มาพร้อมกับ NextPDF Pro (nextpdf/pro) และเปิดใช้งานด้วย envelope ใบอนุญาตระดับ Pro การติดตั้งใช้งานที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ ไม่มีแฟล็ก ความสามารถในขณะรันไทม์ที่จำกัดสิทธิ์โมดูลนี้ เปรียบเทียบรุ่นและรับใบอนุญาต

พื้นผิว API สาธารณะ

โมดูลนี้เปิดเผยบริการจุดเข้าใช้งานสองรายการและ value object ที่ไม่เปลี่ยนแปลงสี่รายการ สัญลักษณ์ทุกตัวด้านล่างเป็นสาธารณะและเสถียร

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
TemplateParser::parse	string $json	ตรวจสอบความถูกต้อง แล้วสร้างนิยาม	TemplateDefinition	InvalidArgumentException เมื่อมีข้อผิดพลาดการตรวจสอบใดๆ	มอบหมายให้ validate ก่อน
TemplateParser::validate	string $json	รวบรวมข้อผิดพลาดเชิงโครงสร้างทั้งหมดในรอบเดียว	list<string> (ว่างเมื่อถูกต้อง)	ไม่เคยโยน การถอดรหัส JSON ที่ล้มเหลวจะถูกคืนเป็นข้อความ	เกตที่เชื่อถือได้สำหรับขอบเขตความยาวและความแม่นยำ
TemplateDataBinder::bind	TemplateDefinition $template, array<string,mixed> $data	จับคู่ placeholder แบบไม่คำนึงถึงตัวพิมพ์ใหญ่เล็ก และจัดรูปแบบตามชนิด	BindingResult	ไม่เคยโยน ความผิดปกติจะกลายเป็นคำเตือนหรือฟิลด์ที่ขาดหาย	ใช้ค่าเริ่มต้นของ placeholder เมื่อไม่มีคีย์
TemplateDefinition::__construct	string $name, string $pageSize, string $orientation, list<TemplatePlaceholder> $placeholders, string $backgroundPdf = ''	เก็บนิยามที่แจงแล้ว	TemplateDefinition	TypeError เมื่อชนิดของอาร์กิวเมนต์ไม่ตรงกัน	value object แบบ final readonly
TemplateDefinition::getPlaceholder	string $name	ค้นหาตามชื่อแบบไม่คำนึงถึงตัวพิมพ์ใหญ่เล็ก	TemplatePlaceholder|null	ไม่มีความล้มเหลว คืน null เมื่อไม่มี	—
TemplateDefinition::requiredFields	ไม่มี	รวบรวมชื่อของ placeholder ที่ไม่มีค่าเริ่มต้น	list<string>	ไม่มีความล้มเหลว	ค่าเริ่มต้นที่ไม่ว่างทำให้ placeholder เป็นตัวเลือก
TemplatePlaceholder::__construct	string $name, PlaceholderType $type, float $x, float $y, float $width, float $height, string $defaultValue = '', string $format = ''	เก็บพื้นที่ placeholder หนึ่งรายการ	TemplatePlaceholder	TypeError เมื่อชนิดของอาร์กิวเมนต์ไม่ตรงกัน	พิกัดเป็นหน่วยพอยต์นับจากมุมบนซ้าย
TemplatePlaceholder::matches	string $key	เปรียบเทียบชื่อแบบไม่คำนึงถึงตัวพิมพ์ใหญ่เล็ก	bool	ไม่มีความล้มเหลว	—
BindingResult::__construct	list<BoundPlaceholder> $bindings, list<string> $missingFields, list<string> $warnings	เก็บผลลัพธ์ของการ binding	BindingResult	TypeError เมื่อชนิดของอาร์กิวเมนต์ไม่ตรงกัน	value object แบบ final readonly
BindingResult::isComplete	ไม่มี	รายงานว่าฟิลด์ที่จำเป็นทุกฟิลด์ถูก bind หรือไม่	bool	ไม่มีความล้มเหลว	จริงเมื่อ missingFields ว่าง
BindingResult::count	ไม่มี	นับ placeholder ที่ bind สำเร็จ	int	ไม่มีความล้มเหลว	—
BoundPlaceholder::__construct	TemplatePlaceholder $placeholder, string $formattedValue, mixed $rawValue	จับคู่ placeholder กับค่าที่จัดรูปแบบแล้ว	BoundPlaceholder	TypeError เมื่อชนิดของอาร์กิวเมนต์ไม่ตรงกัน	value object แบบ final readonly
PlaceholderType	enum case Text, Image, Barcode, Date, Number, Currency, Conditional	อนุกรมวิธาน placeholder แบบสตริง	อินสแตนซ์ enum	ValueError จาก from() เมื่อค่าไม่รู้จัก	tryFrom() คืน null แทน
PlaceholderType::requiresFormatting	ไม่มี	รายงานว่าชนิดนั้นใช้สตริงรูปแบบหรือไม่	bool	ไม่มีความล้มเหลว	จริงสำหรับ Date, Number, Currency

final class TemplateParser
{
    public function parse(string $json): TemplateDefinition;
    public function validate(string $json): array;
}

final class TemplateDataBinder
{
    public function bind(TemplateDefinition $template, array $data): BindingResult;
}

สัญญาพฤติกรรม

รูปแบบ JSON ที่ยอมรับ:

{
  "name": "string (required, non-empty)",
  "pageSize": "A3|A4|A5|A6|B4|B5|Letter|Legal|Tabloid",
  "orientation": "P|L",
  "backgroundPdf": "optional path string",
  "placeholders": [
    { "name": "string", "type": "text|image|barcode|date|number|currency|conditional",
      "x": number, "y": number, "width": number, "height": number,
      "defaultValue": "optional", "format": "optional" }
  ]
}

กฎการตรวจสอบความถูกต้อง ทั้งหมดแสดงผ่าน validate เป็นข้อความ และถูกรวมโดย parse เป็นข้อยกเว้นเดียว:

• name ขาดหายไปหรือว่าง
• pageSize อยู่นอก allow-list หรือ orientation ไม่ใช่ P หรือ L
• placeholders ขาดหายไป หรือเป็นค่าที่ไม่ใช่ array
• ต่อ placeholder: ชื่อขาดหายไปหรือว่าง; ชนิดไม่ถูกต้อง; x, y, width, height ขาดหายไปหรือไม่ใช่ตัวเลข; ชื่อซ้ำ (ไม่คำนึงถึงตัวพิมพ์ใหญ่เล็ก)
• defaultValue: ไม่ใช่สตริง ยาวเกิน 4096 ไบต์ หรือมีอักขระควบคุม ASCII
• format: ไม่ใช่สตริง ยาวเกิน 256 ไบต์ หรือมีอักขระควบคุม ASCII
• format ของ placeholder ชนิด number ที่ไม่ใช่จำนวนเต็มไม่ติดลบ หรือที่เกิน 30

ความหมายของการ binding (TemplateDataBinder::bind):

• คีย์ข้อมูลถูกแปลงเป็นตัวพิมพ์เล็กเพื่อการจับคู่แบบไม่คำนึงถึงตัวพิมพ์ใหญ่เล็กกับชื่อ placeholder
• คีย์ที่ขาดหายซึ่งมีค่าเริ่มต้นที่ไม่ว่างจะ bind ค่าเริ่มต้น ส่วนคีย์ที่ขาดหายและไม่มีค่าเริ่มต้น จะถูกรายงานใน missingFields
• ค่าของ text, image และ barcode จะถูก cast เป็นสตริงโดยไม่เปลี่ยนแปลง
• การ binding วันที่รับ DateTimeInterface, integer Unix timestamp หรือสตริงในหนึ่งในสี่ รูปแบบที่ระบุชัดเจน รูปแบบผลลัพธ์เริ่มต้นคือ Y-m-d
• การ binding ตัวเลขใช้ number_format(value, decimals, '.', ',') จำนวนทศนิยมมาจาก format มีค่าเริ่มต้นเป็น 2 และถูกจำกัดในช่วง 0 ถึง 30
• การ binding สกุลเงินจะนำ format มานำหน้าตัวเลขที่จัดรูปแบบแล้ว โดยคำนำหน้าเริ่มต้นเป็น $
• การ binding แบบ conditional จะปล่อย "true" หรือ "false" จากการ cast แบบบูลีน

กรณีขอบและโหมดความล้มเหลว

• backgroundPdf จะไม่ถูกเปิดหรือ dereference โดยโมดูลนี้ มันเป็นสตริง ทึบที่ส่งต่อให้ตัวเรนเดอร์
• ค่าที่ไม่ใช่ตัวเลขซึ่ง bind กับ placeholder ชนิด Number หรือ Currency จะให้ คำเตือน ค่าจะถูก cast เป็นสตริง ไม่ใช่ถูกปฏิเสธ
• สตริงวันที่ถูกแจงอย่างเข้มงวด โทเคนแบบสัมพัทธ์และภาษาธรรมชาติ (“now”, “+1 year”, “tomorrow”) ไม่ตรงกับรูปแบบที่ยอมรับใดๆ จึงเตือนและค่าดิบจะถูกส่งผ่านไปโดยไม่เปลี่ยนแปลง
• ค่าวันที่ที่เป็นจำนวนเต็มจะถูกอ่านเป็น Unix timestamp ผ่านรูปแบบ epoch @
• ความแม่นยำ format ของ Number ที่อยู่นอกช่วง 0 ถึง 30 ซึ่งไปถึง binder จะถูกปฏิเสธ พร้อมคำเตือน binder จะย้อนกลับไปใช้ความแม่นยำเริ่มต้นที่ 2
• ไม่มีการดำเนินการเชิงการเข้ารหัสลับเกิดขึ้นในโมดูลนี้ จึงไม่มีพฤติกรรมเฉพาะของโหมด FIPS

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

ไม่มีพื้นผิวข้อกำหนด PDF โดยตรง คำศัพท์ของขนาดหน้าและการวางแนวเป็นแบบแผนของ NextPDF และโมดูลนี้ปล่อยค่าที่จัดรูปแบบแล้ว ไม่ใช่ออบเจกต์ PDF allow-list สตริงวันที่แบบ เข้มงวดยอมรับโปรไฟล์วันที่/เวลาแบบอินเทอร์เน็ตของ ISO 8601 ที่นิยามใน RFC 3339 §5.6 ควบคู่กับวันที่ปฏิทิน Y-m-d และรูปแบบวันที่-เวลาแบบท้องถิ่นสองรูปแบบ NextPDF บันทึก ความสามารถในการอ่านรูปแบบเหล่านี้ แต่ไม่ได้อ้างการรับรองใดๆ ต่อ RFC 3339 หรือ ISO 8601

หมายเหตุการพัฒนา

• TemplateParser และ TemplateDataBinder ไม่มีสถานะ อินสแตนซ์เดียวสามารถนำกลับมา ใช้ซ้ำและใช้ร่วมกันข้ามการ binding ได้อย่างปลอดภัย
• value object ทั้งสี่เป็น final readonly ควรสร้างผ่าน parser แทนการสร้างด้วยมือ สำหรับข้อมูลนำเข้าในการใช้งานจริง
• validate รายงานข้อผิดพลาดเชิงโครงสร้างทุกข้อในรอบเดียว ในขณะที่ parse เรียก validate ก่อนและโยนด้วยข้อความที่รวมแล้ว ใช้ validate สำหรับข้อเสนอแนะแบบฟอร์ม และ parse สำหรับการนำเข้าแบบ fail-fast
• ขอบเขตความยาวและความแม่นยำถูกบังคับใช้ที่ parser ในฐานะเกตที่เชื่อถือได้ TemplateDataBinder ตรวจสอบความแม่นยำของตัวเลขซ้ำในฐานะการป้องกันฝั่งปลายทางต่อ การขยายหน่วยความจำของ number_format

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น เส้นทาง namespace ภายใน คลาสช่วยเหลือ ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้า ticket อยู่นอกขอบเขต

ดูเพิ่มเติม

• Template (คู่มือความสามารถ)
• Toc
• Merge