PageBackfill: مخزَّن الصفحات المحتفَظ به

لمحة سريعة

معاينة اختيارية. مخزَّن الصفحات المحتفَظ به مُعطَّل افتراضيًا. ومع إيقافه، يكون الكاتب المُسلسِل التدفّقي كما كان دائمًا — متطابق بايتًا ببايت. فعِّله فقط عندما تحتاج فعلًا إلى الرسم على صفحة سابقة، واقرأ قائمة الإغلاق الآمن أدناه أولًا.

افتراضيًا، يُدفِّق الكاتب الصفحات ويُفرِّغها بالترتيب؛ وبمجرّد تفريغ صفحة لا يمكن الرسم عليها مرّةً أخرى. ومخزَّن الصفحات المحتفَظ به هو الخيار الاختياري الذي يحتفظ بالصفحات المُفرَّغة بحيث يمكن إعادة ملء صفحة سبق تفريغها — الرسم على صفحة سابقة — قبل تسلسل المستند. والاستخدام الكلاسيكي هو مجموع أو صندوق ملخّص لا يمكنك وضعه إلا بعد تخطيط الصفحات اللاحقة.

التثبيت

composer require nextpdf/core:^3

يُشحَن مخزَّن الصفحات المحتفَظ به في حزمة core. Config::withRetainedPageBuffer() ودوال إعادة الملء في Document هي @since 6.1.0. ويبقى الافتراضي هو الكاتب التدفّقي. وADR-037، الذي كان قد أجّل هذه القدرة سابقًا، صار الآن مُسجَّلًا كمُطبَّق.

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

Config::withRetainedPageBuffer() يُدخِل المستند في الصفحات المحتفَظ بها. وبمجرّد التفعيل، يُعيد Document::setActiveBackfillPage(int $pageIndex) توجيه الرسم إلى صفحة سابقة سبق تفريغها؛ ويُعيد Document::endPageBackfill() الرسم إلى موضع الإلحاق العادي. والمحتوى الذي تكتبه بين الاستدعاءين يقع على الصفحة السابقة. ويحتفظ المخزَّن بالصفحات حتى save()، فتُطبَّق إعادة الملء قبل كتابة جدول المراجع المتقاطعة والمقطورة (⁨ISO 32000-2⁩ §⁨7.5⁩).

حدّ الإغلاق الآمن — التركيبات المرفوضة

إعادة الملء عملية ذات وصول عشوائي، وتفترض عدّة ميزات مستند بايتات مُدفَّقة بالإلحاق فقط. ويرفض مخزَّن الصفحات المحتفَظ به الاقتران بأيٍّ منها، بصرف النظر عن الترتيب وقبل التسلسل، فلا يمكنه أبدًا أن يكسر توقيعًا أو ادّعاء مطابقة بصمت:

• توقيع رقمي.
• ⁨PDF⁩ موسوم (شجرة بنية).
• PDF/A.
• الخطّية.
• حزم تدفّقات الكائنات.
• التعمية.
• وضع تصيير ⁨CSS⁩ الآمن.

تحدّ ميزانية بايتات غير مضغوطة لكل مستند مقدار ما قد يحتفظ به المخزَّن؛ وأي مستند يتجاوزها يفشل بصرامة بدلًا من استهلاك ذاكرة غير محدودة. ولا يزال الافتراضي التدفّقي يُغلَق بأمان لحظة محاولة المُستدعي تبديلًا بوصول عشوائي دون الخيار الاختياري — فتفعيل المخزَّن هو السبيل الوحيد للحصول على إعادة الملء، وهو غير متوافق مع الميزات أعلاه بنية.

سطح الـ ⁨API⁩

الرمز	الموقع	الدور
Config::withRetainedPageBuffer(bool $enabled = true): self	src/Core/Config.php	يُدخِل المستند في مخزَّن الصفحات المحتفَظ به.
Document::setActiveBackfillPage(int $pageIndex): static	src/Core/Document.php	يُعيد توجيه الرسم إلى صفحة سابقة سبق تفريغها.
Document::endPageBackfill(): static	src/Core/Document.php	يُعيد الرسم إلى موضع الإلحاق العادي.

أي محاولة إعادة ملء تنتهك تركيبة مرفوضة تطرح استثناء تهيئة مُحدَّد النوع عند الحدّ، لا مستندًا تالفًا.

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

احجز موضعًا في الصفحة الأولى، واملأ بقية المستند، ثم أعِد ملء الموضع المحجوز بقيمة تُحسَب في النهاية.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Config;
use NextPDF\Core\Document;

$config = (new Config())->withRetainedPageBuffer();

$doc = Document::createStandalone($config);
$doc->addPage();                 // page 0 — leaves room for a grand total
$doc->writeHtml('<h1>Invoice</h1>');

