Output Pipeline — szczegółowa dokumentacja referencyjna

W skrócie

Ta strona jest szczegółową dokumentacją referencyjną publicznej powierzchni NextPDF\Pro\OutputPipeline. Obejmuje budowę i walidację manifestu, topologiczny porządek wykonania, semantykę ponawiania i limitu czasu, zachowanie wznawiania oraz bramkę możliwości Pack działającą w trybie fail-closed. Podaje parametry, wartości domyślne i tryby awarii każdego publicznego symbolu. Najpierw zapoznaj się ze stroną możliwości Output Pipeline, aby uzyskać wskazówki dotyczące przepływu pracy.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się przy użyciu koperty licencyjnej poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Executor i siedem z dziesięciu typów kroków nie mają flagi dla poszczególnych funkcji. Trzy typy kroków wymagają dodatkowo możliwości Pack:

Typ kroku	Wartość w manifeście	Wymagana możliwość	Pack
Redagowanie	redact	pack.privacy.redact	Privacy Pack
Ekstrakcja	extract	pack.intelligence.extract	Intelligence Pack
Nakładka OCR	ocr_overlay	pack.intelligence.searchable_pdf	Intelligence Pack

Bramka jest egzekwowana w czasie wykonania, w trybie fail-closed, zanim krok dotrze do swojego resolvera. Bramkowany krok bez licencji daje wynik kroku ze statusem Failed, niosący kod SPEC-LIC-001 oraz wymaganą możliwość; resolver nie jest nigdy wywoływany. Potok bez wstrzykniętego resolvera możliwości odrzuca każdy bramkowany krok.

Powierzchnia publicznego API

composer require nextpdf/pro:^3

Metapakiet nextpdf/premium instaluje kod nextpdf/pro; ten moduł znajduje się w przestrzeni nazw NextPDF\Pro\OutputPipeline.

