Riferimento delle enum

In sintesi

Diversi metodi di authoring di NextPDF accettano una enum tipizzata anziché una semplice stringa o un intero. L’enum è il contratto: vincola l’argomento a un insieme fisso e valido, e l’IDE e PHPStan rifiutano qualsiasi valore al di fuori di esso. Questa pagina è la tabella di consultazione dei valori ammessi per le enum che si impostano (o si ricevono) tramite l’API pubblica del Document e di Config — più un’enum di colore a livello di motore (RenderingIntent), inclusa perché i suoi case fanno parte del contratto pubblico del colore e segnalata come a livello di motore dove compare.

Questo è il complemento del riferimento di configurazione. Dove l’oggetto Config indica quale manopola girare, questa pagina indica quali valori quella manopola accetta. Ogni voce elenca il nome completo della classe (FQCN) dell’enum, il suo tipo di backing, l’elenco esatto dei case copiato dal codice sorgente e il metodo pubblico che la accetta.

Le enum profonde, interne al motore (layout HTML/CSS, l’albero di sintassi astratta, la CLI, gli interni dello shaper) sono deliberatamente escluse — non si impostano mai quelle. Quasi tutto ciò che segue è un valore che si passa attraverso l’API pubblica; l’unica eccezione, RenderingIntent, è un’enum di colore a livello di motore senza setter pubblico, elencata per completezza ed etichettata come tale dove compare.

Tipi di backing

Le enum di PHP hanno due forme, e la forma cambia il modo in cui si scrive il valore:

Un’enum backed (enum X: string o enum X: int) ha un value scalare per ogni case, quindi compie un round-trip tramite X::from('...') / $case->value. La maggior parte delle enum qui sono backed.
Un’enum pure (enum X senza tipo di backing) ha case ma nessun valore scalare; ci si riferisce sempre ad essa per case (X::SomeCase). Solo UnderlineStyle è pure.

In entrambe le forme si passa il case stesso — per esempio $pdf->addPage(orientation: Orientation::Landscape). Il tipo di backing conta solo quando occorre serializzare la scelta o rileggerla dalla configurazione.

Impostazione della pagina

Orientation

Geometria della pagina verticale o orizzontale. Passata quando si aggiunge una pagina; il motore scambia larghezza e altezza per adeguarsi.

Property	Value
FQCN	`NextPDF\Contracts\Orientation`
Backing	`string`
Set via	`Document::addPage(?PageSize $size = null, Orientation $orientation = Orientation::Portrait)`

Case	Backing value
`Portrait`	`'P'`
`Landscape`	`'L'`

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

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

Disegno e grafica

LineCap

Come termina un tracciato aperto sottoposto a stroke. ISO 32000-2:2020 §8.4.3.3.

Property	Value
FQCN	`NextPDF\Graphics\LineCap`
Backing	`int`
Set via	l’oggetto di configurazione `LineStyle` (`new LineStyle(cap: ...)`), applicato con `Document::setLineStyle(LineStyle $style)`

Case	Backing value	Meaning
`Butt`	`0`	Estremità squadrata sull’endpoint, senza sporgenza.
`Round`	`1`	Arco semicircolare sull’endpoint.
`Square`	`2`	Sporgenza quadrata che si estende per metà della larghezza della linea oltre l’endpoint.

LineJoin

Come si incontrano a un angolo due segmenti sottoposti a stroke. ISO 32000-2:2020 §8.4.3.4.

Property	Value
FQCN	`NextPDF\Graphics\LineJoin`
Backing	`int`
Set via	l’oggetto di configurazione `LineStyle` (`new LineStyle(join: ...)`), applicato con `Document::setLineStyle(LineStyle $style)`

Case	Backing value	Meaning
`Miter`	`0`	Angolo netto esteso fino al limite di smussatura (miter limit).
`Round`	`1`	Arco circolare che unisce i bordi esterni.
`Bevel`	`2`	Diagonale che collega i bordi esterni.

LineCap e LineJoin non si passano direttamente a un metodo del Document — sono campi del value object immutabile NextPDF\Graphics\LineStyle, che poi si consegna 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 funzione di blend della trasparenza applicata al disegno successivo. I primi dodici case sono separabili; gli ultimi quattro sono le modalità HSL non separabili. ISO 32000-2:2020 §11.3.5.

Property	Value
FQCN	`NextPDF\Graphics\BlendMode`
Backing	`string`
Set via	`Document::setAlpha(float $alpha, BlendMode $mode = BlendMode::Normal)`

