Pro phiên bản

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

Tổng quan nhanh

Trang này là tài liệu tham chiếu chuyên sâu cho bề mặt công khai của NextPDF\Pro\OutputPipeline. Nó bao quát việc dựng và kiểm tra manifest, thứ tự thực thi topo, ngữ nghĩa thử lại và timeout, hành vi resume, và cổng năng lực Pack fail-closed. Nó nêu rõ tham số, giá trị mặc định, và các chế độ thất bại cho mọi ký hiệu công khai. Hãy đọc trang giới thiệu tính năng Output Pipeline trước để có hướng dẫn quy trình làm việc.

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

Tính năng này được phát hành trong NextPDF Pro (nextpdf/pro) và được kích hoạt bằng một license envelope cấp Pro. Một triển khai không có entitlement đó 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.

Executor và bảy trong số mười kiểu bước không mang cờ theo từng tính năng. Ba kiểu bước còn cần thêm một năng lực Pack:

Kiểu bước	Giá trị manifest	Năng lực bắt buộc	Pack
Redact	`redact`	`pack.privacy.redact`	Privacy Pack
Extract	`extract`	`pack.intelligence.extract`	Intelligence Pack
OCR overlay	`ocr_overlay`	`pack.intelligence.searchable_pdf`	Intelligence Pack

Cổng được thực thi tại thời điểm chạy, fail-closed, trước khi bước đạt tới resolver của nó. Một bước bị kiểm soát mà không có giấy phép sẽ cho ra một kết quả bước Failed mang theo mã SPEC-LIC-001 và năng lực bắt buộc; resolver không bao giờ được gọi. Một pipeline không có capability resolver được tiêm vào sẽ từ chối mọi bước bị kiểm soát.

Bề mặt API công khai

composer require nextpdf/pro:^3