Symbol	Parametry	Domyślne zachowanie	Zwraca	Zgłasza lub kończy niepowodzeniem z	Uwagi
PipelineExecutor::__construct	StepResolverRegistry $registry, ?CapabilityResolverInterface $capabilityResolver = null	Wiąże wbudowany rejestr resolverów oraz opcjonalne źródło uprawnień	PipelineExecutor	Nic nie zadeklarowano	Resolver możliwości równy null odrzuca każdy krok bramkowany przez Pack
PipelineExecutor::execute	PipelineManifest $manifest, array $variables = []	Uruchamia kroki w porządku topologicznym i agreguje wyniki	PipelineResult	Nic nie zadeklarowano; niepowodzenia resolvera są przechwytywane jako wyniki kroków ze statusem Failed	Zaprojektowany do działania wewnątrz asynchronicznego workera zadań
PipelineManifest::__construct	string $id, array $steps, PipelineOptions $options = new PipelineOptions(), ?string $resumeFromStepId = null	Waliduje graf kroków podczas konstrukcji	PipelineManifest	InvalidArgumentException przy pustej liście kroków, zduplikowanych identyfikatorach kroków, nieznanych zależnościach, cyklach, niezgodności typu wyjścia lub brakującym kroku wznawiania; OverflowException powyżej 10 000 kroków	Cała walidacja kończy się przed jakimkolwiek wykonaniem
PipelineManifest::topologicalOrder	brak	Porządkuje kroki tak, aby zależności były przed elementami zależnymi	list<PipelineStep>	Nic nie zadeklarowano	Deterministyczny dla danego manifestu
PipelineManifest::getStep	string $stepId	Liniowe wyszukiwanie według identyfikatora kroku	?PipelineStep	Nic nie zadeklarowano	null dla nieznanego identyfikatora
PipelineManifest::rootSteps	brak	Zwraca kroki bez zależności	list<PipelineStep>	Nic nie zadeklarowano	Kroki główne (root) uruchamiają się pierwsze
PipelineManifestBuilder::create	string $manifestId	Rozpoczyna nowy builder	self	Nic nie zadeklarowano	Konstruktor jest prywatny; to jedyne wejście
PipelineManifestBuilder::addStep	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], ?StepOutputType $outputType = null	Dodaje krok; typ wyjścia równy null jest wywnioskowany z typu kroku	self	Nic nie zadeklarowano	Walidacja jest odroczona do build()
PipelineManifestBuilder::stopOnError	bool $stop = true	Ustawia zatrzymanie przy pierwszym niepowodzeniu	self	Nic nie zadeklarowano	Domyślnie true
PipelineManifestBuilder::maxRetries	int $retries	Ustawia górny limit ponawiania dla pojedynczego kroku	self	Nic nie zadeklarowano	Domyślnie 0 (bez ponawiania)
PipelineManifestBuilder::timeout	int $timeoutMs	Ustawia globalny limit czasu potoku	self	Nic nie zadeklarowano	0 wyłącza limit czasu
PipelineManifestBuilder::resumeFrom	string $stepId	Ustawia punkt wznawiania	self	Nic nie zadeklarowano	Krok musi istnieć w chwili build()
PipelineManifestBuilder::build	brak	Konstruuje zwalidowany manifest	PipelineManifest	Jak PipelineManifest::__construct	—
PipelineOptions::__construct	bool $stopOnError = true, int $maxRetries = 0, int $timeoutMs = 0	Niezmienne opcje wykonania	PipelineOptions	Nic nie zadeklarowano	Obiekt wartości readonly
PipelineStep::__construct	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], StepOutputType $outputType = StepOutputType::Pdf	Niezmienna definicja kroku	PipelineStep	Nic nie zadeklarowano	Bezpośrednia konstrukcja domyślnie ustawia typ wyjścia na PDF dla każdego typu
PipelineStep::isRoot	brak	True, gdy krok nie ma zależności	bool	Nic nie zadeklarowano	—
PipelineStepType (enum)	—	Dziesięć przypadków opartych na łańcuchach znaków: generate, merge, split, inspect, compress, sign, convert oraz bramkowane redact, extract, ocr_overlay	—	—	Jeden przypadek na każdą wbudowaną operację
PipelineStepType::requiresPack	brak	True dla Redact, Extract oraz OcrOverlay	bool	Nic nie zadeklarowano	Wszystkie pozostałe przypadki zwracają false
PipelineStepType::requiredCapability	brak	Mapuje bramkowane przypadki na ich kody możliwości	?string	Nic nie zadeklarowano	null dla przypadków niebramkowanych
PipelineStatus (enum)	—	Pięć przypadków: pending, running, completed, failed, cancelled	—	—	Współdzielone przez wyniki potoku i kroków
PipelineStatus::isTerminal	brak	True dla Completed, Failed oraz Cancelled	bool	Nic nie zadeklarowano	Pending i Running nie są terminalne
StepOutputType (enum)	—	Trzy przypadki: pdf, json, metadata	—	—	Napędza walidację krawędzi w czasie budowania
StepOutputType::forStepType	PipelineStepType $stepType	Domyślny typ wyjścia dla danego typu kroku	self	Nic nie zadeklarowano	Inspect i Extract mapują się na JSON; wszystkie pozostałe typy mapują się na PDF
StepOutputType::isCompatibleWith	self $expectedInput	True przy zgodności tego samego typu lub wyjściu PDF	bool	Nic nie zadeklarowano	Pomocnik; PDF jest uniwersalnym wejściem
PipelineContext::__construct	string $manifestId, array $variables = [], ?string $resumeFromStepId = null	Kontekst w pamięci dla pojedynczego przebiegu	PipelineContext	Nic nie zadeklarowano	Brak TTL, wygasania, trwałości lub magazynu zapasowego
PipelineContext::setStepResult / ::getStepResult	string $stepId (+ StepResult przy zapisie)	Zapisuje lub odczytuje wynik kroku	void / ?StepResult	Nic nie zadeklarowano	null dla kroku jeszcze niewykonanego
PipelineContext::setStepOutput / ::getStepOutput	string $stepId (+ mixed przy zapisie)	Zapisuje lub odczytuje wyjście pośrednie	void / mixed	Nic nie zadeklarowano	null dla brakującego wyjścia
PipelineContext::hasStepResult	string $stepId	Czy krok już się wykonał	bool	Nic nie zadeklarowano	Wspiera sprawdzanie wznawiania
PipelineContext::allStepResults	brak	Wszystkie wyniki zapisane dotychczas	array<string, StepResult>	Nic nie zadeklarowano	Kluczowane według identyfikatora kroku
PipelineContext::isResume	brak	Czy przebieg wznawia się od kroku	bool	Nic nie zadeklarowano	—
PipelineResult::isSuccess	brak	True tylko dla ogólnego statusu Completed	bool	Nic nie zadeklarowano	Wynik jest wytwarzany przez executor
PipelineResult::getStepResult	string $stepId	Znajduje jeden wynik kroku według identyfikatora	?StepResult	Nic nie zadeklarowano	null dla kroków pominiętych lub nieznanych
PipelineResult::failedSteps	brak	Filtruje wyniki kroków ze statusem niepowodzenia	list<StepResult>	Nic nie zadeklarowano	Pusta lista przy pełnym powodzeniu
StepResult::isSuccess	brak	True tylko dla statusu kroku Completed	bool	Nic nie zadeklarowano	Niesie stepId, type, status, durationMs, error, output
CapabilityResolverInterface::hasCapability	string $capability	Twierdzący test uprawnienia dla jednego kodu możliwości	bool	Nie może zgłaszać wyjątku	Odmowa przez pominięcie (deny-by-omission): false dla nieznanych, wygasłych lub niezmapowanych kodów

