Referência de enums

Visão geral

Vários métodos de autoria do NextPDF recebem um enum tipado em vez de uma string simples ou um inteiro. O enum é o contrato: ele restringe o argumento a um conjunto fixo e válido, e a IDE e o PHPStan rejeitam qualquer valor fora dele. Esta página é a consulta de valores permitidos para os enums que você define (ou recebe) por meio da API pública de Document e Config — além de um enum de cor em nível de mecanismo (RenderingIntent), incluído porque seus cases fazem parte do contrato de cor público e marcado como sendo de nível de mecanismo onde aparece.

Este é o complemento da referência de configuração. Onde o objeto Config informa qual botão girar, esta página informa quais valores aquele botão aceita. Cada entrada lista o nome de classe totalmente qualificado (FQCN) do enum, seu tipo de backing, a lista exata de cases copiada do código-fonte e o método público que o recebe.

Enums profundos, internos ao mecanismo (layout HTML/CSS, a árvore de sintaxe abstrata, a CLI, os internos do shaper), são deliberadamente excluídos — você nunca os define. Quase tudo abaixo é um valor que você passa pela API pública; a única exceção, RenderingIntent, é um enum de cor em nível de mecanismo sem setter público, listado para fins de completude e identificado como tal onde aparece.

Tipos de backing

Os enums do PHP vêm em dois formatos, e o formato muda como você escreve o valor:

Um enum backed (enum X: string ou enum X: int) tem um value escalar para cada case, então ele faz round-trip por meio de X::from('...') / $case->value. A maioria dos enums aqui é backed.
Um enum pure (enum X sem tipo de backing) tem cases mas nenhum valor escalar; você sempre se refere a ele pelo case (X::SomeCase). Apenas UnderlineStyle é pure.

Em ambos os formatos você passa o próprio case — por exemplo $pdf->addPage(orientation: Orientation::Landscape). O tipo de backing importa apenas quando você precisa serializar a escolha ou lê-la de volta a partir da configuração.

Configuração de página

Orientation

Geometria de página retrato ou paisagem. Passada quando você adiciona uma página; o mecanismo troca largura e altura para corresponder.

Propriedade	Valor
FQCN	`NextPDF\Contracts\Orientation`
Backing	`string`
Definido via	`Document::addPage(?PageSize $size = null, Orientation $orientation = Orientation::Portrait)`

Case	Valor de backing
`Portrait`	`'P'`
`Landscape`	`'L'`

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

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

Desenho e gráficos

LineCap

Como um caminho aberto traçado termina. ISO 32000-2:2020 §8.4.3.3.

Propriedade	Valor
FQCN	`NextPDF\Graphics\LineCap`
Backing	`int`
Definido via	o objeto de configuração `LineStyle` (`new LineStyle(cap: ...)`), aplicado com `Document::setLineStyle(LineStyle $style)`

Case	Valor de backing	Significado
`Butt`	`0`	Extremidade quadrada no ponto final, sem projeção.
`Round`	`1`	Arco semicircular no ponto final.
`Square`	`2`	Projeção quadrada que se estende por metade da largura da linha além do ponto final.

LineJoin

Como dois segmentos traçados se encontram em um canto. ISO 32000-2:2020 §8.4.3.4.

Propriedade	Valor
FQCN	`NextPDF\Graphics\LineJoin`
Backing	`int`
Definido via	o objeto de configuração `LineStyle` (`new LineStyle(join: ...)`), aplicado com `Document::setLineStyle(LineStyle $style)`

Case	Valor de backing	Significado
`Miter`	`0`	Canto agudo estendido até o limite de miter.
`Round`	`1`	Arco circular unindo as bordas externas.
`Bevel`	`2`	Diagonal conectando as bordas externas.

LineCap e LineJoin não são passados diretamente para um método de Document — eles são campos do objeto de valor imutável NextPDF\Graphics\LineStyle, que você então 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

A função de mesclagem de transparência aplicada ao desenho subsequente. Os primeiros doze cases são separáveis; os quatro últimos são os modos HSL não separáveis. ISO 32000-2:2020 §11.3.5.

Propriedade	Valor
FQCN	`NextPDF\Graphics\BlendMode`
Backing	`string`
Definido via	`Document::setAlpha(float $alpha, BlendMode $mode = BlendMode::Normal)`

