เอกสารอ้างอิงอีนัม

ภาพรวมโดยสังเขป

เมธอด authoring หลายตัวของ NextPDF รับ enum แบบมีชนิด แทนสตริงหรือจำนวนเต็มเปล่า อีนัมคือสัญญา: มันจำกัดอาร์กิวเมนต์ให้อยู่ในชุดที่แน่นอนและถูกต้อง และ IDE กับ PHPStan จะปฏิเสธค่าใดที่อยู่นอกชุดนั้น หน้านี้คือที่ค้นหาค่าที่อนุญาตสำหรับอีนัมที่คุณตั้ง (หรือรับ) ผ่าน API สาธารณะของ Document และ Config — บวกกับอีนัมสีระดับเอนจินหนึ่งตัว (RenderingIntent) ที่รวมไว้เพราะเคสของมันเป็นส่วนหนึ่งของสัญญาสีสาธารณะ และถูกระบุว่าเป็นระดับเอนจินตรงที่มันปรากฏ

นี่คือคู่หูของเอกสารอ้างอิงการกำหนดค่า ขณะที่อ็อบเจกต์ Config บอกคุณว่า ปุ่มใด ที่ต้องหมุน หน้านี้บอกคุณว่า ปุ่มนั้นรับค่าใดบ้าง แต่ละรายการระบุชื่อคลาสแบบเต็ม (FQCN) ของอีนัม ชนิดเบื้องหลัง รายการเคสที่แน่นอนซึ่งคัดลอกมาจากซอร์ส และเมธอดสาธารณะที่รับค่านั้น

อีนัมระดับลึกภายในเอนจิน (HTML/CSS layout, abstract syntax tree, CLI, ภายในของ shaper) ถูกตัดออกโดยเจตนา — คุณไม่เคยตั้งค่าเหล่านั้น เกือบทุกอย่างด้านล่างคือค่าที่คุณส่งเข้าผ่าน API สาธารณะ ข้อยกเว้นหนึ่งเดียวคือ RenderingIntent ซึ่งเป็นอีนัมสีระดับเอนจินที่ไม่มี setter สาธารณะ ระบุไว้เพื่อความครบถ้วนและกำกับไว้เช่นนั้นตรงที่มันปรากฏ

ชนิดเบื้องหลัง

อีนัมของ PHP มีสองรูปแบบ และรูปแบบเปลี่ยนวิธีที่คุณเขียนค่า:

อีนัมแบบ backed (enum X: string หรือ enum X: int) มี value แบบ scalar สำหรับทุกเคส จึงไป-กลับผ่าน X::from('...') / $case->value ได้ อีนัมส่วนใหญ่ในที่นี้เป็นแบบ backed
อีนัมแบบ pure (enum X ที่ไม่มีชนิดเบื้องหลัง) มีเคสแต่ไม่มีค่า scalar คุณอ้างถึงมันด้วยเคสเสมอ (X::SomeCase) มีเพียง UnderlineStyle เท่านั้นที่เป็นแบบ pure

ในทั้งสองรูปแบบ คุณส่งตัวเคสเอง — ตัวอย่างเช่น $pdf->addPage(orientation: Orientation::Landscape) ชนิดเบื้องหลังสำคัญเฉพาะเมื่อคุณต้อง serialize ตัวเลือกนั้นหรืออ่านกลับจากการกำหนดค่า

การตั้งค่าหน้า

Orientation

เรขาคณิตหน้าแบบ portrait หรือ landscape ส่งเข้าตอนเพิ่มหน้า เอนจินจะสลับความกว้างและความสูงให้ตรงกัน

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);

การวาดและกราฟิก

LineCap

วิธีที่ open path ที่ถูก stroke สิ้นสุดลง ISO 32000-2:2020 §8.4.3.3

Property	Value
FQCN	`NextPDF\Graphics\LineCap`
Backing	`int`
Set via	อ็อบเจกต์กำหนดค่า `LineStyle` (`new LineStyle(cap: ...)`) นำไปใช้ด้วย `Document::setLineStyle(LineStyle $style)`

Case	Backing value	Meaning
`Butt`	`0`	ปลายฉากที่จุดสิ้นสุด ไม่มีการยื่นออก
`Round`	`1`	ส่วนโค้งครึ่งวงกลมที่จุดสิ้นสุด
`Square`	`2`	การยื่นแบบฉากออกไปครึ่งหนึ่งของความกว้างเส้นเลยจุดสิ้นสุด

LineJoin

วิธีที่ส่วนเส้นที่ถูก stroke สองส่วนมาบรรจบกันที่มุม ISO 32000-2:2020 §8.4.3.4

Property	Value
FQCN	`NextPDF\Graphics\LineJoin`
Backing	`int`
Set via	อ็อบเจกต์กำหนดค่า `LineStyle` (`new LineStyle(join: ...)`) นำไปใช้ด้วย `Document::setLineStyle(LineStyle $style)`

