Enterprise edycja

Output Pipeline — szczegółowa referencja

W skrócie

NextPDF\Enterprise\OutputPipeline wykonuje wiele manifestów potoku Pro jako jeden wsad. BatchPipelineOrchestrator opakowuje PipelineExecutor Pro koordynacją wsadu: zabezpieczeniem ograniczającym zasoby dla rozmiaru wsadu, opcjonalnym globalnym limitem czasu wsadu, wstrzykiwaniem zmiennych dla poszczególnych manifestów oraz zbiorczym rozliczaniem. Opcjonalna kontrola zgodności na końcu wsadu ponownie waliduje każdy ukończony wynik przez bramę zgodności Enterprise i kończy się niepowodzeniem w sposób bezpieczny (fail closed). Każdy przebieg zwraca BatchPipelineResult niosący wyniki dla poszczególnych manifestów, liczby ukończonych i nieudanych, pomiar czasu oraz opcjonalny raport zgodności.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się wraz z kopertą licencyjną poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Poziom	Powierzchnia output-pipeline
Core	Brak powierzchni output-pipeline.
Pro	Potok pojedynczego manifestu (możliwość `pro.output.pipeline`).
Enterprise	Orkiestracja wsadowa, ograniczenie rozmiaru wsadu, limit czasu wsadu, przekazanie do zgodności.

Wsadowa powierzchnia Enterprise nie niesie osobnego kodu możliwości dla poszczególnych funkcji; bramkuje ją granica pakietu. Możliwość Pro dla pojedynczego manifestu pro.output.pipeline jest warunkiem wstępnym, a nie bramą. Sama licencja Pro odblokowuje wyłącznie bazowy potok pojedynczego manifestu, a nie tę powierzchnię wsadową.

composer require nextpdf/enterprise:^3

Powierzchnia publicznego API

Symbol	Parametry	Domyślne zachowanie	Zwraca	Zgłasza lub kończy się niepowodzeniem	Uwagi
`BatchPipelineOrchestrator::__construct()`	`PipelineExecutor $executor`, `BatchPipelineConfig $config`, `?ComplianceGateway $complianceGateway`, `ComplianceProfile $complianceProfile`	Domyślna konfiguracja; brak bramy; profil `ComplianceProfile::PdfA4`	—	Nic	Wstrzyknij bramę, gdy kontrola zgodności jest włączona; bez niej każdy sprawdzany manifest jest zgłaszany jako nieudany.
`BatchPipelineOrchestrator::executeBatch()`	`list<PipelineManifest> $manifests`, `array<string, array<string, mixed>> $variablesMap = []`	Wykonuje manifesty w kolejności zgłoszenia; zmienne są rozwiązywane po ID manifestu	`BatchPipelineResult`	`OverflowException`, gdy wsad przekracza 10,000 manifestów; wyjątki bramy, gdy kontrola zgodności jest włączona (zob. Przypadki brzegowe)	Wyjątki `Throwable` z resolvera nigdy nie wydostają się na zewnątrz; egzekutor Pro degraduje je do nieudanych wyników kroków.
`BatchPipelineConfig::__construct()`	`int $maxConcurrency = 4`, `int $timeoutMs = 0`, `bool $complianceCheckOnComplete = false`	Współbieżność 4; brak limitu czasu; brak kontroli zgodności	—	Nic	Obiekt wartości readonly. `timeoutMs = 0` wyłącza limit czasu wsadu.
`BatchPipelineResult::__construct()`	`list<PipelineResult> $results`, `int $totalManifests`, `int $completedCount`, `int $failedCount`, `float $durationMs`, `?array $complianceReport = null`	Agregat po wartościach `PipelineResult` dla poszczególnych manifestów	—	Nic	Readonly. `complianceReport` pozostaje `null`, o ile kontrola nie została uruchomiona.
`BatchPipelineResult::allSucceeded()`	—	Sprawdza `failedCount === 0`	`bool`	Nic	Zwraca true dla wsadu obciętego limitem czasu z zerową liczbą niepowodzeń; zob. Przypadki brzegowe.
`BatchPipelineResult::successRate()`	—	`completedCount / totalManifests`	`float`	Nic	Zwraca `1.0` dla pustego wsadu.
`BatchPipelineResult::hasComplianceReport()`	—	Sprawdza `complianceReport !== null`	`bool`	Nic	—

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

Kontrakt zachowania

executeBatch() najpierw weryfikuje rozmiar wsadu względem limitu 10,000 manifestów. Wsad powyżej limitu zgłasza OverflowException przed wykonaniem jakiegokolwiek manifestu; nic nie ulega obniżeniu po cichu.

Manifesty są następnie wykonywane w kolejności zgłoszenia przez PipelineExecutor Pro. Każdy manifest otrzymuje wpis zmiennych zakluczowany jego ID w $variablesMap; manifest bez wpisu otrzymuje pustą mapę zmiennych. Manifest liczy się jako ukończony, gdy status jego PipelineResult to Completed; każdy inny status końcowy liczy się jako nieudany. Wyjątki resolvera nie wydostają się na zewnątrz: egzekutor Pro konwertuje każdy Throwable resolvera na nieudany wynik kroku, więc executeBatch() zawsze agreguje wyniki, zamiast przerywać wsad w połowie z powodu błędu kroku.

Gdy timeoutMs jest większy od zera, czas, który upłynął, jest sprawdzany przed rozpoczęciem każdego manifestu. Po wyczerpaniu budżetu pozostałe manifesty są pomijane: nie wytwarzają PipelineResult i nie liczą się ani jako ukończone, ani jako nieudane. totalManifests zawsze raportuje liczbę zgłoszonych.