Sygnatury punktów wejścia

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

Kontrakt zachowania

Walidacja manifestu

Walidacja przebiega w konstruktorze PipelineManifest, przed jakimkolwiek wykonaniem. W kolejności: lista kroków musi być niepusta; liczba kroków jest ograniczona do 10 000, co zamienia wrogo głębokie łańcuchy zależności w przechwytywalny OverflowException zamiast natywnego wyczerpania stosu; identyfikatory kroków muszą być unikalne; każde odwołanie dependsOn musi się rozwiązać; graf zależności musi być acykliczny; typy wyjścia muszą być zgodne; zadeklarowany krok wznawiania musi istnieć. Każde naruszenie zgłasza InvalidArgumentException z konkretnym komunikatem.

Kontrola typu wyjścia dotyczy kroków, których typ mapuje się na wyjście PDF: każda zależność takiego kroku musi sama produkować wyjście PDF. Krawędzie zależności prowadzące do typów kroków produkujących JSON (inspect, extract) nie są sprawdzane pod kątem typu w tej wersji.

Porządek wykonania, wznawianie i limit czasu

execute($manifest, $variables) buduje nowy PipelineContext, oblicza porządek topologiczny i uruchamia kroki sekwencyjnie w tym porządku. Gdy ustawiony jest punkt wznawiania, wcześniejsze kroki są pomijane, aż osiągnięty zostanie nazwany krok. Pominięci poprzednicy nie są wykonywani ponownie, a ich wyjścia nie są przywracane: kontekst dotyczy pojedynczego przebiegu i jest w pamięci, więc wznowiony krok odczytujący wyjście pominiętego poprzednika obserwuje null.

Globalny limit czasu, gdy jest dodatni, jest oceniany między krokami, przed startem każdego kroku. Po jego upływie status potoku staje się Failed, a pozostałe kroki się nie rozpoczynają. Już wykonywany krok nigdy nie jest przerywany w trakcie wykonania, więc jeden długi krok może przekroczyć budżet.

Ponawiania i przechwytywanie niepowodzeń

Każdy krok otrzymuje najwyżej maxRetries + 1 prób. Udana próba zwraca natychmiast. Każda nieudana próba — wynik Failed z resolvera lub zgłoszony Throwable — jest ponawiana, dopóki pozostają próby; zwracany jest wynik ostatniej próby. Throwable zgłoszony wewnątrz resolvera jest degradowany do wyniku kroku ze statusem Failed niosącego komunikat wyjątku lub Unknown error, gdy komunikat jest pusty. execute() zawsze zatem zwraca PipelineResult; nigdy nie propaguje niepowodzenia resolvera.

Typ kroku bez zarejestrowanego resolvera daje wynik kroku ze statusem Failed wraz z jawnym komunikatem; przebieg nie jest przerywany. Przy stopOnError równym true (domyślnie) wykonanie zatrzymuje się na pierwszym nieudanym kroku, a status potoku to Failed. Przy false wykonanie jest kontynuowane, a końcowy status to Failed, jeśli którykolwiek krok się nie powiódł, w przeciwnym razie Completed.

Bramka możliwości Pack

Przed jakimkolwiek wywołaniem resolvera każdy krok bramkowany przez Pack (Redact, Extract, OcrOverlay) jest sprawdzany względem wstrzykniętego CapabilityResolverInterface. Bramka działa w trybie fail-closed: brakujący resolver, odpowiedź false lub niezmapowany kod możliwości — wszystkie odrzucają krok. Odrzucenie wytwarza wynik kroku ze statusem Failed, którego błąd niesie kod SPEC-LIC-001, typ kroku oraz wymaganą możliwość. Bramkowe odrzucenie nie zużywa żadnych prób ponawiania i raportuje czas trwania równy 0.0. Implementacje resolvera muszą zwracać true tylko dla twierdząco posiadanego uprawnienia i nie mogą zgłaszać wyjątku.

