Referencia de enumeraciones

De un vistazo

Varios métodos de creación de NextPDF reciben un enum tipado en lugar de una cadena o un entero a secas. La enumeración es el contrato: restringe el argumento a un conjunto fijo y válido, y tanto el IDE como PHPStan rechazan cualquier valor fuera de él. Esta página es la consulta de valores permitidos para las enumeraciones que se establecen (o se reciben) a través de la API pública de Document y de Config —más una enumeración de color de nivel de motor (RenderingIntent), incluida porque sus casos forman parte del contrato público de color y señalada como de nivel de motor allí donde aparece.

Es el complemento de la referencia de configuración. Donde el objeto Config indica qué control girar, esta página indica qué valores acepta ese control. Cada entrada enumera el nombre de clase totalmente cualificado (FQCN) de la enumeración, su tipo de respaldo, la lista exacta de casos copiada del código fuente y el método público que la recibe.

Las enumeraciones internas profundas del motor (la maquetación de HTML/CSS, el árbol de sintaxis abstracta, la CLI, las interioridades del shaper) se excluyen deliberadamente: nunca se establecen. Casi todo lo que sigue es un valor que se pasa a través de la API pública; la única excepción, RenderingIntent, es una enumeración de color de nivel de motor sin setter público, listada por exhaustividad y etiquetada como tal allí donde aparece.

Tipos de respaldo

Las enumeraciones de PHP vienen en dos formas, y la forma cambia cómo se escribe el valor:

Una enumeración respaldada (enum X: string o enum X: int) tiene un value escalar para cada caso, de modo que va y vuelve mediante X::from('...') / $case->value. La mayoría de las enumeraciones aquí están respaldadas.
Una enumeración pura (enum X sin tipo de respaldo) tiene casos pero ningún valor escalar; siempre se hace referencia a ella por caso (X::SomeCase). Solo UnderlineStyle es pura.

En ambas formas se pasa el propio caso; por ejemplo, $pdf->addPage(orientation: Orientation::Landscape). El tipo de respaldo solo importa cuando hay que serializar la elección o volver a leerla desde la configuración.

Configuración de página

Orientation

Geometría de página vertical u horizontal. Se pasa al añadir una página; el motor intercambia el ancho y el alto para que coincidan.

Propiedad	Valor
FQCN	`NextPDF\Contracts\Orientation`
Respaldo	`string`
Se establece mediante	`Document::addPage(?PageSize $size = null, Orientation $orientation = Orientation::Portrait)`

Caso	Valor de respaldo
`Portrait`	`'P'`
`Landscape`	`'L'`

use NextPDF\Contracts\Orientation;
use NextPDF\ValueObjects\PageSize;

$pdf->addPage(PageSize::a4(), Orientation::Landscape);

Dibujo y gráficos

LineCap

Cómo termina un trazado abierto con borde. ISO 32000-2:2020 §8.4.3.3.

Propiedad	Valor
FQCN	`NextPDF\Graphics\LineCap`
Respaldo	`int`
Se establece mediante	el objeto de configuración `LineStyle` (`new LineStyle(cap: ...)`), aplicado con `Document::setLineStyle(LineStyle $style)`

Caso	Valor de respaldo	Significado
`Butt`	`0`	Extremo cuadrado en el punto final, sin proyección.
`Round`	`1`	Arco semicircular en el punto final.
`Square`	`2`	Proyección cuadrada que se extiende la mitad del ancho de línea más allá del punto final.

LineJoin

Cómo se encuentran dos segmentos con borde en una esquina. ISO 32000-2:2020 §8.4.3.4.

Propiedad	Valor
FQCN	`NextPDF\Graphics\LineJoin`
Respaldo	`int`
Se establece mediante	el objeto de configuración `LineStyle` (`new LineStyle(join: ...)`), aplicado con `Document::setLineStyle(LineStyle $style)`

Caso	Valor de respaldo	Significado
`Miter`	`0`	Esquina afilada extendida hasta el límite de inglete.
`Round`	`1`	Arco circular que une los bordes exteriores.
`Bevel`	`2`	Diagonal que conecta los bordes exteriores.

LineCap y LineJoin no se pasan directamente a un método de Document: son campos del objeto de valor inmutable NextPDF\Graphics\LineStyle, que luego se entrega a setLineStyle():