Case	Valor de backing	Case	Valor de backing
`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');

Cor

RenderingIntent

Como cores fora do gamut são remapeadas durante a conversão de cor. Emitido como o operador ri. ISO 32000-2:2020 §8.6.5.8 (Tabela 71).

Diferentemente dos outros enums desta página, RenderingIntent não tem setter público de Document ou Config — ele é um enum de nível de mecanismo. Ele é aplicado diretamente no mecanismo de desenho interno (DrawingEngine::setRenderingIntent()), que emite o operador ri no stream de conteúdo atual. Nós o listamos aqui para fins de completude porque seus cases fazem parte do contrato de cor público, mas ele não faz parte da API de autoria voltada ao desenvolvedor que o resto desta página documenta; trate o mecanismo de desenho como uma classe interna, e não como o ponto de entrada contra o qual você programa.

Propriedade	Valor
FQCN	`NextPDF\Graphics\RenderingIntent`
Backing	`string`
Definido via	Apenas em nível de mecanismo — aplicado no mecanismo de desenho interno; sem setter público de Document/`Config`.

Case	Valor de backing	Significado
`RelativeColorimetric`	`'RelativeColorimetric'`	Preserva cores dentro do gamut; recorta as fora do gamut.
`AbsoluteColorimetric`	`'AbsoluteColorimetric'`	Preserva os valores colorimétricos exatamente, incluindo o branco do papel.
`Saturation`	`'Saturation'`	Preserva saturação vívida em detrimento de matiz/luminância.
`Perceptual`	`'Perceptual'`	Preserva relações visuais; compressão suave do gamut.

OutputColorProfile

O perfil de cor do espaço de trabalho declarado no /OutputIntent do documento. O padrão DeviceRGB preserva o comportamento legado de “nenhum OutputIntent extra”; selecionar qualquer outro case faz o escritor emitir um OutputIntent /GTS_PDFX com o perfil ICC empacotado (ISO 32000-2:2020 §14.11.5). Este é um valor de Config, não um método por chamada — defina-o no objeto de configuração que você passa para o Document.

Propriedade	Valor
FQCN	`NextPDF\Core\OutputColorProfile`
Backing	`string`
Definido via	`Config::withOutputColorProfile(OutputColorProfile $profile)` (o parâmetro `$outputColorProfile` do construtor de `Config`)

Case	Valor de backing	Observações
`DeviceRGB`	`'device-rgb'`	Padrão. Nenhum OutputIntent adicional emitido.
`Srgb`	`'srgb'`	OutputIntent sRGB explícito (IEC 61966-2-1). Não é wide gamut.
`DisplayP3`	`'display-p3'`	Display-P3 wide gamut (D65).
`Rec2020`	`'rec2020'`	ITU-R BT.2020 / Rec.2020 wide gamut.
`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

Se os glifos são preenchidos, traçados, recortados ou renderizados invisivelmente (o modo invisível é a base das camadas de OCR pesquisáveis). ISO 32000-2:2020 §9.3.6, Tabela 104.

Propriedade	Valor
FQCN	`NextPDF\Content\TextRenderingMode`
Backing	`int`
Definido via	`Document::setTextRenderingMode(TextRenderingMode $mode)`

Case	Valor de backing	Significado
`Fill`	`0`	Preenche os glifos.
`Stroke`	`1`	Traça os contornos dos glifos.
`FillStroke`	`2`	Preenche e depois traça.
`Invisible`	`3`	Renderiza invisivelmente (camadas de OCR pesquisáveis).
`FillClip`	`4`	Preenche e adiciona ao caminho de recorte.
`StrokeClip`	`5`	Traça e adiciona ao caminho de recorte.
`FillStrokeClip`	`6`	Preenche, traça e recorta.
`Clip`	`7`	Adiciona apenas ao caminho de recorte (sem renderização visível).

UnderlineStyle

Como uma decoração de sublinhado é desenhada. Este é o único enum pure aqui, então você sempre se refere a ele pelo case.

Propriedade	Valor
FQCN	`NextPDF\Contracts\UnderlineStyle`
Backing	pure (sem valor de backing)
Definido via	`Document::setUnderlineStyle(UnderlineStyle $style)`

Case	Significado
`RectFill`	Retângulo preenchido abaixo da linha de base (padrão compatível com TCPDF).
`StrokeLine`	Linha traçada abaixo da linha de base (desenho de linha semântico).

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

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

Conformidade

ConformanceMode

O contrato de conformidade em nível de documento: qual parte da ISO o escritor deve honrar e se a marcação estrutural é obrigatória. O padrão Plain é uma saída PDF 2.0 sem restrições. ISO 14289-2:2024 (PDF/UA-2) e as partes ISO 19005 PDF/A.

