Enterprise редакция

Branding — глубокий справочник

Кратко

Эта страница — подробный справочник по модулю NextPDF\Enterprise\Branding. Модуль помечает ознакомительный вывод и оставляет платный вывод нетронутым. Разрешённый лицензией BrandingMode выбирает стратегию; BrandingApplicator применяет разрешённую стратегию к отрендеренным байтам PDF. При платной лицензии преобразование является тождественным: вывод не изменяется побайтово и не требует изменений кода. Для ознакомительного сценария сначала прочитайте страницу возможности Branding.

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

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

Подсистема несёт выделенный код возможности enterprise.branding, поскольку управляет поведением ознакомления во всех редакциях. Режим брендинга разрешается из подписанного лицензионного конверта во время выполнения; ни один флаг приложения его не выбирает. Платная лицензия разрешает режим в None и никогда не формирует брендированный вывод. Нет производственной сборки, которую нужно переключать.

Публичная поверхность API

Символ	Параметры	Поведение по умолчанию	Возвращает	Бросает или завершается с	Примечания
`BrandingMode`	—	`None` (`'none'`): без изменений	—	—	Перечисление на основе строки; `EvaluationWatermark` (`'evaluation'`) включает ознакомительный брендинг.
`BrandingStrategy`	—	Контракт, потребляемый точками интеграции	—	—	Интерфейс; вызывающий код никогда не ветвится по `BrandingMode` напрямую.
`BrandingStrategy::isActive`	—	`false` для нулевой стратегии, `true` для ознакомительной	`bool`	—	`false` означает, что все прочие методы возвращают тождественные значения.
`BrandingStrategy::buildPageWatermark`	`float $pageWidth`, `float $pageHeight` (в пунктах)	Пустая строка, если неактивна; операторы диагонального водяного знака, если активна	`string`	—	Поток предполагает наличие ресурса шрифта `/helvetica` на странице.
`BrandingStrategy::decorateProducer`	`string $producer`	Тождество, если неактивна; добавляет ознакомительный суффикс, если активна	`string`	—	Суффикс по умолчанию: `[EVALUATION]`.
`BrandingStrategy::decorateSubject`	`string $subject`	Тождество, если неактивна; добавляет ознакомительный префикс в начало, если активна	`string`	—	Пустой subject даёт обрезанный маркер.
`BrandingStrategyFactory::create`	`BrandingMode $mode`, `?EvaluationBrandingConfig $config = null`	Сопоставляет `None` с `NullBrandingStrategy`, `EvaluationWatermark` с `EvaluationBrandingStrategy`	`BrandingStrategy`	—	Статический; `null`-конфигурация использует значения по умолчанию.
`EvaluationBrandingConfig::__construct`	Шесть необязательных именованных параметров (text, suffix, prefix, size, gray, angle)	Значения по умолчанию: 48 pt, gray 0.85, 45 градусов	Экземпляр	`InvalidArgumentException` при пустом тексте, неположительном размере шрифта или уровне серого вне 0.0–1.0	`final readonly`; неизменяемый.
`EvaluationBrandingStrategy`	Необязательный `EvaluationBrandingConfig`	Наносит водяной знак и декорирование метаданных	—	—	`final readonly`; реализует `BrandingStrategy`.
`NullBrandingStrategy`	—	Тождество в каждом методе	—	—	Выбирается при платной лицензии.
`BrandingApplicator::apply`	`string $pdfBytes`, `BrandingStrategy $strategy`	Неактивная стратегия: вход возвращается побайтово; активная: добавляется одно инкрементное обновление	`string`	`BrandingApplicationException`, когда активный брендинг нельзя применить безопасно	Чистое, детерминированное байтовое преобразование.
`BrandingApplicationException`	—	Терминальный, отказоустойчивый (fail-closed) сигнал ошибки	—	—	Несёт `SPEC_CODE` (`SPEC-BRANDING-UNAPPLICABLE`); фабрика `unsupportedStructure()`.

Сигнатуры точек входа

