Enum-Referenz

Auf einen Blick

Mehrere NextPDF-Authoring-Methoden nehmen ein typisiertes enum entgegen statt einer bloßen Zeichenkette oder Ganzzahl. Das Enum ist der Vertrag: Es schränkt das Argument auf eine feste, gültige Menge ein, und die IDE sowie PHPStan weisen jeden Wert außerhalb davon zurück. Diese Seite ist das Nachschlagewerk der zulässigen Werte für die Enums, die Sie über die öffentliche Document- und Config-API setzen (oder empfangen) — plus einem Farb-Enum auf Engine-Ebene (RenderingIntent), das aufgenommen ist, weil seine Cases Teil des öffentlichen Farbvertrags sind und das dort, wo es erscheint, als Engine-Ebene gekennzeichnet ist.

Dies ist die Ergänzung zur Konfigurationsreferenz. Wo das Config-Objekt Ihnen sagt, welchen Regler Sie drehen, sagt Ihnen diese Seite, welche Werte dieser Regler akzeptiert. Jeder Eintrag listet den voll qualifizierten Klassennamen (FQCN) des Enums, seinen Backing-Typ, die exakte aus dem Quellcode kopierte Case-Liste und die öffentliche Methode, die es entgegennimmt.

Tiefe engine-interne Enums (HTML-/CSS-Layout, der abstrakte Syntaxbaum, die CLI, die Shaper-Interna) sind bewusst ausgeschlossen — diese setzen Sie nie. Fast alles unten ist ein Wert, den Sie über die öffentliche API übergeben; die eine Ausnahme, RenderingIntent, ist ein Farb-Enum auf Engine-Ebene ohne öffentlichen Setter, das der Vollständigkeit halber aufgeführt und dort, wo es erscheint, als solches gekennzeichnet ist.

Backing-Typen

PHP-Enums gibt es in zwei Ausprägungen, und die Ausprägung ändert, wie Sie den Wert schreiben:

• Ein backed Enum (enum X: string oder enum X: int) hat für jeden Case einen skalaren value, sodass es über X::from('...') / $case->value hin und zurück konvertiert. Die meisten Enums hier sind backed.
• Ein pures Enum (enum X ohne Backing-Typ) hat Cases, aber keinen skalaren Wert; Sie verweisen immer per Case darauf (X::SomeCase). Nur UnderlineStyle ist pur.

In beiden Ausprägungen übergeben Sie den Case selbst — zum Beispiel $pdf->addPage(orientation: Orientation::Landscape). Der Backing-Typ ist nur dann von Bedeutung, wenn Sie die Auswahl serialisieren oder aus der Konfiguration zurücklesen müssen.

Seiteneinrichtung

Orientation

Hoch- oder Querformat-Seitengeometrie. Wird übergeben, wenn Sie eine Seite hinzufügen; die Engine tauscht Breite und Höhe, damit sie passen.

Eigenschaft	Wert
FQCN	NextPDF\Contracts\Orientation
Backing	string
Gesetzt über	Document::addPage(?PageSize $size = null, Orientation $orientation = Orientation::Portrait)

Case	Backing-Wert
Portrait	'P'
Landscape	'L'

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

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

Zeichnen und Grafik

LineCap

Wie ein gestricheltes offenes Pfadende abschließt. ISO 32000-2:2020 §8.4.3.3.

Eigenschaft	Wert
FQCN	NextPDF\Graphics\LineCap
Backing	int
Gesetzt über	das LineStyle-Konfigurationsobjekt (new LineStyle(cap: ...)), angewendet mit Document::setLineStyle(LineStyle $style)

Case	Backing-Wert	Bedeutung
Butt	0	Quadratisches Ende am Endpunkt, ohne Überstand.
Round	1	Halbkreisförmiger Bogen am Endpunkt.
Square	2	Quadratischer Überstand, der die halbe Linienbreite über den Endpunkt hinausragt.

LineJoin

Wie zwei gestrichelte Segmente an einer Ecke zusammentreffen. ISO 32000-2:2020 §8.4.3.4.

