Pro รุ่น

เทมเพลต

ภาพรวมโดยสังเขป

NextPDF\Pro\Template แจงนิยาม template แบบ JSON ให้เป็น value object ที่มีชนิด และ bind array ข้อมูลแบบ associative เข้ากับ placeholder ของมันด้วย การจัดรูปแบบที่รับรู้ชนิด มันผลิตผลลัพธ์การ binding ที่มีโครงสร้าง มันไม่ เรนเดอร์ PDF ด้วยตัวเอง

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

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

การติดตั้ง

composer require nextpdf/pro:^3

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

template เป็นเอกสาร JSON ที่อธิบายการตั้งค่าหน้าและรายการ placeholder ที่มีตำแหน่ง TemplateParser ตรวจสอบความถูกต้องของ JSON และผลิต TemplateDefinition แบบ immutable การตรวจสอบความถูกต้องเป็นแบบเข้มงวด มันตรวจสอบขนาดหน้า เทียบกับ allow-list (A3–A6, B4, B5, Letter, Legal, Tabloid) การวางแนว (P หรือ L) และชื่อ ชนิด และพิกัดเชิงตัวเลขของแต่ละ placeholder และมันปฏิเสธชื่อ placeholder ที่ซ้ำกัน

TemplateDataBinder bind array ข้อมูล (match กับชื่อ placeholder โดยไม่คำนึงถึงตัวพิมพ์ใหญ่เล็ก) และจัดรูปแบบแต่ละค่าตาม PlaceholderType:

Text / Image / Barcode ค่าถูกส่งผ่านเป็นสตริง
Date จัดรูปแบบด้วยรูปแบบของ placeholder (ค่าเริ่มต้น Y-m-d) รับสตริง Unix timestamp หรือ DateTimeInterface
Number number_format พร้อมจำนวนทศนิยมจากรูปแบบ (ค่าเริ่มต้น 2)
Currency ตัวเลขที่จัดรูปแบบด้วยสตริงรูปแบบเป็นคำนำหน้า (ค่าเริ่มต้น $)
Conditional "true" หรือ "false" ตามความเป็นจริง

ผลลัพธ์คือ BindingResult ที่พกค่าที่ bind แล้ว รายการ ฟิลด์ที่จำเป็นที่ขาดหายไป และคำเตือนการจัดรูปแบบใด ๆ การเปลี่ยนค่าที่ bind แล้ว ให้เป็น PDF ที่เรนเดอร์เป็นความรับผิดชอบของผู้เรียกใช้ โดยใช้ document และ writer API ของ Core และการอ้างอิง backgroundPdf ที่เลือกได้

เหตุใดจึงทำงานเช่นนี้

parser เป็นด่านที่มีอำนาจเพียงหนึ่งเดียว มันเปลี่ยน JSON ที่ไม่น่าเชื่อถือให้เป็น TemplateDefinition แบบ immutable ที่มีชนิดครบถ้วน จากนั้นการ binding จึงทำงานเป็นฟังก์ชัน บริสุทธิ์ของ value นั้น ทุกฟิลด์ที่จะไปถึง sink การจัดรูปแบบในภายหลังถูกใส่ allow-list และจำกัดความยาวตั้งแต่เวลาแจง ขนาดหน้า การวางแนว ความละเอียดตัวเลข และอักขระควบคุมทั้งหมดล้มเหลวที่นี่ ไม่ใช่กลางการเรนเดอร์ สตริงวันที่ถูก match เทียบกับชุดรูปแบบมาตรฐานที่ตายตัว ดังนั้นค่าอย่าง now หรือ +1 year จึงไม่สามารถทำให้เอาต์พุตขึ้นกับนาฬิกาผนังได้ โมดูลหยุด อย่างจงใจที่ BindingResult และปล่อยการเรนเดอร์ การแปลงเส้นทาง และการ composite พื้นหลังให้ผู้เรียกใช้ ซึ่งทำให้ขอบเขตความน่าเชื่อถือชัดเจน

พื้นเพการออกแบบ: ใบแจ้งหนี้และ e-invoicing

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

Input สตริง JSON (TemplateParser) และ array ข้อมูล (TemplateDataBinder)
Output TemplateDefinition จากการแจง BindingResult จากการ binding
Validation validate() คืนรายการข้อผิดพลาดที่มนุษย์อ่านได้และ ไม่เคยโยน parse() โยน InvalidArgumentException เมื่อการตรวจสอบความถูกต้อง ล้มเหลว
Missing data placeholder ที่ไม่มีข้อมูลและมี default ว่างจะ ถูกรายงานใน missingFields ส่วนที่มี default ที่ไม่ว่างจะใช้ default
Determinism การแจงและการ binding เป็นฟังก์ชันบริสุทธิ์ของอินพุต

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

