Output Pipeline — Derinlemesine başvuru

Bir bakışta

Bu sayfa, NextPDF\Pro\OutputPipeline genel yüzeyi için derinlemesine başvurudur. Manifest oluşturma ve doğrulama, topolojik yürütme sırası, yeniden deneme ve zaman aşımı semantiği, devam etme davranışı ve fail-closed pack yeteneği kapısını kapsar. Her genel simge için parametreleri, varsayılanları ve hata modlarını belirtir. İş akışı yönlendirmesi için önce Output Pipeline yetenek sayfasını okuyun.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile gönderilir ve bir Pro katmanı lisans zarfıyla etkinleştirilir. Bu yetkiye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve lisans edinin.

Çalıştırıcı ve on adım türünün yedisi, özellik başına bir bayrak taşımaz. Üç adım türü ayrıca bir Pack yeteneği gerektirir:

Adım türü	Manifest değeri	Gerekli yetenek	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

Kapı, yürütme zamanında, fail-closed olarak, adım çözümleyicisine ulaşmadan önce zorunlu kılınır. Lisanssız kapılı bir adım, SPEC-LIC-001 kodunu ve gerekli yeteneği taşıyan bir Failed adım sonucu verir; çözümleyici hiçbir zaman çağrılmaz. Enjekte edilmiş yetenek çözümleyicisi olmayan bir pipeline, her kapılı adımı reddeder.

Genel API yüzeyi

composer require nextpdf/pro:^3

nextpdf/premium metapaketi nextpdf/pro kodunu yükler; bu modül NextPDF\Pro\OutputPipeline ad alanı altında yer alır.

