Брендирование

Кратко

Подсистема брендирования применяет видимое оценочное брендирование к создаваемым PDF во время оценки и не применяет ничего при платной лицензии. Она поставляется в пакете nextpdf/enterprise, управляет оценочным поведением во всех редакциях и полностью управляется лицензией — а не кодом приложения. Полный сценарий оценки см. в Пробный период и оценочное брендирование; эта страница документирует саму подсистему брендирования.

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

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

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

Установка

composer require nextpdf/enterprise:^3

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

У среды выполнения есть режим брендирования с двумя состояниями, моделируемый BrandingMode:

• None — нет оценочного брендирования. Платный и обычный вывод никогда не изменяется. Это значение по умолчанию.
• EvaluationWatermark — к создаваемым PDF применяется видимое оценочное брендирование.

BrandingStrategyFactory сопоставляет режим со стратегией: NullBrandingStrategy для None (она не выполняет работы и не вносит изменений) и EvaluationBrandingStrategy для EvaluationWatermark. Режим выбирает состояние лицензии — а не код приложения. Платная лицензия никогда не создаёт брендированный вывод, и нет ни продакшн-сборки для переключения, ни флага в коде для изменения.

Эта страница описывает только поведение во время выполнения. Она не даёт никакой гарантии и не делает заявления о праве на участие или юридическом эффекте; условия, применимые к вашей оценке или подписке, определяются исключительно вашим лицензионным соглашением.

Программный интерфейс

Понятие	Поведение
BrandingMode	Два состояния: None (по умолчанию, без изменений) или EvaluationWatermark.
BrandingStrategyFactory	Разрешает BrandingMode в стратегию.
EvaluationBrandingStrategy	Применяет оценочный водяной знак и декорирование метаданных.
NullBrandingStrategy	Стратегия-заглушка для платного / обычного вывода.
EvaluationBrandingConfig	Неизменяемые текст водяного знака, декорирование метаданных, размер шрифта, уровень серого и угол.
BrandingStrategy	Контракт, который использует слой интеграции: isActive(), buildPageWatermark(), decorateProducer(), decorateSubject().
BrandingApplicator	Применяет разрешённую стратегию к отрисованным байтам PDF; отказоустойчиво в закрытом состоянии — выбрасывает BrandingApplicationException, когда активное брендирование не может быть нанесено.

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

Пример кода — Быстрый старт

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

resolve-strategy.php

<?php

declare(strict_types=1);

use NextPDF\Enterprise\Branding\BrandingMode;
use NextPDF\Enterprise\Branding\BrandingStrategyFactory;

// The license resolves the mode; None is what a paid license produces.
$strategy = BrandingStrategyFactory::create(BrandingMode::None);

\var_dump($strategy->isActive());                 // bool(false)
echo $strategy->decorateProducer('NextPDF 3.1');  // NextPDF 3.1 (unchanged)

Пример кода — Продакшн

Нанесите маркеры на уже отрисованные байты PDF с помощью стратегии, разрешённой лицензией. BrandingApplicator::apply() возвращает вход без изменений для платной лицензии и, для оценочной лицензии, добавляет водяной знак и маркеры метаданных, оставляя исходные байты нетронутыми. Он выбрасывает BrandingApplicationException, когда активное брендирование не может быть безопасно применено, — считайте это терминальным и никогда не сохраняйте байты без маркеров.

apply-evaluation-branding.php

<?php

declare(strict_types=1);

use NextPDF\Enterprise\Branding\BrandingApplicationException;
use NextPDF\Enterprise\Branding\BrandingApplicator;
use NextPDF\Enterprise\Branding\BrandingMode;
use NextPDF\Enterprise\Branding\BrandingStrategyFactory;
use NextPDF\Enterprise\Branding\EvaluationBrandingConfig;

/**
 * Apply the branding the license resolved to freshly rendered PDF bytes.
 *
 * @param string       $renderedPdf Bytes from the render engine.
 * @param BrandingMode $mode        Resolved from the signed license envelope.
 *
 * @throws BrandingApplicationException When active branding cannot be marked.
 */
function markEvaluationOutput(string $renderedPdf, BrandingMode $mode): string
{
    $strategy = BrandingStrategyFactory::create(
        $mode,
        new EvaluationBrandingConfig(
            watermarkText: 'EVALUATION COPY — Not for Production Use',
        ),
    );

    try {
        return (new BrandingApplicator())->apply($renderedPdf, $strategy);
    } catch (BrandingApplicationException $e) {
        // Fail-closed: never emit unbranded evaluation output. Dead-letter.
        throw $e;
    }
}

Что делает оценочное брендирование

Когда активная лицензия выбирает EvaluationWatermark, оценочная стратегия:

• рисует светло-серый диагональный текст водяного знака на каждой странице, отрисовываемый как поток содержимого страницы в изолированном графическом состоянии, поэтому он не изменяет окружающее содержимое или вашу вёрстку;
• добавляет оценочный суффикс к метаданным производителя документа;
• добавляет оценочный префикс к метаданным темы документа.