Metapackage nextpdf/premium cài mã nextpdf/pro; module này nằm dưới namespace NextPDF\Pro\OutputPipeline.

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ú
`PipelineExecutor::__construct`	`StepResolverRegistry $registry`, `?CapabilityResolverInterface $capabilityResolver = null`	Gắn registry resolver dựng sẵn và nguồn entitlement tùy chọn	`PipelineExecutor`	Không khai báo gì	Một capability resolver null sẽ từ chối mọi bước bị kiểm soát theo Pack
`PipelineExecutor::execute`	`PipelineManifest $manifest`, `array $variables = []`	Chạy các bước theo thứ tự topo và tổng hợp kết quả	`PipelineResult`	Không khai báo gì; các thất bại của resolver được ghi nhận thành kết quả bước Failed	Được thiết kế để chạy bên trong một job worker bất đồng bộ
`PipelineManifest::__construct`	`string $id`, `array $steps`, `PipelineOptions $options = new PipelineOptions()`, `?string $resumeFromStepId = null`	Kiểm tra đồ thị bước tại thời điểm khởi tạo	`PipelineManifest`	`InvalidArgumentException` khi 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, kiểu đầu ra không khớp, hoặc thiếu bước resume; `OverflowException` khi vượt quá 10 000 bước	Toàn bộ kiểm tra hoàn tất trước bất kỳ lần thực thi nào
`PipelineManifest::topologicalOrder`	không có	Sắp xếp các bước sao cho phụ thuộc đứng trước bên phụ thuộc vào nó	`list<PipelineStep>`	Không khai báo gì	Xác định (deterministic) với một manifest cho trước
`PipelineManifest::getStep`	`string $stepId`	Tra cứu tuyến tính theo step ID	`?PipelineStep`	Không khai báo gì	`null` với một ID không xác định
`PipelineManifest::rootSteps`	không có	Trả về các bước không có phụ thuộc	`list<PipelineStep>`	Không khai báo gì	Các bước gốc chạy trước
`PipelineManifestBuilder::create`	`string $manifestId`	Khởi tạo một builder mới	`self`	Không khai báo gì	Hàm khởi tạo là private; đây là lối vào duy nhất
`PipelineManifestBuilder::addStep`	`string $id`, `PipelineStepType $type`, `array $parameters = []`, `array $dependsOn = []`, `?StepOutputType $outputType = null`	Thêm một bước; kiểu đầu ra null được suy ra từ kiểu bước	`self`	Không khai báo gì	Việc kiểm tra được hoãn tới `build()`
`PipelineManifestBuilder::stopOnError`	`bool $stop = true`	Đặt chế độ dừng khi gặp thất bại đầu tiên	`self`	Không khai báo gì	Mặc định là `true`
`PipelineManifestBuilder::maxRetries`	`int $retries`	Đặt trần số lần thử lại theo từng bước	`self`	Không khai báo gì	Mặc định là `0` (không thử lại)
`PipelineManifestBuilder::timeout`	`int $timeoutMs`	Đặt timeout toàn cục của pipeline	`self`	Không khai báo gì	`0` vô hiệu hóa timeout
`PipelineManifestBuilder::resumeFrom`	`string $stepId`	Đặt điểm resume	`self`	Không khai báo gì	Bước đó phải tồn tại tại thời điểm `build()`
`PipelineManifestBuilder::build`	không có	Dựng manifest đã được kiểm tra	`PipelineManifest`	Như `PipelineManifest::__construct`	—
`PipelineOptions::__construct`	`bool $stopOnError = true`, `int $maxRetries = 0`, `int $timeoutMs = 0`	Tùy chọn thực thi bất biến	`PipelineOptions`	Không khai báo gì	Value object readonly
`PipelineStep::__construct`	`string $id`, `PipelineStepType $type`, `array $parameters = []`, `array $dependsOn = []`, `StepOutputType $outputType = StepOutputType::Pdf`	Định nghĩa bước bất biến	`PipelineStep`	Không khai báo gì	Khởi tạo trực tiếp mặc định kiểu đầu ra là PDF cho mọi kiểu
`PipelineStep::isRoot`	không có	True khi bước không có phụ thuộc	`bool`	Không khai báo gì	—
`PipelineStepType` (enum)	—	Mười case dựa trên chuỗi: `generate`, `merge`, `split`, `inspect`, `compress`, `sign`, `convert`, cùng các bước bị kiểm soát `redact`, `extract`, `ocr_overlay`	—	—	Mỗi case ứng với một thao tác dựng sẵn
`PipelineStepType::requiresPack`	không có	True với Redact, Extract, và OcrOverlay	`bool`	Không khai báo gì	Mọi case còn lại trả về `false`
`PipelineStepType::requiredCapability`	không có	Ánh xạ các case bị kiểm soát tới mã năng lực của chúng	`?string`	Không khai báo gì	`null` với các case không bị kiểm soát
`PipelineStatus` (enum)	—	Năm case: `pending`, `running`, `completed`, `failed`, `cancelled`	—	—	Dùng chung cho kết quả pipeline và kết quả bước
`PipelineStatus::isTerminal`	không có	True với Completed, Failed, và Cancelled	`bool`	Không khai báo gì	Pending và Running không phải trạng thái cuối
`StepOutputType` (enum)	—	Ba case: `pdf`, `json`, `metadata`	—	—	Điều khiển việc kiểm tra cạnh lúc build
`StepOutputType::forStepType`	`PipelineStepType $stepType`	Kiểu đầu ra mặc định cho một kiểu bước	`self`	Không khai báo gì	Inspect và Extract ánh xạ sang JSON; mọi kiểu khác ánh xạ sang PDF
`StepOutputType::isCompatibleWith`	`self $expectedInput`	True khi cùng kiểu hoặc khi đầu ra là PDF	`bool`	Không khai báo gì	Hàm hỗ trợ; PDF là đầu vào phổ quát
`PipelineContext::__construct`	`string $manifestId`, `array $variables = []`, `?string $resumeFromStepId = null`	Context trong bộ nhớ theo từng lượt chạy	`PipelineContext`	Không khai báo gì	Không có TTL, hết hạn, lưu bền, hay kho lưu trữ nền
`PipelineContext::setStepResult` / `::getStepResult`	`string $stepId` (+ `StepResult` khi set)	Ghi hoặc đọc một kết quả bước	`void` / `?StepResult`	Không khai báo gì	`null` với một bước chưa được thực thi
`PipelineContext::setStepOutput` / `::getStepOutput`	`string $stepId` (+ `mixed` khi set)	Lưu hoặc đọc một đầu ra trung gian	`void` / `mixed`	Không khai báo gì	`null` với một đầu ra thiếu vắng
`PipelineContext::hasStepResult`	`string $stepId`	Cho biết một bước đã được thực thi hay chưa	`bool`	Không khai báo gì	Hỗ trợ kiểm tra resume
`PipelineContext::allStepResults`	không có	Mọi kết quả đã ghi cho đến hiện tại	`array<string, StepResult>`	Không khai báo gì	Khóa theo step ID
`PipelineContext::isResume`	không có	Cho biết lượt chạy có resume từ một bước hay không	`bool`	Không khai báo gì	—
`PipelineResult::isSuccess`	không có	Chỉ True khi trạng thái tổng thể là Completed	`bool`	Không khai báo gì	Kết quả do executor tạo ra
`PipelineResult::getStepResult`	`string $stepId`	Tìm một kết quả bước theo ID	`?StepResult`	Không khai báo gì	`null` với các bước bị bỏ qua hoặc không xác định
`PipelineResult::failedSteps`	không có	Lọc ra các kết quả bước thất bại	`list<StepResult>`	Không khai báo gì	Danh sách rỗng khi thành công hoàn toàn
`StepResult::isSuccess`	không có	Chỉ True khi trạng thái bước là Completed	`bool`	Không khai báo gì	Mang theo `stepId`, `type`, `status`, `durationMs`, `error`, `output`
`CapabilityResolverInterface::hasCapability`	`string $capability`	Kiểm tra entitlement khẳng định cho một mã năng lực	`bool`	Không được ném ngoại lệ	Từ chối theo mặc định thiếu vắng: `false` với các mã không xác định, hết hạn, hoặc không được ánh xạ

