مرجع التعدادات

لمحة سريعة

تأخذ عدّة توابع تأليف في ⁨NextPDF⁩ تعدادًا (‏enum) مُحدَّد النوع بدلًا من سلسلة أو عددٍ صحيح مجرَّد. التعداد هو العقد: فهو يقيّد الوسيطة بمجموعة ثابتة وصالحة، وترفض بيئة التطوير المتكاملة و⁨PHPStan⁩ أيّ قيمة خارجها. هذه الصفحة هي مرجع البحث عن القيم المسموح بها للتعدادات التي تضبطها (أو تتلقّاها) عبر واجهة ⁨API⁩ العامة للمستند و‏Config — إضافةً إلى تعداد لونٍ واحد على مستوى المحرّك (‏RenderingIntent)، أُدرِج لأنّ حالاته جزء من عقد اللون العام ومُعلَّم بأنّه على مستوى المحرّك حيثما ظهر.

هذه الصفحة هي رفيقة مرجع الإعداد. فحيث يخبرك كائن Config بأيِّ مفتاح تُديره، تخبرك هذه الصفحة بأيِّ قيمٍ يقبلها ذلك المفتاح. يَسرُد كلّ مدخل اسم صنف التعداد المؤهَّل بالكامل (‏FQCN)، ونوعه الداعم، وقائمة الحالات الدقيقة المنسوخة من المصدر، والتابع العام الذي يأخذه.

أمّا التعدادات الداخلية العميقة للمحرّك (تخطيط ⁨HTML/CSS⁩، وشجرة الصياغة المجرَّدة، وواجهة سطر الأوامر، ودواخل المُشكِّل) فمُستبعَدة عمدًا — فأنت لا تضبطها أبدًا. وكلّ ما هو أدناه تقريبًا قيمةٌ تمرّرها عبر واجهة ⁨API⁩ العامة؛ والاستثناء الوحيد، ‏RenderingIntent، تعداد لونٍ على مستوى المحرّك بلا ضابط عام، أُدرِج للاكتمال ومُعلَّم بذلك حيثما ظهر.

الأنواع الداعمة

تأتي تعدادات ⁨PHP⁩ في شكلين، ويغيّر الشكل كيفية كتابتك للقيمة:

التعداد المدعوم (‏enum X: string أو enum X: int) له قيمة value عدديةٌ لكلّ حالة، فيتنقّل ذهابًا وإيابًا عبر X::from('...') / $case->value. ومعظم التعدادات هنا مدعومة.
التعداد الخالص (‏enum X بلا نوع داعم) له حالات لكن بلا قيمة عددية؛ تشير إليه دائمًا بحالته (‏X::SomeCase). و‏UnderlineStyle وحده خالص.

في كلا الشكلين تمرّر الحالة نفسها — مثلًا ‏$pdf->addPage(orientation: Orientation::Landscape). ولا يهمّ النوع الداعم إلّا عندما تحتاج إلى تسلسل الاختيار أو قراءته من جديد من الإعداد.

إعداد الصفحة

Orientation

هندسة الصفحة عموديةً أو أفقيةً. تُمرَّر عند إضافتك صفحةً؛ ويبدّل المحرّك العرض والارتفاع لتطابقها.

الخاصّية	القيمة
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

كيف ينتهي مسارٌ مفتوحٌ مرسومٌ بالحدّ. ‏⁨ISO 32000-2⁩:2020 §8.4.3.3.

الخاصّية	القيمة
FQCN	`NextPDF\Graphics\LineCap`
Backing	`int`
Set via	the `LineStyle` config object (`new LineStyle(cap: ...)`), applied with `Document::setLineStyle(LineStyle $style)`

Case	Backing value	المعنى
`Butt`	`0`	نهاية مربّعة عند نقطة النهاية، بلا بروز.
`Round`	`1`	قوس نصف دائري عند نقطة النهاية.
`Square`	`2`	بروز مربّع يمتدّ نصف عرض الخطّ خلف نقطة النهاية.

LineJoin

كيف يلتقي قطعتان مرسومتان بالحدّ عند زاوية. ‏⁨ISO 32000-2⁩:2020 §8.4.3.4.

الخاصّية	القيمة
FQCN	`NextPDF\Graphics\LineJoin`
Backing	`int`
Set via	the `LineStyle` config object (`new LineStyle(join: ...)`), applied with `Document::setLineStyle(LineStyle $style)`

