Referencja enumów

W skrócie

Kilka metod autorskich NextPDF przyjmuje typowany enum, a nie zwykły łańcuch znaków czy liczbę całkowitą. Enum to kontrakt: ogranicza argument do ustalonego, poprawnego zbioru, a IDE i PHPStan odrzucają każdą wartość spoza niego. Ta strona jest miejscem wyszukiwania dozwolonych wartości dla enumów, które ustawiasz (lub otrzymujesz) przez publiczne API Document i Config — plus jeden enum koloru na poziomie silnika (RenderingIntent), uwzględniony, ponieważ jego przypadki są częścią publicznego kontraktu koloru i oznaczony jako działający na poziomie silnika tam, gdzie się pojawia.

To uzupełnienie referencji konfiguracji. Tam, gdzie obiekt Config mówi ci, którą gałkę przekręcić, ta strona mówi ci, jakie wartości ta gałka przyjmuje. Każdy wpis wymienia w pełni kwalifikowaną nazwę klasy enuma (FQCN), jego typ bazowy, dokładną listę przypadków skopiowaną ze źródła oraz publiczną metodę, która go przyjmuje.

Głębokie enumy wewnętrzne silnika (układ HTML/CSS, abstrakcyjne drzewo składni, CLI, wnętrza shapera) są celowo pominięte — nigdy ich nie ustawiasz. Niemal wszystko poniżej to wartość, którą przekazujesz przez publiczne API; jedyny wyjątek, RenderingIntent, to enum koloru na poziomie silnika bez publicznego settera, wymieniony dla kompletności i oznaczony jako taki tam, gdzie się pojawia.

Typy bazowe

Enumy PHP występują w dwóch postaciach, a postać zmienia sposób zapisu wartości:

• Backed enum (enum X: string lub enum X: int) ma skalarną wartość value dla każdego przypadku, więc przechodzi w obie strony przez X::from('...') / $case->value. Większość enumów tutaj to enumy backed.
• Pure enum (enum X bez typu bazowego) ma przypadki, ale nie ma skalarnej wartości; zawsze odwołujesz się do niego przez przypadek (X::SomeCase). Tylko UnderlineStyle jest pure.

W obu postaciach przekazujesz sam przypadek — na przykład $pdf->addPage(orientation: Orientation::Landscape). Typ bazowy ma znaczenie tylko wtedy, gdy musisz zserializować wybór lub odczytać go z konfiguracji.

Konfiguracja strony

Orientation

Geometria strony pionowa lub pozioma. Przekazywana, gdy dodajesz stronę; silnik zamienia szerokość i wysokość, aby się dopasować.

Właściwość	Wartość
FQCN	NextPDF\Contracts\Orientation
Typ bazowy	string
Ustawiane przez	Document::addPage(?PageSize $size = null, Orientation $orientation = Orientation::Portrait)

Przypadek	Wartość bazowa
Portrait	'P'
Landscape	'L'

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

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

Rysowanie i grafika

LineCap

Jak kończy się obrysowana otwarta ścieżka. ISO 32000-2:2020 §8.4.3.3.

Właściwość	Wartość
FQCN	NextPDF\Graphics\LineCap
Typ bazowy	int
Ustawiane przez	obiekt konfiguracji LineStyle (new LineStyle(cap: ...)), stosowany za pomocą Document::setLineStyle(LineStyle $style)

Przypadek	Wartość bazowa	Znaczenie
Butt	0	Prosty koniec w punkcie końcowym, bez wystawania.
Round	1	Półkolisty łuk w punkcie końcowym.
Square	2	Prostokątne wystawanie sięgające o połowę szerokości linii poza punkt końcowy.

LineJoin

Jak dwa obrysowane segmenty spotykają się w narożniku. ISO 32000-2:2020 §8.4.3.4.

Właściwość	Wartość
FQCN	NextPDF\Graphics\LineJoin
Typ bazowy	int
Ustawiane przez	obiekt konfiguracji LineStyle (new LineStyle(join: ...)), stosowany za pomocą Document::setLineStyle(LineStyle $style)

Przypadek	Wartość bazowa	Znaczenie
Miter	0	Ostry narożnik wyciągnięty do limitu zaostrzenia (miter limit).
Round	1	Kolisty łuk łączący zewnętrzne krawędzie.
Bevel	2	Przekątna łącząca zewnętrzne krawędzie.

LineCap i LineJoin nie są przekazywane bezpośrednio do metody Document — są polami niezmiennego obiektu wartości NextPDF\Graphics\LineStyle, który następnie przekazujesz do 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

Funkcja mieszania przezroczystości stosowana do dalszego rysowania. Pierwsze dwanaście przypadków jest rozdzielnych; ostatnie cztery to nierozdzielne tryby HSL. ISO 32000-2:2020 §11.3.5.

Właściwość	Wartość
FQCN	NextPDF\Graphics\BlendMode
Typ bazowy	string
Ustawiane przez	Document::setAlpha(float $alpha, BlendMode $mode = BlendMode::Normal)

Przypadek	Wartość bazowa	Przypadek	Wartość bazowa
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');

