Pro 에디션

출력 파이프라인

한눈에 보기

출력 파이프라인은 PDF 단계의 선언적 매니페스트를 의존성 순서로 실행하며, 단계별 재시도와 오류 시 중지 옵션을 제공합니다. 일부 단계 유형은 추가 Enterprise Pack 기능을 요구합니다.

가용성 및 라이선스

이 기능은 NextPDF Pro(nextpdf/pro)로 제공되며 Pro 티어 라이선스 엔벨로프로 활성화됩니다. 해당 권한이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션 비교 및 라이선스 받기.

파이프라인 실행기 자체는 Pro 에디션의 일부입니다. 세 가지 단계 유형은 추가로 명명된 Enterprise Pack 기능을 요구합니다. 수정(redaction) 단계는 Privacy Pack 기능을 요구하고, 추출 및 OCR 오버레이 단계는 Intelligence Pack 기능을 요구합니다. 라이선스가 없는 게이트된 단계는 실행 시점에 실패-차단됩니다 — 전체 실행을 중단하는 대신 실패한 단계 결과를 산출하고 해당 리졸버는 결코 호출되지 않습니다.

설치

composer require nextpdf/pro:^3

코드는 NextPDF\Pro\OutputPipeline 네임스페이스 아래에 있습니다.

개념 개요

PipelineExecutor는 PipelineManifest를 받아 단계를 위상 순서로 정렬하고, 각 단계를 StepResolverRegistry에 등록된 리졸버로 디스패치합니다. 단계 출력은 하위 단계를 위해 PipelineContext에 저장됩니다. 실행기는 전역 타임아웃을 적용하고, 단계별 재시도를 지원하며, 명명된 단계에서 재개할 수 있습니다. 이는 요청 핸들러에서 직접 실행하는 것이 아니라 비동기 작업 워커 내부에서 실행되도록 설계되었습니다.

내장 단계 유형에는 generate, merge, split, inspect, compress, sign, convert가 포함됩니다. 수정(redaction), 추출, OCR 오버레이 단계 유형은 기능 라이선스가 필요하며 Enterprise Pack 기능에 매핑됩니다.

이렇게 동작하는 이유

실행기는 오케스트레이션만 담당합니다. 단계를 정렬하고, 라이선스 게이트를 적용하며, 각 단계를 등록된 리졸버로 디스패치하지만 PDF 작업 자체는 전혀 수행하지 않습니다. 이 분리 덕분에 하나의 매니페스트가 이 순차적 PHP 경로를 통하거나, 단계를 병렬로 디스패치하는 대역 외 워커를 통하거나, 호출 코드 변경 없이 실행될 수 있습니다. 이 설계는 요청 핸들러가 아닌 비동기 작업 워커를 대상으로 하는데, 다단계 파이프라인은 흔히 요청 예산보다 오래 지속되며 큐는 워커를 추가해 처리량을 확장하기 때문입니다. 전역 타임아웃이 단계 사이에서 검사되는 것도 같은 이유입니다. 하나의 단계 전체가 리졸버에 넘겨지는 작업 단위이며, 오케스트레이터는 그 리졸버의 실행에 관여하지 않습니다. 실패는 던져진 예외가 아니라 단계별 StepResult 값으로 표면화되므로, 실패한 한 단계가 워커가 보고하는 집계 PipelineResult를 결코 무너뜨리지 않습니다.

설계 배경: 대용량 문서 생성.

동작 계약

execute($manifest, $variables)는 전체 상태, 단계별 결과, 소요 시간, 그리고 완료 및 실패한 단계 수를 담은 결과를 반환합니다.
단계는 위상 순서로 실행됩니다. 단계 유형에 대한 리졸버가 누락되면 명확한 메시지와 함께 실패한 단계가 됩니다.
PipelineOptions::$stopOnError는 첫 실패 시 실행을 중지합니다. 그렇지 않으면 실행이 계속되며 최종 상태가 모든 실패를 반영합니다.
설정된 전역 타임아웃은 다음 단계가 시작되기 전에 초과되면 파이프라인을 실패시킵니다.
단계별 재시도는 구성된 최댓값으로 제한됩니다. 비종단(non-terminal) 실패만 재시도됩니다.
단계에서 재개는 명명된 단계에 도달할 때까지 이전 단계를 건너뜁니다.
기능 게이트된 단계 유형은 필요한 Pack 기능이 없을 때 실행 시점에 라이선스 오류 코드와 함께 실패-차단됩니다. 해당 리졸버는 결코 호출되지 않습니다.

코드 샘플 — 빠른 시작

다음은 문서화된 공개 API를 반영합니다. 리포지터리는 이 모듈에 대한 실행 가능한 예제를 제공하지 않습니다.

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

$result = (new PipelineExecutor($stepResolverRegistry))->execute($manifest);

코드 샘플 — 프로덕션

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

$executor = new PipelineExecutor($stepResolverRegistry);

// Invoke from an async job worker, not a request handler.
$result = $executor->execute($manifest, ['customerName' => 'Acme']);

if ($result->status !== \NextPDF\Pro\OutputPipeline\PipelineStatus::Completed) {
    foreach ($result->stepResults as $stepResult) {
        // Inspect per-step error detail.
    }
}

엣지 케이스 및 함정

파이프라인은 작업 시스템을 통해 비동기적으로 실행되도록 의도되었습니다. 인라인으로 실행하면 파이프라인 전체 기간 동안 호출자를 차단합니다.
등록된 리졸버가 없는 단계 유형은 전체 파이프라인을 중단하는 대신 해당 단계를 실패시킵니다(오류 시 중지가 설정되지 않은 경우).
전역 타임아웃은 단계 중간이 아니라 단계 사이에서 검사됩니다. 오래 실행되는 단계는 검사가 발생하기 전에 예산을 초과할 수 있습니다.

성능

총 소요 시간은 단계 소요 시간의 합에 재시도 오버헤드를 더한 것입니다. 전역 타임아웃이 최악의 경우 경과 시간을 제한합니다. 발행된 처리량 수치는 없습니다. 파이프라인 비용은 포함하는 단계가 좌우합니다. 대표적인 매니페스트로 측정하십시오.

보안 참고

실행기는 입력 문서와 변수를 단계 리졸버에 전달합니다. 이를 신뢰할 수 없는 것으로 취급하고 각 리졸버 내에서 검증하십시오. 기능 게이트된 단계는 라이선스가 없을 때 실패-차단됩니다. 실행기는 문서 콘텐츠를 로깅하지 않습니다.

적합성

실행기 자체는 형식 적합성 작업을 수행하지 않습니다. 적합성은 개별 단계 리졸버(generate, merge, split, sign, convert)에 달려 있습니다. 작성 시점에 RAG 코퍼스를 사용할 수 없었으므로, 이 페이지는 외부 조항 식별자를 주장하지 않습니다.

Enterprise 경계 참고

Enterprise는 게이트된 단계 유형(수정(redaction), 추출, OCR 오버레이)을 동작 수준에서 잠금 해제하는 Pack 기능을 추가합니다. 그러한 Pack이 없어도 파이프라인은 게이트되지 않은 모든 단계를 여전히 실행합니다. Pack 내부는 여기에서 범위 밖입니다.

Core 폴백 / 대안

Pro 없이는 NextPDF Core API로 PDF 작업을 명령형으로 오케스트레이션하십시오. 선언적 매니페스트, 의존성 순서 지정, 재시도는 Pro 추가 기능입니다.를 참조하십시오.

발행 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일명, 티켓 접두사는 범위 밖입니다.