Case	Backing value	Meaning
`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

ฟังก์ชัน blend แบบโปร่งใสที่นำไปใช้กับการวาดถัดไป สิบสองเคสแรกเป็นแบบ separable ส่วนสี่เคสสุดท้ายเป็นโหมด HSL แบบ non-separable 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');

สี

RenderingIntent

วิธีที่สีนอก gamut ถูกแมปใหม่ระหว่างการแปลงสี ปล่อยออกมาเป็นตัวดำเนินการ ri ISO 32000-2:2020 §8.6.5.8 (Table 71)

ต่างจากอีนัมอื่นในหน้านี้ RenderingIntent ไม่มี setter สาธารณะของ Document หรือ Config — มันเป็นอีนัม ระดับเอนจิน มันถูกนำไปใช้โดยตรงบนเอนจินการวาดภายใน (DrawingEngine::setRenderingIntent()) ซึ่งปล่อยตัวดำเนินการ ri เข้าไปใน content stream ปัจจุบัน เราระบุไว้ที่นี่เพื่อความครบถ้วนเพราะเคสของมันเป็นส่วนหนึ่งของสัญญาสีสาธารณะ แต่มันไม่ใช่ส่วนหนึ่งของ authoring API ที่นักพัฒนาใช้งานซึ่งหน้าที่เหลือนี้บันทึกไว้ ให้ถือว่าเอนจินการวาดเป็นคลาสภายใน ไม่ใช่จุดเข้าใช้งานที่คุณเขียนโปรแกรมต่อ

Property	Value
FQCN	`NextPDF\Graphics\RenderingIntent`
Backing	`string`
Set via	ระดับเอนจินเท่านั้น — นำไปใช้บนเอนจินการวาดภายใน ไม่มี setter สาธารณะของ Document/`Config`

Case	Backing value	Meaning
`RelativeColorimetric`	`'RelativeColorimetric'`	คงสีใน gamut clip สีนอก gamut
`AbsoluteColorimetric`	`'AbsoluteColorimetric'`	คงค่า colorimetric ไว้อย่างแม่นยำ รวมถึงสีขาวของกระดาษ
`Saturation`	`'Saturation'`	คงความอิ่มตัวที่สดใสโดยแลกกับ hue/luminance
`Perceptual`	`'Perceptual'`	คงความสัมพันธ์ทางสายตา การบีบอัด gamut แบบลื่นไหล

OutputColorProfile

โปรไฟล์สีของพื้นที่ทำงานที่ประกาศบน /OutputIntent ของเอกสาร ค่าเริ่มต้น DeviceRGB คงพฤติกรรม “ไม่มี OutputIntent เพิ่ม” แบบเดิม การเลือกเคสอื่นใดทำให้ตัวเขียนปล่อย /GTS_PDFX OutputIntent พร้อมโปรไฟล์ ICC ที่มากับชุด (ISO 32000-2:2020 §14.11.5) นี่เป็นค่า Config ไม่ใช่เมธอดต่อการเรียก — ตั้งบนอ็อบเจกต์การกำหนดค่าที่คุณส่งเข้า Document

Property	Value
FQCN	`NextPDF\Core\OutputColorProfile`
Backing	`string`
Set via	`Config::withOutputColorProfile(OutputColorProfile $profile)` (พารามิเตอร์ `$outputColorProfile` ของคอนสตรักเตอร์ `Config`)

Case	Backing value	Notes
`DeviceRGB`	`'device-rgb'`	ค่าเริ่มต้น ไม่มีการปล่อย OutputIntent เพิ่ม
`Srgb`	`'srgb'`	sRGB OutputIntent แบบชัดเจน (IEC 61966-2-1) ไม่ใช่ 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);

ข้อความ

TextRenderingMode

กลีฟถูกเติม stroke clip หรือเรนเดอร์แบบมองไม่เห็น (โหมดมองไม่เห็นเป็นพื้นฐานของชั้น OCR ที่ค้นหาได้) 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`	เติมกลีฟ
`Stroke`	`1`	stroke เส้นขอบกลีฟ
`FillStroke`	`2`	เติมแล้วจึง stroke
`Invisible`	`3`	เรนเดอร์แบบมองไม่เห็น (ชั้น OCR ที่ค้นหาได้)
`FillClip`	`4`	เติมและเพิ่มเข้า clipping path
`StrokeClip`	`5`	stroke และเพิ่มเข้า clipping path
`FillStrokeClip`	`6`	เติม stroke และ clip
`Clip`	`7`	เพิ่มเข้า clipping path เท่านั้น (ไม่มีการเรนเดอร์ที่มองเห็น)

UnderlineStyle

วิธีที่ตกแต่งขีดเส้นใต้ถูกวาด นี่คืออีนัม pure เพียงตัวเดียวในที่นี้ คุณจึงอ้างถึงมันด้วยเคสเสมอ

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

Case	Meaning
`RectFill`	สี่เหลี่ยมที่เติมสีใต้เส้นฐาน (ค่าเริ่มต้นที่เข้ากันได้กับ TCPDF)
`StrokeLine`	เส้นที่ stroke ใต้เส้นฐาน (การวาดเส้นเชิงความหมาย)

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

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

