Support: أدوات مشتركة + Clock + Sleeper

لمحة سريعة

تتضمّن وحدة ⁨Support⁩ أدوات مشتركة يستخدمها المحرّك داخليًا. كما توفّر سطحًا عموميًا صغيرًا: ساعة النظام وفق ⁨PHP Standards Recommendation 20⁩ ‏(⁨PSR-20⁩)، وخطّ أنابيب لتجميع التحذيرات، وأوّليّات تسلسل ⁨Portable Document Format⁩ ‏(⁨PDF⁩). معظم مساحة الأسماء بنية تحتية داخلية. توثّق هذه الصفحة الأجزاء التي يمكنك الاعتماد عليها، وتكتفي بالإشارة إلى الأجزاء الداخلية.

التثبيت

composer require nextpdf/core:^3

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

الساعة ‏(⁨PSR-20⁩). يُنفّذ SystemClock الواجهة Psr\Clock\ClockInterface. يُرجع الأسلوب now() الوقت الحالي بصيغة DateTimeImmutable. يُعرّف نموذج ⁨PSR-20⁩ واجهة ساعة بعملية قراءة واحدة تُرجع الوقت الحالي كقيمة تاريخ ووقت غير قابلة للتغيير ‏(⁨PSR-20⁩ psr_20_clock#2.1). SystemClock هو الإعداد الافتراضي؛ يستخدمه المحرّك عندما لا تُحقن ساعة. للحصول على وقت ثابت في الاختبارات، احقن ساعة مجمّدة تُنفّذ الواجهة نفسها. اقرن الساعة بـ Config::deterministic عندما تحتاج إلى مخرجات متطابقة على مستوى البايت.

خطّ أنابيب التحذيرات. WarningCollector هو القناة الرئيسية داخل الذاكرة لمشكلات العرض غير الفادحة. يضيف المحرّك كائن Warning لكل تدهور حتمي، مثل عمود جدول مضغوط، أو خط غير محلول، أو محرف ناقص. بعد التوليد، اقرأ التحذيرات عبر Document::getWarnings(). Warning هو كائن قيمة غير قابل للتغيير. يحمل WarningCode، وWarningSeverity ‏(warning أو degraded)، والصفحة، ونوع العنصر، ومعرّف الميزة، وراية تكافؤ متدهور، ورسالة، وDegradationImpact، ومعرّف قدرة اختياري. WarningCode هو تعداد مدعوم بسلسلة نصية من معرّفات مستقرة. تستخدم المعرّفات البادئة NEXTPDF_W_، مثل NEXTPDF_W_FONT_UNRESOLVED، بحيث يمكنك مطابقتها بأمان في الاختبارات. يفرض addWithPolicy() سياسة DegradationPolicy النشطة. في ظل سياسة صارمة، يطرح أيّ تأثير امتثالي أو دلالي أو حاجب DegradedException. في ظل سياسة متوازنة، لا يطرح إلا التأثير الحاجب. السياسة المتساهلة لا تطرح أبدًا.

أوّليّات ⁨PDF.⁩ PdfStringEscaper هو المصدر الوحيد للحقيقة لإفلات سلاسل وأسماء ⁨PDF.⁩ يُفلت escapeLiteral() المحارف المطلوبة في سلسلة ⁨PDF⁩ حرفية: الخط المائل العكسي، والأقواس، وحرف العودة إلى أول السطر ‏(⁨CR⁩)، والتغذية السطرية ‏(⁨LF⁩)، وعلامة الجدولة الأفقية ‏(⁨HT⁩)، ومسافة الرجوع للخلف ‏(⁨BS⁩)، والتغذية النموذجية ‏(⁨FF⁩). كما يزيل بايت ⁨NUL.⁩ يرمّز escapeName() البايتات ست عشريًا عندما تقع خارج نطاق المحارف القابلة للطباعة في ⁨American Standard Code for Information Interchange⁩ ‏(⁨ASCII⁩)، وكذلك البايتات ضمن مجموعة فواصل ⁨PDF⁩ لكائن اسم. BinaryBuffer هو مُراكِم ثنائي مُحسّن لكتابة كائنات ⁨PDF⁩ ودفقاتها. في وضع التدفق، يفيض إلى مقبض php://temp للمستندات الكبيرة. ويدعم أيضًا عمليات نطاق البايتات التي يحتاجها تضمين التوقيع. يحتفظ PdfOperators بسلاسل تنسيق معاملات دفق المحتوى للمسارات والنص وحالة الرسوميات والخطوط. تتشارك طبقتا الرسم والتحليل هذه السلاسل.

إنّ BinaryBuffer، وPdfOperators، ومعظم ما تبقّى من NextPDF\Support\ هي بنية تحتية داخلية. تستخدمها طبقتا الكاتب والرسم. توثّقها هذه الصفحة للاكتمال والتدقيق. إنّها ليست جزءًا من واجهة برمجة التطبيقات العمومية المدعومة ‏(⁨API⁩). اعتمد بدلًا من ذلك على واجهة Document ومساحة الأسماء Contracts. أمّا SystemClock، وWarningCollector، وWarning، وWarningCode، وWarningSeverity، وDegradationImpact فهي أعضاء موجّهة للعموم.

سطح ⁨API⁩

الرمز	النوع	إمكانية الوصول	الأعضاء الرئيسيون
NextPDF\Support\SystemClock	⁨final class⁩	⁨public⁩	now(): DateTimeImmutable ‏(⁨PSR-20⁩ ClockInterface)
NextPDF\Support\WarningCollector	⁨final class⁩	⁨public⁩	add(), emit(), addWithPolicy(), getWarnings(), hasWarnings(), hasDegradedParity(), clear()
NextPDF\Support\Warning	⁨final readonly class⁩	⁨public⁩	$code, $severity, $page, $elementType, $featureId, $degradedParity, $message, $impact, $capabilityId
NextPDF\Support\WarningCode	⁨string enum⁩	⁨public⁩	معرّفات NEXTPDF_W_* مستقرة
NextPDF\Support\WarningSeverity	⁨string enum⁩	⁨public⁩	Warning, Degraded
NextPDF\Support\DegradationImpact	⁨string enum⁩	⁨public⁩	Cosmetic, LayoutRisk, SemanticLoss, ComplianceRisk, Blocking
NextPDF\Support\PdfStringEscaper	⁨final readonly class⁩	⁨internal⁩	escapeLiteral(), escapeName() (⁨static⁩)
NextPDF\Support\BinaryBuffer	⁨final class⁩	⁨internal⁩	write(), writeStream(), replaceAt(), extract(), enableStreaming(), getContents()
NextPDF\Support\PdfOperators	⁨final class⁩	⁨internal⁩	ثوابت سلاسل تنسيق معاملات دفق المحتوى

نموذج شيفرة — بداية سريعة

اقرأ التحذيرات المجمّعة بعد التوليد.

<?php

declare(strict_types=1);

use NextPDF\Support\WarningCollector;

$collector = new WarningCollector();

// The engine appends warnings during rendering. After generation:
if ($collector->hasWarnings()) {
    foreach ($collector->getWarnings() as $warning) {
        \printf(
            "[%s] page %d: %s\n",
            $warning->code->value,
            $warning->page,
            $warning->message,
        );
    }
}

نموذج شيفرة — الإنتاج

احقن ساعة لجعل الوقت حتميًا، وتعامل مع تحذير التكافؤ المتدهور على أنّه فشل في البناء.

<?php

declare(strict_types=1);

use NextPDF\Support\SystemClock;
use NextPDF\Support\WarningCollector;
use Psr\Clock\ClockInterface;

// Production uses the real system clock.
$clock = new SystemClock();
$now = $clock->now();          // DateTimeImmutable
$epoch = $now->getTimestamp(); // int

// In tests, swap in any ClockInterface that returns a fixed instant
// (the parameter is typed to the PSR-20 interface, not SystemClock).
function buildReport(ClockInterface $clock): \DateTimeImmutable
{
    return $clock->now();
}

$collector = new WarningCollector();
// ... run generation ...
if ($collector->hasDegradedParity()) {
    throw new \RuntimeException('Output parity degraded; failing the build.');
}

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

• يُرجع SystemClock::now() كائن DateTimeImmutable جديدًا في كل استدعاء. لا تفترض أنّ استدعاءين يُرجعان اللحظة نفسها. للحصول على وقت ثابت، احقن ساعة مجمّدة.
• WarningCollector يعمل في الذاكرة وخاصّ بكل نسخة. إنّه قناة التحذير الأساسية. يُصدَر ملف ⁨JavaScript Object Notation⁩ ‏(⁨JSON⁩) الجانبي ومخرجات الخطأ القياسي ‏(⁨STDERR⁩) لواجهة سطر الأوامر ‏(⁨CLI⁩) عند حدّ المخرجات، لا من المُجمِّع نفسه.
• قد يطرح addWithPolicy() الاستثناء DegradedException في منتصف العرض في ظل سياسة صارمة. التقطه عند حدّ التوليد إذا كنت تحتاج إلى مخرجات جزئية.
• قيم WarningCode سلاسل نصية مستقرة. طابق حالة التعداد، لا نص الرسالة، فهو موجّه للقراءة البشرية وقد يتغيّر.
• BinaryBuffer::getLength() هو اسم بديل مقصود لـ getOffset() من أجل التكافؤ مع واجهة الدفق. كلاهما يُرجع عدد البايتات نفسه.
• تعامل مع PdfStringEscaper، وBinaryBuffer، وPdfOperators على أنّها بنية تحتية داخلية. إنّها غير مشمولة بوعد استقرار ⁨API⁩ العمومي.

الأداء

يُنشئ SystemClock::now() كائنًا واحدًا ويعمل بتعقيد ⁨O⁩(1). عمليات الإلحاق في WarningCollector هي دفعات إلى القائمة بتعقيد ⁨O⁩(1) مُستهلَك. يُرجع getWarnings() القائمة الداعمة. في وضع التدفق، يحتفظ BinaryBuffer بالذاكرة حتى عتبة maxmemory ‏(افتراضيًا 2 ⁨MB⁩) قبل أن يفيض إلى القرص، مما يُبقي ذروة الذاكرة ثابتة للمستندات الكبيرة. قيمة performance_budget الافتراضية لهذه الصفحة المرجعية هي wall_ms: 1500 وpeak_mb: 64.

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

استخدم سطح الساعة لإزالة اللاحتمية الزمنية الفعلية من المخرجات الموقّعة والمختومة زمنيًا عبر حقن ساعة ثابتة إلى جانب Config::deterministic. PdfStringEscaper هو المُفلِت الوحيد القابل للتدقيق لمخرجات سلاسل وأسماء ⁨PDF.⁩ مرّر كل إصدار للسلاسل عبره لمنع حقن المحتوى من خلال الأقواس أو الفواصل غير المُفلتة في النص المُقدَّم من المستخدم. قد تحمل التحذيرات تفاصيل مشتقّة من المستند، مثل أنواع العناصر ومعرّفات الميزات. نظّف مخرجات التحذير قبل تمريرها إلى وجهة سجلّ منخفضة الثقة.

المطابقة

المواصفة	البند	الموضوع
⁨PSR-20⁩ ‏(⁨PHP-FIG⁩)	psr_20_clock#2.1	عملية قراءة الساعة تُرجع تاريخًا ووقتًا غير قابلين للتغيير
⁨ISO 32000-2⁩:2020	§7.3.4.2 / §7.3.5	إفلات السلاسل الحرفية وكائنات الأسماء ‏(مُعاد صياغته؛ نص ⁨ISO⁩ غير مقتبس، ولا مقطع مثبّت)

يُنفّذ SystemClock الواجهة ClockInterface وفق ⁨PSR-20.⁩ يتّبع المُفلِت قواعد محارف السلاسل الحرفية وكائنات الأسماء في ⁨PDF.⁩ نص ⁨ISO⁩ مُعاد صياغته بموجب سياسة الاستشهاد في الموقع؛ ولا يُثبَّت أيّ مقطع حرفي.

انظر أيضًا

• /modules/core/exception/ — الاستثناء DegradedException الذي يطرحه addWithPolicy()
• /modules/core/contracts/ — DegradationPolicy، وCapability
• /modules/core/observability/ — إعادة توجيه التحذيرات والمقاييس
• /modules/core/config/ — Config::deterministic يقترن بالساعة
• /modules/core/writer/ — مستهلك داخلي لـ BinaryBuffer وPdfOperators

المسرد: ⁨PSR-20⁩ · سياسة التدهور · كائن القيمة