Simge	Parametreler	Varsayılan davranış	Döndürür	Fırlatır veya şununla başarısız olur	Notlar
PipelineExecutor::__construct	StepResolverRegistry $registry, ?CapabilityResolverInterface $capabilityResolver = null	Yerleşik çözümleyici kayıt defterini ve isteğe bağlı yetki kaynağını bağlar	PipelineExecutor	Beyan edilmedi	null bir yetenek çözümleyicisi, her pack kapılı adımı reddeder
PipelineExecutor::execute	PipelineManifest $manifest, array $variables = []	Adımları topolojik sırada çalıştırır ve sonuçları toplar	PipelineResult	Beyan edilmedi; çözümleyici hataları Failed adım sonuçları olarak yakalanır	Bir eşzamansız iş çalışanı içinde çalışacak şekilde tasarlandı
PipelineManifest::__construct	string $id, array $steps, PipelineOptions $options = new PipelineOptions(), ?string $resumeFromStepId = null	Adım grafiğini oluşturma sırasında doğrular	PipelineManifest	Boş adım listesi, yinelenen adım kimlikleri, bilinmeyen bağımlılıklar, döngüler, çıktı türü uyuşmazlığı veya eksik bir devam adımında InvalidArgumentException; 10 000 adımın üzerinde OverflowException	Tüm doğrulama, herhangi bir yürütmeden önce tamamlanır
PipelineManifest::topologicalOrder	yok	Adımları, bağımlılıkları bağımlılardan önce gelecek şekilde sıralar	list<PipelineStep>	Beyan edilmedi	Belirli bir manifest için belirlenimci
PipelineManifest::getStep	string $stepId	Adım kimliğine göre doğrusal arama	?PipelineStep	Beyan edilmedi	Bilinmeyen bir kimlik için null
PipelineManifest::rootSteps	yok	Bağımlılığı olmayan adımları döndürür	list<PipelineStep>	Beyan edilmedi	Kök adımlar önce çalışır
PipelineManifestBuilder::create	string $manifestId	Yeni bir oluşturucu başlatır	self	Beyan edilmedi	Yapıcı özeldir; tek giriş budur
PipelineManifestBuilder::addStep	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], ?StepOutputType $outputType = null	Bir adım ekler; null bir çıktı türü, adım türünden çıkarılır	self	Beyan edilmedi	Doğrulama build() işlemine ertelenir
PipelineManifestBuilder::stopOnError	bool $stop = true	İlk hatada durmayı ayarlar	self	Beyan edilmedi	Varsayılan true
PipelineManifestBuilder::maxRetries	int $retries	Adım başına yeniden deneme üst sınırını ayarlar	self	Beyan edilmedi	Varsayılan 0 (yeniden deneme yok)
PipelineManifestBuilder::timeout	int $timeoutMs	Genel pipeline zaman aşımını ayarlar	self	Beyan edilmedi	0 zaman aşımını devre dışı bırakır
PipelineManifestBuilder::resumeFrom	string $stepId	Devam noktasını ayarlar	self	Beyan edilmedi	Adım, build() zamanında var olmalıdır
PipelineManifestBuilder::build	yok	Doğrulanmış manifesti oluşturur	PipelineManifest	PipelineManifest::__construct ile aynı	—
PipelineOptions::__construct	bool $stopOnError = true, int $maxRetries = 0, int $timeoutMs = 0	Değişmez yürütme seçenekleri	PipelineOptions	Beyan edilmedi	Readonly değer nesnesi
PipelineStep::__construct	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], StepOutputType $outputType = StepOutputType::Pdf	Değişmez adım tanımı	PipelineStep	Beyan edilmedi	Doğrudan oluşturma, her tür için çıktı türünü PDF’e varsayar
PipelineStep::isRoot	yok	Adımın bağımlılığı olmadığında true	bool	Beyan edilmedi	—
PipelineStepType (enum)	—	On dize destekli durum: generate, merge, split, inspect, compress, sign, convert, artı kapılı redact, extract, ocr_overlay	—	—	Yerleşik işlem başına bir durum
PipelineStepType::requiresPack	yok	Redact, Extract ve OcrOverlay için true	bool	Beyan edilmedi	Diğer tüm durumlar false döndürür
PipelineStepType::requiredCapability	yok	Kapılı durumları yetenek kodlarına eşler	?string	Beyan edilmedi	Kapısız durumlar için null
PipelineStatus (enum)	—	Beş durum: pending, running, completed, failed, cancelled	—	—	pipeline ve adım sonuçları tarafından paylaşılır
PipelineStatus::isTerminal	yok	Completed, Failed ve Cancelled için true	bool	Beyan edilmedi	Pending ve Running sonlandırıcı değildir
StepOutputType (enum)	—	Üç durum: pdf, json, metadata	—	—	Oluşturma zamanı kenar doğrulamasını yönlendirir
StepOutputType::forStepType	PipelineStepType $stepType	Bir adım türü için varsayılan çıktı türü	self	Beyan edilmedi	Inspect ve Extract JSON’a eşlenir; diğer tüm türler PDF’e eşlenir
StepOutputType::isCompatibleWith	self $expectedInput	Aynı tür eşleşmesi veya bir PDF çıktısı için true	bool	Beyan edilmedi	Yardımcı; PDF evrensel giriştir
PipelineContext::__construct	string $manifestId, array $variables = [], ?string $resumeFromStepId = null	Çalıştırma başına bellek içi bağlam	PipelineContext	Beyan edilmedi	TTL, sona erme, kalıcılık veya destekleyici depo yok
PipelineContext::setStepResult / ::getStepResult	string $stepId (ayarlamada + StepResult)	Bir adım sonucunu kaydeder veya okur	void / ?StepResult	Beyan edilmedi	Henüz yürütülmemiş bir adım için null
PipelineContext::setStepOutput / ::getStepOutput	string $stepId (ayarlamada + mixed)	Bir ara çıktıyı depolar veya okur	void / mixed	Beyan edilmedi	Eksik bir çıktı için null
PipelineContext::hasStepResult	string $stepId	Bir adımın zaten yürütülüp yürütülmediği	bool	Beyan edilmedi	Devam denetimlerini destekler
PipelineContext::allStepResults	yok	Şimdiye kadar kaydedilen tüm sonuçlar	array<string, StepResult>	Beyan edilmedi	Adım kimliğiyle anahtarlanır
PipelineContext::isResume	yok	Çalıştırmanın bir adımdan devam edip etmediği	bool	Beyan edilmedi	—
PipelineResult::isSuccess	yok	Yalnızca genel Completed durumu için true	bool	Beyan edilmedi	Sonuç, çalıştırıcı tarafından üretilir
PipelineResult::getStepResult	string $stepId	Kimliğe göre bir adım sonucu bulur	?StepResult	Beyan edilmedi	Atlanan veya bilinmeyen adımlar için null
PipelineResult::failedSteps	yok	Başarısız adım sonuçlarını filtreler	list<StepResult>	Beyan edilmedi	Tam başarıda boş liste
StepResult::isSuccess	yok	Yalnızca Completed adım durumu için true	bool	Beyan edilmedi	stepId, type, status, durationMs, error, output taşır
CapabilityResolverInterface::hasCapability	string $capability	Bir yetenek kodu için olumlu yetki testi	bool	Fırlatmamalıdır	Atlama yoluyla reddet: bilinmeyen, süresi dolmuş veya eşlenmemiş kodlar için false

