Pro phiên bản

Output pipeline

Tổng quan nhanh

Output Pipeline chạy một manifest khai báo gồm các bước PDF theo thứ tự phụ thuộc, với việc thử lại theo từng bước và một tùy chọn dừng-khi-lỗi. Một số loại bước cần thêm một năng lực Enterprise Pack.

Khả dụng & cấp phép

Tính năng này đi kèm trong NextPDF Pro (nextpdf/pro) và kích hoạt bằng một envelope giấy 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 tính năng. So sánh các phiên bản và lấy giấy phép.

Bản thân bộ thực thi pipeline là một phần của phiên bản Pro. Ba loại bước ngoài ra còn cần một năng lực Enterprise Pack có tên gọi: bước xóa che cần một năng lực Privacy Pack, còn các bước trích xuất và OCR-overlay cần các năng lực Intelligence Pack. Một bước bị kiểm soát mà chưa được cấp phép sẽ fail closed ở khâu thực thi — nó tạo ra một kết quả bước thất bại và resolver của nó không bao giờ được gọi — thay vì hủy bỏ toàn bộ lần chạy.

Cài đặt

composer require nextpdf/pro:^3

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

Tổng quan khái niệm

PipelineExecutor nhận một PipelineManifest, sắp các bước theo thứ tự topo, và phân phối mỗi bước đến một resolver được đăng ký trong StepResolverRegistry. Đầu ra của các bước được lưu trong một PipelineContext cho các bước phía sau. Bộ thực thi thực thi một timeout toàn cục, hỗ trợ thử lại theo từng bước, và có thể tiếp tục từ một bước được nêu tên. Nó được thiết kế để chạy bên trong một job worker bất đồng bộ, không phải trực tiếp từ một request handler.

Các loại bước dựng sẵn bao gồm generate, merge, split, inspect, compress, sign, và convert. Các loại bước xóa che, trích xuất, và OCR-overlay được cấp phép theo năng lực và ánh xạ tới các năng lực Enterprise Pack.

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

Bộ thực thi chỉ làm điều phối. Nó sắp các bước, thực thi cổng giấy phép, và phân phối mỗi bước đến một resolver đã đăng ký, nhưng bản thân không thực hiện công việc PDF nào. Sự phân tách đó cho phép một manifest chạy hoặc qua đường PHP tuần tự này hoặc qua một worker ngoài luồng phân phối các bước song song, mà không thay đổi mã gọi. Thiết kế nhắm tới một job worker bất đồng bộ thay vì một request handler, vì một pipeline nhiều bước thường sống lâu hơn ngân sách của một request, và một hàng đợi mở rộng thông lượng bằng cách thêm worker. Timeout toàn cục được kiểm tra giữa các bước cũng vì lý do đó: một cả bước là đơn vị công việc được giao cho một resolver, và bộ điều phối đứng ngoài lần chạy của resolver đó. Các thất bại nổi lên dưới dạng các giá trị StepResult theo từng bước thay vì các exception được ném ra, nên một bước thất bại không bao giờ làm sụp đổ PipelineResult tổng hợp mà worker báo cáo.

Bối cảnh thiết kế: Sinh tài liệu khối lượng lớn.

Hợp đồng hành vi

execute($manifest, $variables) trả về một kết quả với trạng thái tổng thể, kết quả theo từng bước, thời lượng, và số đếm các bước đã hoàn tất và thất bại.
Các bước chạy theo thứ tự topo; một resolver bị thiếu cho một loại bước sẽ tạo ra một bước thất bại kèm một thông báo rõ ràng.
PipelineOptions::$stopOnError dừng thực thi ở lần thất bại đầu tiên; nếu không, việc thực thi tiếp tục và trạng thái cuối phản ánh mọi thất bại.
Timeout toàn cục, khi được đặt, làm pipeline thất bại nếu bị vượt quá trước khi bước kế tiếp bắt đầu.
Việc thử lại theo từng bước bị giới hạn bởi giá trị tối đa đã cấu hình; chỉ các thất bại không phải dạng cuối mới được thử lại.
Tiếp-tục-từ-bước bỏ qua các bước trước đó cho đến khi đến bước được nêu tên.
Các loại bước bị kiểm soát năng lực fail closed ở khâu thực thi kèm một mã lỗi giấy phép khi vắng năng lực Pack cần thiết; resolver không bao giờ được gọi.

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\OutputPipeline\PipelineExecutor;

$result = (new PipelineExecutor($stepResolverRegistry))->execute($manifest);

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

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

$executor = new PipelineExecutor($stepResolverRegistry);

// Invoke from an async job worker, not a request handler.
$result = $executor->execute($manifest, ['customerName' => 'Acme']);

if ($result->status !== \NextPDF\Pro\OutputPipeline\PipelineStatus::Completed) {
    foreach ($result->stepResults as $stepResult) {
        // Inspect per-step error detail.
    }
}

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

Pipeline được thiết kế để chạy bất đồng bộ qua một hệ thống job. Chạy nó nội tuyến sẽ chặn bên gọi trong suốt thời lượng của toàn bộ pipeline.
Một loại bước không có resolver được đăng ký sẽ làm bước đó thất bại thay vì hủy bỏ toàn bộ pipeline (trừ khi dừng-khi-lỗi được đặt).
Timeout toàn cục được kiểm tra giữa các bước, không phải giữa chừng một bước; một bước chạy lâu có thể vượt ngân sách trước khi phép kiểm tra kích hoạt.

Hiệu năng

Tổng thời lượng là tổng các thời lượng bước cộng với chi phí thử lại. Timeout toàn cục giới hạn thời gian thực-tế trường-hợp-xấu-nhất. Không có con số thông lượng nào được công bố; chi phí pipeline bị chi phối bởi các bước bạn đưa vào. Hãy đo bằng các manifest đại diện.

Lưu ý bảo mật

Bộ thực thi truyền các tài liệu đầu vào và biến cho các step resolver; hãy coi chúng là không đáng tin và xác thực bên trong mỗi resolver. Các bước bị kiểm soát năng lực fail closed khi chưa được cấp phép. Bộ thực thi không ghi nhật ký nội dung tài liệu nào.

Tính phù hợp

Bản thân bộ thực thi không thực hiện công việc phù hợp định dạng nào; sự phù hợp phụ thuộc vào từng step resolver (generate, merge, split, sign, convert). 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.

Lưu ý ranh giới Enterprise

Enterprise bổ sung các năng lực Pack mở khóa các loại bước bị kiểm soát (xóa che, trích xuất, OCR overlay) ở mức hành vi. Không có các Pack đó, pipeline vẫn chạy mọi bước không bị kiểm soát. Phần nội bộ của Pack nằm ngoài phạm vi ở đây.

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

Không có Pro, hãy điều phối các thao tác PDF theo lối mệnh lệnh với các API NextPDF Core; manifest khai báo, thứ tự phụ thuộc, và việc thử lại là các bổ sung của 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ộ, 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.