Chữ ký điểm vào

final class PipelineExecutor
{
    public function __construct(
        private readonly StepResolverRegistry $registry,
        private readonly ?CapabilityResolverInterface $capabilityResolver = null,
    )

    public function execute(PipelineManifest $manifest, array $variables = []): PipelineResult
}

final class PipelineManifestBuilder
{
    public static function create(string $manifestId): self

    public function addStep(
        string $id,
        PipelineStepType $type,
        array $parameters = [],
        array $dependsOn = [],
        ?StepOutputType $outputType = null,
    ): self

    public function stopOnError(bool $stop = true): self

    public function maxRetries(int $retries): self

    public function timeout(int $timeoutMs): self

    public function resumeFrom(string $stepId): self

    public function build(): PipelineManifest
}

interface CapabilityResolverInterface
{
    public function hasCapability(string $capability): bool;
}

Hợp đồng hành vi

Kiểm tra manifest

Việc kiểm tra chạy trong hàm khởi tạo của PipelineManifest, trước bất kỳ lần thực thi nào. Theo thứ tự: danh sách bước phải không rỗng; số lượng bước bị giới hạn ở 10 000, biến những chuỗi phụ thuộc sâu mang tính đối kháng thành một OverflowException có thể bắt được thay vì cạn kiệt ngăn xếp ở tầng native; ID bước phải là duy nhất; mọi tham chiếu dependsOn phải phân giải được; đồ thị phụ thuộc phải không có chu trình; các kiểu đầu ra phải tương thích; một bước resume được khai báo phải tồn tại. Mỗi vi phạm sẽ ném ra InvalidArgumentException kèm một thông báo cụ thể.