Giriş noktası imzaları

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

Davranış sözleşmesi

Manifest doğrulama

Doğrulama, herhangi bir yürütmeden önce PipelineManifest yapıcısında çalışır. Sırayla: adım listesi boş olmamalıdır; adım sayısı 10 000 ile sınırlıdır; bu, düşmanca derin bağımlılık zincirlerini yerel yığın tükenmesi yerine yakalanabilir bir OverflowException’a dönüştürür; adım kimlikleri benzersiz olmalıdır; her dependsOn referansı çözümlenmelidir; bağımlılık grafiği döngüsüz olmalıdır; çıktı türleri uyumlu olmalıdır; bildirilen bir devam adımı var olmalıdır. Her ihlal, belirli bir mesajla InvalidArgumentException fırlatır.

Çıktı türü denetimi, türü PDF çıktısına eşlenen adımlar için geçerlidir: böyle bir adımın her bağımlılığı da PDF çıktısı üretmelidir. JSON üreten adım türlerine (inspect, extract) giden bağımlılık kenarları bu sürümde tür denetiminden geçmez.

Yürütme sırası, devam etme ve zaman aşımı

execute($manifest, $variables), yeni bir PipelineContext oluşturur, topolojik sırayı hesaplar ve adımları bu sırada ardışık olarak çalıştırır. Bir devam noktası ayarlandığında, adlandırılan adıma ulaşılana kadar önceki adımlar atlanır. Atlanan öncüller yeniden çalıştırılmaz ve çıktıları geri yüklenmez: bağlam, çalıştırma başına ve bellek içidir; bu nedenle atlanan bir öncülün çıktısını okuyan devam eden bir adım null gözlemler.

Genel zaman aşımı, pozitif olduğunda, adımlar arasında, her adım başlamadan önce değerlendirilir. Süre dolduğunda pipeline durumu Failed olur ve kalan adımlar başlamaz. Halihazırda çalışan bir adım, yürütme ortasında asla kesintiye uğratılmaz; bu nedenle tek bir uzun adım bütçeyi aşabilir.

Yeniden denemeler ve hata yakalama

Her adım en fazla maxRetries + 1 deneme alır. Başarılı bir deneme hemen döner. Başarısız herhangi bir deneme — çözümleyiciden gelen bir Failed sonuç veya fırlatılan bir Throwable — deneme kaldığı sürece yeniden denenir; son denemenin sonucu döndürülür. Bir çözümleyici içinde fırlatılan bir Throwable, istisna mesajını taşıyan bir Failed adım sonucuna, mesaj boşsa Unknown error’a indirgenir. execute() bu nedenle her zaman bir PipelineResult döndürür; bir çözümleyici hatasını asla yaymaz.

Kayıtlı çözümleyicisi olmayan bir adım türü, açık bir mesajla bir Failed adım sonucu verir; çalıştırma iptal edilmez. stopOnError true olduğunda (varsayılan), yürütme ilk başarısız adımda durur ve pipeline durumu Failed olur. false olduğunda, yürütme devam eder ve herhangi bir adım başarısız olduysa son durum Failed, aksi hâlde Completed olur.

Pack yeteneği kapısı

Herhangi bir çözümleyici gönderiminden önce, her pack kapılı adım (Redact, Extract, OcrOverlay) enjekte edilmiş CapabilityResolverInterface’e karşı denetlenir. Kapı fail-closed’dır: eksik bir çözümleyici, false bir yanıt veya eşlenmemiş bir yetenek kodunun tümü adımı reddeder. Reddetme, hatası SPEC-LIC-001 kodunu, adım türünü ve gerekli yeteneği taşıyan bir Failed adım sonucu üretir. Kapılı bir reddetme hiçbir yeniden deneme denemesi tüketmez ve 0.0 süre bildirir. Çözümleyicinin uygulamaları yalnızca olumlu olarak tutulan bir yetki için true döndürmeli ve fırlatmamalıdır.

