Справочник перечислений

Кратко

Несколько авторских методов NextPDF принимают типизированный enum, а не голую строку или целое число. Перечисление — это контракт: оно ограничивает аргумент фиксированным, допустимым набором, и IDE и PHPStan отклоняют любое значение вне его. Эта страница — справочник допустимых значений для перечислений, которые вы задаёте (или получаете) через публичный API Document и Config, плюс одно перечисление цвета уровня движка (RenderingIntent), включённое потому, что его варианты — часть публичного контракта цвета и помечено как уровень движка там, где оно появляется.

Это спутник справочника по конфигурации. Там, где объект Config говорит вам, какой регулятор повернуть, эта страница говорит, какие значения этот регулятор принимает. Каждая запись приводит полностью квалифицированное имя класса (FQCN) перечисления, его базовый тип, точный список вариантов, скопированный из исходного кода, и публичный метод, который его принимает.

Глубокие внутренние для движка перечисления (макет HTML/CSS, абстрактное синтаксическое дерево, CLI, внутренности шейпера) намеренно исключены — вы их никогда не задаёте. Почти всё ниже — это значение, которое вы передаёте через публичный API; единственное исключение, RenderingIntent, — это перечисление цвета уровня движка без публичного сеттера, перечисленное для полноты и помеченное соответствующим образом там, где оно появляется.

Базовые типы

Перечисления PHP бывают двух форм, и форма меняет то, как вы пишете значение:

Backed-перечисление (enum X: string или enum X: int) имеет скалярный value для каждого варианта, поэтому оно круговым образом проходит через X::from('...') / $case->value. Большинство перечислений здесь — backed.
Pure-перечисление (enum X без базового типа) имеет варианты, но не имеет скалярного значения; вы всегда ссылаетесь на него по варианту (X::SomeCase). Только UnderlineStyle — pure.

В обеих формах вы передаёте сам вариант — например, $pdf->addPage(orientation: Orientation::Landscape). Базовый тип имеет значение только тогда, когда нужно сериализовать выбор или прочитать его обратно из конфигурации.

Настройка страницы

Orientation

Книжная или альбомная геометрия страницы. Передаётся при добавлении страницы; движок меняет местами ширину и высоту, чтобы они соответствовали.

Свойство	Значение
FQCN	`NextPDF\Contracts\Orientation`
Базовый тип	`string`
Задаётся через	`Document::addPage(?PageSize $size = null, Orientation $orientation = Orientation::Portrait)`

Вариант	Базовое значение
`Portrait`	`'P'`
`Landscape`	`'L'`

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

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

Отрисовка и графика

LineCap

Как завершается обведённый открытый контур. ISO 32000-2:2020 §8.4.3.3.

Свойство	Значение
FQCN	`NextPDF\Graphics\LineCap`
Базовый тип	`int`
Задаётся через	объект конфигурации `LineStyle` (`new LineStyle(cap: ...)`), применяемый через `Document::setLineStyle(LineStyle $style)`

Вариант	Базовое значение	Смысл
`Butt`	`0`	Квадратное окончание в конечной точке, без выступа.
`Round`	`1`	Полукруглая дуга в конечной точке.
`Square`	`2`	Квадратный выступ, выходящий за конечную точку на половину ширины линии.

LineJoin

Как два обведённых сегмента встречаются в углу. ISO 32000-2:2020 §8.4.3.4.

Свойство	Значение
FQCN	`NextPDF\Graphics\LineJoin`
Базовый тип	`int`
Задаётся через	объект конфигурации `LineStyle` (`new LineStyle(join: ...)`), применяемый через `Document::setLineStyle(LineStyle $style)`

Вариант	Базовое значение	Смысл
`Miter`	`0`	Острый угол, продлённый до предела скоса (miter limit).
`Round`	`1`	Круговая дуга, соединяющая внешние края.
`Bevel`	`2`	Диагональ, соединяющая внешние края.

LineCap и LineJoin не передаются методу Document напрямую — это поля неизменяемого объекта-значения NextPDF\Graphics\LineStyle, который вы затем передаёте в 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

Функция смешивания прозрачности, применяемая к последующей отрисовке. Первые двенадцать вариантов разделимые; последние четыре — неразделимые режимы HSL. ISO 32000-2:2020 §11.3.5.

Свойство	Значение
FQCN	`NextPDF\Graphics\BlendMode`
Базовый тип	`string`
Задаётся через	`Document::setAlpha(float $alpha, BlendMode $mode = BlendMode::Normal)`