Phép kiểm tra kiểu đầu ra áp dụng cho các bước có kiểu ánh xạ sang đầu ra PDF: mọi phụ thuộc của một bước như vậy tự nó cũng phải tạo ra đầu ra PDF. Các cạnh phụ thuộc đi vào những kiểu bước tạo ra JSON (inspect, extract) không bị kiểm tra kiểu trong bản phát hành này.

Thứ tự thực thi, resume, và timeout

execute($manifest, $variables) dựng một PipelineContext mới, tính thứ tự topo, và chạy các bước tuần tự theo thứ tự đó. Khi có đặt điểm resume, các bước trước đó bị bỏ qua cho đến khi đạt tới bước được nêu tên. Các bước tiền nhiệm bị bỏ qua sẽ không được thực thi lại và đầu ra của chúng không được khôi phục: context là theo từng lượt chạy và nằm trong bộ nhớ, nên một bước được resume mà đọc đầu ra của một tiền nhiệm bị bỏ qua sẽ thấy null.

Timeout toàn cục, khi dương, được đánh giá giữa các bước, trước khi mỗi bước bắt đầu. Khi hết hạn, trạng thái pipeline trở thành Failed và các bước còn lại không khởi động. Một bước đang chạy sẽ không bao giờ bị ngắt giữa chừng, nên một bước kéo dài có thể làm vượt ngân sách.

Thử lại và ghi nhận thất bại

Mỗi bước nhận tối đa maxRetries + 1 lần thử. Một lần thử thành công sẽ trả về ngay lập tức. Bất kỳ lần thử thất bại nào — một kết quả Failed từ resolver, hoặc một Throwable được ném ra — đều được thử lại khi còn lượt thử; kết quả của lần thử cuối cùng được trả về. Một Throwable phát sinh bên trong một resolver bị hạ cấp thành một kết quả bước Failed mang theo thông báo ngoại lệ, hoặc Unknown error khi thông báo rỗng. Do đó execute() luôn trả về một PipelineResult; nó không bao giờ lan truyền một thất bại của resolver.

Một kiểu bước không có resolver nào được đăng ký sẽ cho ra một kết quả bước Failed kèm thông báo rõ ràng; lượt chạy không bị hủy bỏ. Khi stopOnError là true (mặc định), việc thực thi dừng lại ở bước thất bại đầu tiên và trạng thái pipeline là Failed. Khi nó là false, việc thực thi tiếp tục và trạng thái cuối cùng là Failed nếu có bất kỳ bước nào thất bại, ngược lại là Completed.

Cổng năng lực Pack

Trước bất kỳ lần điều phối resolver nào, mọi bước bị kiểm soát theo Pack (Redact, Extract, OcrOverlay) đều được kiểm tra với CapabilityResolverInterface được tiêm vào. Cổng này fail-closed: một resolver thiếu vắng, một câu trả lời false, hoặc một mã năng lực không được ánh xạ đều từ chối bước. Việc từ chối tạo ra một kết quả bước Failed mà lỗi của nó mang theo mã SPEC-LIC-001, kiểu bước, và năng lực bắt buộc. Một lần từ chối bởi cổng không tiêu tốn lượt thử lại nào và báo cáo thời lượng là 0.0. Các hiện thực của resolver chỉ được trả về true cho một entitlement được nắm giữ một cách khẳng định và không được ném ngoại lệ.

Tổng hợp kết quả

PipelineResult báo cáo manifest ID, trạng thái tổng thể, kết quả theo từng bước theo thứ tự thực thi, tổng thời lượng tính bằng mili-giây, và số bước tổng cộng, đã hoàn tất, và đã thất bại. stepsTotal đếm mọi bước trong manifest, bao gồm các bước bị bỏ qua do resume hoặc chưa được chạm tới sau một lần dừng; stepsCompleted và stepsFailed chỉ đếm các bước đã được thực thi.

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