enum BrandingMode: string
{
    case None = 'none';
    case EvaluationWatermark = 'evaluation';
}

public static function create(
    BrandingMode $mode,
    ?EvaluationBrandingConfig $config = null,
): BrandingStrategy

public function __construct(
    public string $watermarkText = 'EVALUATION COPY — Not for Production Use',
    public string $producerSuffix = ' [EVALUATION]',
    public string $subjectPrefix = '[EVALUATION] ',
    public float $watermarkFontSize = 48.0,
    public float $watermarkGray = 0.85,
    public float $watermarkAngle = 45.0,
)

public function apply(string $pdfBytes, BrandingStrategy $strategy): string

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

Разрешение режима и стратегии. Состояние лицензии — а не код приложения — выбирает BrandingMode. BrandingStrategyFactory::create сопоставляет None с NullBrandingStrategy и EvaluationWatermark с EvaluationBrandingStrategy. Точки интеграции потребляют интерфейс BrandingStrategy и никогда не проверяют режим напрямую, поэтому логика брендинга остаётся централизованной. При платной лицензии выбирается нулевая стратегия, и вывод идентичен выводу, сформированному вовсе без подсистемы брендинга.

Формирование водяного знака. buildPageWatermark выдаёт операторы потока содержимого PDF для одной страницы: изолированное графическое состояние (q/Q), шрифт Standard-14 Helvetica через имя ресурса /helvetica, режим отрисовки текста заливкой и матрицу поворота, размещающую текст по диагонали через центр страницы. Стиль по умолчанию — текст 48 pt при уровне серого 0.85, повёрнутый на 45 градусов. Центрирование приближает ширину текста по числу глифов — кластеры графем, если загружено расширение intl; кодовые точки Unicode через mbstring в противном случае; длина в байтах как последний запасной вариант. По замыслу ширины продвижения отдельных глифов не учитываются. Текст водяного знака экранируется как литеральная строка PDF согласно ISO 32000-2:2020 §7.3.4.2 (обратная косая черта и круглые скобки).

Декорирование метаданных. decorateProducer добавляет суффикс producer к значению /Producer. decorateSubject добавляет префикс subject в начало значения /Subject; пустой subject даёт обрезанный маркер, поэтому документ без метаданных subject всё равно помечается.

Применение на уровне байтов. BrandingApplicator::apply — конечный потребитель управления брендингом. С неактивной стратегией он возвращает вход побайтово. С активной стратегией он добавляет одно инкрементное обновление в форме, определённой ISO 32000-2:2020 §7.5.6: исходные байты остаются нетронутыми, а добавленное тело содержит декорированный объект Info (повторно используя существующий номер объекта), один поток содержимого водяного знака плюс один обновлённый объект страницы на каждую страницу и новый поток перекрёстных ссылок (/Type /XRef, /W [1 4 2]), чей /Prev указывает назад на предыдущий startxref. Преобразование чистое и детерминированное для заданного входа и конфигурации.

Отказоустойчивый (fail-closed) контракт. Когда стратегия активна, вход должен быть пригоден для брендинга: заголовок %PDF-, отсутствие записи /Encrypt, отсутствие потоков объектов (/ObjStm), хвост в виде потока перекрёстных ссылок и ресурс шрифта /helvetica, разрешимый с каждой страницы. Любое нарушение вызывает BrandingApplicationException вместо возврата небрендированных байтов. Вызывающий код должен считать исключение терминальным и не должен фиксировать исходные, непомеченные байты.

Граничные случаи и режимы отказа

