Output Pipeline — Referensi Mendalam

Sekilas pandang

Halaman ini adalah referensi mendalam untuk permukaan publik NextPDF\Pro\OutputPipeline. Halaman ini mencakup konstruksi dan validasi manifest, urutan eksekusi topologis, semantik retry dan timeout, perilaku resume, serta gerbang kapabilitas pack yang fail-closed. Halaman ini menyatakan parameter, nilai default, dan mode kegagalan untuk setiap simbol publik. Baca halaman kapabilitas Output Pipeline terlebih dahulu untuk panduan alur kerja.

Ketersediaan & lisensi

Kapabilitas ini dikirimkan dalam NextPDF Pro (nextpdf/pro) dan diaktifkan dengan license envelope tingkat Pro. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Executor dan tujuh dari sepuluh tipe langkah tidak membawa flag per-fitur. Tiga tipe langkah tambahan membutuhkan kapabilitas Pack:

Tipe langkah	Nilai manifest	Kapabilitas yang dibutuhkan	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

Gerbang ini diberlakukan pada waktu eksekusi, fail-closed, sebelum langkah mencapai resolver-nya. Langkah tergerbang tanpa lisensi menghasilkan hasil langkah Failed yang membawa kode SPEC-LIC-001 dan kapabilitas yang dibutuhkan; resolver tidak pernah dipanggil. Pipeline tanpa capability resolver yang di-inject menolak setiap langkah tergerbang.

Permukaan API publik

composer require nextpdf/pro:^3

Metapackage nextpdf/premium memasang kode nextpdf/pro; modul ini berada di dalam namespace NextPDF\Pro\OutputPipeline.

Simbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
PipelineExecutor::__construct	StepResolverRegistry $registry, ?CapabilityResolverInterface $capabilityResolver = null	Mengikat registry resolver bawaan dan sumber entitlement opsional	PipelineExecutor	Tidak ada yang dideklarasikan	Capability resolver bernilai null menolak setiap langkah yang digerbang pack
PipelineExecutor::execute	PipelineManifest $manifest, array $variables = []	Menjalankan langkah dalam urutan topologis dan mengagregasi hasil	PipelineResult	Tidak ada yang dideklarasikan; kegagalan resolver ditangkap sebagai hasil langkah Failed	Dirancang untuk berjalan di dalam job worker asinkron
PipelineManifest::__construct	string $id, array $steps, PipelineOptions $options = new PipelineOptions(), ?string $resumeFromStepId = null	Memvalidasi graf langkah saat konstruksi	PipelineManifest	InvalidArgumentException pada daftar langkah kosong, ID langkah duplikat, dependensi tak dikenal, siklus, ketidakcocokan tipe output, atau langkah resume yang hilang; OverflowException di atas 10 000 langkah	Semua validasi selesai sebelum eksekusi apa pun
PipelineManifest::topologicalOrder	tidak ada	Mengurutkan langkah dengan dependensi sebelum yang bergantung	list<PipelineStep>	Tidak ada yang dideklarasikan	Deterministik untuk manifest tertentu
PipelineManifest::getStep	string $stepId	Pencarian linear berdasarkan ID langkah	?PipelineStep	Tidak ada yang dideklarasikan	null untuk ID tak dikenal
PipelineManifest::rootSteps	tidak ada	Mengembalikan langkah yang tidak memiliki dependensi	list<PipelineStep>	Tidak ada yang dideklarasikan	Langkah root berjalan lebih dulu
PipelineManifestBuilder::create	string $manifestId	Memulai builder baru	self	Tidak ada yang dideklarasikan	Konstruktor bersifat private; ini satu-satunya entri
PipelineManifestBuilder::addStep	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], ?StepOutputType $outputType = null	Menambahkan langkah; tipe output null disimpulkan dari tipe langkah	self	Tidak ada yang dideklarasikan	Validasi ditangguhkan ke build()
PipelineManifestBuilder::stopOnError	bool $stop = true	Mengatur halt-on-first-failure	self	Tidak ada yang dideklarasikan	Default true
PipelineManifestBuilder::maxRetries	int $retries	Mengatur batas atas retry per-langkah	self	Tidak ada yang dideklarasikan	Default 0 (tanpa retry)
PipelineManifestBuilder::timeout	int $timeoutMs	Mengatur timeout global pipeline	self	Tidak ada yang dideklarasikan	0 menonaktifkan timeout
PipelineManifestBuilder::resumeFrom	string $stepId	Mengatur titik resume	self	Tidak ada yang dideklarasikan	Langkah harus ada pada waktu build()
PipelineManifestBuilder::build	tidak ada	Mengonstruksi manifest yang tervalidasi	PipelineManifest	Sama seperti PipelineManifest::__construct	—
PipelineOptions::__construct	bool $stopOnError = true, int $maxRetries = 0, int $timeoutMs = 0	Opsi eksekusi yang immutable	PipelineOptions	Tidak ada yang dideklarasikan	Value object readonly
PipelineStep::__construct	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], StepOutputType $outputType = StepOutputType::Pdf	Definisi langkah yang immutable	PipelineStep	Tidak ada yang dideklarasikan	Konstruksi langsung menetapkan tipe output ke PDF secara default untuk setiap tipe
PipelineStep::isRoot	tidak ada	True ketika langkah tidak memiliki dependensi	bool	Tidak ada yang dideklarasikan	—
PipelineStepType (enum)	—	Sepuluh case berbasis string: generate, merge, split, inspect, compress, sign, convert, ditambah redact, extract, ocr_overlay yang tergerbang	—	—	Satu case per operasi bawaan
PipelineStepType::requiresPack	tidak ada	True untuk Redact, Extract, dan OcrOverlay	bool	Tidak ada yang dideklarasikan	Semua case lain mengembalikan false
PipelineStepType::requiredCapability	tidak ada	Memetakan case tergerbang ke kode kapabilitasnya	?string	Tidak ada yang dideklarasikan	null untuk case yang tidak tergerbang
PipelineStatus (enum)	—	Lima case: pending, running, completed, failed, cancelled	—	—	Digunakan bersama oleh hasil pipeline dan langkah
PipelineStatus::isTerminal	tidak ada	True untuk Completed, Failed, dan Cancelled	bool	Tidak ada yang dideklarasikan	Pending dan Running bersifat non-terminal
StepOutputType (enum)	—	Tiga case: pdf, json, metadata	—	—	Menggerakkan validasi edge pada waktu build
StepOutputType::forStepType	PipelineStepType $stepType	Tipe output default untuk sebuah tipe langkah	self	Tidak ada yang dideklarasikan	Inspect dan Extract dipetakan ke JSON; semua tipe lain dipetakan ke PDF
StepOutputType::isCompatibleWith	self $expectedInput	True untuk kecocokan tipe yang sama atau output PDF	bool	Tidak ada yang dideklarasikan	Helper; PDF adalah input universal
PipelineContext::__construct	string $manifestId, array $variables = [], ?string $resumeFromStepId = null	Konteks in-memory per-run	PipelineContext	Tidak ada yang dideklarasikan	Tanpa TTL, kedaluwarsa, persistence, atau backing store
PipelineContext::setStepResult / ::getStepResult	string $stepId (+ StepResult saat set)	Merekam atau membaca hasil langkah	void / ?StepResult	Tidak ada yang dideklarasikan	null untuk langkah yang belum dieksekusi
PipelineContext::setStepOutput / ::getStepOutput	string $stepId (+ mixed saat set)	Menyimpan atau membaca output antara	void / mixed	Tidak ada yang dideklarasikan	null untuk output yang hilang
PipelineContext::hasStepResult	string $stepId	Apakah sebuah langkah sudah dieksekusi	bool	Tidak ada yang dideklarasikan	Mendukung pemeriksaan resume
PipelineContext::allStepResults	tidak ada	Semua hasil yang direkam sejauh ini	array<string, StepResult>	Tidak ada yang dideklarasikan	Berkunci berdasarkan ID langkah
PipelineContext::isResume	tidak ada	Apakah run dilanjutkan dari sebuah langkah	bool	Tidak ada yang dideklarasikan	—
PipelineResult::isSuccess	tidak ada	True hanya untuk status Completed keseluruhan	bool	Tidak ada yang dideklarasikan	Hasil diproduksi oleh executor
PipelineResult::getStepResult	string $stepId	Menemukan satu hasil langkah berdasarkan ID	?StepResult	Tidak ada yang dideklarasikan	null untuk langkah yang dilewati atau tak dikenal
PipelineResult::failedSteps	tidak ada	Memfilter hasil langkah yang gagal	list<StepResult>	Tidak ada yang dideklarasikan	Daftar kosong pada keberhasilan penuh
StepResult::isSuccess	tidak ada	True hanya untuk status langkah Completed	bool	Tidak ada yang dideklarasikan	Membawa stepId, type, status, durationMs, error, output
CapabilityResolverInterface::hasCapability	string $capability	Uji entitlement afirmatif untuk satu kode kapabilitas	bool	Tidak boleh melempar	Deny-by-omission: false untuk kode yang tak dikenal, kedaluwarsa, atau tak terpetakan