ความสอดคล้องตามมาตรฐาน

ConformanceMode

สัญญาความสอดคล้องระดับเอกสาร: ส่วน ISO ใดที่ตัวเขียนต้องเคารพ และจำเป็นต้องมีการ tag เชิงโครงสร้างหรือไม่ ค่าเริ่มต้น Plain คือผลลัพธ์ PDF 2.0 แบบไม่ถูกจำกัด ISO 14289-2:2024 (PDF/UA-2) และส่วน PDF/A ของ ISO 19005

Property	Value
FQCN	`NextPDF\Conformance\ConformanceMode`
Backing	`string`
Set via	`Document::setConformanceMode(ConformanceMode $mode)` (escape hatch ระดับล่าง ให้เลือกใช้ `enableTaggedPdf()` สำหรับ PDF/UA-2 ใน Core หรือ `enablePdfA()` — Premium เท่านั้น — สำหรับ PDF/A)

Case	Backing value	Contract
`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 profile discriminator)
`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 (PDF/A-4 profile discriminator)
`PdfA4e`	`'pdfa4e'`	ISO 19005-4:2020 PDF/A-4e (Engineering)
`PdfA4f`	`'pdfa4f'`	ISO 19005-4:2020 PDF/A-4f (File attachments)

อีนัมพก predicate helper มาด้วย — isTagged(), isAccessibility(), isArchival() และ pdfaPart() — เพื่อให้ gate ฝั่งตัวเขียนแตกแขนงตามโหมด แทนการ derive ใหม่

เคสใดที่ build แบบ Core-only ใช้ได้จริง ชนิด enum ระบุทุกเคส แต่การระบุเคสไม่เท่ากับการ สร้าง ความสอดคล้องนั้นจาก Core ได้:

Core (ไม่มีแพ็กเกจเพิ่ม): Plain, PdfUa1 และ PdfUa2 เส้นทาง Tagged PDF / PDF/UA ถูกสร้างไว้ใน Core — enableTaggedPdf() เลือกเส้นทาง authoring PDF/UA (PdfUa2 โดยค่าเริ่มต้น) และเดินสาย structure tree โดยไม่มีการตรวจสอบสิทธิ์ใช้งาน
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() เป็น escape hatch ระดับล่างที่เขียนเฉพาะฟิลด์ discriminator เท่านั้น — มัน ไม่ ติดตั้งกลไก PDF/A การตั้งเคส PdfA* ผ่านมันใน build แบบ Core-only จึงเป็นการ label เอกสารโดยไม่ให้การรับประกันการเก็บถาวรที่ enablePdfA() มอบให้ ดังนั้นโหมด Premium เท่านั้นจึง ต้องไม่ ถูกพึ่งพาใน build แบบ Core-only ให้ใช้ enableTaggedPdf() / enablePdfA() สำหรับเส้นทางความสอดคล้องจริง และหันไปใช้แพ็กเกจ Premium ทุกครั้งที่ต้องการส่งมอบ PDF/A

use NextPDF\Conformance\ConformanceMode;

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

ไฟล์แนบ

AFRelationship

ค่า /AFRelationship สำหรับไฟล์ associated ที่ฝัง ค่าที่ไม่สอดคล้องจะทำให้การตรวจสอบ PDF/A-3 และ PDF/A-4 ล้มเหลว อีนัมจึงเป็นวิธีที่ปลอดภัยในการตั้งค่านี้ 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'`	เอกสารต้นทางที่ใช้สร้าง PDF
`Data`	`'Data'`	ข้อมูลดิบที่ PDF ได้มาจาก (เช่น Factur-X / ZUGFeRD XML)
`Alternative`	`'Alternative'`	การนำเสนอแบบทางเลือก (braille, captions, SVG)
`Supplement`	`'Supplement'`	สื่อประกอบเพิ่มเติม
`EncryptedPayload`	`'EncryptedPayload'`	blob ที่เข้ารหัสแบบทึบซึ่ง PDF ห่อหุ้มไว้
`FormData`	`'FormData'`	ข้อมูลฟอร์ม (XFDF, FDF, XML)
`Schema`	`'Schema'`	schema ที่อธิบายไฟล์ `Data` (XSD, JSON Schema) PDF 2.0
`Unspecified`	`'Unspecified'`	ไม่ระบุความสัมพันธ์ (ค่าเริ่มต้น)

embedFile() รับได้ทั้งเคสอีนัมหรือสตริงลิเทอรัลของมัน (มีหรือไม่มี slash นำหน้า) ดังนั้น 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 — discriminator ConformanceMode และเส้นทาง enable ของ PDF/UA / PDF/A
โมดูล Navigation — ไฟล์ associated และกลไก /AF
ดัชนีอ้างอิง — จุดเข้าใช้งานสำหรับเอกสารอ้างอิง API การกำหนดค่า และความเข้ากันได้