Enterprise edisi

Output Pipeline — Referensi Mendalam

Sekilas

NextPDF\Enterprise\OutputPipeline menjalankan banyak manifest pipeline Pro sebagai satu batch. BatchPipelineOrchestrator membungkus PipelineExecutor milik Pro dengan koordinasi batch: penjaga sumber daya terbatas pada ukuran batch, timeout batch global opsional, injeksi variabel per manifest, dan akuntansi agregat. Sebuah pemeriksaan kepatuhan opsional di akhir batch memvalidasi ulang setiap output yang selesai melalui gateway kepatuhan Enterprise dan gagal secara tertutup (fail closed). Setiap eksekusi mengembalikan BatchPipelineResult yang membawa hasil per manifest, jumlah yang selesai dan yang gagal, timing, serta laporan kepatuhan opsional.

Ketersediaan & lisensi

Kapabilitas ini tersedia di NextPDF Enterprise (nextpdf/enterprise) dan aktif dengan amplop lisensi tier Enterprise. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Tier	Permukaan output-pipeline
Core	Tidak ada permukaan output-pipeline.
Pro	Pipeline manifest tunggal (kapabilitas `pro.output.pipeline`).
Enterprise	Orkestrasi batch, batas ukuran batch, timeout batch, handoff kepatuhan.

Permukaan batch Enterprise tidak membawa kode kapabilitas per fitur tersendiri; batas paketlah yang menggerbanginya. Kapabilitas manifest tunggal Pro pro.output.pipeline adalah prasyarat, bukan gerbangnya. Lisensi Pro saja hanya membuka pipeline manifest tunggal yang mendasarinya, bukan permukaan batch ini.

composer require nextpdf/enterprise:^3

Permukaan API publik

Simbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
`BatchPipelineOrchestrator::__construct()`	`PipelineExecutor $executor`, `BatchPipelineConfig $config`, `?ComplianceGateway $complianceGateway`, `ComplianceProfile $complianceProfile`	Config default; tanpa gateway; profil `ComplianceProfile::PdfA4`	—	Tidak ada	Injeksikan gateway saat pemeriksaan kepatuhan diaktifkan; tanpa itu, setiap manifest yang diperiksa dilaporkan gagal.
`BatchPipelineOrchestrator::executeBatch()`	`list<PipelineManifest> $manifests`, `array<string, array<string, mixed>> $variablesMap = []`	Menjalankan manifest dalam urutan pengiriman; variabel diselesaikan berdasarkan ID manifest	`BatchPipelineResult`	`OverflowException` saat batch melebihi 10.000 manifest; exception gateway saat pemeriksaan kepatuhan diaktifkan (lihat Kasus tepi)	`Throwable` dari resolver tidak pernah lolos; executor Pro menurunkannya menjadi hasil langkah yang gagal.
`BatchPipelineConfig::__construct()`	`int $maxConcurrency = 4`, `int $timeoutMs = 0`, `bool $complianceCheckOnComplete = false`	Konkurensi 4; tanpa timeout; tanpa pemeriksaan kepatuhan	—	Tidak ada	Value object readonly. `timeoutMs = 0` menonaktifkan timeout batch.
`BatchPipelineResult::__construct()`	`list<PipelineResult> $results`, `int $totalManifests`, `int $completedCount`, `int $failedCount`, `float $durationMs`, `?array $complianceReport = null`	Agregat atas nilai `PipelineResult` per manifest	—	Tidak ada	Readonly. `complianceReport` tetap `null` kecuali pemeriksaan berjalan.
`BatchPipelineResult::allSucceeded()`	—	Menguji `failedCount === 0`	`bool`	Tidak ada	Mengembalikan true pada batch yang terpotong timeout dengan nol kegagalan; lihat Kasus tepi.
`BatchPipelineResult::successRate()`	—	`completedCount / totalManifests`	`float`	Tidak ada	Mengembalikan `1.0` untuk batch kosong.
`BatchPipelineResult::hasComplianceReport()`	—	Menguji `complianceReport !== null`	`bool`	Tidak ada	—

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,
) {}

Kontrak perilaku

executeBatch() pertama-tama menegaskan ukuran batch terhadap batas 10.000 manifest. Batch di atas batas memicu OverflowException sebelum ada manifest yang dieksekusi; tidak ada yang terdegradasi secara diam-diam.

Manifest kemudian dieksekusi dalam urutan pengiriman melalui PipelineExecutor milik Pro. Setiap manifest menerima entri variabel yang di-key berdasarkan ID-nya di $variablesMap; manifest tanpa entri menerima peta variabel kosong. Sebuah manifest dihitung selesai ketika status PipelineResult-nya adalah Completed; status terminal lainnya dihitung gagal. Exception resolver tidak lolos: executor Pro mengonversi setiap Throwable resolver menjadi hasil langkah yang gagal, sehingga executeBatch() selalu mengagregasi hasil ketimbang membatalkan batch di tengah jalan karena error langkah.

Ketika timeoutMs lebih besar dari nol, waktu berjalan diperiksa sebelum setiap manifest dimulai. Setelah anggaran habis, manifest yang tersisa dilewati: mereka tidak menghasilkan PipelineResult, dan tidak dihitung sebagai selesai maupun gagal. totalManifests selalu melaporkan jumlah yang dikirimkan.