Signature entry-point

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;
}

Kontrak perilaku

Validasi manifest

Validasi berjalan di konstruktor PipelineManifest, sebelum eksekusi apa pun. Secara berurutan: daftar langkah harus tidak kosong; jumlah langkah dibatasi pada 10 000, mengubah rantai dependensi yang dalam secara adversarial menjadi OverflowException yang dapat ditangkap alih-alih native stack exhaustion; ID langkah harus unik; setiap referensi dependsOn harus dapat diselesaikan; graf dependensi harus asiklik; tipe output harus kompatibel; langkah resume yang dideklarasikan harus ada. Setiap pelanggaran memunculkan InvalidArgumentException dengan pesan spesifik.

Pemeriksaan tipe output berlaku untuk langkah yang tipenya dipetakan ke output PDF: setiap dependensi dari langkah tersebut harus menghasilkan output PDF juga. Edge dependensi ke tipe langkah yang menghasilkan JSON (inspect, extract) tidak diperiksa tipenya pada rilis ini.

Urutan eksekusi, resume, dan timeout

execute($manifest, $variables) membangun PipelineContext baru, menghitung urutan topologis, dan menjalankan langkah secara berurutan dalam urutan tersebut. Dengan titik resume yang ditetapkan, langkah-langkah sebelumnya dilewati sampai langkah bernama tercapai. Predesesor yang dilewati tidak dieksekusi ulang dan outputnya tidak dipulihkan: konteks bersifat per-run dan in-memory, sehingga langkah yang dilanjutkan yang membaca output predesesor yang dilewati akan mengamati null.

Timeout global, jika positif, dievaluasi di antara langkah, sebelum tiap langkah dimulai. Saat kedaluwarsa, status pipeline menjadi Failed dan langkah-langkah yang tersisa tidak dimulai. Langkah yang sudah berjalan tidak pernah diinterupsi di tengah eksekusi, sehingga satu langkah yang panjang dapat melampaui anggaran.

Retry dan penangkapan kegagalan

Setiap langkah menerima paling banyak maxRetries + 1 upaya. Upaya yang berhasil langsung mengembalikan hasil. Setiap upaya yang gagal — hasil Failed dari resolver, atau Throwable yang dilempar — diulang selama masih ada upaya tersisa; hasil dari upaya terakhir yang dikembalikan. Throwable yang dimunculkan di dalam resolver diturunkan menjadi hasil langkah Failed yang membawa pesan eksepsi, atau Unknown error ketika pesannya kosong. Oleh karena itu execute() selalu mengembalikan PipelineResult; ia tidak pernah merambatkan kegagalan resolver.

Tipe langkah tanpa resolver terdaftar menghasilkan hasil langkah Failed dengan pesan eksplisit; run tidak dibatalkan. Dengan stopOnError bernilai true (default), eksekusi berhenti pada langkah gagal pertama dan status pipeline menjadi Failed. Dengan nilai false, eksekusi berlanjut dan status akhir menjadi Failed jika ada langkah yang gagal, jika tidak Completed.

Gerbang kapabilitas pack

Sebelum dispatch resolver apa pun, setiap langkah yang digerbang pack (Redact, Extract, OcrOverlay) diperiksa terhadap CapabilityResolverInterface yang di-inject. Gerbang bersifat fail-closed: resolver yang hilang, jawaban false, atau kode kapabilitas yang tak terpetakan semuanya menolak langkah tersebut. Penolakan menghasilkan hasil langkah Failed yang error-nya membawa kode SPEC-LIC-001, tipe langkah, dan kapabilitas yang dibutuhkan. Penolakan tergerbang tidak mengonsumsi upaya retry dan melaporkan durasi 0.0. Implementasi resolver harus mengembalikan true hanya untuk entitlement yang dipegang secara afirmatif dan tidak boleh melempar.

