Enterprise phiên bản

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

Nhìn tổng quan

NextPDF\Enterprise\OutputPipeline thực thi nhiều manifest pipeline của Pro như một batch. BatchPipelineOrchestrator bọc PipelineExecutor của Pro với sự điều phối batch: một bộ bảo vệ tài nguyên có giới hạn trên kích thước batch, một timeout batch toàn cục tùy chọn, việc tiêm biến theo từng manifest, và hạch toán tổng hợp. Một lần kiểm tra tuân thủ ở cuối batch tùy chọn sẽ xác thực lại mọi đầu ra đã hoàn thành qua gateway tuân thủ Enterprise và thất bại theo hướng đóng. Mỗi lần chạy trả về một BatchPipelineResult mang theo kết quả theo từng manifest, số lượng hoàn thành và thất bại, thời gian, và báo cáo tuân thủ tùy chọn.

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

Năng lực này đi kèm trong NextPDF Enterprise (nextpdf/enterprise) và kích hoạt với một envelope giấy phép bậc Enterprise. Một triển khai không có quyền dùng đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và lấy giấy phép.

Bậc	Bề mặt output-pipeline
Core	Không có bề mặt output-pipeline.
Pro	Pipeline single-manifest (capability `pro.output.pipeline`).
Enterprise	Điều phối batch, giới hạn kích thước batch, timeout batch, handoff tuân thủ.

Bề mặt batch của Enterprise không mang mã capability riêng theo từng tính năng; ranh giới gói mới là cổng của nó. Capability single-manifest pro.output.pipeline của Pro là một điều kiện tiên quyết, không phải là cổng. Chỉ một giấy phép Pro thì chỉ mở khóa pipeline single-manifest bên dưới, không phải bề mặt batch này.

composer require nextpdf/enterprise:^3

Bề mặt Public API

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
`BatchPipelineOrchestrator::__construct()`	`PipelineExecutor $executor`, `BatchPipelineConfig $config`, `?ComplianceGateway $complianceGateway`, `ComplianceProfile $complianceProfile`	Config mặc định; không có gateway; profile `ComplianceProfile::PdfA4`	—	Không gì	Tiêm một gateway khi kiểm tra tuân thủ được bật; nếu không có, mọi manifest được kiểm tra đều bị báo là thất bại.
`BatchPipelineOrchestrator::executeBatch()`	`list<PipelineManifest> $manifests`, `array<string, array<string, mixed>> $variablesMap = []`	Thực thi các manifest theo thứ tự gửi vào; biến được phân giải theo ID manifest	`BatchPipelineResult`	`OverflowException` khi batch vượt quá 10,000 manifest; các exception của gateway khi kiểm tra tuân thủ được bật (xem Trường hợp biên)	`Throwable` của resolver không bao giờ thoát ra; executor của Pro hạ chúng xuống thành kết quả bước thất bại.
`BatchPipelineConfig::__construct()`	`int $maxConcurrency = 4`, `int $timeoutMs = 0`, `bool $complianceCheckOnComplete = false`	Đồng thời 4; không timeout; không kiểm tra tuân thủ	—	Không gì	Value object readonly. `timeoutMs = 0` vô hiệu hóa timeout batch.
`BatchPipelineResult::__construct()`	`list<PipelineResult> $results`, `int $totalManifests`, `int $completedCount`, `int $failedCount`, `float $durationMs`, `?array $complianceReport = null`	Tổng hợp trên các giá trị `PipelineResult` theo từng manifest	—	Không gì	Readonly. `complianceReport` vẫn là `null` trừ khi kiểm tra đã chạy.
`BatchPipelineResult::allSucceeded()`	—	Kiểm tra `failedCount === 0`	`bool`	Không gì	Trả về true trên một batch bị cắt cụt do timeout với zero thất bại; xem Trường hợp biên.
`BatchPipelineResult::successRate()`	—	`completedCount / totalManifests`	`float`	Không gì	Trả về `1.0` cho một batch rỗng.
`BatchPipelineResult::hasComplianceReport()`	—	Kiểm tra `complianceReport !== null`	`bool`	Không gì	—