Брендированный вывод означает, что состояние лицензии относится к ознакомительному типу. Это отражает состояние лицензии, а не дефект.
Водяной знак центрирован и диагонален по замыслу. Он не настраивается для продакшена; платная лицензия убирает его полностью.
EvaluationBrandingConfig отклоняет пустой текст водяного знака, неположительный размер шрифта и уровень серого вне 0.0–1.0 с InvalidArgumentException.
Активная стратегия, не производящая изменений Producer, Subject или водяного знака, отклоняется с BrandingApplicationException, вместо того чтобы выдавать байты, выглядящие как платные.
Страница без пригодного /MediaBox (отсутствующего или унаследованного) получает водяной знак при значении по умолчанию ISO 216 A4 — 595.276 × 841.890 пункта.
Поддерживаются обе формы /Contents — одиночная ссылка и массив; ссылка на водяной знак добавляется последней, чтобы он рисовался поверх. Странице без /Contents она добавляется.
Строковые значения Info сохраняются в исходном представлении при обратном преобразовании: шестнадцатеричные строки (UTF-16BE) остаются шестнадцатеричными, литеральные строки остаются литеральными. Отсутствующий ключ добавляется, кодируясь в шестнадцатеричном виде, если значение содержит символы вне ASCII.
Зашифрованные документы отклоняются: переписывание строковых объектов под /Encrypt потребовало бы ключа шифрования документа.
Ошибки несут стабильный код SPEC-BRANDING-UNAPPLICABLE (BrandingApplicationException::SPEC_CODE), поэтому потребляющие конвейеры могут отправлять в dead-letter и аудировать непригодный для брендинга вывод.
Модуль не выполняет криптографических операций. Проверка подписи лицензионного конверта относится к подсистеме лицензирования; см. подробный справочник по лицензированию.

Соответствие

Утверждение	Стандарт	Пункт
Инкрементные обновления добавляют изменения в конец файла и оставляют исходное содержимое нетронутым.	ISO 32000-2	§7.5.6
Секция перекрёстных ссылок обновления охватывает только изменённые объекты, а добавленный trailer несёт запись `Prev`, указывающую на предыдущую секцию перекрёстных ссылок.	ISO 32000-2	§7.5.6
Литеральные строки записываются в круглых скобках; несбалансированные скобки и обратная косая черта требуют экранирования.	ISO 32000-2	§7.3.4.2

Все пункты изложены в пересказе; NextPDF не воспроизводит нормативный текст. NextPDF не делает заявлений о сертификации. Аппликатор записывает инкрементные обновления в форме, указанной в ISO 32000-2, как заявление о возможности; это не сертифицированный и не прошедший независимую проверку писатель. Эта страница описывает только поведение во время выполнения. Она не даёт никаких гарантий, не делает заявлений о праве на использование или юридической силе и не является юридической консультацией; условия ознакомления или подписки определяются исключительно лицензионным соглашением.

Заметки для разработчиков

BrandingMode, BrandingStrategy, обе стратегии и конфигурация несут @since 3.0.0; BrandingApplicator и BrandingApplicationException несут @since 3.1.0.
Подсистема не делает сетевых вызовов. Аппликатор читает только те структурные поля, которые переписывает: строки словаря Info, словари страниц и хвост перекрёстных ссылок.
Лицензионный конверт — это подписанный артефакт, подпись эмитента которого проверяет среда выполнения. Подготовка, продление и безопасное хранение лицензии — обязанность оператора.
Все конкретные типы — final; стратегии и конфигурация также readonly. Чтобы изменить стиль водяного знака, создайте новый экземпляр конфигурации.
Возврат false из BrandingStrategy::isActive() гарантирует тождественные значения от всех прочих методов; вызывающий код может замыкаться на этом ради производительности.
Поток водяного знака ссылается на имя ресурса /helvetica. Core регистрирует этот ресурс для собственного брендинга; интеграция, отключающая брендинг Core, должна обеспечить наличие этого ресурса.
Аппликатор не вычисляет дайджест; вызывающий код повторно вычисляет дайджест брендированных байтов перед их фиксацией.
Детали внутреннего механизма остаются во внутренней документации исходного репозитория и выходят за рамки данного руководства.

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

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

См. также

Branding — страница возможности подсистемы ознакомительного брендинга.
Пробный режим и ознакомительный брендинг — полный сценарий ознакомления.
Лицензирование — подробный справочник
Обзор Enterprise