Marca

De un vistazo

El subsistema de marca aplica una marca de evaluación visible a los PDF generados durante una evaluación y no aplica nada bajo una licencia de pago. Se distribuye en el paquete nextpdf/enterprise, gobierna el comportamiento de evaluación en todas las ediciones y está gobernado por completo por la licencia — no por el código de la aplicación. Para el relato de evaluación de extremo a extremo, consulte Prueba y marca de evaluación; esta página documenta el subsistema de marca en sí.

Disponibilidad y licenciamiento

Esta capacidad se distribuye en NextPDF Enterprise (nextpdf/enterprise) y se activa con un sobre de licencia de nivel Enterprise. Una implementación sin ese derecho no carga las clases de la capacidad. Compare ediciones y obtenga una licencia.

A diferencia de la mayoría de las superficies de Enterprise, lleva un código de capacidad dedicado, enterprise.branding, porque gobierna el comportamiento de evaluación en todas las ediciones —incluidas las implementaciones solo con Core y solo con Pro—. El modo de marca se resuelve a partir del sobre de licencia firmado en tiempo de ejecución; ningún indicador de la aplicación lo selecciona, y una licencia de pago en cualquier edición se resuelve en BrandingMode::None.

Instalación

composer require nextpdf/enterprise:^3

Descripción conceptual

El tiempo de ejecución tiene un modo de marca con dos estados, modelado por BrandingMode:

• None — sin marca de evaluación. La salida de pago y normal nunca se modifica. Este es el valor predeterminado.
• EvaluationWatermark — se aplica una marca de evaluación visible a los PDF generados.

BrandingStrategyFactory asigna el modo a una estrategia: NullBrandingStrategy para None (no realiza ningún trabajo y no produce ninguna modificación) y EvaluationBrandingStrategy para EvaluationWatermark. El estado de la licencia —no el código de la aplicación— selecciona el modo. Una licencia de pago nunca produce salida con marca, y no hay ninguna compilación de producción que cambiar ni ningún indicador de código que activar.

Esta página describe únicamente el comportamiento en tiempo de ejecución. No ofrece ninguna garantía ni declaración sobre elegibilidad o efecto legal; los términos que se aplican a su evaluación o suscripción están definidos únicamente por su acuerdo de licencia.

Superficie de la API

Concepto	Comportamiento
BrandingMode	Dos estados: None (predeterminado, sin modificación) o EvaluationWatermark.
BrandingStrategyFactory	Resuelve un BrandingMode a una estrategia.
EvaluationBrandingStrategy	Aplica la marca de agua de evaluación y la decoración de metadatos.
NullBrandingStrategy	Estrategia sin operación para la salida de pago / normal.
EvaluationBrandingConfig	Texto de marca de agua, decoración de metadatos, tamaño de fuente, nivel de gris y ángulo inmutables.
BrandingStrategy	Contrato que consume la capa de integración: isActive(), buildPageWatermark(), decorateProducer(), decorateSubject().
BrandingApplicator	Aplica una estrategia resuelta a los bytes de PDF representados; a prueba de fallos — lanza BrandingApplicationException cuando no se puede marcar la marca activa.

El subsistema expone una pequeña superficie invocable para la capa de integración que aplica la estrategia que resolvió la licencia; el código de la aplicación nunca elige si aplicar la marca. Los ejemplos siguientes muestran los dos puntos de contacto: leer una estrategia resuelta y marcar los bytes representados con el aplicador a prueba de fallos.

Ejemplo de código — Inicio rápido

Resuelva la estrategia que seleccionó la licencia y lea su comportamiento. Una licencia de pago se resuelve en BrandingMode::None, cuya estrategia está inactiva y deja pasar todos los valores sin cambios.

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)

Ejemplo de código — Producción

Marque los bytes de PDF ya representados con la estrategia que resolvió la licencia. BrandingApplicator::apply() devuelve la entrada sin cambios para una licencia de pago y, para una licencia de evaluación, añade la marca de agua y los marcadores de metadatos dejando intactos los bytes originales. Lanza BrandingApplicationException cuando no se puede aplicar de forma segura la marca activa — trátelo como terminal y nunca confirme los bytes sin marcar.

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;
    }
}

Qué hace la marca de evaluación

Cuando la licencia activa selecciona EvaluationWatermark, la estrategia de evaluación:

• dibuja un texto de marca de agua diagonal en gris claro en cada página, representado como un flujo de contenido de página en un estado gráfico aislado, de modo que no altera el contenido circundante ni su maquetación;
• añade un sufijo de evaluación a los metadatos de productor del documento;
• antepone un prefijo de evaluación a los metadatos de asunto del documento.

La marca de agua utiliza una fuente Base14 y una matriz de rotación para posicionar el texto en diagonal a través del centro de la página. El objeto de configuración es inmutable y valida sus entradas (por ejemplo, el texto de la marca de agua no puede estar vacío y el tamaño de fuente debe ser positivo).

Cómo una licencia de pago elimina la marca

Bajo una licencia de pago (no de evaluación), el modo de marca es None y se selecciona la estrategia nula: sin marca de agua, sin sufijo de productor, sin prefijo de asunto. La salida es idéntica a la salida producida sin ningún subsistema de marca en absoluto. Eliminar la marca de evaluación no requiere ningún cambio de código — instale una licencia de pago y el siguiente documento generado no llevará marca.

