ValueObjects: primitive miền và đơn vị

Tổng quan nhanh

Module ValueObjects cung cấp các primitive hình học bất biến được dùng xuyên suốt engine: PageSize, Dimension, Position, Margin, và enum Unit. Mỗi đối tượng là một lớp final readonly. Bạn có thể thoải mái chia sẻ cùng một instance; mỗi phép biến đổi đều trả về một instance mới.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

Cả bốn value object đều là final readonly. Chúng lưu trữ tọa độ float và không cung cấp mutator; các phương thức biến đổi sẽ dựng lại một instance mới bằng đối số đặt tên. Bạn có thể cache chúng, truyền chúng giữa các tài liệu và chia sẻ giữa các worker mà không cần sao chép để phòng vệ.

PageSize lưu trữ chiều rộng, chiều cao (theo point; 1 pt = 1/72 inch) và tên. Các factory tĩnh bao gồm dòng A của International Organization for Standardization (ISO) 216 (A0–A6), dòng B của ISO 216 (B0–B5), và các khổ Bắc Mỹ (Letter, Legal, Tabloid). Kích thước A/B tuân theo dòng khổ giấy đã xén do ISO 216 định nghĩa. fromName() phân giải tên không phân biệt chữ hoa chữ thường và ném ra PageLayoutException khi gặp tên không xác định. landscape() và portrait() trả về biến thể theo hướng tương ứng, hoặc self khi trang đã ở đúng hướng đó. toDimension() chuyển đổi khổ trang thành một Dimension theo point.

Dimension lưu trữ chiều rộng, chiều cao và một Unit. Các factory (fromMillimeters(), fromPoints(), fromInches()) tạo một dimension theo đơn vị đã chọn. toPoints() và toMillimeters() chuyển đổi đơn vị; toPoints() trả về self khi dimension đã dùng đơn vị point. withWidth() và withHeight() trả về một bản sao đã đổi kích thước. Phép chuyển đổi dùng các hệ số chính xác: 72/25.4 point trên mỗi milimét, 72/2.54 trên mỗi centimét và 72 trên mỗi inch.

Position là một điểm 2D trong không gian người dùng của Portable Document Format (PDF) (x, y). origin() trả về (0, 0). translate(dx, dy) trả về một bản sao đã được dịch chuyển. withX() / withY() trả về một bản sao trong đó một trục được thay thế.

Margin chứa top, right, bottom và left. Các factory gồm uniform() (cùng một giá trị ở mọi cạnh), symmetric(vertical, horizontal) và zero().

Unit là enum dựa trên chuỗi: Point (pt), Millimeter (mm), Centimeter (cm), và Inch (in). toPointFactor() trả về hệ số nhân để quy đổi về point.

Bề mặt API

Ký hiệu	Loại	Thành viên chính
NextPDF\ValueObjects\PageSize	lớp final readonly	$width, $height, $name; các factory A0–A6, B0–B5, Letter, Legal, Tabloid; fromName(), landscape(), portrait(), toDimension()
NextPDF\ValueObjects\Dimension	lớp final readonly	$width, $height, $unit; fromMillimeters(), fromPoints(), fromInches(), toPoints(), toMillimeters(), withWidth(), withHeight()
NextPDF\ValueObjects\Position	lớp final readonly	$x, $y; origin(), translate(), withX(), withY()
NextPDF\ValueObjects\Margin	lớp final readonly	$top, $right, $bottom, $left; uniform(), symmetric(), zero()
NextPDF\ValueObjects\Unit	enum chuỗi	Point, Millimeter, Centimeter, Inch; toPointFactor()

Mẫu mã — Khởi động nhanh

Dùng các factory để tạo các primitive hình học.

<?php

declare(strict_types=1);

use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;
use NextPDF\ValueObjects\Position;

$page = PageSize::A4();                       // 595.276 x 841.890 pt
$margin = Margin::uniform(18.0);              // 18 pt all sides
$origin = Position::origin()->translate(72.0, 72.0); // 1 inch in from corner