Case	Backing value	Case	Backing value
`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');

Colore

RenderingIntent

Come i colori fuori gamut vengono rimappati durante la conversione del colore. Emesso come operatore ri. ISO 32000-2:2020 §8.6.5.8 (Table 71).

A differenza delle altre enum di questa pagina, RenderingIntent non ha alcun setter pubblico su Document o Config — è un’enum a livello di motore. Viene applicata direttamente sul motore di disegno interno (DrawingEngine::setRenderingIntent()), che emette l’operatore ri nel content stream corrente. La elenchiamo qui per completezza perché i suoi case fanno parte del contratto pubblico del colore, ma non fa parte dell’API di authoring esposta agli sviluppatori documentata nel resto di questa pagina; trattare il motore di disegno come una classe interna anziché come il punto di ingresso con cui si programma.

Property	Value
FQCN	`NextPDF\Graphics\RenderingIntent`
Backing	`string`
Set via	Solo a livello di motore — applicata sul motore di disegno interno; nessun setter pubblico su Document/`Config`.

Case	Backing value	Meaning
`RelativeColorimetric`	`'RelativeColorimetric'`	Conserva i colori in gamut; clip di quelli fuori gamut.
`AbsoluteColorimetric`	`'AbsoluteColorimetric'`	Conserva esattamente i valori colorimetrici, incluso il bianco della carta.
`Saturation`	`'Saturation'`	Conserva una saturazione vivida a scapito di tinta/luminanza.
`Perceptual`	`'Perceptual'`	Conserva le relazioni visive; compressione fluida del gamut.

OutputColorProfile

Il profilo di colore dello spazio di lavoro dichiarato sull’/OutputIntent del documento. Il valore predefinito DeviceRGB conserva il comportamento legacy «nessun OutputIntent aggiuntivo»; selezionando qualsiasi altro case il writer emette un OutputIntent /GTS_PDFX con il profilo ICC incluso (ISO 32000-2:2020 §14.11.5). Questo è un valore di Config, non un metodo per chiamata — impostarlo sull’oggetto di configurazione passato al Document.

Property	Value
FQCN	`NextPDF\Core\OutputColorProfile`
Backing	`string`
Set via	`Config::withOutputColorProfile(OutputColorProfile $profile)` (il parametro `$outputColorProfile` del costruttore di `Config`)

Case	Backing value	Notes
`DeviceRGB`	`'device-rgb'`	Predefinito. Nessun OutputIntent aggiuntivo emesso.
`Srgb`	`'srgb'`	OutputIntent sRGB esplicito (IEC 61966-2-1). Non a gamut esteso.
`DisplayP3`	`'display-p3'`	Display-P3 a gamut esteso (D65).
`Rec2020`	`'rec2020'`	ITU-R BT.2020 / Rec.2020 a gamut esteso.
`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);

Testo

TextRenderingMode

Se i glifi sono riempiti, sottoposti a stroke, ritagliati o resi in modo invisibile (la modalità invisibile è alla base dei livelli OCR ricercabili). ISO 32000-2:2020 §9.3.6, Table 104.

Property	Value
FQCN	`NextPDF\Content\TextRenderingMode`
Backing	`int`
Set via	`Document::setTextRenderingMode(TextRenderingMode $mode)`

Case	Backing value	Meaning
`Fill`	`0`	Riempie i glifi.
`Stroke`	`1`	Esegue lo stroke dei contorni dei glifi.
`FillStroke`	`2`	Riempie e poi esegue lo stroke.
`Invisible`	`3`	Rende in modo invisibile (livelli OCR ricercabili).
`FillClip`	`4`	Riempie e aggiunge al tracciato di clipping.
`StrokeClip`	`5`	Esegue lo stroke e aggiunge al tracciato di clipping.
`FillStrokeClip`	`6`	Riempie, esegue lo stroke e ritaglia.
`Clip`	`7`	Aggiunge solo al tracciato di clipping (nessun rendering visibile).

UnderlineStyle

Come viene disegnata una decorazione di sottolineatura. Questa è l’unica enum pure qui presente, quindi ci si riferisce sempre ad essa per case.

Property	Value
FQCN	`NextPDF\Contracts\UnderlineStyle`
Backing	pure (no backing value)
Set via	`Document::setUnderlineStyle(UnderlineStyle $style)`

Case	Meaning
`RectFill`	Rettangolo riempito sotto la linea di base (default compatibile con TCPDF).
`StrokeLine`	Linea sottoposta a stroke sotto la linea di base (disegno semantico della linea).

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

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

Conformità

ConformanceMode

Il contratto di conformità a livello di documento: quale parte ISO il writer deve rispettare e se è richiesto il tagging strutturale. Il valore predefinito Plain è output PDF 2.0 non vincolato. ISO 14289-2:2024 (PDF/UA-2) e le parti PDF/A di ISO 19005.