Ketika complianceCheckOnComplete diaktifkan, orchestrator memvalidasi PDF akhir dari setiap manifest yang selesai terhadap ComplianceProfile yang dikonfigurasi melalui ComplianceGateway yang diinjeksikan. Pemeriksaan gagal secara tertutup (fail closed):

Tidak ada gateway yang diinjeksikan: setiap manifest yang diperiksa dilaporkan gagal, karena kepatuhan tidak pernah divalidasi.
Tidak ada output PDF yang dapat diselesaikan dari output langkah manifest: gagal.
Gateway tidak mengembalikan hasil (ketidaktersediaan sidecar mode opsional): gagal. Ketiadaan hasil positif bukanlah kelulusan.
Gateway melaporkan ketidaksesuaian apa pun: gagal.

PDF akhir diselesaikan dengan memindai output langkah dari manifest yang selesai, langkah terakhir terlebih dahulu, untuk nilai string langsung yang diawali dengan header %PDF. Output langkah tidak pernah menyarangkan byte-string PDF di dalam sub-array; hanya nilai output langsung yang diperiksa. Manifest yang tidak selesai dilewati, tidak diperiksa.

Laporan kepatuhan adalah array dengan kunci profile, checked, passed, failed, dan failures; setiap entri kegagalan membawa manifestId dan reason. Laporan tersebut melekat pada BatchPipelineResult::$complianceReport dan dapat dijangkau melalui hasComplianceReport().

Handoff kepatuhan adalah bantuan validasi ulang, bukan kontrol otorisasi. Ia hanya melaporkan temuan.

Kasus tepi & mode kegagalan

Lebih dari 10.000 manifest: OverflowException sebelum ada eksekusi yang dimulai.
timeoutMs = 0 berarti tidak ada timeout batch. Setel nilai berhingga di produksi.
Pemotongan timeout: manifest yang dilewati tidak muncul dalam hitungan apa pun, sehingga completedCount + failedCount bisa kurang dari totalManifests. allSucceeded() hanya menguji failedCount === 0 dan bisa mengembalikan true untuk batch yang terpotong. Bandingkan count($result->results) dengan totalManifests untuk mendeteksi pemotongan.
successRate() mengembalikan 1.0 untuk batch kosong (nol manifest dikirimkan).
ID manifest tidak dideduplikasi di tingkat batch. Dua manifest yang berbagi ID keduanya dieksekusi dan menyelesaikan entri variabel yang sama.
Error manifest struktural (daftar langkah kosong, ID langkah duplikat, dependensi tidak dikenal, siklus dependensi, ketidakcocokan tipe output, langkah resume yang hilang) memicu InvalidArgumentException saat konstruksi manifest, sebelum executeBatch() pernah dipanggil.
Dengan pemeriksaan kepatuhan diaktifkan, ComplianceGateway::validate() dapat melempar ComplianceSidecarUnavailableException (sidecar tidak tersedia dalam mode wajib) atau InvalidArgumentException (tidak ada validator yang terdaftar untuk tool profil). Salah satu exception lolos dari executeBatch() setelah eksekusi tetapi sebelum hasil dibangun, sehingga hasil per manifest hilang bagi pemanggil. Dalam mode opsional gateway mengembalikan null, dan manifest dicatat sebagai kegagalan kepatuhan.
Langkah handoff kepatuhan dalam pipeline gagal ketika tidak ada output langkah hulu yang berisi byte PDF yang dapat dikenali; ia tidak pernah lulus secara diam-diam.
Modul ini tidak melakukan operasi kriptografis; mode FIPS tidak berlaku.

Konformitas

Tidak ada klaim konformitas standar untuk modul ini; ia adalah lapisan orkestrasi. Pemeriksaan kepatuhan opsional menyerahkan kepada gateway kepatuhan Enterprise dan validator eksternalnya, yang membawa referensinya sendiri. Profil default adalah ComplianceProfile::PdfA4; profil gateway lain mencakup target PDF/A, PDF/UA, dan PAdES lebih lanjut.

Sebuah laporan kepatuhan menyatakan temuan validator terhadap profil yang dipilih. Ia tidak mensertifikasi dokumen, menjamin kecukupan regulasi, atau merupakan nasihat hukum. Menilai apakah suatu output memenuhi kewajiban Anda adalah tanggung jawab Anda.

Catatan pengembangan

Dalam deployment produksi, dispatch worker paralel dan backpressure ditangani oleh sidecar eksekusi terpisah. Orchestrator PHP menyediakan koordinasi batch dan logika handoff kepatuhan serta dipanggil oleh job worker, bukan langsung oleh handler request.
Jalur fallback PHP menjalankan manifest secara sekuensial. maxConcurrency membatasi callback worker konkuren dalam deployment yang digerakkan sidecar; menetapkan ukurannya relatif terhadap pool worker PHP adalah tanggung jawab operator.
Resolver langkah handoff kepatuhan dalam pipeline adalah tipe internal yang terdaftar untuk langkah bertipe inspect. Aktifkan validasi akhir batch melalui BatchPipelineConfig ketimbang membangun langkah pipeline untuknya secara langsung.
Bangun instans PipelineManifest sedini mungkin. Validasi strukturalnya berjalan di konstruktor, sehingga graf yang tidak valid gagal cepat dan tidak pernah menghabiskan anggaran batch.

Batas publikasi

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