Type	Kind	Key members
`NextPDF\Pro\Template\TemplateParser`	`final class`	`parse(string $json): TemplateDefinition`, `validate(string $json): list<string>`
`NextPDF\Pro\Template\TemplateDataBinder`	`final class`	`bind(TemplateDefinition $template, array $data): BindingResult`
`NextPDF\Pro\Template\TemplateDefinition`	`final readonly class`	`string $name`, `string $pageSize`, `string $orientation`, `array $placeholders`, `string $backgroundPdf`, `getPlaceholder(string $name): ?TemplatePlaceholder`, `requiredFields(): list<string>`
`NextPDF\Pro\Template\TemplatePlaceholder`	`final readonly class`	name, `PlaceholderType $type`, coordinates, default, format
`NextPDF\Pro\Template\BindingResult`	`final readonly class`	`array $bindings`, `array $missingFields`, `array $warnings`
`NextPDF\Pro\Template\PlaceholderType`	`enum`	`Text`, `Image`, `Barcode`, `Date`, `Number`, `Currency`, `Conditional`; `requiresFormatting(): bool`

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

<?php

declare(strict_types=1);

use NextPDF\Pro\Template\TemplateDataBinder;
use NextPDF\Pro\Template\TemplateParser;

$json = '{"name":"Invoice","pageSize":"A4","orientation":"P","placeholders":'
 . '[{"name":"total","type":"currency","x":400,"y":700,"width":120,'
 . '"height":18,"format":"$"}]}';

$template = (new TemplateParser())->parse($json);
$result = (new TemplateDataBinder())->bind($template, ['total' => 1299.5]);

foreach ($result->bindings as $bound) {
 echo $bound->placeholder->name, ' => ', $bound->formattedValue, "\n";
}

ตัวอย่างโค้ด — โปรดักชัน

<?php

declare(strict_types=1);

use NextPDF\Pro\Template\TemplateDataBinder;
use NextPDF\Pro\Template\TemplateParser;

function bindOrReject(string $json, array $data): array
{
 $parser = new TemplateParser();

 $errors = $parser->validate($json);
 if ($errors !== []) {
 throw new InvalidArgumentException(implode('; ', $errors));
 }

 $template = $parser->parse($json);
 $result = (new TemplateDataBinder())->bind($template, $data);

 if ($result->missingFields !== []) {
 throw new RuntimeException(
 'missing required fields: ' . implode(', ', $result->missingFields),
 );
 }

 return $result->bindings; // hand to the renderer
}

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

สตริงวันที่ที่แจงไม่ได้จะให้คำเตือนและสตริงเดิมจะ ถูกเก็บไว้ แทนที่จะโยน
สตริงรูปแบบสกุลเงินถูกใช้เป็นคำนำหน้า literal (เช่น "$" หรือ "EUR ") ไม่ใช่ตัวระบุ locale
backgroundPdf เป็นการอ้างอิงเส้นทางที่พกไว้บนนิยาม โมดูลนี้ ไม่เปิด ตรวจสอบความถูกต้อง หรือ composite มัน นั่นเป็นงานของตัวเรนเดอร์
ชื่อ placeholder ถูก match โดยไม่คำนึงถึงตัวพิมพ์ใหญ่เล็ก ชื่อที่ซ้ำกันใน JSON เป็นข้อผิดพลาดของการตรวจสอบความถูกต้อง

ประสิทธิภาพ

การแจงคือการ decode JSON หนึ่งครั้งบวกการตรวจสอบความถูกต้องเชิงโครงสร้าง การ binding เป็นเชิงเส้นตาม จำนวน placeholder ดู performance_budget

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

JSON ถูก decode ด้วย JSON_THROW_ON_ERROR และตรวจสอบความถูกต้องเทียบกับ allow-list ที่ตายตัวก่อนที่ TemplateDefinition จะถูกสร้าง โมดูลทำการ I/O ของไฟล์หรือเครือข่ายเป็นศูนย์ เส้นทาง backgroundPdf ไม่ถูก dereference ที่นี่ ดังนั้น การจัดการเส้นทางและการควบคุมการเข้าถึงเป็นของตัวเรนเดอร์

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

โมดูลนี้ไม่มีพื้นผิวข้อกำหนด PDF โดยตรง มันแจง template แบบ JSON และจัดรูปแบบค่า คำศัพท์ของขนาดหน้าและการวางแนวเป็น แบบแผนของ NextPDF ไม่ใช่โครงสร้าง PDF เชิงบรรทัดฐาน

ทางเลือก / fallback ของ Core

ไม่มีชั้นนิยาม template ของ Core สำหรับการสร้างเอกสารแบบ imperative ทั้งหมด ให้ใช้ document และ writer API ของ Core แบบโอเพนซอร์สโดยตรง ดู /modules/core/document/

หมายเหตุขอบเขต Enterprise

โมดูลนี้นิยามและ bind template มันไม่ทำการประสานงาน mail-merge การจัดกำหนดการ batch job หรือการเรนเดอร์ ความกังวลเหล่านั้นอยู่นอกขอบเขต และถูกจัดการที่อื่น

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

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