public function __construct(
    private readonly PipelineExecutor $executor,
    private readonly BatchPipelineConfig $config = new BatchPipelineConfig(),
    private readonly ?ComplianceGateway $complianceGateway = null,
    private readonly ComplianceProfile $complianceProfile = ComplianceProfile::PdfA4,
) {}

public function executeBatch(
    array $manifests,
    array $variablesMap = [],
): BatchPipelineResult

public function __construct(
    public int $maxConcurrency = 4,
    public int $timeoutMs = 0,
    public bool $complianceCheckOnComplete = false,
) {}

Hợp đồng hành vi

executeBatch() trước tiên khẳng định kích thước batch so với mức trần 10,000 manifest. Một batch vượt trần sẽ phát sinh OverflowException trước khi bất kỳ manifest nào được thực thi; không có gì suy giảm âm thầm.

Các manifest sau đó thực thi theo thứ tự gửi vào qua PipelineExecutor của Pro. Mỗi manifest nhận mục biến được đặt khóa theo ID của nó trong $variablesMap; một manifest không có mục nào sẽ nhận một bản đồ biến rỗng. Một manifest được tính là hoàn thành khi trạng thái PipelineResult của nó là Completed; bất kỳ trạng thái kết thúc nào khác đều tính là thất bại. Exception của resolver không thoát ra: executor của Pro chuyển mọi Throwable của resolver thành một kết quả bước thất bại, nên executeBatch() luôn tổng hợp kết quả thay vì hủy giữa chừng batch khi có lỗi bước.

Khi timeoutMs lớn hơn không, thời gian đã trôi qua được kiểm tra trước khi mỗi manifest bắt đầu. Một khi ngân sách cạn kiệt, các manifest còn lại bị bỏ qua: chúng không tạo ra PipelineResult, và chúng không tính là hoàn thành cũng không tính là thất bại. totalManifests luôn báo cáo số lượng đã gửi vào.

Khi complianceCheckOnComplete được bật, trình điều phối xác thực PDF cuối cùng của mọi manifest đã hoàn thành so với ComplianceProfile đã cấu hình qua ComplianceGateway được tiêm. Lần kiểm tra thất bại theo hướng đóng:

Không có gateway được tiêm: mọi manifest được kiểm tra đều bị báo là thất bại, vì tuân thủ chưa bao giờ được xác thực.
Không có đầu ra PDF nào phân giải được từ các đầu ra bước của manifest: thất bại.
Gateway không trả về kết quả nào (sidecar chế độ tùy chọn không khả dụng): thất bại. Sự vắng mặt của một kết quả tích cực không phải là một lần đạt.
Gateway báo cáo bất kỳ sự không phù hợp nào: thất bại.

PDF cuối cùng được phân giải bằng cách quét các đầu ra bước của một manifest đã hoàn thành, bước cuối trước, để tìm một giá trị chuỗi trực tiếp bắt đầu bằng header %PDF. Các đầu ra bước không bao giờ lồng chuỗi byte PDF bên trong các sub-array; chỉ các giá trị đầu ra trực tiếp mới được kiểm tra. Các manifest chưa hoàn thành sẽ bị bỏ qua, không được kiểm tra.

Báo cáo tuân thủ là một array với các khóa profile, checked, passed, failed, và failures; mỗi mục thất bại mang theo manifestId và reason. Báo cáo gắn vào BatchPipelineResult::$complianceReport và có thể truy cập qua hasComplianceReport().

Handoff tuân thủ là một công cụ hỗ trợ xác thực lại, không phải một kiểm soát ủy quyền. Nó chỉ báo cáo các phát hiện.

Trường hợp biên và các chế độ thất bại