Вариант	Базовое значение	Вариант	Базовое значение
`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');

Цвет

RenderingIntent

Как цвета за пределами охвата переотображаются во время преобразования цвета. Выдаётся как оператор ri. ISO 32000-2:2020 §8.6.5.8 (таблица 71).

В отличие от других перечислений на этой странице, у RenderingIntent нет публичного сеттера Document или Config — это перечисление уровня движка. Оно применяется прямо на внутреннем движке отрисовки (DrawingEngine::setRenderingIntent()), который выдаёт оператор ri в текущий поток содержимого. Мы перечисляем его здесь для полноты, потому что его варианты — часть публичного контракта цвета, но оно не входит в авторский API для разработчика, который документирует остальная часть этой страницы; относитесь к движку отрисовки как к внутреннему классу, а не как к точке входа, против которой вы программируете.

Свойство	Значение
FQCN	`NextPDF\Graphics\RenderingIntent`
Базовый тип	`string`
Задаётся через	Только уровень движка — применяется на внутреннем движке отрисовки; публичного сеттера Document/`Config` нет.

Вариант	Базовое значение	Смысл
`RelativeColorimetric`	`'RelativeColorimetric'`	Сохраняет цвета в охвате; отсекает цвета за пределами охвата.
`AbsoluteColorimetric`	`'AbsoluteColorimetric'`	Сохраняет колориметрические значения точно, включая белизну бумаги.
`Saturation`	`'Saturation'`	Сохраняет яркую насыщенность за счёт оттенка/яркости.
`Perceptual`	`'Perceptual'`	Сохраняет визуальные соотношения; плавное сжатие охвата.

OutputColorProfile

Цветовой профиль рабочего пространства, объявляемый в /OutputIntent документа. По умолчанию DeviceRGB сохраняет устаревшее поведение “без дополнительного OutputIntent”; выбор любого другого варианта заставляет writer выдать OutputIntent /GTS_PDFX со вложенным профилем ICC (ISO 32000-2:2020 §14.11.5). Это значение Config, а не метод на каждый вызов — задайте его на объекте конфигурации, который вы передаёте Document.

Свойство	Значение
FQCN	`NextPDF\Core\OutputColorProfile`
Базовый тип	`string`
Задаётся через	`Config::withOutputColorProfile(OutputColorProfile $profile)` (параметр `$outputColorProfile` конструктора `Config`)

Вариант	Базовое значение	Примечания
`DeviceRGB`	`'device-rgb'`	По умолчанию. Дополнительный OutputIntent не выдаётся.
`Srgb`	`'srgb'`	Явный OutputIntent sRGB (IEC 61966-2-1). Не широкий охват.
`DisplayP3`	`'display-p3'`	Широкий охват Display-P3 (D65).
`Rec2020`	`'rec2020'`	Широкий охват 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);

Текст

TextRenderingMode

Заливаются ли глифы, обводятся, отсекаются или отрисовываются невидимо (невидимый режим лежит в основе слоёв OCR с возможностью поиска). ISO 32000-2:2020 §9.3.6, таблица 104.

Свойство	Значение
FQCN	`NextPDF\Content\TextRenderingMode`
Базовый тип	`int`
Задаётся через	`Document::setTextRenderingMode(TextRenderingMode $mode)`

Вариант	Базовое значение	Смысл
`Fill`	`0`	Заливать глифы.
`Stroke`	`1`	Обводить контуры глифов.
`FillStroke`	`2`	Сначала заливать, затем обводить.
`Invisible`	`3`	Отрисовывать невидимо (слои OCR с возможностью поиска).
`FillClip`	`4`	Заливать и добавлять к контуру отсечения.
`StrokeClip`	`5`	Обводить и добавлять к контуру отсечения.
`FillStrokeClip`	`6`	Заливать, обводить и отсекать.
`Clip`	`7`	Только добавлять к контуру отсечения (без видимой отрисовки).

UnderlineStyle

Как рисуется декорация подчёркивания. Это единственное pure-перечисление здесь, поэтому вы всегда ссылаетесь на него по варианту.

Свойство	Значение
FQCN	`NextPDF\Contracts\UnderlineStyle`
Базовый тип	pure (без базового значения)
Задаётся через	`Document::setUnderlineStyle(UnderlineStyle $style)`

Вариант	Смысл
`RectFill`	Залитый прямоугольник под базовой линией (умолчание, совместимое с TCPDF).
`StrokeLine`	Обведённая линия под базовой линией (семантическая отрисовка линии).

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

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

Соответствие

ConformanceMode

Контракт соответствия уровня документа: какую часть ISO writer обязан соблюдать и требуется ли структурная разметка тегами. По умолчанию Plain — это неограниченный вывод PDF 2.0. ISO 14289-2:2024 (PDF/UA-2) и части PDF/A ISO 19005.

Свойство	Значение
FQCN	`NextPDF\Conformance\ConformanceMode`
Базовый тип	`string`
Задаётся через	`Document::setConformanceMode(ConformanceMode $mode)` (низкоуровневый аварийный выход; предпочитайте `enableTaggedPdf()` для PDF/UA-2 в Core или `enablePdfA()` — только Premium — для PDF/A)

Вариант	Базовое значение	Контракт
`Plain`	`'plain'`	PDF 2.0, без ограничений (по умолчанию).
`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).
`PdfA3b`	`'pdfa3b'`	ISO 19005-3 PDF/A-3b (Basic).
`PdfA3u`	`'pdfa3u'`	ISO 19005-3 PDF/A-3u (с извлекаемым Unicode).
`PdfA4`	`'pdfa4'`	ISO 19005-4:2020 (дискриминатор профиля PDF/A-4).
`PdfA4e`	`'pdfa4e'`	ISO 19005-4:2020 PDF/A-4e (Engineering).
`PdfA4f`	`'pdfa4f'`	ISO 19005-4:2020 PDF/A-4f (File attachments).

