Pro phiên bản

Template — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Tài liệu tham chiếu chuyên sâu này ghi lại lược đồ mẫu JSON được chấp nhận, mọi quy tắc thẩm định, và hành vi định dạng chính xác theo từng kiểu của bộ ràng buộc dữ liệu. Module phân tích một định nghĩa mẫu, rồi ràng buộc dữ liệu của bên gọi vào các placeholder có kiểu. Nó phát ra các chuỗi đã định dạng; nó không vẽ các đối tượng PDF.

Tính khả dụng & cấp phép

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

Bề mặt API công khai

Module phơi bày hai dịch vụ điểm vào và bốn đối tượng giá trị bất biến. Mọi ký hiệu bên dưới đều công khai và ổn định.

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném ra hoặc thất bại với	Ghi chú
`TemplateParser::parse`	`string $json`	Thẩm định, rồi dựng định nghĩa	`TemplateDefinition`	`InvalidArgumentException` khi có bất kỳ lỗi thẩm định nào	Ủy quyền cho `validate` trước.
`TemplateParser::validate`	`string $json`	Thu thập mọi lỗi cấu trúc trong một lượt	`list<string>` (rỗng khi hợp lệ)	Không bao giờ ném ra; một lỗi giải mã JSON được trả về dưới dạng thông báo	Cổng thẩm quyền cho các giới hạn độ dài và độ chính xác.
`TemplateDataBinder::bind`	`TemplateDefinition $template`, `array<string,mixed> $data`	Khớp placeholder không phân biệt hoa thường và định dạng theo kiểu	`BindingResult`	Không bao giờ ném ra; các bất thường trở thành cảnh báo hoặc trường thiếu	Dùng giá trị mặc định của placeholder khi khóa vắng mặt.
`TemplateDefinition::__construct`	`string $name`, `string $pageSize`, `string $orientation`, `list<TemplatePlaceholder> $placeholders`, `string $backgroundPdf = ''`	Lưu trữ định nghĩa đã phân tích	`TemplateDefinition`	`TypeError` khi kiểu đối số không khớp	Đối tượng giá trị final readonly.
`TemplateDefinition::getPlaceholder`	`string $name`	Tra cứu theo tên không phân biệt hoa thường	`TemplatePlaceholder\|null`	Không thất bại; trả về `null` khi vắng mặt	—
`TemplateDefinition::requiredFields`	không có	Thu thập tên các placeholder không có giá trị mặc định	`list<string>`	Không thất bại	Một giá trị mặc định không rỗng đánh dấu placeholder là tùy chọn.
`TemplatePlaceholder::__construct`	`string $name`, `PlaceholderType $type`, `float $x`, `float $y`, `float $width`, `float $height`, `string $defaultValue = ''`, `string $format = ''`	Lưu trữ một vùng placeholder	`TemplatePlaceholder`	`TypeError` khi kiểu đối số không khớp	Tọa độ là điểm tính từ góc trên bên trái.
`TemplatePlaceholder::matches`	`string $key`	So sánh tên không phân biệt hoa thường	`bool`	Không thất bại	—
`BindingResult::__construct`	`list<BoundPlaceholder> $bindings`, `list<string> $missingFields`, `list<string> $warnings`	Lưu trữ kết quả ràng buộc	`BindingResult`	`TypeError` khi kiểu đối số không khớp	Đối tượng giá trị final readonly.
`BindingResult::isComplete`	không có	Báo cáo liệu mọi trường bắt buộc đã được ràng buộc hay chưa	`bool`	Không thất bại	Đúng khi `missingFields` rỗng.
`BindingResult::count`	không có	Đếm các placeholder được ràng buộc thành công	`int`	Không thất bại	—
`BoundPlaceholder::__construct`	`TemplatePlaceholder $placeholder`, `string $formattedValue`, `mixed $rawValue`	Ghép một placeholder với giá trị đã định dạng của nó	`BoundPlaceholder`	`TypeError` khi kiểu đối số không khớp	Đối tượng giá trị final readonly.
`PlaceholderType`	các case enum `Text`, `Image`, `Barcode`, `Date`, `Number`, `Currency`, `Conditional`	Phân loại placeholder được hậu thuẫn bằng chuỗi	thực thể enum	`ValueError` từ `from()` với một giá trị không xác định	`tryFrom()` trả về `null` thay vào đó.
`PlaceholderType::requiresFormatting`	không có	Báo cáo liệu kiểu có tiêu thụ một chuỗi định dạng hay không	`bool`	Không thất bại	Đúng cho `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;
}

Hợp đồng hành vi

Hình dạng JSON được chấp nhận:

{
  "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" }
  ]
}

Các quy tắc thẩm định, tất cả được validate bộc lộ dưới dạng thông báo và được parse tổng hợp thành một ngoại lệ:

Thiếu hoặc rỗng name.
pageSize nằm ngoài danh sách cho phép, hoặc orientation không phải P hay L.
Thiếu placeholders, hoặc một giá trị không phải mảng.
Theo từng placeholder: thiếu hoặc rỗng tên; kiểu không hợp lệ; thiếu hoặc không phải số ở x, y, width, height; tên trùng lặp (không phân biệt hoa thường).
defaultValue: không phải chuỗi, dài hơn 4096 byte, hoặc mang một ký tự điều khiển ASCII.
format: không phải chuỗi, dài hơn 256 byte, hoặc mang một ký tự điều khiển ASCII.
Một format của placeholder number không phải là số nguyên không âm, hoặc vượt quá 30.

Ngữ nghĩa ràng buộc (TemplateDataBinder::bind):

Các khóa dữ liệu được chuyển về chữ thường để khớp không phân biệt hoa thường với tên placeholder.
Một khóa vắng mặt có giá trị mặc định không rỗng sẽ ràng buộc giá trị mặc định; một khóa vắng mặt không có giá trị đó được báo cáo trong missingFields.
Các giá trị text, image, và barcode được ép sang chuỗi mà không đổi.
Ràng buộc date chấp nhận một DateTimeInterface, một dấu thời gian Unix dạng số nguyên, hoặc một chuỗi ở một trong bốn định dạng tường minh. Định dạng đầu ra mặc định là Y-m-d.
Ràng buộc number dùng number_format(value, decimals, '.', ','). Số chữ số thập phân đến từ format, mặc định là 2, và bị giới hạn trong khoảng 0 đến 30.
Ràng buộc currency đặt format làm tiền tố cho số đã định dạng, với tiền tố mặc định là $.
Ràng buộc conditional phát ra "true" hoặc "false" từ một phép ép kiểu boolean.

Trường hợp ngoại lệ & chế độ thất bại

backgroundPdf không bao giờ được module này mở hay tham chiếu ngược. Nó là một chuỗi không trong suốt được trao cho bộ render.
Một giá trị không phải số được ràng buộc vào một placeholder Number hoặc Currency sẽ tạo ra một cảnh báo; giá trị được ép kiểu chuỗi, chứ không bị từ chối.
Các chuỗi date được phân tích một cách nghiêm ngặt. Các token tương đối và ngôn ngữ tự nhiên (“now”, “+1 year”, “tomorrow”) không khớp định dạng được chấp nhận nào, nên chúng cảnh báo và giá trị thô đi qua nguyên trạng.
Một giá trị date dạng số nguyên được đọc như một dấu thời gian Unix qua dạng epoch @.
Một độ chính xác format của Number nằm ngoài khoảng 0 đến 30 mà lọt tới bộ ràng buộc sẽ bị từ chối kèm một cảnh báo; bộ ràng buộc quay về độ chính xác mặc định là 2.
Không có thao tác mã hóa nào xảy ra trong module này, nên không có hành vi đặc thù chế độ FIPS nào.

Tính phù hợp

Không tồn tại bề mặt đặc tả PDF trực tiếp nào. Các bộ từ vựng về kích thước trang và hướng trang là quy ước của NextPDF, và module phát ra các giá trị đã định dạng, không phải các đối tượng PDF. Danh sách cho phép chuỗi-date nghiêm ngặt chấp nhận hồ sơ ngày/giờ Internet của ISO 8601 được định nghĩa trong RFC 3339 §5.6, cùng với một Y-m-d ngày lịch và hai dạng ngày-giờ cục bộ. NextPDF ghi lại năng lực đọc các định dạng này; nó không tuyên bố bất kỳ chứng nhận nào theo RFC 3339 hay ISO 8601.

Ghi chú phát triển

TemplateParser và TemplateDataBinder là vô trạng thái. Một thực thể đơn có thể tái sử dụng và an toàn để chia sẻ qua nhiều lần ràng buộc.
Bốn đối tượng giá trị là final readonly; hãy dựng chúng qua bộ phân tích thay vì bằng tay đối với dữ liệu đầu vào production.
validate báo cáo mọi lỗi cấu trúc trong một lượt, trong khi parse gọi validate trước và ném ra trên thông báo đã tổng hợp. Dùng validate cho phản hồi kiểu biểu mẫu và parse cho việc nạp fail-fast.
Các giới hạn độ dài và độ chính xác được thực thi tại bộ phân tích như cổng thẩm quyền. TemplateDataBinder kiểm tra lại độ chính xác số như một bảo vệ phía đầu ra chống lại sự khuếch đại bộ nhớ của number_format.

Ranh giới xuất bản

Trang này chỉ ghi lại 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 nằm ngoài phạm vi.