Pro phiên bản

Mẫu

Tổng quan nhanh

NextPDF\Pro\Template phân tích một định nghĩa template JSON thành một value object có kiểu và ràng buộc một mảng dữ liệu liên kết vào các placeholder của nó với định dạng nhận biết kiểu. Nó tạo ra một kết quả ràng buộc có cấu trúc; nó không tự render một PDF.

Tình trạng khả dụng & cấp phép

Tính năng này có trong NextPDF Pro (nextpdf/pro) và được kích hoạt bằng một license envelope hạng Pro. Một triển khai không có quyền đó sẽ không nạp các lớp của tính năng. Không có cờ năng lực lúc chạy bổ sung nào kiểm soát module này ngoài giấy phép theo hạng. So sánh các phiên bản và lấy giấy phép.

Cài đặt

composer require nextpdf/pro:^3

Tổng quan khái niệm

Một template là một tài liệu JSON mô tả một thiết lập trang và một danh sách các placeholder được định vị. TemplateParser thẩm định JSON và tạo ra một TemplateDefinition bất biến. Việc thẩm định là nghiêm ngặt: nó kiểm tra kích thước trang theo một danh sách cho phép (A3–A6, B4, B5, Letter, Legal, Tabloid), hướng trang (P hoặc L), và tên, kiểu, cùng tọa độ số của mỗi placeholder, và nó từ chối các tên placeholder trùng lặp.

TemplateDataBinder ràng buộc một mảng dữ liệu (được khớp không phân biệt hoa thường với tên placeholder) và định dạng mỗi giá trị theo PlaceholderType:

Text / Image / Barcode — giá trị đi qua nguyên trạng dưới dạng một chuỗi.
Date — được định dạng theo format của placeholder (mặc định Y-m-d), chấp nhận chuỗi, dấu thời gian Unix, hoặc DateTimeInterface.
Number — number_format với số chữ số thập phân lấy từ format (mặc định 2).
Currency — số được định dạng với chuỗi format làm tiền tố (mặc định $).
Conditional — "true" hoặc "false" dựa trên tính chân lý (truthiness).

Kết quả là một BindingResult mang theo các giá trị đã ràng buộc, danh sách các trường bắt buộc còn thiếu, và bất kỳ cảnh báo định dạng nào. Việc biến các giá trị đã ràng buộc thành một PDF được render là trách nhiệm của bên gọi, sử dụng các API document và writer của Core cùng tham chiếu backgroundPdf tùy chọn.

Vì sao nó hoạt động theo cách này

Bộ phân tích là cổng thẩm quyền duy nhất. Nó biến JSON không đáng tin thành một TemplateDefinition bất biến, có kiểu đầy đủ, và việc ràng buộc sau đó chạy như một hàm thuần túy của giá trị đó. Mọi trường sau này đi đến một điểm nhận định dạng đều được đưa vào danh sách cho phép và giới hạn độ dài tại thời điểm phân tích. Kích thước trang, hướng trang, độ chính xác số, và các ký tự điều khiển đều thất bại ở đây, chứ không phải giữa lúc render. Các chuỗi date được khớp theo một tập cố định các format chuẩn tắc, nên một giá trị như now hay +1 year không thể khiến đầu ra phụ thuộc vào đồng hồ hệ thống. Module dừng lại có chủ ý ở một BindingResult và để việc render, phân giải đường dẫn, và ghép nền cho bên gọi, nhờ đó giữ cho ranh giới tin cậy được rõ ràng.

Bối cảnh thiết kế: Hóa đơn và hóa đơn điện tử.

Hợp đồng hành vi

Đầu vào. Một chuỗi JSON (TemplateParser) và một mảng dữ liệu (TemplateDataBinder).
Đầu ra. TemplateDefinition từ việc phân tích; BindingResult từ việc ràng buộc.
Thẩm định. validate() trả về một danh sách các lỗi đọc được và không bao giờ ném ra; parse() ném InvalidArgumentException khi việc thẩm định thất bại.
Dữ liệu thiếu. Một placeholder không có dữ liệu và có default rỗng sẽ được báo cáo trong missingFields; một placeholder có default không rỗng sẽ dùng default.
Tính tất định. Việc phân tích và ràng buộc là các hàm thuần túy của đầu vào của chúng.

Bề mặt API công khai

Kiểu	Loại	Thành viên chính
`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`	tên, `PlaceholderType $type`, tọa độ, 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`

Mẫu mã — Bắt đầu nhanh

<?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";
}

Mẫu mã — Sản phẩm

<?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
}

Trường hợp ngoại lệ & lưu ý

Một chuỗi date không phân tích được sẽ tạo ra một cảnh báo và chuỗi gốc được giữ lại, thay vì ném ra.
Chuỗi format tiền tệ được dùng làm một tiền tố literal (ví dụ "$" hoặc "EUR "), không phải một định danh locale.
backgroundPdf là một tham chiếu đường dẫn được mang trên definition; module này không mở, thẩm định, hay ghép nó — đó là việc của bộ render.
Tên placeholder được khớp không phân biệt hoa thường; các tên trùng lặp trong JSON là một lỗi thẩm định.

Hiệu năng

Việc phân tích là một lần decode JSON cộng với việc thẩm định cấu trúc; việc ràng buộc tuyến tính theo số lượng placeholder. Xem performance_budget.

Lưu ý bảo mật

JSON được decode với JSON_THROW_ON_ERROR và được thẩm định theo các danh sách cho phép cố định trước khi một TemplateDefinition được dựng. Module không thực hiện I/O tệp hay mạng nào; đường dẫn backgroundPdf không được tham chiếu ngược ở đây, nên việc xử lý đường dẫn và kiểm soát truy cập thuộc về bộ render.

Tính phù hợp

Module này không có bề mặt đặc tả PDF trực tiếp: nó phân tích một template JSON và định dạng các giá trị. Các bộ từ vựng về kích thước trang và hướng trang là các quy ước của NextPDF, không phải các cấu trúc PDF quy phạm.

Phương án dự phòng / thay thế của Core

Không có tầng định nghĩa template nào trong Core. Đối với việc dựng tài liệu hoàn toàn mệnh lệnh (imperative), hãy dùng trực tiếp các API document và writer của Core mã nguồn mở. Xem /modules/core/document/.

Lưu ý về ranh giới Enterprise

Module này định nghĩa và ràng buộc các template. Nó không thực hiện việc điều phối mail-merge, lập lịch job hàng loạt, hay render; những vấn đề đó nằm ngoài phạm vi và được xử lý ở nơi khác.

Ranh giới công bố

Trang này chỉ tài liệu hóa hành vi quan sát được từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, các lớp trợ giúp, các bảng cơ chế, các tên tệp runbook, và các tiền tố ticket đều nằm ngoài phạm vi.