Перечисление несёт вспомогательные предикаты — isTagged(), isAccessibility(), isArchival() и pdfaPart() — поэтому защитные проверки на стороне writer ветвятся по режиму, а не выводят его заново.

Какие варианты сборка только из Core реально может использовать. Тип enum перечисляет каждый вариант, но перечислить вариант — не то же самое, что иметь возможность произвести это соответствие из Core:

Core (без дополнительного пакета): Plain, PdfUa1 и PdfUa2. Путь Tagged PDF / PDF/UA встроен в Core — enableTaggedPdf() выбирает авторский путь PDF/UA (PdfUa2 по умолчанию) и подключает дерево структуры без какой-либо проверки лицензии.
Только Premium: каждый вариант PDF/A (PdfA2, PdfA3, PdfA3b, PdfA3u, PdfA4, PdfA4e, PdfA4f). Реальный вывод PDF/A производится через enablePdfA(), который является возможностью уровня Premium (ADR-011): он требует пакета nextpdf/pro и завершается с ошибкой (fail closed) с InvalidConfigException (“install the nextpdf/pro package”), когда этот пакет отсутствует.

setConformanceMode() — это низкоуровневый аварийный выход, который только записывает поле дискриминатора — он не устанавливает машинерию PDF/A. Поэтому установка варианта PdfA* через него в сборке только из Core помечает документ, не давая ему архивных гарантий, которые предоставляет enablePdfA(), поэтому на режимы только Premium нельзя полагаться в сборке только из Core. Используйте enableTaggedPdf() / enablePdfA() для реальных путей соответствия и обращайтесь к пакету Premium всякий раз, когда требуется поставляемый результат PDF/A.

use NextPDF\Conformance\ConformanceMode;

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

Вложения

AFRelationship

Значение /AFRelationship для встроенного связанного файла. Несоответствующее значение не проходит валидацию PDF/A-3 и PDF/A-4, поэтому перечисление — безопасный способ его задать. ISO 32000-2:2020 §14.13.5 (таблица 401).

Свойство	Значение
FQCN	`NextPDF\Navigation\AFRelationship`
Базовый тип	`string`
Задаётся через	`Document::embedFile(string $path, string $description = '', AFRelationship\|string $afRelationship = AFRelationship::Unspecified)`

Вариант	Базовое значение	Применение
`Source`	`'Source'`	Исходный документ, из которого был произведён PDF.
`Data`	`'Data'`	Сырые данные, из которых выведен PDF (например, XML Factur-X / ZUGFeRD).
`Alternative`	`'Alternative'`	Альтернативное представление (Брайль, субтитры, SVG).
`Supplement`	`'Supplement'`	Дополнительный материал.
`EncryptedPayload`	`'EncryptedPayload'`	Непрозрачный зашифрованный блоб, который оборачивает PDF.
`FormData`	`'FormData'`	Данные формы (XFDF, FDF, XML).
`Schema`	`'Schema'`	Схема, описывающая файл `Data` (XSD, JSON Schema). PDF 2.0.
`Unspecified`	`'Unspecified'`	Связь не указана (по умолчанию).

embedFile() принимает либо вариант перечисления, либо его строковый литерал (с ведущим слешем или без него), поэтому AFRelationship::Data и '/Data' эквивалентны. Передача варианта — типобезопасный выбор.

use NextPDF\Navigation\AFRelationship;

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

См. также

Справочник по конфигурации — объект Config, чьи значения ограничивают эти перечисления, включая withOutputColorProfile().
Модуль Graphics — LineStyle, BlendMode, RenderingIntent и движок отрисовки.
Модуль Typography — отрисовка текста и декорация подчёркивания.
Модуль Conformance — дискриминатор ConformanceMode и пути включения PDF/UA / PDF/A.
Модуль Navigation — связанные файлы и механизм /AF.
Указатель справочника — точка входа в справочные материалы по API, конфигурации и совместимости.