Casos límite y trampas

• La marca aparece cuando el estado de la licencia es de tipo evaluación. Esto refleja el estado de la licencia, no un defecto; compruebe el estado de la licencia y renuévela a través del portal de licencias.
• La marca de agua está centrada y es diagonal por diseño para que la salida de evaluación sea inequívoca; no está pensada para ajustarse para producción. Una licencia de pago la elimina por completo.
• Los metadatos de productor y de asunto transportan marcadores de evaluación durante una evaluación y están ausentes bajo una licencia de pago.

Rendimiento

La marca de agua es un flujo de contenido por página pequeño y fijo, con un impacto insignificante en el tiempo de generación o el tamaño del documento. Bajo una licencia de pago, el subsistema no realiza ningún trabajo. El presupuesto de rendimiento de la página refleja la representación de la documentación.

Notas de seguridad

La marca de evaluación es un marcador de visibilidad, no un control de seguridad. Indica una salida de evaluación. No es una firma digital y no se debe confiar en ella como tal. Para una salida con evidencia de manipulación, utilice las capacidades de firma descritas en la matriz de funciones. La licencia que selecciona el modo de marca es un sobre firmado cuya firma del emisor verifica el tiempo de ejecución.

Residencia de datos y mitigaciones de PII

El subsistema de marca añade una marca de agua fija y marcadores de metadatos; no lee ni transmite contenido del documento y no realiza llamadas de red.

Telemetría segura y depuración de registros

El subsistema no registra el contenido del documento. Las transiciones de estado de la licencia que cambian el modo de marca se exponen a través del subsistema de licenciamiento, no aquí.

Conformidad

No se reclama ninguna conformidad con estándares para esta página. Describe únicamente el comportamiento en tiempo de ejecución. No declara ni implica ninguna garantía, certificación ni elegibilidad. Los términos de su evaluación o suscripción están definidos únicamente por su acuerdo de licencia.

Comportamiento en modo FIPS

Este módulo no realiza operaciones criptográficas. La verificación de la firma de la licencia la gestiona el subsistema de licenciamiento.

Modelo de amenazas

El subsistema de marca en sí no procesa ninguna entrada externa más allá del modo de marca resuelto. El sobre de la licencia que selecciona el modo está firmado y su firma de emisor la verifica el tiempo de ejecución; suplantar el modo requeriría falsificar esa firma.

Contrato de comportamiento

• BrandingMode tiene dos estados: None (predeterminado; sin modificación de la salida) y EvaluationWatermark.
• Bajo una licencia de pago (no de evaluación), el modo es None y se selecciona la estrategia nula: la salida es idéntica a la salida producida sin ningún subsistema de marca en absoluto.
• Bajo una licencia de evaluación, la estrategia dibuja una marca de agua diagonal en un estado gráfico aislado y añade marcadores de evaluación a los metadatos de productor y de asunto.
• El objeto de configuración es inmutable y valida sus entradas (texto de marca de agua no vacío, tamaño de fuente positivo).

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie de API pública admitida. Las rutas internas de espacio de nombres, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de tickets quedan fuera del alcance.

Alternativa de Core

El subsistema de marca se distribuye en el paquete nextpdf/enterprise, pero gobierna el comportamiento de evaluación en todas las ediciones, incluidas las implementaciones solo con Core y solo con Pro que utilizan una licencia de evaluación. No hay ningún subsistema de marca solo de Core al que recurrir; una licencia de pago en cualquier edición se resuelve en BrandingMode::None.

Alternativa de Pro

No hay ningún subsistema de marca de Pro independiente. El mismo subsistema de marca de nextpdf/enterprise gobierna el comportamiento de evaluación para las implementaciones de Pro; una licencia de pago de Pro se resuelve en BrandingMode::None exactamente igual que una licencia de pago de Enterprise.

Nota sobre el límite de Enterprise

El detalle de los mecanismos internos permanece en la documentación interna del repositorio de origen y queda fuera del alcance de este manual.

Límite de despliegue

El sobre de la licencia que selecciona el modo de marca es un artefacto firmado cuya firma de emisor verifica el tiempo de ejecución; el aprovisionamiento de la licencia, su renovación y el almacenamiento seguro de la licencia son responsabilidad del operador. El subsistema no realiza llamadas de red ni lee contenido del documento.

Límite de cumplimiento legal

Esta página describe únicamente el comportamiento en tiempo de ejecución. No declara ni implica ninguna garantía, certificación ni elegibilidad, y no constituye asesoramiento legal. Los términos de su evaluación o suscripción —incluido qué marca se aplica y durante cuánto tiempo— están definidos únicamente por su acuerdo de licencia. Consulte ese acuerdo o contacte con ventas.

Consulte también

• Marca — Referencia detallada — API pública y contrato de comportamiento de este subsistema.
• Prueba y marca de evaluación — el relato de evaluación de extremo a extremo.
• Activación de licencia
• Visión general de Enterprise
• Matriz de funciones: núcleo frente a Pro frente a Enterprise