ValueObjects: كائنات القيمة الأساسية + الوحدات

نظرة سريعة

توفّر وحدة ⁨ValueObjects⁩ الأوّليّات الهندسية غير القابلة للتغيير المستخدمة في أنحاء المحرّك: PageSize، Dimension، Position، Margin، والتعداد Unit. كلّ واحد منها صنف final readonly. يمكنك مشاركة المثيل بحرّيّة، ويُعيد كلّ تحويل مثيلًا جديدًا.

التثبيت

composer require nextpdf/core:^3

نظرة مفاهيمية عامة

كائنات القيمة الأربعة كلّها final readonly. تخزّن إحداثيات float ولا تكشف أيّ مُعدِّلات؛ إذ تعيد طرائق التحويل بناء مثيل جديد باستخدام وسائط مُسمّاة. يمكنك تخزينها مؤقتًا وتمريرها بين المستندات ومشاركتها بين العمّال دون نسخ دفاعي.

PageSize يخزّن العرض والارتفاع (بالنقاط؛ نقطة واحدة ⁨pt⁩ = 1/72 بوصة)، إضافةً إلى الاسم. تغطّي المصانع الساكنة سلسلة ⁨A⁩ في ⁨ISO 216⁩ (A0–A6)، وسلسلة ⁨B⁩ في ⁨ISO 216⁩ (B0–B5)، والأحجام الأمريكية الشمالية (Letter، Legal، Tabloid). تتبع أبعاد ⁨A/B⁩ سلسلة أحجام الورق المقصوصة المُعرَّفة في ⁨ISO 216.⁩ يحلّ fromName() الأسماء دون حساسية لحالة الأحرف ويطرح PageLayoutException عند وجود اسم غير معروف. يعيد landscape() وportrait() متغيّر الاتّجاه، أو self عندما تكون الصفحة بهذا الاتّجاه مسبقًا. يحوّل toDimension() حجم الصفحة إلى Dimension بالنقاط.

Dimension يخزّن العرض والارتفاع وUnit. تُنشئ المصانع (fromMillimeters()، fromPoints()، fromInches()) بُعدًا بالوحدة المختارة. يحوّل toPoints() وtoMillimeters() الوحدات؛ ويعيد toPoints() القيمة self عندما يكون البُعد بالنقاط مسبقًا. يعيد withWidth() وwithHeight() نسخةً بحجم مُعدَّل. يستخدم التحويل عوامل دقيقة: 72/25.4 نقطة لكلّ مليمتر، و72/2.54 لكلّ سنتيمتر، و72 لكلّ بوصة.

Position نقطة ثنائية الأبعاد في فضاء مستخدم تنسيق المستندات المحمولة (⁨PDF⁩) (x، y). يعيد origin() القيمة (0, 0). يعيد translate(dx, dy) نسخة مُزاحة. ويعيد withX() / withY() نسخةً مع استبدال أحد المحورين.

Margin يحمل top، right، bottom، وleft. المصانع هي uniform() (القيمة نفسها على كلّ الجوانب)، وsymmetric(vertical, horizontal)، وzero().

Unit تعداد مدعوم بسلسلة: Point (pt)، وMillimeter (mm)، وCentimeter (cm)، وInch (in). يعيد toPointFactor() المُضاعِف المؤدّي إلى النقاط.

سطح واجهة برمجة التطبيقات (⁨API⁩)

الرمز	النوع	الأعضاء الرئيسيون
`NextPDF\ValueObjects\PageSize`	صنف ⁨final readonly⁩	`$width`، `$height`، `$name`؛ المصانع `A0`–`A6`، `B0`–`B5`، `Letter`، `Legal`، `Tabloid`؛ `fromName()`، `landscape()`، `portrait()`، `toDimension()`
`NextPDF\ValueObjects\Dimension`	صنف ⁨final readonly⁩	`$width`، `$height`، `$unit`؛ `fromMillimeters()`، `fromPoints()`، `fromInches()`، `toPoints()`، `toMillimeters()`، `withWidth()`، `withHeight()`
`NextPDF\ValueObjects\Position`	صنف ⁨final readonly⁩	`$x`، `$y`؛ `origin()`، `translate()`، `withX()`، `withY()`
`NextPDF\ValueObjects\Margin`	صنف ⁨final readonly⁩	`$top`، `$right`، `$bottom`، `$left`؛ `uniform()`، `symmetric()`، `zero()`
`NextPDF\ValueObjects\Unit`	تعداد سلسلة	`Point`، `Millimeter`، `Centimeter`، `Inch`؛ `toPointFactor()`

عيّنة كود — بداية سريعة

استخدم المصانع لإنشاء الأوّليّات الهندسية.

<?php

declare(strict_types=1);

