Pro phiên bản

Phép chiếu

Tổng quan nhanh

Projection phân tích cú pháp một content stream PDF thành một danh sách token phẳng và phát ra một content stream mới từ các token đó. Việc phát ra cần một ý định được khai báo tường minh. Module này không phải là một trình soạn thảo PDF đa dụng.

Lưu ý. “Projection” ở đây nghĩa là phép chiếu token content-stream. Nó không phải là phép chiếu tọa độ hay địa không gian. Đối với các tính năng địa không gian, xem module Geo.

Tính 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 bậc 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. So sánh các phiên bản và lấy giấy phép.

Không có cờ giấy phép riêng theo từng tính năng. Một đối số ProjectionIntent bắt buộc kiểm soát việc phát ra ở cấp API, không phải một công tắc giấy phép.

Cài đặt

composer require nextpdf/pro:^3

Mã nằm dưới namespace NextPDF\Pro\Projection.

Tổng quan khái niệm

ContentProjectionWriter cung cấp ba thao tác static:

tokenize() phân tích cú pháp một content stream thành một danh sách token phẳng, đã sắp thứ tự. Thao tác này chỉ đọc và không cần ý định.
emit() ghi một content stream mới từ một danh sách token (có thể đã được sửa đổi). Nó cần một ProjectionIntent.
roundTrip() tokenize rồi tái-phát mà không thay đổi gì, để xác thực.

Đầu ra về mặt khái niệm là một content stream mới, không phải một bản sao đã chỉnh sửa của bản gốc. Bộ phát chuẩn hóa khoảng trắng và chú thích nhưng giữ chính xác chuỗi toán tử và các giá trị toán hạng. Enum ý định có đúng hai trường hợp — làm sạch (xóa che) và nhúng giấu tin — và cố ý không có trường hợp tổng quát, để phân tích tĩnh có thể phát hiện việc sử dụng ngoài ý muốn.

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

Projection từ chối trở thành một trình soạn thảo PDF đa dụng. Việc phát ra dựng lại một content stream mới từ một danh sách token phẳng, nên bản gốc không bao giờ bị biến đổi tại chỗ. Chính mô hình một chiều đó làm cho việc xóa che trở nên đáng tin cậy: các token đã loại bỏ vắng mặt khỏi đầu ra, chứ không phải bị tô đè lên. Do đó emit() đòi hỏi một ProjectionIntent tường minh, và enum chỉ cung cấp làm sạch và nhúng giấu tin — không có trường hợp tổng quát. Khi đó phân tích tĩnh có thể đánh dấu bất kỳ việc phát ra nào thiếu một mục đích đã khai báo, đã biết. Thiết kế đánh đổi sự tiện lợi khi chỉnh sửa để lấy một bảo đảm rằng ý định phá hủy luôn hiển thị tại điểm gọi.

Bối cảnh thiết kế: Xóa che không phải là một hình chữ nhật đen.

Hợp đồng hành vi

tokenize($contentStream) trả về một danh sách token bao gồm chuỗi, tên, số, mảng, từ điển, boolean, null, và toán tử.
emit($tokens, $intent) cần một ý định tường minh; hệ thống kiểu thực thi điều này tại điểm gọi.
Đầu ra của roundTrip() không giống hệt theo byte với đầu vào, nhưng chuỗi toán tử và các giá trị toán hạng khớp nhau.
Bộ phát định dạng các số để giữ phân biệt giữa số nguyên và số thực và tái-escape các chuỗi literal.
Hai ý định được khai báo là làm sạch (một thao tác xóa che mang tính phá hủy, không thể đảo ngược) và nhúng giấu tin.

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

Phần dưới đây phản ánh public API đã được ghi tài liệu. Kho mã không đi kèm một ví dụ có thể chạy cho module này.

use NextPDF\Pro\Projection\ContentProjectionWriter;

$tokens = ContentProjectionWriter::tokenize($contentStream);

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

use NextPDF\Pro\Projection\ContentProjectionWriter;
use NextPDF\Pro\Projection\ProjectionIntent;

$tokens = ContentProjectionWriter::tokenize($contentStream);

// Validate first: a clean round-trip must hold before any modification.
$check = ContentProjectionWriter::roundTrip($contentStream);

// Apply your modification to $tokens, then emit with a declared intent.
$output = ContentProjectionWriter::emit($tokens, ProjectionIntent::Sanitization);

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

Chạy roundTrip() và xác nhận nó đứng vững trước khi bạn tin tưởng một chuỗi sửa-đổi-rồi-phát. Hãy coi một round-trip thất bại là một điều kiện dừng.
Ý định làm sạch là không thể đảo ngược. Nội dung đã loại bỏ không thể khôi phục từ đầu ra.
Bộ phát chuẩn hóa khoảng trắng và bỏ các chú thích, nên việc so sánh ở cấp byte với bản gốc sẽ khác nhau ngay cả với một round-trip không sửa đổi.

Hiệu năng

Tokenize và emit tuyến tính theo độ dài content-stream. Bộ tokenize giới hạn việc đọc octal escape và xử lý chuỗi hex. Không có con số thông lượng nào được công bố. Hãy đo bằng các content stream đại diện.

Lưu ý bảo mật

Đối số ý định bắt buộc ngăn việc lạm dụng như một trình soạn thảo đa dụng. Ý định làm sạch mang tính phá hủy và không thể đảo ngược; hãy xác minh round-trip trước và xác nhận đầu ra đã xóa che trước khi phân phối. Module này không ghi nhật ký nội dung nào.

Tính phù hợp

Việc tokenize theo các quy ước từ vựng và content-stream trong ISO 32000-2; nguồn chú thích các điều khoản liên quan. Corpus RAG không khả dụng tại thời điểm soạn thảo, nên trang này không khẳng định định danh điều khoản bên ngoài nào và giới hạn các phát biểu phù hợp ở hành vi đã được kiểm chứng bởi các bài test của module.

Lưu ý ranh giới Enterprise

Enterprise không thay đổi hành vi của Projection. Enterprise bổ sung các tính năng quyền riêng tư và tuân thủ bậc cao hơn được ghi tài liệu riêng; chúng không cần thiết để dùng API projection.

Phương án dự phòng / thay thế ở Core

Không có thành phần tương đương ở Core. Không có Pro, các bên gọi phải tự dựng bộ tokenize content-stream của mình; mô hình projection bị kiểm soát ý định là một bổ sung chỉ có ở Pro.

Ranh giới xuất bản

Trang này chỉ ghi tài liệu hành vi quan sát được từ bên ngoài và bề mặt public API đượ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ế, tên tệp runbook, và các tiền tố ticket nằm ngoài phạm vi.