$doc->addPage();                 // page 1 — line items
$doc->writeHtml('<p>Line items…</p>');
$total = 1234.56;                // computed after laying out the items

$doc->setActiveBackfillPage(0);  // draw back onto page 0
$doc->writeHtml('<p>Grand total: ' . number_format($total, 2) . '</p>');
$doc->endPageBackfill();

$doc->save(__DIR__ . '/invoice.pdf');

نموذج برمجي — إنتاجي

أبقِ المخزَّن مُعطَّلًا لأي مستند موقَّع أو موسوم أو ⁨PDF⁩/A أو خطّي أو مُعمّى أو بتدفّق كائنات — فتلك بالضبط التركيبات التي يرفضها المخزَّن. اختر مسارًا واحدًا صراحةً.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Config;
use NextPDF\Core\Document;

function renderReport(bool $needsBackfill, bool $mustBeSigned): Document
{
    if ($needsBackfill && $mustBeSigned) {
        // The buffer refuses to combine with signing. Resolve the requirement
        // before building: pre-compute the value, or sign a separate pass.
        throw new \LogicException('Back-fill and signing are mutually exclusive.');
    }

    $config = new Config();
    if ($needsBackfill) {
        $config = $config->withRetainedPageBuffer();
    }

    return Document::createStandalone($config);
}

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

• الإيقاف متطابق بايتًا ببايت. مع إيقاف المخزَّن، يُدفِّق الكاتب كما من قبل.
• متبادِل الاستبعاد مع التوقيع والوسم و⁨PDF⁩/A والخطّية وتدفّقات الكائنات والتعمية ووضع ⁨CSS⁩ الآمن. الرفض مستقلّ عن الترتيب ويُطلَق قبل التسلسل. خطِّط المستند لوضع أو آخر.
• ميزانية البايتات تفشل بصرامة. المخزَّن المحتفَظ به محدود؛ وأي مستند يتجاوز ميزانية البايتات غير المضغوطة يفشل بدلًا من النمو بلا حدّ.
• اقرِن الاستدعاءات. ينبغي أن يقابل كلَّ setActiveBackfillPage() استدعاء endPageBackfill() لتُلحَق المحتويات اللاحقة بصورة عادية.
• الافتراضي التدفّقي يرفض الوصول العشوائي. بدون الخيار الاختياري، أي تبديل بوصول عشوائي يُغلَق بأمان. والمخزَّن هو المسار المدعوم الوحيد.

الأداء

يُقايض مخزَّن الصفحات المحتفَظ به الذاكرة بقدرة إعادة الملء: فهو يحتفظ بالصفحات المُفرَّغة حتى save()، محدودًا بميزانية البايتات غير المضغوطة لكل مستند. وملف الذاكرة المسطّح للكاتب التدفّقي ينطبق فقط مع إيقاف المخزَّن. وتعكس ميزانية الأداء performance_budget (wall_ms: 1500، peak_mb: 128) سقف الذاكرة الأعلى لمسار الاحتفاظ.

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

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

المطابقة

العبارة	المواصفة	البند
يُسلسِل الكاتب الجسم وبنية المراجع المتقاطعة والمقطورة وقت الحفظ.	ISO 32000-2	§7.5

هذه قدرة معاينة. يرفض ⁨NextPDF⁩ مخزَّن إعادة الملء للمستندات الموقَّعة والموسومة و⁨PDF⁩/A والخطّية والمُعمّاة وذات تدفّق الكائنات، فلا يقدّم أي ادّعاء مطابقة لتلك الملفات عبر هذا المسار. ولا يُعاد إنتاج أي نص معياري.

محوِّل التوافق (⁨TCPDF⁩)

يكشف محوِّل توافق ⁨TCPDF⁩ عن هذه القدرة كامتداد للمُنشئ. أنشِئ المحوِّل بـ retainedPageBuffer: true، عندئذٍ يُفوِّض أي استدعاء setPage() أو lastPage() يستهدف صفحة سابقة إلى إعادة الملء في النواة بدلًا من طرح UnsupportedFeatureException التدفّقي. وهذا الوسيط الإنشائي امتداد من ⁨NextPDF⁩، لا تكافؤ مع ⁨TCPDF⁩ القديم — فلا عَلَم كهذا في ⁨TCPDF⁩ القديم. وتنطبق رفوضات الإغلاق الآمن نفسها. راجع صفحة مخزَّن الصفحات المحتفَظ به في محوِّل التوافق للاطّلاع على تفاصيل جانب المحوِّل.

انظر أيضًا

• وحدة الكاتب
• وحدة المستند
• وحدة Config
• وحدة الخطّية