Executor được thiết kế cho việc thực thi bất đồng bộ bên trong một job worker. Việc dùng trực tiếp (inline) sẽ chặn bên gọi trong suốt toàn bộ thời gian pipeline chạy.
Timeout toàn cục là một phép kiểm tra giữa các bước. Một bước đơn lẻ kéo dài có thể làm vượt ngân sách; không bước nào bị ngắt giữa chừng.
Resume chỉ bỏ qua các bước trong cùng một lần thực thi. Nó không khôi phục đầu ra từ bất kỳ kho lưu trữ nào; resume xuyên lượt chạy với đầu ra đã cache không được hiện thực.
Khởi tạo PipelineStep trực tiếp sẽ mặc định kiểu đầu ra là PDF cho mọi kiểu bước. Hãy dùng builder, hoặc truyền kiểu đầu ra một cách tường minh, để các bước inspect và extract khai báo đầu ra JSON và việc kiểm tra cạnh vẫn có ý nghĩa.
Một ngoại lệ của resolver với thông báo rỗng được chuẩn hóa thành Unknown error trong kết quả bước.
Các kết quả bước Failed do cổng hoặc do một resolver thiếu vắng tạo ra sẽ báo cáo thời lượng là 0.0.
PipelineResult::getStepResult() trả về null cho cả các ID không xác định lẫn các bước bị bỏ qua do resume hoặc do một lần dừng; phân biệt qua stepsTotal so với độ dài của danh sách kết quả.
Module này không thực hiện thao tác mã hóa nào và không định nghĩa hành vi đặc thù FIPS nào. Tư thế FIPS cho bước sign được điều chỉnh bởi module ký, không phải bởi pipeline.

Tính phù hợp

Pipeline không tự thực hiện công việc kiểm tra phù hợp định dạng nào. Tính phù hợp của mỗi artifact được tạo ra thuộc về module đứng sau bước đang thực thi — ký, tối ưu hóa, chuyển đổi, v.v. — và được ghi lại trên các trang tham chiếu của những module đó. Trang này không khẳng định định danh điều khoản bên ngoài nào; mọi phát biểu đều được đặt nền trên mã nguồn sản phẩm. NextPDF không đưa ra tuyên bố chứng nhận nào.

Ghi chú phát triển

Mã nguồn module mang @since 2.2.0; tài liệu tham chiếu này mô tả bề mặt như được phát hành trong nextpdf/pro 3.1.0.
Mọi lớp đều là final; các kiểu manifest, options, step, và result là các value object readonly. Hãy khởi tạo instance mới thay vì thay đổi tại chỗ.
StepResolverInterface và StepResolverRegistry là @internal. Các step resolver chỉ có sẵn dựng sẵn; các trình xử lý bước tùy chỉnh do người dùng định nghĩa không được hỗ trợ trong bản phát hành này.
CapabilityResolverInterface là điểm nối entitlement công khai. Các hiện thực phải theo nguyên tắc từ chối-theo-thiếu-vắng và không được mặc định cho phép.
Executor PHP này là đường kiểm tra manifest và thực thi tuần tự; các triển khai production có thể điều phối qua sidecar để dàn xếp song song. Cổng năng lực trên đường PHP luôn fail-closed một cách độc lập trong cả hai trường hợp.
Chi tiết cơ chế nội bộ nằm trong tài liệu nội bộ của kho mã nguồn và nằm ngoài phạm vi của tài liệu hướng dẫn này.

Ranh giới công bố

Trang này chỉ ghi lại hành vi có thể quan sát 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ộ, lớp hỗ trợ, bảng cơ chế, tên file runbook, và tiền tố ticket đều nằm ngoài phạm vi.

Xem thêm

Output Pipeline — trang giới thiệu tính năng cho hướng dẫn quy trình làm việc.
Output Pipeline — NextPDF Enterprise Deep Reference — dàn xếp theo lô xuyên nhiều manifest.
Document — Tài liệu tham chiếu chuyên sâu
Accelerator — Tài liệu tham chiếu chuyên sâu