Mẫu mã — Production

Chuyển đổi đơn vị, xác định hướng và truyền lề vào cấu hình.

<?php

declare(strict_types=1);

use NextPDF\Core\Config;
use NextPDF\ValueObjects\Dimension;
use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;

// A label sized in millimeters, resolved to points for the engine.
$label = Dimension::fromMillimeters(width: 100.0, height: 150.0)->toPoints();

$page = PageSize::A4()->landscape();   // swap to width >= height
$margin = Margin::symmetric(vertical: 20.0, horizontal: 15.0);

$config = (new Config())
    ->withPageSize($page)
    ->withMargins($margin);

// $label->width / $label->height are now in points for downstream layout.

Trường hợp biên & điều cần lưu ý

• Mọi kích thước đều dùng point trừ khi bạn cung cấp một Dimension với một Unit tường minh. Lề của Config mặc định dùng point.
• PageSize::landscape() / portrait() trả về cùng một instance khi hướng đã khớp; không có cấp phát nào xảy ra và danh tính được giữ nguyên.
• PageSize::fromName() không phân biệt chữ hoa chữ thường nhưng chỉ phân giải các factory đã được đặt tên. Tên không xác định sẽ ném ra PageLayoutException, chứ không rơi về một kích thước mặc định.
• Dimension::toPoints() trả về self khi đơn vị đã là Point; đừng cho rằng đó là một đối tượng mới.
• Các đối tượng này giữ giá trị float thô và không áp dụng kiểm tra phạm vi. Chúng chấp nhận kích thước âm hoặc bằng không khi khởi tạo. Tính hợp lệ của hình học được thực thi ở các lớp layout và writer, không phải ở những đối tượng này.
• Phép chuyển đổi số dấu phẩy động dùng các hệ số hữu tỉ chính xác (72/25.4, 72/2.54); chỉ làm tròn tại ranh giới trình bày để giữ kết xuất có thể tái lập ổn định.

Hiệu năng

Mỗi value object là một struct readonly phẳng gồm các số float. Việc khởi tạo và mỗi phép biến đổi đều là một lần cấp phát đơn O(1), không sao chép sâu vì không có trạng thái có thể thay đổi lồng nhau. Bạn có thể chia sẻ một instance giữa các tài liệu mà không phát sinh thêm chi phí. performance_budget mặc định cho trang tham khảo này là wall_ms: 1500, peak_mb: 64.

Lưu ý về bảo mật

Các value object này không thực hiện input/output (I/O), không mang chuỗi do người dùng cung cấp ngoài tên khổ trang, và không giữ handle tài nguyên ngoài nào, nên chúng không tạo ra bề mặt tấn công trực tiếp. PageSize::fromName() từ chối đầu vào không xác định bằng một exception thay vì âm thầm dùng giá trị dự phòng, nên cấu hình sai định dạng sẽ thất bại rõ ràng thay vì tạo ra hình học trang ngoài dự kiến.

Tuân thủ

Đặc tả	Điều khoản	Chủ đề
ISO 216:2007	Dòng A / B	Kích thước khổ giấy đã xén cho các factory A* / B* (diễn giải lại; không trích nguyên văn ISO, không ghim chunk)

Kích thước của các factory A và B tương ứng với các khổ đã xén của ISO 216, được biểu diễn theo point. Các khổ Bắc Mỹ (Letter, Legal, Tabloid) là những khổ được dùng phổ biến trong thực tế ngành, không dựa trên ISO. Tham chiếu ISO được diễn giải lại theo chính sách trích dẫn của trang. Không có chunk nguyên văn nào được ghim.

Xem thêm

• /modules/core/config/ — Config dùng PageSize và Margin
• /modules/core/layout/ — các thành phần layout dùng những primitive này
• /modules/core/graphics/ — Position trong không gian tọa độ vẽ
• /modules/core/contracts/ — Orientation với PageSize
• /modules/core/exception/ — PageLayoutException từ fromName()