use NextPDF\Graphics\{LineStyle, LineCap, LineJoin};

$style = new LineStyle(width: 1.5, cap: LineCap::Round, join: LineJoin::Bevel);
$pdf->setLineStyle($style);
$pdf->line(20, 20, 120, 20);

BlendMode

La función de mezcla de transparencia aplicada al dibujo posterior. Los primeros doce casos son separables; los cuatro últimos son los modos HSL no separables. ISO 32000-2:2020 §11.3.5.

Propiedad	Valor
FQCN	`NextPDF\Graphics\BlendMode`
Respaldo	`string`
Se establece mediante	`Document::setAlpha(float $alpha, BlendMode $mode = BlendMode::Normal)`

Caso	Valor de respaldo	Caso	Valor de respaldo
`Normal`	`'Normal'`	`HardLight`	`'HardLight'`
`Multiply`	`'Multiply'`	`SoftLight`	`'SoftLight'`
`Screen`	`'Screen'`	`Difference`	`'Difference'`
`Overlay`	`'Overlay'`	`Exclusion`	`'Exclusion'`
`Darken`	`'Darken'`	`Hue`	`'Hue'`
`Lighten`	`'Lighten'`	`Saturation`	`'Saturation'`
`ColorDodge`	`'ColorDodge'`	`Color`	`'Color'`
`ColorBurn`	`'ColorBurn'`	`Luminosity`	`'Luminosity'`

use NextPDF\Graphics\BlendMode;

$pdf->setAlpha(0.6, BlendMode::Multiply);
$pdf->rect(20, 20, 80, 40, 'F');

Color

RenderingIntent

Cómo se reasignan los colores fuera de gama durante la conversión de color. Se emite como el operador ri. ISO 32000-2:2020 §8.6.5.8 (Tabla 71).

A diferencia de las demás enumeraciones de esta página, RenderingIntent no tiene setter público de Document ni de Config: es una enumeración de nivel de motor. Se aplica directamente sobre el motor de dibujo interno (DrawingEngine::setRenderingIntent()), que emite el operador ri en el flujo de contenido actual. La listamos aquí por exhaustividad porque sus casos forman parte del contrato público de color, pero no forma parte de la API de creación orientada al desarrollador que documenta el resto de esta página; trata el motor de dibujo como una clase interna en lugar de como el punto de entrada contra el que programas.

Propiedad	Valor
FQCN	`NextPDF\Graphics\RenderingIntent`
Respaldo	`string`
Se establece mediante	Solo a nivel de motor: se aplica sobre el motor de dibujo interno; sin setter público de Document/`Config`.

Caso	Valor de respaldo	Significado
`RelativeColorimetric`	`'RelativeColorimetric'`	Conserva los colores dentro de gama; recorta los que están fuera de gama.
`AbsoluteColorimetric`	`'AbsoluteColorimetric'`	Conserva los valores colorimétricos con exactitud, incluido el blanco de papel.
`Saturation`	`'Saturation'`	Conserva una saturación vívida a costa del tono/luminancia.
`Perceptual`	`'Perceptual'`	Conserva las relaciones visuales; compresión de gama suave.

OutputColorProfile

El perfil de color del espacio de trabajo declarado en el /OutputIntent del documento. El valor predeterminado DeviceRGB conserva el comportamiento heredado de «sin OutputIntent adicional»; seleccionar cualquier otro caso hace que el escritor emita un OutputIntent /GTS_PDFX con el perfil ICC incluido (ISO 32000-2:2020 §14.11.5). Es un valor de Config, no un método por llamada: se establece en el objeto de configuración que se pasa al Document.

Propiedad	Valor
FQCN	`NextPDF\Core\OutputColorProfile`
Respaldo	`string`
Se establece mediante	`Config::withOutputColorProfile(OutputColorProfile $profile)` (el parámetro `$outputColorProfile` del constructor de `Config`)