Sonuç toplama

PipelineResult; manifest kimliğini, genel durumu, yürütme sırasındaki adım başına sonuçları, milisaniye cinsinden toplam süreyi ve toplam, tamamlanan ve başarısız adım sayılarını bildirir. stepsTotal, devam nedeniyle atlanan veya bir durdurmadan sonra ulaşılamayan adımlar dahil manifestteki her adımı sayar; stepsCompleted ve stepsFailed yalnızca yürütülen adımları sayar.

Uç durumlar ve hata modları

• Çalıştırıcı, bir iş çalışanı içinde eşzamansız yürütme için tasarlandı. Satır içi kullanım, çağıranı tüm pipeline süresince engeller.
• Genel zaman aşımı, adımlar arası bir denetimdir. Tek bir uzun adım bütçeyi aşabilir; hiçbir adım ortasında kesintiye uğratılmaz.
• Devam etme, yalnızca aynı yürütme içindeki adımları atlar. Hiçbir depodan çıktıları geri yüklemez; önbelleğe alınmış çıktılarla çalıştırmalar arası devam etme uygulanmamıştır.
• PipelineStep’i doğrudan oluşturmak, her adım türü için çıktı türünü PDF’e varsayar. inspect ve extract adımlarının JSON çıktısı bildirmesi ve kenar doğrulamasının anlamlı kalması için oluşturucuyu kullanın veya çıktı türünü açıkça geçirin.
• Boş mesajlı bir çözümleyici istisnası, adım sonucunda Unknown error’a normalleştirilir.
• Kapı tarafından veya eksik bir çözümleyici tarafından üretilen Failed adım sonuçları 0.0 süre bildirir.
• PipelineResult::getStepResult(), hem bilinmeyen kimlikler hem de devam veya durdurma nedeniyle atlanan adımlar için null döndürür; stepsTotal ile sonuç listesi uzunluğunu karşılaştırarak ayırt edin.
• Bu modül hiçbir kriptografik işlem gerçekleştirmez ve FIPS’e özgü hiçbir davranış tanımlamaz. sign adımının FIPS duruşu, pipeline tarafından değil, imzalama modülü tarafından yönetilir.

Uygunluk

Pipeline, kendi başına hiçbir biçim uygunluğu işi yapmaz. Üretilen her yapının uygunluğu, yürüten adımın arkasındaki modüle — imzalama, optimizasyon, dönüştürme vb. — aittir ve bu modüllerin başvuru sayfalarında belgelenir. Bu sayfa hiçbir harici madde tanımlayıcısı öne sürmez; her ifade ürün kaynağına dayanır. NextPDF hiçbir sertifikasyon iddiasında bulunmaz.

Geliştirme notları

• Modül kaynağı @since 2.2.0 taşır; bu başvuru, nextpdf/pro 3.1.0 sürümünde gönderilen yüzeyi belgeler.
• Tüm sınıflar final’dır; manifest, seçenekler, adım ve sonuç türleri readonly değer nesneleridir. Değiştirmek yerine yeni örnekler oluşturun.
• StepResolverInterface ve StepResolverRegistry @internal’dır. Adım çözümleyicileri yalnızca yerleşiktir; kullanıcı tanımlı özel adım işleyicileri bu sürümde desteklenmez.
• CapabilityResolverInterface, genel yetki dikişidir. Uygulamalar atlama yoluyla reddetme ilkesine uymalı ve varsayılan olarak izin vermemelidir.
• Bu PHP çalıştırıcısı, manifest doğrulama ve ardışık yürütme yoludur; production dağıtımları paralel orkestrasyon için sidecar üzerinden gönderim yapabilir. PHP yolundaki yetenek kapısı her iki durumda da bağımsız olarak fail-closed’dır.
• Dahili mekanizma ayrıntısı, kaynak deposunun dahili belgelerinde kalır ve bu kılavuzun kapsamı dışındadır.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahili ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bkz.

• Output Pipeline — iş akışı yönlendirmesi için yetenek sayfası.
• Output Pipeline — NextPDF Enterprise Derinlemesine başvuru — manifestler arası toplu orkestrasyon.
• Document — Derinlemesine başvuru
• Accelerator — Derinlemesine başvuru