Propriedade	Valor
FQCN	`NextPDF\Conformance\ConformanceMode`
Backing	`string`
Definido via	`Document::setConformanceMode(ConformanceMode $mode)` (escape hatch de baixo nível; prefira `enableTaggedPdf()` para PDF/UA-2 no Core, ou `enablePdfA()` — apenas Premium — para PDF/A)

Case	Valor de backing	Contrato
`Plain`	`'plain'`	PDF 2.0, sem restrições (padrão).
`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 (Unicode-extractable).
`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).

O enum carrega helpers de predicado — isTagged(), isAccessibility(), isArchival() e pdfaPart() — para que os gates do lado do escritor ramifiquem sobre o modo em vez de derivá-lo novamente.

Quais cases um build apenas-Core pode realmente usar. O tipo enum lista todos os cases, mas listar um case não é o mesmo que ser capaz de produzir aquela conformidade a partir do Core:

Core (sem pacote extra): Plain, PdfUa1 e PdfUa2. O caminho Tagged PDF / PDF/UA é embutido no Core — enableTaggedPdf() seleciona o caminho de autoria PDF/UA (PdfUa2 por padrão) e conecta a árvore de estrutura sem qualquer verificação de licença.
Apenas Premium: todos os cases PDF/A (PdfA2, PdfA3, PdfA3b, PdfA3u, PdfA4, PdfA4e, PdfA4f). A saída PDF/A real é produzida por enablePdfA(), que é um recurso de nível Premium (ADR-011): ele requer o pacote nextpdf/pro e falha de forma fechada com uma InvalidConfigException (“install the nextpdf/pro package”) quando esse pacote está ausente.

setConformanceMode() é um escape hatch de baixo nível que apenas escreve o campo discriminador — ele não instala a maquinaria de PDF/A. Definir um case PdfA* por meio dele em um build apenas-Core, portanto, rotula o documento sem lhe dar as garantias de arquivamento que enablePdfA() fornece, então os modos apenas-Premium não devem ser invocados em um build apenas-Core. Use enableTaggedPdf() / enablePdfA() para os caminhos de conformidade reais e recorra ao pacote Premium sempre que um entregável PDF/A for necessário.

use NextPDF\Conformance\ConformanceMode;

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

Anexos

AFRelationship

O valor de /AFRelationship para um arquivo associado incorporado. Um valor não conforme reprova na validação de PDF/A-3 e PDF/A-4, então o enum é a forma segura de defini-lo. ISO 32000-2:2020 §14.13.5 (Tabela 401).

Propriedade	Valor
FQCN	`NextPDF\Navigation\AFRelationship`
Backing	`string`
Definido via	`Document::embedFile(string $path, string $description = '', AFRelationship\|string $afRelationship = AFRelationship::Unspecified)`

Case	Valor de backing	Uso
`Source`	`'Source'`	O documento de origem a partir do qual o PDF foi produzido.
`Data`	`'Data'`	Dados brutos dos quais o PDF é derivado (por exemplo, XML Factur-X / ZUGFeRD).
`Alternative`	`'Alternative'`	Apresentação alternativa (braille, legendas, SVG).
`Supplement`	`'Supplement'`	Material suplementar.
`EncryptedPayload`	`'EncryptedPayload'`	Um blob criptografado opaco que o PDF envolve.
`FormData`	`'FormData'`	Dados de formulário (XFDF, FDF, XML).
`Schema`	`'Schema'`	Schema que descreve um arquivo `Data` (XSD, JSON Schema). PDF 2.0.
`Unspecified`	`'Unspecified'`	Nenhuma relação especificada (padrão).

embedFile() aceita tanto o case do enum quanto seu literal de string (com ou sem uma barra inicial), então AFRelationship::Data e '/Data' são equivalentes. Passar o case é a escolha type-safe.

use NextPDF\Navigation\AFRelationship;

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

Veja também

Referência de configuração — o objeto Config cujos valores estes enums restringem, incluindo withOutputColorProfile().
Módulo Graphics — LineStyle, BlendMode, RenderingIntent e o mecanismo de desenho.
Módulo Typography — renderização de texto e decoração de sublinhado.
Módulo Conformance — o discriminador ConformanceMode e os caminhos de habilitação de PDF/UA / PDF/A.
Módulo Navigation — arquivos associados e o mecanismo /AF.
Índice de referência — o ponto de entrada para o material de referência de API, configuração e compatibilidade.