Eigenschaft	Wert
FQCN	NextPDF\Graphics\LineJoin
Backing	int
Gesetzt über	das LineStyle-Konfigurationsobjekt (new LineStyle(join: ...)), angewendet mit Document::setLineStyle(LineStyle $style)

Case	Backing-Wert	Bedeutung
Miter	0	Scharfe Ecke, bis zur Gehrungsgrenze (Miter-Limit) verlängert.
Round	1	Kreisbogen, der die Außenkanten verbindet.
Bevel	2	Diagonale, die die Außenkanten verbindet.

LineCap und LineJoin werden nicht direkt an eine Document-Methode übergeben — sie sind Felder des unveränderlichen NextPDF\Graphics\LineStyle-Value-Objects, das Sie dann an setLineStyle() übergeben:

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

Die Transparenz-Mischfunktion, die auf nachfolgendes Zeichnen angewendet wird. Die ersten zwölf Cases sind separierbar; die letzten vier sind die nicht-separierbaren HSL-Modi. ISO 32000-2:2020 §11.3.5.

Eigenschaft	Wert
FQCN	NextPDF\Graphics\BlendMode
Backing	string
Gesetzt über	Document::setAlpha(float $alpha, BlendMode $mode = BlendMode::Normal)

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

Farbe

RenderingIntent

Wie Farben außerhalb des Gamuts während der Farbkonvertierung umgesetzt werden. Wird als ri-Operator emittiert. ISO 32000-2:2020 §8.6.5.8 (Tabelle 71).

Anders als die übrigen Enums auf dieser Seite hat RenderingIntent keinen öffentlichen Document- oder Config-Setter — es ist ein Enum auf Engine-Ebene. Es wird direkt auf der internen Zeichen-Engine angewendet (DrawingEngine::setRenderingIntent()), die den ri-Operator in den aktuellen Content-Stream emittiert. Wir führen es hier der Vollständigkeit halber auf, weil seine Cases Teil des öffentlichen Farbvertrags sind, aber es ist nicht Teil der für Entwickler bestimmten Authoring-API, die der Rest dieser Seite dokumentiert; behandeln Sie die Zeichen-Engine als interne Klasse statt als Einstiegspunkt, gegen den Sie programmieren.

Eigenschaft	Wert
FQCN	NextPDF\Graphics\RenderingIntent
Backing	string
Gesetzt über	Nur auf Engine-Ebene — angewendet auf der internen Zeichen-Engine; kein öffentlicher Document-/Config-Setter.

Case	Backing-Wert	Bedeutung
RelativeColorimetric	'RelativeColorimetric'	Erhält Farben innerhalb des Gamuts; beschneidet Farben außerhalb.
AbsoluteColorimetric	'AbsoluteColorimetric'	Erhält kolorimetrische Werte exakt, einschließlich Papierweiß.
Saturation	'Saturation'	Erhält lebendige Sättigung auf Kosten von Farbton/Luminanz.
Perceptual	'Perceptual'	Erhält visuelle Beziehungen; sanfte Gamut-Kompression.

OutputColorProfile

Das Arbeitsraum-Farbprofil, das auf dem /OutputIntent des Dokuments deklariert wird. Der Standard DeviceRGB bewahrt das alte Verhalten „kein zusätzlicher OutputIntent“; die Auswahl eines anderen Cases veranlasst den Writer, einen /GTS_PDFX-OutputIntent mit dem mitgelieferten ICC-Profil zu emittieren (ISO 32000-2:2020 §14.11.5). Dies ist ein Config-Wert, keine Methode pro Aufruf — setzen Sie ihn auf dem Konfigurationsobjekt, das Sie an das Document übergeben.

Eigenschaft	Wert
FQCN	NextPDF\Core\OutputColorProfile
Backing	string
Gesetzt über	Config::withOutputColorProfile(OutputColorProfile $profile) (der $outputColorProfile-Parameter des Config-Konstruktors)