Caso	Valor de respaldo	Notas
`DeviceRGB`	`'device-rgb'`	Predeterminado. No se emite ningún OutputIntent adicional.
`Srgb`	`'srgb'`	OutputIntent sRGB explícito (IEC 61966-2-1). Sin gama amplia.
`DisplayP3`	`'display-p3'`	Gama amplia Display-P3 (D65).
`Rec2020`	`'rec2020'`	Gama amplia ITU-R BT.2020 / Rec.2020.
`A98RGB`	`'a98-rgb'`	Adobe RGB 1998.
`ProphotoRGB`	`'prophoto-rgb'`	ProPhoto RGB / ROMM RGB (D50).

use NextPDF\Core\{Config, OutputColorProfile};

$config = (new Config())->withOutputColorProfile(OutputColorProfile::DisplayP3);

Texto

TextRenderingMode

Si los glifos se rellenan, se trazan, se recortan o se renderizan de forma invisible (el modo invisible sustenta las capas OCR buscables). ISO 32000-2:2020 §9.3.6, Tabla 104.

Propiedad	Valor
FQCN	`NextPDF\Content\TextRenderingMode`
Respaldo	`int`
Se establece mediante	`Document::setTextRenderingMode(TextRenderingMode $mode)`

Caso	Valor de respaldo	Significado
`Fill`	`0`	Rellena los glifos.
`Stroke`	`1`	Traza los contornos de los glifos.
`FillStroke`	`2`	Rellena y luego traza.
`Invisible`	`3`	Renderiza de forma invisible (capas OCR buscables).
`FillClip`	`4`	Rellena y añade al trazado de recorte.
`StrokeClip`	`5`	Traza y añade al trazado de recorte.
`FillStrokeClip`	`6`	Rellena, traza y recorta.
`Clip`	`7`	Solo añade al trazado de recorte (sin renderizado visible).

UnderlineStyle

Cómo se dibuja una decoración de subrayado. Es la única enumeración pura aquí, así que siempre se hace referencia a ella por caso.

Propiedad	Valor
FQCN	`NextPDF\Contracts\UnderlineStyle`
Respaldo	pura (sin valor de respaldo)
Se establece mediante	`Document::setUnderlineStyle(UnderlineStyle $style)`

Caso	Significado
`RectFill`	Rectángulo relleno bajo la línea base (predeterminado compatible con TCPDF).
`StrokeLine`	Línea trazada bajo la línea base (dibujo de línea semántico).

use NextPDF\Content\TextRenderingMode;
use NextPDF\Contracts\UnderlineStyle;

$pdf->setTextRenderingMode(TextRenderingMode::Invisible); // OCR text layer
$pdf->setUnderlineStyle(UnderlineStyle::StrokeLine);

Conformidad

ConformanceMode

El contrato de conformidad a nivel de documento: qué parte de ISO debe respetar el escritor y si se requiere etiquetado estructural. El valor predeterminado Plain es salida PDF 2.0 sin restricciones. ISO 14289-2:2024 (PDF/UA-2) y las partes PDF/A de ISO 19005.

Propiedad	Valor
FQCN	`NextPDF\Conformance\ConformanceMode`
Respaldo	`string`
Se establece mediante	`Document::setConformanceMode(ConformanceMode $mode)` (vía de escape de más bajo nivel; prefiere `enableTaggedPdf()` para PDF/UA-2 en Core, o `enablePdfA()` —solo Premium— para PDF/A)

Caso	Valor de respaldo	Contrato
`Plain`	`'plain'`	PDF 2.0, sin restricciones (predeterminado).
`PdfUa1`	`'pdfua1'`	ISO 14289-1 (Tagged PDF/UA-1).
`PdfUa2`	`'pdfua2'`	ISO 14289-2:2024 (Tagged PDF/UA-2).
`PdfA2`	`'pdfa2'`	ISO 19005-2 (PDF/A-2).
`PdfA3`	`'pdfa3'`	ISO 19005-3 (discriminador de perfil PDF/A-3).
`PdfA3b`	`'pdfa3b'`	ISO 19005-3 PDF/A-3b (Basic).
`PdfA3u`	`'pdfa3u'`	ISO 19005-3 PDF/A-3u (extraíble como Unicode).
`PdfA4`	`'pdfa4'`	ISO 19005-4:2020 (discriminador de perfil PDF/A-4).
`PdfA4e`	`'pdfa4e'`	ISO 19005-4:2020 PDF/A-4e (Engineering).
`PdfA4f`	`'pdfa4f'`	ISO 19005-4:2020 PDF/A-4f (File attachments).