Agregasi hasil

PipelineResult melaporkan ID manifest, status keseluruhan, hasil per-langkah dalam urutan eksekusi, total durasi dalam milidetik, serta jumlah langkah total, selesai, dan gagal. stepsTotal menghitung setiap langkah dalam manifest, termasuk langkah yang dilewati oleh resume atau yang tak tercapai setelah halt; stepsCompleted dan stepsFailed hanya menghitung langkah yang dieksekusi.

Kasus tepi & mode kegagalan

• Executor dirancang untuk eksekusi asinkron di dalam job worker. Penggunaan inline memblokir pemanggil selama keseluruhan durasi pipeline.
• Timeout global adalah pemeriksaan antarlangkah. Satu langkah yang panjang dapat melampaui anggaran; tidak ada langkah yang diinterupsi di tengah jalan.
• Resume hanya melewati langkah dalam eksekusi yang sama. Ia tidak memulihkan output dari store mana pun; resume lintas-run dengan output yang di-cache tidak diimplementasikan.
• Mengonstruksi PipelineStep secara langsung menetapkan tipe output ke PDF secara default untuk setiap tipe langkah. Gunakan builder, atau berikan tipe output secara eksplisit, agar langkah inspect dan extract mendeklarasikan output JSON dan validasi edge tetap bermakna.
• Eksepsi resolver dengan pesan kosong dinormalisasi menjadi Unknown error dalam hasil langkah.
• Hasil langkah Failed yang diproduksi oleh gerbang atau oleh resolver yang hilang melaporkan durasi 0.0.
• PipelineResult::getStepResult() mengembalikan null baik untuk ID tak dikenal maupun untuk langkah yang dilewati oleh resume atau halt; bedakan melalui stepsTotal versus panjang daftar hasil.
• Modul ini tidak melakukan operasi kriptografis dan tidak mendefinisikan perilaku khusus FIPS. Postur FIPS untuk langkah sign diatur oleh modul penandatanganan, bukan oleh pipeline.

Kesesuaian

Pipeline tidak melakukan pekerjaan kesesuaian format sendiri. Kesesuaian setiap artefak yang dihasilkan dimiliki oleh modul di balik langkah yang mengeksekusi — penandatanganan, optimasi, konversi, dan seterusnya — dan didokumentasikan pada halaman referensi modul-modul tersebut. Halaman ini tidak mengklaim pengenal klausa eksternal apa pun; setiap pernyataan didasarkan pada source produk. NextPDF tidak membuat klaim sertifikasi.

Catatan pengembangan

• Source modul membawa @since 2.2.0; referensi ini mendokumentasikan permukaan sebagaimana dikirimkan dalam nextpdf/pro 3.1.0.
• Semua kelas bersifat final; tipe manifest, options, step, dan result adalah value object readonly. Konstruksi instance baru alih-alih memutasi.
• StepResolverInterface dan StepResolverRegistry bersifat @internal. Step resolver hanya bawaan; custom step handler yang didefinisikan pengguna tidak didukung pada rilis ini.
• CapabilityResolverInterface adalah seam entitlement publik. Implementasi harus deny-by-omission dan tidak boleh default-allow.
• Executor PHP ini adalah jalur validasi-manifest dan eksekusi sekuensial; deployment produksi dapat melakukan dispatch melalui sidecar untuk orkestrasi paralel. Gerbang kapabilitas pada jalur PHP bersifat fail-closed secara independen dalam kedua kasus.
• Detail mekanisme internal tetap berada di dokumentasi internal repositori source dan berada di luar cakupan manual ini.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Jalur namespace internal, kelas helper, tabel mekanisme, nama file runbook, dan prefix tiket berada di luar cakupan.

Lihat juga

• Output Pipeline — halaman kapabilitas untuk panduan alur kerja.
• Output Pipeline — Referensi Mendalam NextPDF Enterprise — orkestrasi batch lintas manifest.
• Document — Referensi Mendalam
• Accelerator — Referensi Mendalam