use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;
use NextPDF\ValueObjects\Position;

$page = PageSize::A4();                       // 595.276 x 841.890 pt
$margin = Margin::uniform(18.0);              // 18 pt all sides
$origin = Position::origin()->translate(72.0, 72.0); // 1 inch in from corner

عيّنة كود — إنتاج

حوّل الوحدات، واشتقّ الاتّجاه، ومرّر الهوامش إلى التكوين.

<?php

declare(strict_types=1);

use NextPDF\Core\Config;
use NextPDF\ValueObjects\Dimension;
use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;

// A label sized in millimeters, resolved to points for the engine.
$label = Dimension::fromMillimeters(width: 100.0, height: 150.0)->toPoints();

$page = PageSize::A4()->landscape();   // swap to width >= height
$margin = Margin::symmetric(vertical: 20.0, horizontal: 15.0);

$config = (new Config())
    ->withPageSize($page)
    ->withMargins($margin);

// $label->width / $label->height are now in points for downstream layout.

الحالات الحدّية والمزالق

تستخدم كلّ الأبعاد النقاط ما لم تُوفّر Dimension بوحدة Unit صريحة. تستخدم Config النقاط افتراضيًّا للهوامش.
يعيد PageSize::landscape() / portrait() المثيل نفسه عندما يطابق الاتّجاه مسبقًا؛ فلا يحدث أيّ تخصيص، ويُحفَظ التطابق المرجعي.
يتجاهل PageSize::fromName() حالة الأحرف، لكنّه لا يحلّ إلا المصانع المُسمّاة. يطرح الاسم غير المعروف PageLayoutException، لا حجمًا افتراضيًّا.
يعيد Dimension::toPoints() القيمة self عندما تكون الوحدة Point مسبقًا؛ لا تفترض إنشاء كائن جديد.
تحمل هذه الكائنات قيم float خامًا ولا تطبّق أيّ تحقّق من النطاق. تقبل أبعادًا سالبة أو صفرية عند الإنشاء. تفرض طبقتا التخطيط والكاتب صحّة الهندسة، لا هذه الكائنات.
يستخدم التحويل ذو الفاصلة العائمة عوامل نسبية دقيقة (72/25.4، 72/2.54)؛ قرّب فقط عند حدّ العرض للحفاظ على ثبات المخرجات القابلة لإعادة الإنتاج.

الأداء

كلّ كائن قيمة هو بنية readonly مسطّحة من قيم عائمة. الإنشاء وكلّ تحويل عمليتا تخصيص مفردتان بزمن ⁨O⁩(1)، دون نسخ عميق لعدم وجود حالة قابلة للتغيير متداخلة. يمكنك مشاركة مثيل بين المستندات دون تكلفة إضافية. القيمة الافتراضية لـ performance_budget في صفحة المرجع هذه هي wall_ms: 1500، peak_mb: 64.

ملاحظات أمنية

لا تُجري كائنات القيمة هذه أيّ ⁨input/output⁩ (⁨I/O⁩)، ولا تحمل سلاسل من إدخال المستخدم سوى اسم حجم الصفحة، ولا تحمل مقابض موارد خارجية؛ لذلك لا تمثّل أيّ سطح هجوم مباشر. يرفض PageSize::fromName() المدخلات غير المعروفة باستثناء بدلًا من التراجع بصمت، فيفشل التكوين المُشوَّه صراحةً بدلًا من إنتاج هندسة صفحة غير متوقّعة.

المطابقة

المعيار	البند	الموضوع
⁨ISO 216⁩:2007	سلسلتا ⁨A⁩ / ⁨B⁩	أبعاد أحجام الورق المقصوصة لمصانع `A` / `B` (مُعاد صياغته؛ نصّ ⁨ISO⁩ غير مُقتبَس، ولا مقطع مُثبَّت)

تطابق أبعاد مصانع ⁨A⁩ و ⁨B⁩ الأحجام المقصوصة لـ ⁨ISO 216⁩، مُعبَّرًا عنها بالنقاط. الأحجام الأمريكية الشمالية (Letter، Legal، Tabloid) أحجام صناعية بحكم الأمر الواقع دون أساس ⁨ISO.⁩ مرجع ⁨ISO⁩ مُعاد صياغته بموجب سياسة الاقتباس للموقع. لا يوجد مقطع مُقتبَس حرفيًّا مُثبَّت.

انظر أيضًا

/modules/core/config/ — Config يستخدم PageSize وMargin
/modules/core/layout/ — مستهلكو التخطيط لهذه الأوّليّات
/modules/core/graphics/ — Position في فضاء إحداثيات الرسم
/modules/core/contracts/ — Orientation مع PageSize
/modules/core/exception/ — PageLayoutException من fromName()