Property	Value
FQCN	`NextPDF\Conformance\ConformanceMode`
Backing	`string`
Set via	`Document::setConformanceMode(ConformanceMode $mode)` (escape hatch di basso livello; preferire `enableTaggedPdf()` per PDF/UA-2 in Core, o `enablePdfA()` — solo Premium — per PDF/A)

Case	Backing value	Contract
`Plain`	`'plain'`	PDF 2.0, non vincolato (default).
`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 (discriminatore di profilo 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 (discriminatore di profilo PDF/A-4).
`PdfA4e`	`'pdfa4e'`	ISO 19005-4:2020 PDF/A-4e (Engineering).
`PdfA4f`	`'pdfa4f'`	ISO 19005-4:2020 PDF/A-4f (File attachments).

L’enum espone helper predicato — isTagged(), isAccessibility(), isArchival() e pdfaPart() — così che i gate lato writer si diramino in base alla modalità anziché riderivarla.

Quali case può effettivamente usare una build solo Core. Il tipo enum elenca ogni case, ma elencare un case non equivale a poter produrre quella conformità da Core:

Core (nessun pacchetto extra): Plain, PdfUa1 e PdfUa2. Il percorso Tagged PDF / PDF/UA è integrato in Core — enableTaggedPdf() seleziona il percorso di authoring PDF/UA (PdfUa2 per impostazione predefinita) e cabla l’albero della struttura senza alcun controllo di licenza.
Solo Premium: ogni case PDF/A (PdfA2, PdfA3, PdfA3b, PdfA3u, PdfA4, PdfA4e, PdfA4f). L’output PDF/A reale è prodotto da enablePdfA(), che è una funzionalità di livello Premium (ADR-011): richiede il pacchetto nextpdf/pro e fallisce in modo chiuso con una InvalidConfigException («install the nextpdf/pro package») quando tale pacchetto è assente.

setConformanceMode() è un escape hatch di basso livello che scrive solo il campo discriminatore — non installa la macchineria PDF/A. Impostare un case PdfA* tramite esso in una build solo Core etichetta quindi il documento senza conferirgli le garanzie di archiviazione che enablePdfA() fornisce, quindi sulle modalità solo Premium non si deve fare affidamento in una build solo Core. Usare enableTaggedPdf() / enablePdfA() per i percorsi di conformità reali, e ricorrere al pacchetto Premium ogni volta che è richiesto un deliverable PDF/A.

use NextPDF\Conformance\ConformanceMode;

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

Allegati

AFRelationship

Il valore /AFRelationship per un file associato incorporato. Un valore non conforme fa fallire la validazione PDF/A-3 e PDF/A-4, quindi l’enum è il modo sicuro per impostarlo. ISO 32000-2:2020 §14.13.5 (Table 401).

Property	Value
FQCN	`NextPDF\Navigation\AFRelationship`
Backing	`string`
Set via	`Document::embedFile(string $path, string $description = '', AFRelationship\|string $afRelationship = AFRelationship::Unspecified)`

Case	Backing value	Use
`Source`	`'Source'`	Il documento sorgente da cui è stato prodotto il PDF.
`Data`	`'Data'`	Dati grezzi da cui il PDF è derivato (ad es. XML Factur-X / ZUGFeRD).
`Alternative`	`'Alternative'`	Presentazione alternativa (braille, sottotitoli, SVG).
`Supplement`	`'Supplement'`	Materiale supplementare.
`EncryptedPayload`	`'EncryptedPayload'`	Un blob cifrato opaco che il PDF avvolge.
`FormData`	`'FormData'`	Dati di modulo (XFDF, FDF, XML).
`Schema`	`'Schema'`	Schema che descrive un file `Data` (XSD, JSON Schema). PDF 2.0.
`Unspecified`	`'Unspecified'`	Nessuna relazione specificata (default).

embedFile() accetta sia il case dell’enum sia il suo letterale stringa (con o senza slash iniziale), quindi AFRelationship::Data e '/Data' sono equivalenti. Passare il case è la scelta 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);

Vedere anche

Riferimento di configurazione — l’oggetto Config i cui valori queste enum vincolano, incluso withOutputColorProfile().
Modulo Graphics — LineStyle, BlendMode, RenderingIntent e il motore di disegno.
Modulo Typography — rendering del testo e decorazione di sottolineatura.
Modulo Conformance — il discriminatore ConformanceMode e i percorsi di abilitazione PDF/UA / PDF/A.
Modulo Navigation — i file associati e il meccanismo /AF.
Indice del riferimento — il punto di ingresso per il materiale di riferimento su API, configurazione e compatibilità.