Case	Backing-Wert	Hinweise
DeviceRGB	'device-rgb'	Standard. Kein zusätzlicher OutputIntent emittiert.
Srgb	'srgb'	Expliziter sRGB-OutputIntent (IEC 61966-2-1). Kein 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);

Text

TextRenderingMode

Ob Glyphen gefüllt, gestrichen, beschnitten oder unsichtbar gerendert werden (der unsichtbare Modus liegt durchsuchbaren OCR-Ebenen zugrunde). ISO 32000-2:2020 §9.3.6, Tabelle 104.

Eigenschaft	Wert
FQCN	NextPDF\Content\TextRenderingMode
Backing	int
Gesetzt über	Document::setTextRenderingMode(TextRenderingMode $mode)

Case	Backing-Wert	Bedeutung
Fill	0	Glyphen füllen.
Stroke	1	Glyphenumrisse strichen.
FillStroke	2	Füllen, dann strichen.
Invisible	3	Unsichtbar rendern (durchsuchbare OCR-Ebenen).
FillClip	4	Füllen und zum Beschneidungspfad hinzufügen.
StrokeClip	5	Strichen und zum Beschneidungspfad hinzufügen.
FillStrokeClip	6	Füllen, strichen und beschneiden.
Clip	7	Nur zum Beschneidungspfad hinzufügen (kein sichtbares Rendern).

UnderlineStyle

Wie eine Unterstreichungs-Dekoration gezeichnet wird. Dies ist hier das einzige pure Enum, sodass Sie immer per Case darauf verweisen.

Eigenschaft	Wert
FQCN	NextPDF\Contracts\UnderlineStyle
Backing	pur (kein Backing-Wert)
Gesetzt über	Document::setUnderlineStyle(UnderlineStyle $style)

Case	Bedeutung
RectFill	Gefülltes Rechteck unterhalb der Grundlinie (TCPDF-kompatibler Standard).
StrokeLine	Gestrichene Linie unterhalb der Grundlinie (semantisches Linienzeichnen).

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

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

Konformität

ConformanceMode

Der Konformitätsvertrag auf Dokumentebene: welchen ISO-Teil der Writer einhalten muss und ob strukturelles Tagging erforderlich ist. Der Standard Plain ist uneingeschränkte PDF-2.0-Ausgabe. ISO 14289-2:2024 (PDF/UA-2) und die ISO-19005- PDF/A-Teile.

Eigenschaft	Wert
FQCN	NextPDF\Conformance\ConformanceMode
Backing	string
Gesetzt über	Document::setConformanceMode(ConformanceMode $mode) (Escape-Hatch auf niedrigerer Ebene; bevorzugen Sie enableTaggedPdf() für PDF/UA-2 in Core oder enablePdfA() — nur Premium — für PDF/A)

Case	Backing-Wert	Vertrag
Plain	'plain'	PDF 2.0, uneingeschränkt (Standard).
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 (PDF/A-3-Profil-Diskriminator).
PdfA3b	'pdfa3b'	ISO 19005-3 PDF/A-3b (Basic).
PdfA3u	'pdfa3u'	ISO 19005-3 PDF/A-3u (Unicode-extrahierbar).
PdfA4	'pdfa4'	ISO 19005-4:2020 (PDF/A-4-Profil-Diskriminator).
PdfA4e	'pdfa4e'	ISO 19005-4:2020 PDF/A-4e (Engineering).
PdfA4f	'pdfa4f'	ISO 19005-4:2020 PDF/A-4f (Dateianhänge).

Das Enum trägt Prädikat-Helfer — isTagged(), isAccessibility(), isArchival() und pdfaPart() —, sodass Writer-seitige Gates auf den Modus verzweigen, statt ihn neu abzuleiten.

Welche Cases ein reiner Core-Build tatsächlich nutzen kann. Der enum-Typ listet jeden Case, aber einen Case zu listen ist nicht dasselbe, wie diese Konformität aus Core erzeugen zu können:

• Core (kein Zusatzpaket): Plain, PdfUa1 und PdfUa2. Der Tagged-PDF- / PDF/UA-Pfad ist in Core eingebaut — enableTaggedPdf() wählt den PDF/UA-Authoring-Pfad (standardmäßig PdfUa2) und verdrahtet den Strukturbaum ohne jede Lizenzprüfung.
• Nur Premium: jeder PDF/A-Case (PdfA2, PdfA3, PdfA3b, PdfA3u, PdfA4, PdfA4e, PdfA4f). Echte PDF/A-Ausgabe wird durch enablePdfA() erzeugt, was ein Feature der Premium-Stufe ist (ADR-011): Es benötigt das Paket nextpdf/pro und scheitert geschlossen mit einer InvalidConfigException („install the nextpdf/pro package“), wenn dieses Paket fehlt.

setConformanceMode() ist ein Escape-Hatch auf niedrigerer Ebene, der nur das Diskriminator-Feld schreibt — es installiert nicht die PDF/A-Maschinerie. Einen PdfA*-Case darüber in einem reinen Core-Build zu setzen, kennzeichnet das Dokument daher, ohne ihm die Archivgarantien zu geben, die enablePdfA() bietet, sodass auf die nur in Premium verfügbaren Modi in einem reinen Core-Build nicht vertraut werden darf. Verwenden Sie enableTaggedPdf() / enablePdfA() für die echten Konformitätspfade und greifen Sie zum Premium-Paket, wann immer ein PDF/A-Liefergegenstand erforderlich ist.

use NextPDF\Conformance\ConformanceMode;

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

Anhänge

AFRelationship

Der /AFRelationship-Wert für eine eingebettete zugeordnete Datei. Ein nicht-konformer Wert lässt die PDF/A-3- und PDF/A-4-Validierung scheitern, sodass das Enum der sichere Weg ist, ihn zu setzen. ISO 32000-2:2020 §14.13.5 (Tabelle 401).

Eigenschaft	Wert
FQCN	NextPDF\Navigation\AFRelationship
Backing	string
Gesetzt über	Document::embedFile(string $path, string $description = '', AFRelationship|string $afRelationship = AFRelationship::Unspecified)

Case	Backing-Wert	Verwendung
Source	'Source'	Das Quelldokument, aus dem das PDF erzeugt wurde.
Data	'Data'	Rohdaten, von denen das PDF abgeleitet ist (z. B. Factur-X- / ZUGFeRD-XML).
Alternative	'Alternative'	Alternative Darstellung (Braille, Untertitel, SVG).
Supplement	'Supplement'	Ergänzendes Material.
EncryptedPayload	'EncryptedPayload'	Ein opaker verschlüsselter Blob, den das PDF umschließt.
FormData	'FormData'	Formulardaten (XFDF, FDF, XML).
Schema	'Schema'	Schema, das eine Data-Datei beschreibt (XSD, JSON Schema). PDF 2.0.
Unspecified	'Unspecified'	Keine Beziehung angegeben (Standard).

embedFile() akzeptiert entweder den Enum-Case oder sein String-Literal (mit oder ohne führenden Schrägstrich), sodass AFRelationship::Data und '/Data' gleichwertig sind. Den Case zu übergeben ist die typsichere Wahl.

use NextPDF\Navigation\AFRelationship;

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

Siehe auch

• Konfigurationsreferenz — das Config-Objekt, dessen Werte diese Enums einschränken, einschließlich withOutputColorProfile().
• Graphics-Modul — LineStyle, BlendMode, RenderingIntent und die Zeichen-Engine.
• Typography-Modul — Textrendering und Unterstreichungs-Dekoration.
• Conformance-Modul — der ConformanceMode-Diskriminator und die PDF/UA- / PDF/A-Aktivierungspfade.
• Navigation-Modul — zugeordnete Dateien und der /AF-Mechanismus.
• Referenzübersicht — der Einstiegspunkt für API-, Konfigurations- und Kompatibilitätsreferenzmaterial.