Gdy complianceCheckOnComplete jest włączone, orkiestrator waliduje finalny PDF każdego ukończonego manifestu względem skonfigurowanego ComplianceProfile przez wstrzyknięty ComplianceGateway. Kontrola kończy się niepowodzeniem w sposób bezpieczny (fail closed):

Brak wstrzykniętej bramy: każdy sprawdzany manifest jest zgłaszany jako nieudany, ponieważ zgodność nigdy nie została zwalidowana.
Brak wyjścia PDF dającego się wyznaczyć z wyjść kroków manifestu: niepowodzenie.
Brama nie zwraca wyniku (niedostępność sidecara w trybie opcjonalnym): niepowodzenie. Brak pozytywnego wyniku nie jest zaliczeniem.
Brama zgłasza jakąkolwiek niezgodność: niepowodzenie.

Finalny PDF jest wyznaczany przez skanowanie wyjść kroków ukończonego manifestu, od ostatniego kroku, w poszukiwaniu bezpośredniej wartości typu string zaczynającej się od nagłówka %PDF. Wyjścia kroków nigdy nie zagnieżdżają ciągów bajtów PDF wewnątrz pod-tablic; sprawdzane są wyłącznie bezpośrednie wartości wyjściowe. Manifesty, które się nie ukończyły, są pomijane, a nie sprawdzane.

Raport zgodności to tablica z kluczami profile, checked, passed, failed oraz failures; każdy wpis niepowodzenia niesie manifestId oraz reason. Raport dołącza się do BatchPipelineResult::$complianceReport i jest osiągalny przez hasComplianceReport().

Przekazanie do zgodności jest pomocą w ponownej walidacji, a nie mechanizmem autoryzacji. Zgłasza wyłącznie ustalenia.

Przypadki brzegowe i tryby awarii

Więcej niż 10,000 manifestów: OverflowException przed rozpoczęciem jakiegokolwiek wykonania.
timeoutMs = 0 oznacza brak limitu czasu wsadu. W produkcji ustaw wartość skończoną.
Obcięcie limitem czasu: pominięte manifesty nie pojawiają się w żadnej liczbie, więc completedCount + failedCount może być mniejsze niż totalManifests. allSucceeded() sprawdza wyłącznie failedCount === 0 i może zwrócić true dla obciętego wsadu. Porównaj count($result->results) z totalManifests, aby wykryć obcięcie.
successRate() zwraca 1.0 dla pustego wsadu (zgłoszono zero manifestów).
ID manifestów nie są deduplikowane na poziomie wsadu. Dwa manifesty współdzielące ID oba się wykonują i rozwiązują ten sam wpis zmiennych.
Strukturalne błędy manifestu (pusta lista kroków, zduplikowane ID kroków, nieznana zależność, cykl zależności, niezgodność typów wyjścia, brakujący krok wznowienia) zgłaszają InvalidArgumentException podczas konstrukcji manifestu, zanim executeBatch() zostanie w ogóle wywołane.
Przy włączonej kontroli zgodności ComplianceGateway::validate() może zgłosić ComplianceSidecarUnavailableException (sidecar niedostępny w trybie wymaganym) lub InvalidArgumentException (brak zarejestrowanego walidatora dla narzędzia profilu). Każdy z tych wyjątków wydostaje się z executeBatch() po wykonaniu, ale przed zbudowaniem wyniku, więc wyniki dla poszczególnych manifestów są tracone dla wywołującego. W trybie opcjonalnym brama zwraca zamiast tego null, a manifest jest odnotowywany jako niepowodzenie zgodności.
Krok przekazania do zgodności wewnątrz potoku kończy się niepowodzeniem, gdy żadne wyjście kroku wyższego w łańcuchu nie zawiera rozpoznawalnych bajtów PDF; nigdy nie przechodzi po cichu.
Ten moduł nie wykonuje żadnych operacji kryptograficznych; tryb FIPS nie ma zastosowania.

Zgodność

Dla tego modułu nie deklaruje się żadnej zgodności ze standardami; jest to warstwa orkiestracji. Opcjonalna kontrola zgodności deleguje zadanie do bramy zgodności Enterprise oraz jej zewnętrznych walidatorów, które niosą własne odniesienia. Domyślny profil to ComplianceProfile::PdfA4; inne profile bramy obejmują dalsze cele PDF/A, PDF/UA oraz PAdES.

Raport zgodności podaje ustalenia walidatora względem wybranego profilu. Nie certyfikuje dokumentu, nie gwarantuje wystarczalności regulacyjnej ani nie stanowi porady prawnej. Ocena, czy dany wynik spełnia twoje obowiązki, należy do ciebie.

Uwagi dla programistów

We wdrożeniach produkcyjnych równoległe rozdzielanie pracy między procesy robocze oraz przeciwciśnienie obsługuje osobny komponent wykonawczy typu sidecar. Orkiestrator PHP dostarcza logikę koordynacji wsadu oraz przekazania do zgodności i jest wywoływany przez proces roboczy zadania, a nie bezpośrednio przez moduły obsługi żądań.
Zapasowa ścieżka PHP wykonuje manifesty sekwencyjnie. maxConcurrency ogranicza liczbę współbieżnych wywołań zwrotnych roboczych we wdrożeniu opartym na sidecarze; dobór jego rozmiaru względem puli procesów roboczych PHP należy do obowiązków operatora.
Resolver kroku przekazania do zgodności wewnątrz potoku to typ wewnętrzny zarejestrowany dla kroków typu inspect. Włącz walidację na końcu wsadu przez BatchPipelineConfig, zamiast konstruować dla niej kroki potoku bezpośrednio.
Konstruuj instancje PipelineManifest wcześnie. Ich walidacja strukturalna działa w konstruktorze, więc nieprawidłowe grafy zawodzą szybko i nigdy nie zużywają budżetu wsadu.

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.