Nhiều hơn 10,000 manifest: OverflowException trước khi bất kỳ sự thực thi nào bắt đầu.
timeoutMs = 0 nghĩa là không có timeout batch. Hãy đặt một giá trị hữu hạn trong production.
Cắt cụt do timeout: các manifest bị bỏ qua không xuất hiện trong bất kỳ số đếm nào, nên completedCount + failedCount có thể nhỏ hơn totalManifests. allSucceeded() chỉ kiểm tra failedCount === 0 và có thể trả về true cho một batch bị cắt cụt. So sánh count($result->results) với totalManifests để phát hiện sự cắt cụt.
successRate() trả về 1.0 cho một batch rỗng (không có manifest nào được gửi vào).
Các ID manifest không được khử trùng lặp ở mức batch. Hai manifest chia sẻ cùng một ID đều thực thi và phân giải cùng một mục biến.
Các lỗi cấu trúc của manifest (danh sách bước rỗng, ID bước trùng lặp, phụ thuộc không xác định, chu trình phụ thuộc, không khớp kiểu đầu ra, thiếu bước resume) phát sinh InvalidArgumentException khi khởi tạo manifest, trước khi executeBatch() từng được gọi.
Với kiểm tra tuân thủ được bật, ComplianceGateway::validate() có thể ném ComplianceSidecarUnavailableException (sidecar không khả dụng ở chế độ bắt buộc) hoặc InvalidArgumentException (không có validator nào được đăng ký cho tool của profile). Một trong hai exception thoát khỏi executeBatch() sau khi thực thi nhưng trước khi kết quả được dựng, nên các kết quả theo từng manifest bị mất đối với người gọi. Ở chế độ tùy chọn, gateway trả về null thay vào đó, và manifest được ghi nhận là một thất bại tuân thủ.
Một bước handoff tuân thủ trong pipeline thất bại khi không có đầu ra bước phía trước nào chứa byte PDF nhận diện được; nó không bao giờ cho qua âm thầm.
Module này không thực hiện thao tác mật mã nào; chế độ FIPS không áp dụng.

Phù hợp tiêu chuẩn

Không có tuyên bố phù hợp tiêu chuẩn nào cho module này; đây là một lớp điều phối. Kiểm tra tuân thủ tùy chọn nhường cho gateway tuân thủ Enterprise và các validator ngoài của nó, vốn mang theo các tham chiếu của riêng chúng. Profile mặc định là ComplianceProfile::PdfA4; các profile gateway khác bao phủ thêm các mục tiêu PDF/A, PDF/UA, và PAdES.

Một báo cáo tuân thủ nêu các phát hiện của validator so với profile đã chọn. Nó không chứng nhận một tài liệu, không bảo đảm tính đầy đủ về mặt quy định, và không cấu thành tư vấn pháp lý. Việc đánh giá liệu một đầu ra có đáp ứng nghĩa vụ của bạn hay không là trách nhiệm của bạn.

Ghi chú phát triển

Trong các triển khai production, việc dispatch worker song song và backpressure được xử lý bởi một execution sidecar riêng. Trình điều phối PHP cung cấp logic điều phối batch và handoff tuân thủ và được job worker gọi, không phải được các request handler gọi trực tiếp.
Đường dẫn fallback PHP thực thi các manifest tuần tự. maxConcurrency giới hạn số callback worker đồng thời trong triển khai do sidecar dẫn dắt; việc định cỡ nó tương đối với worker pool PHP là trách nhiệm của người vận hành.
Bộ phân giải bước handoff tuân thủ trong pipeline là một kiểu nội bộ được đăng ký cho các bước kiểu inspect. Hãy bật xác thực cuối batch qua BatchPipelineConfig thay vì trực tiếp dựng các bước pipeline cho nó.
Hãy khởi tạo các instance PipelineManifest sớm. Việc xác thực cấu trúc của chúng chạy trong constructor, nên các đồ thị không hợp lệ sẽ thất bại nhanh và không bao giờ tiêu tốn ngân sách batch.

Ranh giới xuất bản

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 Public API được hỗ trợ. Các đường dẫn namespace nội bộ, lớp trợ giúp, bảng cơ chế, tên tệp runbook, và tiền tố ticket nằm ngoài phạm vi.