Водяной знак использует шрифт Base14 и матрицу поворота, чтобы разместить текст по диагонали через центр страницы. Объект конфигурации неизменяем и проверяет свои входные данные (например, текст водяного знака не может быть пустым, а размер шрифта должен быть положительным).

Как платная лицензия удаляет брендирование

При платной (неоценочной) лицензии режим брендирования — None, и выбирается стратегия-заглушка: нет водяного знака, нет суффикса производителя, нет префикса темы. Вывод идентичен выводу, созданному вообще без подсистемы брендирования. Удаление оценочного брендирования не требует изменения кода — установите платную лицензию, и следующий созданный документ будет без брендирования.

Граничные случаи и подводные камни

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

Производительность

Водяной знак — это небольшой фиксированный поток содержимого на страницу с пренебрежимо малым влиянием на время генерации или размер документа. При платной лицензии подсистема не выполняет работы. Бюджет производительности страницы отражает отрисовку документации.

Примечания по безопасности

Оценочное брендирование — это маркер видимости, а не средство контроля безопасности. Оно указывает на оценочный вывод. Это не цифровая подпись, и на него нельзя полагаться как на таковую. Для вывода с защитой от подделки используйте возможности подписания, описанные в матрице возможностей. Лицензия, выбирающая режим брендирования, — это подписанный конверт, подпись издателя которого среда выполнения проверяет.

Резидентность данных и меры по защите PII

Подсистема брендирования добавляет фиксированный водяной знак и маркеры метаданных; она не читает и не передаёт содержимое документа и не делает сетевых вызовов.

Безопасная телеметрия и очистка журналов

Подсистема не логирует содержимое документа. Переходы состояния лицензии, изменяющие режим брендирования, отражаются подсистемой лицензирования, а не здесь.

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

Для этой страницы не заявляется никакого соответствия стандартам. Она описывает только поведение во время выполнения. Она не заявляет и не подразумевает никакой гарантии, сертификации или права на участие. Условия вашей оценки или подписки определяются исключительно вашим лицензионным соглашением.

Поведение в режиме FIPS

Этот модуль не выполняет криптографических операций. Проверка подписи лицензии обрабатывается подсистемой лицензирования.

Модель угроз

Сама подсистема брендирования не обрабатывает внешнего ввода сверх разрешённого режима брендирования. Конверт лицензии, выбирающий режим, подписан, и его подпись издателя проверяется средой выполнения; подмена режима потребовала бы подделки этой подписи.

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

• У BrandingMode два состояния: None (по умолчанию; без изменения вывода) и EvaluationWatermark.
• При платной (неоценочной) лицензии режим — None, и выбирается стратегия-заглушка: вывод идентичен выводу, созданному вообще без подсистемы брендирования.
• При оценочной лицензии стратегия рисует диагональный водяной знак в изолированном графическом состоянии и добавляет оценочные маркеры к метаданным производителя и темы.
• Объект конфигурации неизменяем и проверяет свои входные данные (текст водяного знака непустой, размер шрифта положительный).

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

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

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

Подсистема брендирования поставляется в пакете nextpdf/enterprise, но управляет оценочным поведением во всех редакциях, включая развёртывания только с Core и Pro, использующие оценочную лицензию. Нет отдельной подсистемы брендирования только для Core, к которой можно было бы откатиться; платная лицензия в любой редакции разрешается в BrandingMode::None.

Резервный вариант Pro

Нет отдельной подсистемы брендирования Pro. Та же подсистема брендирования nextpdf/enterprise управляет оценочным поведением для развёртываний Pro; платная лицензия Pro разрешается в BrandingMode::None точно так же, как платная лицензия Enterprise.

Примечание о границе Enterprise

Детали внутреннего механизма остаются во внутренней документации исходного репозитория и находятся вне области этого руководства.

Граница развёртывания

Конверт лицензии, выбирающий режим брендирования, — это подписанный артефакт, подпись издателя которого среда выполнения проверяет; подготовка, продление и безопасное хранение лицензии — это ответственность оператора. Подсистема не делает сетевых вызовов и не читает содержимое документа.

Граница юридического соответствия

Эта страница описывает только поведение во время выполнения. Она не заявляет и не подразумевает никакой гарантии, сертификации или права на участие и не является юридической консультацией. Условия вашей оценки или подписки — включая то, какое брендирование применяется и как долго, — определяются исключительно вашим лицензионным соглашением. Обращайтесь к этому соглашению или в отдел продаж.

См. также

• Брендирование — подробный справочник — публичный API и контракт поведения этой подсистемы.
• Пробный период и оценочное брендирование — полный сценарий оценки.
• Активация лицензии
• Обзор Enterprise
• Матрица возможностей Core, Pro и Enterprise