Pro редакция

Конвейер вывода

Краткий обзор

Output Pipeline выполняет декларативный манифест шагов PDF в порядке зависимостей, с повторами для каждого шага и опцией остановки при ошибке. Некоторые типы шагов требуют дополнительной возможности Enterprise Pack.

Доступность и лицензирование

Эта возможность входит в состав NextPDF Pro (nextpdf/pro) и активируется лицензионным конвертом уровня Pro. Развёртывание без такого права не загружает классы этой возможности. Сравнить редакции и получить лицензию.

Сам исполнитель конвейера входит в редакцию Pro. Три типа шагов дополнительно требуют именованной возможности Enterprise Pack: шаг редактирования требует возможности Privacy Pack, а шаги извлечения и наложения OCR требуют возможностей Intelligence Pack. Нелицензированный ограниченный шаг при исполнении отказывает в закрытое состояние — он даёт результат неудавшегося шага, а его резолвер никогда не вызывается — вместо прерывания всего прогона.

Установка

composer require nextpdf/pro:^3

Код находится в пространстве имён NextPDF\Pro\OutputPipeline.

Концептуальный обзор

PipelineExecutor принимает PipelineManifest, сортирует шаги в топологический порядок и направляет каждый шаг к резолверу, зарегистрированному в StepResolverRegistry. Выходные данные шагов хранятся в PipelineContext для последующих шагов. Исполнитель применяет глобальный тайм-аут, поддерживает повторы для каждого шага и может возобновляться с именованного шага. Он рассчитан на работу внутри асинхронного обработчика заданий, а не напрямую из обработчика запросов.

Встроенные типы шагов включают generate, merge, split, inspect, compress, sign и convert. Типы шагов редактирования, извлечения и наложения OCR лицензируются по возможностям и отображаются на возможности Enterprise Pack.

Почему это работает именно так

Исполнитель занимается только оркестрацией. Он сортирует шаги, применяет лицензионный шлюз и направляет каждый шаг к зарегистрированному резолверу, но сам не выполняет работу с PDF. Такое разделение позволяет одному манифесту выполняться либо через этот последовательный путь на PHP, либо через внешний обработчик, который направляет шаги параллельно, без изменения вызывающего кода. Дизайн ориентирован на асинхронный обработчик заданий, а не на обработчик запросов, потому что многошаговый конвейер обычно живёт дольше бюджета запроса, а очередь масштабирует пропускную способность добавлением обработчиков. Глобальный тайм-аут по той же причине проверяется между шагами: целый шаг — это единица работы, переданная резолверу, и оркестратор не вмешивается в прогон этого резолвера. Сбои проявляются как значения StepResult по каждому шагу, а не как выброшенные исключения, поэтому один неудавшийся шаг никогда не обрушивает агрегированный PipelineResult, о котором сообщает обработчик.

Предпосылки дизайна: Массовая генерация документов.

Контракт поведения

execute($manifest, $variables) возвращает результат с общим статусом, результатами по каждому шагу, длительностью и числом завершённых и неудавшихся шагов.
Шаги выполняются в топологическом порядке; отсутствующий резолвер для типа шага даёт неудавшийся шаг с понятным сообщением.
PipelineOptions::$stopOnError останавливает исполнение при первом сбое; иначе исполнение продолжается, и итоговый статус отражает любые сбои.
Глобальный тайм-аут, когда задан, приводит конвейер к сбою, если он превышен до начала следующего шага.
Повторы для каждого шага ограничены настроенным максимумом; повторяются только нетерминальные сбои.
Возобновление с шага пропускает более ранние шаги до достижения именованного шага.
Ограниченные по возможностям типы шагов при исполнении отказывают в закрытое состояние с кодом лицензионной ошибки, когда требуемой возможности 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 добавляет возможности Pack, которые разблокируют ограниченные типы шагов (редактирование, извлечение, наложение OCR) на уровне поведения. Без этих Pack конвейер по-прежнему выполняет каждый неограниченный шаг. Внутреннее устройство Pack здесь вне области рассмотрения.

Резервный вариант / альтернатива в Core

Без Pro оркеструйте операции с PDF императивно с помощью API NextPDF Core; декларативный манифест, упорядочивание по зависимостям и повторы — дополнения Pro. См..

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую публичную поверхность API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов вне области рассмотрения.