Kolor

RenderingIntent

Jak kolory spoza gamutu są przemapowywane podczas konwersji koloru. Emitowane jako operator ri. ISO 32000-2:2020 §8.6.5.8 (Tabela 71).

W odróżnieniu od pozostałych enumów na tej stronie RenderingIntent nie ma publicznego settera Document ani Config — to enum na poziomie silnika. Jest stosowany bezpośrednio na wewnętrznym silniku rysowania (DrawingEngine::setRenderingIntent()), który emituje operator ri do bieżącego strumienia treści. Wymieniamy go tutaj dla kompletności, ponieważ jego przypadki są częścią publicznego kontraktu koloru, ale nie jest on częścią widocznego dla programisty API autorskiego, które dokumentuje reszta tej strony; traktuj silnik rysowania jako klasę wewnętrzną, a nie jako punkt wejścia, który programujesz.

Właściwość	Wartość
FQCN	NextPDF\Graphics\RenderingIntent
Typ bazowy	string
Ustawiane przez	Tylko na poziomie silnika — stosowane na wewnętrznym silniku rysowania; brak publicznego settera Document/Config.

Przypadek	Wartość bazowa	Znaczenie
RelativeColorimetric	'RelativeColorimetric'	Zachowuje kolory w gamucie; przycina te spoza gamutu.
AbsoluteColorimetric	'AbsoluteColorimetric'	Zachowuje wartości kolorymetryczne dokładnie, łącznie z bielą papieru.
Saturation	'Saturation'	Zachowuje żywe nasycenie kosztem barwy/luminancji.
Perceptual	'Perceptual'	Zachowuje relacje wizualne; gładka kompresja gamutu.

OutputColorProfile

Profil koloru przestrzeni roboczej zadeklarowany w /OutputIntent dokumentu. Domyślny DeviceRGB zachowuje dotychczasowe zachowanie „bez dodatkowego OutputIntent”; wybranie dowolnego innego przypadku sprawia, że writer emituje OutputIntent /GTS_PDFX z dołączonym profilem ICC (ISO 32000-2:2020 §14.11.5). To wartość Config, a nie metoda wywoływana przy każdym wywołaniu — ustaw ją na obiekcie konfiguracji, który przekazujesz do Document.

Właściwość	Wartość
FQCN	NextPDF\Core\OutputColorProfile
Typ bazowy	string
Ustawiane przez	Config::withOutputColorProfile(OutputColorProfile $profile) (parametr $outputColorProfile konstruktora Config)

Przypadek	Wartość bazowa	Uwagi
DeviceRGB	'device-rgb'	Domyślny. Brak dodatkowego emitowanego OutputIntent.
Srgb	'srgb'	Jawny OutputIntent sRGB (IEC 61966-2-1). Nieszerokogamutowy.
DisplayP3	'display-p3'	Szeroki gamut Display-P3 (D65).
Rec2020	'rec2020'	Szeroki gamut 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);

Tekst

TextRenderingMode

Czy glify są wypełnione, obrysowane, przycięte czy renderowane niewidocznie (tryb niewidoczny leży u podstaw przeszukiwalnych warstw OCR). ISO 32000-2:2020 §9.3.6, Tabela 104.

Właściwość	Wartość
FQCN	NextPDF\Content\TextRenderingMode
Typ bazowy	int
Ustawiane przez	Document::setTextRenderingMode(TextRenderingMode $mode)

Przypadek	Wartość bazowa	Znaczenie
Fill	0	Wypełnij glify.
Stroke	1	Obrysuj kontury glifów.
FillStroke	2	Wypełnij, a następnie obrysuj.
Invisible	3	Renderuj niewidocznie (przeszukiwalne warstwy OCR).
FillClip	4	Wypełnij i dodaj do ścieżki przycinania.
StrokeClip	5	Obrysuj i dodaj do ścieżki przycinania.
FillStrokeClip	6	Wypełnij, obrysuj i przytnij.
Clip	7	Dodaj tylko do ścieżki przycinania (bez widocznego renderowania).

UnderlineStyle

Jak rysowana jest dekoracja podkreślenia. To jedyny enum pure tutaj, więc zawsze odwołujesz się do niego przez przypadek.

Właściwość	Wartość
FQCN	NextPDF\Contracts\UnderlineStyle
Typ bazowy	pure (brak wartości bazowej)
Ustawiane przez	Document::setUnderlineStyle(UnderlineStyle $style)

Przypadek	Znaczenie
RectFill	Wypełniony prostokąt pod linią bazową (domyślny tryb zgodny z TCPDF).
StrokeLine	Obrysowana linia pod linią bazową (semantyczne rysowanie linii).

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

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

Zgodność

ConformanceMode

Kontrakt zgodności na poziomie dokumentu: którą część ISO writer musi honorować i czy strukturalne tagowanie jest wymagane. Domyślny Plain to nieograniczone wyjście PDF 2.0. ISO 14289-2:2024 (PDF/UA-2) oraz części PDF/A ISO 19005.