Case	Backing value	المعنى
`Miter`	`0`	زاوية حادّة ممتدّة إلى حدّ الميتر.
`Round`	`1`	قوس دائري يَصِل الحوافّ الخارجية.
`Bevel`	`2`	خطٌّ قُطري يَصِل الحوافّ الخارجية.

لا يُمرَّر LineCap وLineJoin إلى تابع مستندٍ مباشرةً — بل هما حقلان في كائن القيمة غير القابل للتغيير 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`
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

كيف تُعاد مواءمة الألوان الخارجة عن النطاق اللوني أثناء تحويل اللون. تُصدَر بوصفها المُعامِل ri. ‏⁨ISO 32000-2⁩:2020 §8.6.5.8 (Table 71).

بخلاف بقية التعدادات في هذه الصفحة، ليس لـRenderingIntent ضابطٌ عامٌّ في المستند أو في Config — فهو تعدادٌ على مستوى المحرّك. يُطبَّق مباشرةً على محرّك الرسم الداخلي (‏DrawingEngine::setRenderingIntent())، الذي يُصدِر المُعامِل ‏ri في مجرى المحتوى الحالي. ونَسرُده هنا للاكتمال لأنّ حالاته جزءٌ من عقد اللون العام، لكنّه ليس جزءًا من واجهة التأليف الموجَّهة للمطوِّرين التي توثّقها بقية هذه الصفحة؛ عامِل محرّك الرسم بوصفه صنفًا داخليًّا لا نقطة الدخول التي تبرمج تجاهها.

الخاصّية	القيمة
FQCN	`NextPDF\Graphics\RenderingIntent`
Backing	`string`
Set via	Engine-level only — applied on the internal drawing engine; no public Document/`Config` setter.

Case	Backing value	المعنى
`RelativeColorimetric`	`'RelativeColorimetric'`	حافِظ على الألوان داخل النطاق؛ واقطع ما خرج عنه.
`AbsoluteColorimetric`	`'AbsoluteColorimetric'`	حافِظ على القيم القياسية اللونية بدقّة، بما فيها بياض الورق.
`Saturation`	`'Saturation'`	حافِظ على الإشباع الزاهي على حساب التدرّج/الإضاءة.
`Perceptual`	`'Perceptual'`	حافِظ على العلاقات البصرية؛ بضغطٍ سلسٍ للنطاق اللوني.

OutputColorProfile

ملفّ تعريف لون مساحة العمل المُصرَّح به في /OutputIntent الخاصّ بالمستند. يحافظ الافتراضي DeviceRGB على سلوك “بلا OutputIntent إضافي” الموروث؛ ويجعل اختيار أيّ حالة أخرى الكاتب يُصدِر OutputIntent من نوع /GTS_PDFX بملفّ تعريف ⁨ICC⁩ المرفق (‏⁨ISO 32000-2⁩:2020 §⁨14.11.5⁩). هذه قيمة Config، لا تابعٌ لكلّ استدعاء — اضبطها على كائن الإعداد الذي تمرّره إلى المستند.

الخاصّية	القيمة
FQCN	`NextPDF\Core\OutputColorProfile`
Backing	`string`
Set via	`Config::withOutputColorProfile(OutputColorProfile $profile)` (the `Config` constructor’s `$outputColorProfile` parameter)

Case	Backing value	ملاحظات
`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⁩، ‏Table 104.

الخاصّية	القيمة
FQCN	`NextPDF\Content\TextRenderingMode`
Backing	`int`
Set via	`Document::setTextRenderingMode(TextRenderingMode $mode)`

Case	Backing value	المعنى
`Fill`	`0`	املأ المحارف.
`Stroke`	`1`	ارسم مخطّطات المحارف بالحدّ.
`FillStroke`	`2`	املأ ثمّ ارسم بالحدّ.
`Invisible`	`3`	اعرض على نحوٍ غير مرئي (طبقات OCR قابلة للبحث).
`FillClip`	`4`	املأ وأضِف إلى مسار القصّ.
`StrokeClip`	`5`	ارسم بالحدّ وأضِف إلى مسار القصّ.
`FillStrokeClip`	`6`	املأ وارسم بالحدّ واقصّ.
`Clip`	`7`	أضِف إلى مسار القصّ فقط (بلا عرضٍ مرئي).

UnderlineStyle

كيف يُرسَم زخرف التسطير. هذا هو التعداد الخالص الوحيد هنا، فتشير إليه دائمًا بحالته.

