Marca — Referencia detallada

De un vistazo

Esta página es la referencia detallada del módulo NextPDF\Enterprise\Branding. El módulo marca la salida de evaluación y deja intacta la salida de pago. Un BrandingMode resuelto por la licencia selecciona una estrategia; BrandingApplicator aplica la estrategia resuelta a los bytes del PDF renderizado. Con una licencia de pago, la transformación es la identidad: la salida no cambia byte a byte, sin necesidad de ningún cambio de código. Para el flujo de trabajo de evaluación, lea primero la página de capacidad de marca.

Disponibilidad y licencias

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

El subsistema lleva el código de capacidad dedicado enterprise.branding porque gobierna el comportamiento de evaluación en todas las ediciones. 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. Una licencia de pago resuelve el modo a None y nunca produce salida marcada. No hay ninguna compilación de producción que cambiar.

Superficie de la API pública

Símbolo	Parámetros	Comportamiento por defecto	Devuelve	Lanza o falla con	Notas
BrandingMode	—	None ('none'): sin modificación	—	—	Enum respaldado por cadena; EvaluationWatermark ('evaluation') activa la marca de evaluación.
BrandingStrategy	—	Contrato consumido por los puntos de integración	—	—	Interfaz; quienes la invocan nunca bifurcan directamente sobre BrandingMode.
BrandingStrategy::isActive	—	false para la estrategia nula, true para la estrategia de evaluación	bool	—	false significa que todos los demás métodos devuelven valores de identidad.
BrandingStrategy::buildPageWatermark	float $pageWidth, float $pageHeight (puntos)	Cadena vacía cuando está inactiva; operadores de marca de agua diagonal cuando está activa	string	—	El flujo asume un recurso de fuente /helvetica en la página.
BrandingStrategy::decorateProducer	string $producer	Identidad cuando está inactiva; añade el sufijo de evaluación cuando está activa	string	—	Sufijo por defecto: [EVALUATION].
BrandingStrategy::decorateSubject	string $subject	Identidad cuando está inactiva; antepone el prefijo de evaluación cuando está activa	string	—	Un asunto vacío produce el marcador recortado.
BrandingStrategyFactory::create	BrandingMode $mode, ?EvaluationBrandingConfig $config = null	Asigna None a NullBrandingStrategy, EvaluationWatermark a EvaluationBrandingStrategy	BrandingStrategy	—	Estático; una configuración null usa los valores por defecto.
EvaluationBrandingConfig::__construct	Seis parámetros con nombre opcionales (texto, sufijo, prefijo, tamaño, gris, ángulo)	Valores por defecto: 48 pt, gris 0.85, 45 grados	Instancia	InvalidArgumentException con texto vacío, tamaño de fuente no positivo o gris fuera de 0.0–1.0	final readonly; inmutable.
EvaluationBrandingStrategy	EvaluationBrandingConfig opcional	Aplica marca de agua y decoración de metadatos	—	—	final readonly; implementa BrandingStrategy.
NullBrandingStrategy	—	Identidad en cada método	—	—	Seleccionada con una licencia de pago.
BrandingApplicator::apply	string $pdfBytes, BrandingStrategy $strategy	Estrategia inactiva: la entrada se devuelve byte a byte; activa: se añade una actualización incremental	string	BrandingApplicationException cuando la marca activa no puede aplicarse de forma segura	Transformación de bytes pura y determinista.
BrandingApplicationException	—	Señal de fallo terminal, fail-closed	—	—	Lleva SPEC_CODE (SPEC-BRANDING-UNAPPLICABLE); fábrica unsupportedStructure().

Firmas del punto de entrada

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

Contrato de comportamiento

Resolución de modo y estrategia. El estado de la licencia —no el código de la aplicación— selecciona el BrandingMode. BrandingStrategyFactory::create asigna None a NullBrandingStrategy y EvaluationWatermark a EvaluationBrandingStrategy. Los puntos de integración consumen la interfaz BrandingStrategy y nunca inspeccionan el modo directamente, de modo que la lógica de marca permanece centralizada. Con una licencia de pago se selecciona la estrategia nula y la salida es idéntica a la salida producida sin ningún subsistema de marca en absoluto.

Generación de la marca de agua. buildPageWatermark emite operadores de flujo de contenido PDF para una página: un estado gráfico aislado (q/Q), la fuente estándar-14 Helvetica mediante el nombre de recurso /helvetica, el modo de renderizado de texto de relleno, y una matriz de rotación que coloca el texto diagonalmente a través del centro de la página. El estilo por defecto es texto de 48 pt con nivel de gris 0.85, rotado 45 grados. El centrado aproxima el ancho del texto por el número de glifos: clústeres de grafemas cuando intl está cargado, puntos de código Unicode mediante mbstring en caso contrario, y la longitud en bytes como recurso final. Por diseño no se consultan anchos de avance por glifo. El texto de la marca de agua se escapa como una cadena literal PDF según ISO 32000-2:2020 §7.3.4.2 (barra invertida y paréntesis).

Decoración de metadatos. decorateProducer añade el sufijo de productor al valor /Producer. decorateSubject antepone el prefijo de asunto al valor /Subject; un asunto vacío produce el marcador recortado, de modo que un documento sin metadatos de asunto igualmente queda marcado.