Właściwość	Wartość
FQCN	NextPDF\Conformance\ConformanceMode
Typ bazowy	string
Ustawiane przez	Document::setConformanceMode(ConformanceMode $mode) (niskopoziomowa furtka awaryjna; preferuj enableTaggedPdf() dla PDF/UA-2 w Core lub enablePdfA() — tylko Premium — dla PDF/A)

Przypadek	Wartość bazowa	Kontrakt
Plain	'plain'	PDF 2.0, nieograniczony (domyślny).
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 (dyskryminator profilu 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 (dyskryminator profilu PDF/A-4).
PdfA4e	'pdfa4e'	ISO 19005-4:2020 PDF/A-4e (Engineering).
PdfA4f	'pdfa4f'	ISO 19005-4:2020 PDF/A-4f (File attachments).

Enum niesie pomocnicze predykaty — isTagged(), isAccessibility(), isArchival() oraz pdfaPart() — dzięki czemu bramki po stronie writera rozgałęziają się na trybie zamiast wyprowadzać go ponownie.

Których przypadków faktycznie może użyć build wyłącznie Core. Typ enum wymienia każdy przypadek, ale wymienienie przypadku to nie to samo co możliwość wyprodukowania tej zgodności z Core:

• Core (bez dodatkowego pakietu): Plain, PdfUa1 oraz PdfUa2. Ścieżka Tagged PDF / PDF/UA jest wbudowana w Core — enableTaggedPdf() wybiera ścieżkę autorską PDF/UA (PdfUa2 domyślnie) i podpina drzewo struktury bez żadnej weryfikacji licencji.
• Tylko Premium: każdy przypadek PDF/A (PdfA2, PdfA3, PdfA3b, PdfA3u, PdfA4, PdfA4e, PdfA4f). Rzeczywiste wyjście PDF/A jest produkowane przez enablePdfA(), które jest funkcją poziomu Premium (ADR-011): wymaga pakietu nextpdf/pro i kończy się fail-closed wyjątkiem InvalidConfigException („install the nextpdf/pro package”), gdy tego pakietu brakuje.

setConformanceMode() to niskopoziomowa furtka awaryjna, która zapisuje tylko pole dyskryminatora — nie instaluje maszynerii PDF/A. Ustawienie przez nią przypadku PdfA* w buildzie wyłącznie Core etykietuje zatem dokument bez nadawania mu gwarancji archiwizacyjnych, które zapewnia enablePdfA(), więc na trybach tylko-Premium nie wolno polegać w buildzie wyłącznie Core. Użyj enableTaggedPdf() / enablePdfA() dla rzeczywistych ścieżek zgodności i sięgnij po pakiet Premium zawsze, gdy wymagana jest dostawa PDF/A.

use NextPDF\Conformance\ConformanceMode;

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

Załączniki

AFRelationship

Wartość /AFRelationship dla osadzonego powiązanego pliku. Niezgodna wartość nie przechodzi walidacji PDF/A-3 i PDF/A-4, więc enum to bezpieczny sposób jej ustawienia. ISO 32000-2:2020 §14.13.5 (Tabela 401).

Właściwość	Wartość
FQCN	NextPDF\Navigation\AFRelationship
Typ bazowy	string
Ustawiane przez	Document::embedFile(string $path, string $description = '', AFRelationship|string $afRelationship = AFRelationship::Unspecified)

Przypadek	Wartość bazowa	Zastosowanie
Source	'Source'	Dokument źródłowy, z którego wyprodukowano PDF.
Data	'Data'	Surowe dane, z których PDF jest wyprowadzony (np. XML Factur-X / ZUGFeRD).
Alternative	'Alternative'	Prezentacja alternatywna (brajl, napisy, SVG).
Supplement	'Supplement'	Materiał uzupełniający.
EncryptedPayload	'EncryptedPayload'	Nieprzejrzysty zaszyfrowany blob, który PDF opakowuje.
FormData	'FormData'	Dane formularza (XFDF, FDF, XML).
Schema	'Schema'	Schemat opisujący plik Data (XSD, JSON Schema). PDF 2.0.
Unspecified	'Unspecified'	Brak określonego powiązania (domyślny).

embedFile() przyjmuje albo przypadek enuma, albo jego literał łańcuchowy (z ukośnikiem wiodącym lub bez), więc AFRelationship::Data i '/Data' są równoważne. Przekazanie przypadku to wybór bezpieczny typowo.

use NextPDF\Navigation\AFRelationship;

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

Zobacz też

• Referencja konfiguracji — obiekt Config, którego wartości te enumy ograniczają, w tym withOutputColorProfile().
• Moduł grafiki — LineStyle, BlendMode, RenderingIntent oraz silnik rysowania.
• Moduł typografii — renderowanie tekstu i dekoracja podkreślenia.
• Moduł zgodności — dyskryminator ConformanceMode oraz ścieżki włączania PDF/UA / PDF/A.
• Moduł nawigacji — powiązane pliki i mechanizm /AF.
• Indeks referencji — punkt wejścia do materiałów referencyjnych API, konfiguracji i kompatybilności.