الخاصّية	القيمة
FQCN	`NextPDF\Contracts\UnderlineStyle`
Backing	pure (no backing value)
Set via	`Document::setUnderlineStyle(UnderlineStyle $style)`

Case	المعنى
`RectFill`	مستطيل مملوء أسفل خطّ الأساس (الافتراضي المتوافق مع ⁨TCPDF⁩).
`StrokeLine`	خطٌّ مرسومٌ بالحدّ أسفل خطّ الأساس (رسم خطٍّ دلالي).

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

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

المطابقة

ConformanceMode

عقد المطابقة على مستوى المستند: أيّ جزءٍ من ⁨ISO⁩ يجب أن يُكرّمه الكاتب، وهل التوسيم البنيوي مطلوب. الافتراضي Plain هو إخراج ⁨PDF 2.0⁩ غير المقيَّد. ‏ISO 14289-2:2024 (⁨PDF/UA-2⁩) وأجزاء ⁨PDF/A⁩ من ⁨ISO 19005⁩.

الخاصّية	القيمة
FQCN	`NextPDF\Conformance\ConformanceMode`
Backing	`string`
Set via	`Document::setConformanceMode(ConformanceMode $mode)` (lower-level escape hatch; prefer `enableTaggedPdf()` for PDF/UA-2 in Core, or `enablePdfA()` — Premium-only — for PDF/A)

Case	Backing value	العقد
`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() — كي تتفرّع بوّابات جانب الكاتب على النمط بدلًا من إعادة اشتقاقه.

أيّ الحالات يمكن لبناءٍ من النواة فقط استخدامها فعليًّا. يَسرُد نوع enum كلّ حالة، لكنّ سرد حالةٍ ليس كالقدرة على إنتاج تلك المطابقة من النواة:

النواة (بلا حزمة إضافية): Plain وPdfUa1 وPdfUa2. فمسار ⁨Tagged PDF⁩ / ⁨PDF/UA⁩ مبنيٌّ داخل النواة — يختار enableTaggedPdf() مسار تأليف ⁨PDF/UA⁩ (‏PdfUa2 افتراضيًّا) ويوصِّل شجرة البنية دون أيّ فحص ترخيص.
الحصري للنسخة المميَّزة: كلّ حالات ⁨PDF/A⁩ (‏PdfA2 وPdfA3 وPdfA3b وPdfA3u وPdfA4 وPdfA4e وPdfA4f). يُنتَج إخراج ⁨PDF/A⁩ الحقيقي عبر ‏enablePdfA()، وهي ميزةٌ من فئة النسخة المميَّزة (‏ADR-011): تتطلّب حزمة ‏nextpdf/pro وتفشل بأمانٍ مغلق برمي InvalidConfigException (“‏install the nextpdf/pro package”) عند غياب تلك الحزمة.

‏setConformanceMode() مَخرَجٌ على مستوًى أدنى لا يكتب إلّا حقل المميِّز — فهو لا يثبّت آلِيّة ⁨PDF/A⁩. وضبط حالة PdfA* عبره في بناءٍ من النواة فقط يَسِم المستند بالتالي دون منحه ضمانات الأرشفة التي يوفّرها enablePdfA()، فيجب ألّا يُعتمَد على الأنماط الحصرية للنسخة المميَّزة في بناءٍ من النواة فقط. استخدم ‏enableTaggedPdf() / enablePdfA() لمسارات المطابقة الحقيقية، والجأ إلى الحزمة المميَّزة كلّما لزم تسليم ⁨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⁩ (Table 401).

الخاصّية	القيمة
FQCN	`NextPDF\Navigation\AFRelationship`
Backing	`string`
Set via	`Document::embedFile(string $path, string $description = '', AFRelationship\|string $afRelationship = AFRelationship::Unspecified)`

Case	Backing value	الاستخدام
`Source`	`'Source'`	المستند المصدر الذي أُنتِج منه ملف PDF.
`Data`	`'Data'`	بيانات خام اشتُقّ منها ملف PDF (مثل Factur-X / ZUGFeRD XML).
`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().
وحدة الرسوميات — LineStyle وBlendMode وRenderingIntent ومحرّك الرسم.
وحدة الطباعة — عرض النصّ وزخرف التسطير.
وحدة المطابقة — مميِّز ConformanceMode ومسارا تمكين ⁨PDF/UA⁩ / ⁨PDF/A⁩.
فهرس المرجع — نقطة الدخول إلى مواد مرجع واجهة ⁨API⁩ والإعداد والتوافق.