La enumeración incorpora ayudantes de predicado —isTagged(), isAccessibility(), isArchival() y pdfaPart()— para que las puertas del lado del escritor ramifiquen según el modo en lugar de volver a derivarlo.

Qué casos puede usar realmente una compilación solo de Core. El tipo enum enumera todos los casos, pero listar un caso no es lo mismo que poder producir esa conformidad desde Core:

Core (sin paquete adicional): Plain, PdfUa1 y PdfUa2. La vía de Tagged PDF / PDF/UA está integrada en Core: enableTaggedPdf() selecciona la vía de creación de PDF/UA (PdfUa2 de forma predeterminada) y conecta el árbol de estructura sin ninguna comprobación de licencia.
Solo Premium: todos los casos PDF/A (PdfA2, PdfA3, PdfA3b, PdfA3u, PdfA4, PdfA4e, PdfA4f). La salida PDF/A real la produce enablePdfA(), que es una función de nivel Premium (ADR-011): requiere el paquete nextpdf/pro y falla de forma cerrada con una InvalidConfigException («install the nextpdf/pro package») cuando ese paquete está ausente.

setConformanceMode() es una vía de escape de más bajo nivel que solo escribe el campo discriminador: no instala la maquinaria de PDF/A. Por tanto, establecer un caso PdfA* a través de él en una compilación solo de Core etiqueta el documento sin darle las garantías de archivado que proporciona enablePdfA(), de modo que no se debe confiar en los modos solo de Premium en una compilación solo de Core. Usa enableTaggedPdf() / enablePdfA() para las vías de conformidad reales, y recurre al paquete Premium siempre que se requiera un entregable PDF/A.

use NextPDF\Conformance\ConformanceMode;

$pdf->setConformanceMode(ConformanceMode::PdfUa2);

Archivos adjuntos

AFRelationship

El valor /AFRelationship de un archivo asociado incrustado. Un valor no conforme falla la validación de PDF/A-3 y PDF/A-4, así que la enumeración es la forma segura de establecerlo. ISO 32000-2:2020 §14.13.5 (Tabla 401).

Propiedad	Valor
FQCN	`NextPDF\Navigation\AFRelationship`
Respaldo	`string`
Se establece mediante	`Document::embedFile(string $path, string $description = '', AFRelationship\|string $afRelationship = AFRelationship::Unspecified)`

Caso	Valor de respaldo	Uso
`Source`	`'Source'`	El documento de origen a partir del cual se produjo el PDF.
`Data`	`'Data'`	Datos en bruto de los que deriva el PDF (p. ej., XML de Factur-X / ZUGFeRD).
`Alternative`	`'Alternative'`	Presentación alternativa (braille, subtítulos, SVG).
`Supplement`	`'Supplement'`	Material complementario.
`EncryptedPayload`	`'EncryptedPayload'`	Un blob cifrado opaco que el PDF envuelve.
`FormData`	`'FormData'`	Datos de formulario (XFDF, FDF, XML).
`Schema`	`'Schema'`	Esquema que describe un archivo `Data` (XSD, JSON Schema). PDF 2.0.
`Unspecified`	`'Unspecified'`	Sin relación especificada (predeterminado).

embedFile() acepta tanto el caso de la enumeración como su literal de cadena (con o sin barra inicial), de modo que AFRelationship::Data y '/Data' son equivalentes. Pasar el caso es la opción con seguridad de tipos.

use NextPDF\Navigation\AFRelationship;

// e-invoice payload: declare the XML as the source data
$pdf->embedFile('invoice.xml', 'Factur-X invoice data', AFRelationship::Data);

Véase también

Referencia de configuración: el objeto Config cuyos valores restringen estas enumeraciones, incluido withOutputColorProfile().
Módulo de gráficos: LineStyle, BlendMode, RenderingIntent y el motor de dibujo.
Módulo de tipografía: renderizado de texto y decoración de subrayado.
Módulo de conformidad: el discriminador ConformanceMode y las vías de activación de PDF/UA / PDF/A.
Módulo de navegación: archivos asociados y el mecanismo /AF.
Índice de referencia: el punto de entrada al material de referencia de API, configuración y compatibilidad.