Agregacja wyników

PipelineResult raportuje identyfikator manifestu, status ogólny, wyniki poszczególnych kroków w porządku wykonania, całkowity czas trwania w milisekundach oraz liczby kroków: całkowitą, ukończonych i nieudanych. stepsTotal liczy każdy krok w manifeście, w tym kroki pominięte przez wznawianie lub nieosiągnięte po zatrzymaniu; stepsCompleted i stepsFailed liczą wyłącznie kroki wykonane.

Przypadki brzegowe i tryby awarii

• Executor jest zaprojektowany do asynchronicznego wykonywania wewnątrz workera zadań. Użycie inline blokuje wywołującego na cały czas trwania potoku.
• Globalny limit czasu to sprawdzenie między krokami. Pojedynczy długi krok może przekroczyć budżet; żaden krok nie jest przerywany w trakcie.
• Wznawianie pomija kroki wyłącznie w obrębie tego samego wykonania. Nie przywraca wyjść z żadnego magazynu; wznawianie międzyprzebiegowe z buforowanymi wyjściami nie jest zaimplementowane.
• Bezpośrednia konstrukcja PipelineStep domyślnie ustawia typ wyjścia na PDF dla każdego typu kroku. Użyj buildera lub przekaż typ wyjścia jawnie, aby kroki inspect i extract deklarowały wyjście JSON, a walidacja krawędzi pozostała znacząca.
• Wyjątek resolvera z pustym komunikatem jest normalizowany do Unknown error w wyniku kroku.
• Wyniki kroków ze statusem Failed wytworzone przez bramkę lub przez brakujący resolver raportują czas trwania równy 0.0.
• PipelineResult::getStepResult() zwraca null zarówno dla nieznanych identyfikatorów, jak i dla kroków pominiętych przez wznawianie lub zatrzymanie; rozróżnij za pomocą stepsTotal względem długości listy wyników.
• Ten moduł nie wykonuje żadnych operacji kryptograficznych i nie definiuje zachowania specyficznego dla FIPS. Postawa FIPS dla kroku sign jest rządzona przez moduł podpisywania, a nie przez potok.

Zgodność ze standardami

Potok nie wykonuje żadnej własnej pracy zgodności formatu. Zgodność każdego wytworzonego artefaktu należy do modułu stojącego za wykonywanym krokiem — podpisywania, optymalizacji, konwersji i tak dalej — i jest udokumentowana na stronach referencyjnych tych modułów. Ta strona nie formułuje żadnych zewnętrznych identyfikatorów klauzul; każde stwierdzenie jest oparte na źródle produktu. NextPDF nie formułuje żadnego roszczenia certyfikacyjnego.

Uwagi deweloperskie

• Źródło modułu niesie @since 2.2.0; ta dokumentacja opisuje powierzchnię w postaci dostarczonej w nextpdf/pro 3.1.0.
• Wszystkie klasy są final; typy manifestu, opcji, kroku i wyniku to obiekty wartości readonly. Konstruuj nowe instancje zamiast mutować.
• StepResolverInterface i StepResolverRegistry są @internal. Resolvery kroków są wyłącznie wbudowane; niestandardowe procedury obsługi kroków definiowane przez użytkownika nie są wspierane w tej wersji.
• CapabilityResolverInterface to publiczny szew uprawnień. Implementacje muszą stosować odmowę przez pominięcie (deny-by-omission) i nie mogą domyślnie zezwalać.
• Ten executor PHP to ścieżka walidacji manifestu i sekwencyjnego wykonania; wdrożenia produkcyjne mogą kierować pracę przez sidecar w celu równoległej orkiestracji. Bramka możliwości na ścieżce PHP jest niezależnie fail-closed w obu przypadkach.
• Szczegóły wewnętrznego mechanizmu pozostają w wewnętrznej dokumentacji repozytorium źródłowego i są poza zakresem tego podręcznika.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie oraz wspieraną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.

Zobacz także

• Output Pipeline — strona możliwości ze wskazówkami dotyczącymi przepływu pracy.
• Output Pipeline — szczegółowa dokumentacja referencyjna NextPDF Enterprise — wsadowa orkiestracja wielu manifestów.
• Document — szczegółowa dokumentacja referencyjna
• Accelerator — szczegółowa dokumentacja referencyjna