Aplicación de bytes. BrandingApplicator::apply es el consumidor terminal del control de marca. Con una estrategia inactiva devuelve la entrada byte a byte. Con una estrategia activa añade una única actualización incremental con la forma definida por ISO 32000-2:2020 §7.5.6: los bytes originales permanecen intactos, y el cuerpo añadido contiene un objeto Info decorado (reutilizando el número de objeto existente), un flujo de contenido de marca de agua más un objeto de página actualizado por página, y un nuevo flujo de referencias cruzadas (/Type /XRef, /W [1 4 2]) cuyo /Prev apunta al startxref anterior. La transformación es pura y determinista para una entrada y configuración dadas.

Contrato fail-closed. Cuando la estrategia está activa, la entrada debe ser marcable: una cabecera %PDF-, ninguna entrada /Encrypt, ningún flujo de objetos (/ObjStm), una cola de flujo de referencias cruzadas, y un recurso de fuente /helvetica resoluble desde cada página. Cualquier violación lanza BrandingApplicationException en lugar de devolver bytes sin marcar. Quienes la invocan deben tratar la excepción como terminal y no deben confirmar los bytes originales sin marcar.

Casos límite y modos de fallo

• Una salida marcada significa que el estado de la licencia es de tipo evaluación. Eso refleja el estado de la licencia, no un defecto.
• La marca de agua es centrada y diagonal por diseño. No es ajustable para uso en producción; una licencia de pago la elimina por completo.
• EvaluationBrandingConfig rechaza el texto de marca de agua vacío, un tamaño de fuente no positivo y un nivel de gris fuera de 0.0–1.0 con InvalidArgumentException.
• Una estrategia activa que no produzca ningún cambio de Producer, Subject o marca de agua se rechaza con BrandingApplicationException en lugar de emitir bytes que parezcan de pago.
• Una página sin un /MediaBox utilizable (ausente o heredado) se marca con el valor por defecto ISO 216 A4 de 595.276 × 841.890 puntos.
• Se admiten /Contents tanto en forma de referencia única como de arreglo; la referencia de la marca de agua se añade al final para que se dibuje encima. Una página sin /Contents recibe uno.
• Los valores de cadena de Info conservan su representación original: las cadenas hexadecimales (UTF-16BE) siguen siendo hexadecimales, las cadenas literales siguen siendo literales. Una clave ausente se añade, codificada en hexadecimal cuando el valor contiene caracteres no ASCII.
• Los documentos cifrados se rechazan: reescribir objetos de cadena bajo /Encrypt requeriría la clave de cifrado del documento.
• Los fallos llevan el código estable SPEC-BRANDING-UNAPPLICABLE (BrandingApplicationException::SPEC_CODE) para que las canalizaciones consumidoras puedan enviar a cola de mensajes fallidos y auditar la salida no marcable.
• El módulo no realiza operaciones criptográficas. La verificación de la firma del sobre de licencia pertenece al subsistema de licencias; véase la referencia detallada de Licencias.

Conformidad

Afirmación	Estándar	Cláusula
Las actualizaciones incrementales añaden los cambios al final del archivo y dejan intacto el contenido original.	ISO 32000-2	§7.5.6
La sección de referencias cruzadas de la actualización cubre solo los objetos cambiados, y el tráiler añadido lleva una entrada Prev que localiza la sección de referencias cruzadas anterior.	ISO 32000-2	§7.5.6
Las cadenas literales se escriben entre paréntesis; los paréntesis no balanceados y la barra invertida requieren tratamiento de escape.	ISO 32000-2	§7.3.4.2

Todas las cláusulas están parafraseadas; NextPDF no reproduce texto normativo. NextPDF no formula ninguna afirmación de certificación. El aplicador escribe actualizaciones incrementales con la forma ISO 32000-2 citada como declaración de capacidad; no es un escritor certificado ni validado de forma independiente. Esta página describe únicamente el comportamiento en tiempo de ejecución. No ofrece ninguna garantía, ninguna declaración sobre elegibilidad o efecto legal, y no constituye asesoramiento legal; los términos de una evaluación o suscripción se definen únicamente por el acuerdo de licencia.

Notas de desarrollo

• BrandingMode, BrandingStrategy, ambas estrategias y la configuración llevan @since 3.0.0; BrandingApplicator y BrandingApplicationException llevan @since 3.1.0.
• El subsistema no realiza llamadas de red. El aplicador lee solo los campos estructurales que reescribe: las cadenas del diccionario Info, los diccionarios de página y la cola de referencias cruzadas.
• El sobre de licencia es un artefacto firmado cuya firma del emisor verifica el tiempo de ejecución. El aprovisionamiento, la renovación y el almacenamiento seguro de la licencia son responsabilidad del operador.
• Todos los tipos concretos son final; las estrategias y la configuración también son readonly. Construya una nueva instancia de configuración para cambiar el estilo de la marca de agua.
• Que BrandingStrategy::isActive() devuelva false garantiza valores de identidad en todos los demás métodos; quienes lo invocan pueden cortocircuitar sobre ello por rendimiento.
• El flujo de la marca de agua referencia el nombre de recurso /helvetica. Core registra este recurso para su propia marca; una integración que desactive la marca de Core debe garantizar que el recurso exista.
• El aplicador no calcula ningún resumen; quien lo invoca vuelve a calcular el resumen de los bytes marcados antes de confirmarlos.
• Los detalles internos del mecanismo permanecen en la documentación interna del repositorio de código fuente y quedan fuera del alcance de este manual.

Límite de publicación

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

Véase también

• Marca — página de capacidad del subsistema de marca de evaluación.
• Prueba y marca de evaluación — la historia de evaluación de extremo a extremo.
• Licencias — Referencia detallada
• Descripción general de Enterprise