إنشاء مستند متعدد الصفحات باستخدام فواصل صفحات تلقائية

لمحة سريعة

أنشئ مستندًا يمتد على عدة صفحات، وأضف المحتوى تباعًا. عند تمكين setAutoPageBreak()، يبدأ محرك التخطيط صفحة جديدة عندما يصل المؤشر إلى الهامش السفلي. بعد save()، اقرأ عدد الصفحات النهائي باستخدام getNumPages(). تتبع هذه الوصفة examples/05-multi-page.php.

أثناء save()، يكتب المحرك تعليمات كل صفحة في دفق محتوى. يعرّف ⁨ISO 32000-2⁩ §7.7.3.3 عنصر Contents للصفحة بأنه دفق واحد أو مصفوفة من التدفقات المتسلسلة بالترتيب. لذلك تكون المخرجات متعددة الصفحات سلسلة من كائنات الصفحات، وليست مخزنًا مؤقتًا واحدًا.

التثبيت

composer require nextpdf/core:^3

لا تحتاج إلى أي امتداد اختياري. تعمل هذه الوصفة على مصفوفة الخلفيات المدعومة لـ ⁨PHP 8.1⁩–8.4. كل من getNumPages() وsetAutoPageBreak() مستقر منذ الإصدار 1.0.0.

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

مستند ⁨NextPDF⁩ هو شجرة صفحات. كلما أضفت محتوى، تحرّك مؤشر داخلي (getY()) إلى أسفل الصفحة. عند تفعيل فواصل الصفحات التلقائية، يتحقق المحرك من المساحة الرأسية المتبقية قبل كل كتلة محتوى. إذا تعذّر احتواء الكتلة فوق الهامش السفلي، يفرّغ المحرك الصفحة الحالية ويستدعي addPage() نيابةً عنك. الهامش السفلي الذي تمرّره إلى setAutoPageBreak() هو عتبة التشغيل.

سمات مستوى الصفحة، مثل صندوق الوسائط (⁨media box⁩)، قابلة للوراثة. يحدّد ⁨ISO 32000-2⁩ §7.7.3.4 أن السمة المحذوفة من كائن صفحة تُحَل من عقدة سلف في شجرة الصفحات. يضبط ⁨NextPDF⁩ حجم صفحة موحدًا على مستوى المستند، فتستخدم كل صفحة مُنشأة الهندسة نفسها، ولا تحتاج إلى تكرارها لكل صفحة.

سطح واجهة ⁨API⁩

يُنشأ سطح واجهة برمجة التطبيقات (⁨API⁩) من ⁨PHPDoc.⁩ تعتمد هذه الوصفة على الطرائق الآتية:

• Document::createStandalone(): self — ينشئ مستندًا معزولًا.
• setAutoPageBreak(bool $enabled, float $margin = 20): static — يُمكّن فواصل الصفحات التلقائية. $margin هو عتبة تشغيل الهامش السفلي بالمليمترات.
• addPage(?PageSize $size = null, Orientation $orientation = Orientation::Portrait): static — يبدأ الصفحة الأولى وأي صفحة صريحة.
• multiCell(...): static / cell(...): static — يصدران كتل نص متدفقة أو ثابتة. يقيس فحص فاصل الصفحة هذه الكتل.
• getNumPages(): int — عدد الصفحات بعد التخطيط.

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

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setAutoPageBreak(true, margin: 25);
$doc->addPage();

$doc->setFont('helvetica', '', 11);
for ($i = 1; $i <= 60; $i++) {
    $doc->multiCell(0, 7, "Line {$i}: content flows until the page is full, "
        . 'then the engine starts a new page automatically.');
}

$doc->save(getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/multi-page.pdf');
echo 'Pages: ' . $doc->getNumPages() . "\n";

عينة برمجية — للإنتاج

هذا هو المثال الكامل الجاهز للتشغيل داخل إطار الاختبار. يلتزم بالمتغير NEXTPDF_COOKBOOK_OUTPUT الذي يضبطه إطار الاختبار، لذلك لا يطبع ⁨PDF⁩ إلى ⁨STDOUT.⁩ ولا يضيف أي عشوائية من جانبه. عندما يشغّله إطار الاختبار، يثبّت DeterministicMode الساعة و/ID والعلامة التجارية.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Multi-Page Document');

// Enable automatic page breaks. The 25 mm bottom margin is the trigger:
// when the cursor would cross it, the engine flushes the page and adds
// a new one before the next block is drawn.
$doc->setAutoPageBreak(true, margin: 25);
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Multi-Page Document Example', newLine: true);
$doc->ln(5);

for ($chapter = 1; $chapter <= 3; $chapter++) {
    $doc->setFont('helvetica', 'B', 14);
    $doc->cell(0, 10, "Chapter {$chapter}: Lorem Ipsum", newLine: true);
    $doc->setFont('helvetica', '', 11);

    for ($para = 1; $para <= 5; $para++) {
        $text = "Paragraph {$para} of Chapter {$chapter}. "
            . 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. '
            . 'Sed do eiusmod tempor incididunt ut labore et dolore magna '
            . 'aliqua. Ut enim ad minim veniam, quis nostrud exercitation '
            . 'ullamco laboris nisi ut aliquip ex ea commodo consequat.';
        $doc->multiCell(0, 7, $text);
        $doc->ln(3);
    }
    $doc->ln(5);
}

// The harness sets NEXTPDF_COOKBOOK_OUTPUT; honour it. STDOUT stays free
// for progress text only.
$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/multi-page.pdf';
$doc->save($out);

echo 'Created multi-page.pdf with ' . $doc->getNumPages() . " pages\n";

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

• تعطيل فاصل الصفحات التلقائي. مع setAutoPageBreak(false, …)، يُقتطع المحتوى الذي يتجاوز الهامش السفلي عند حدود الصفحة بدلًا من أن يتدفق، ويبقى المستند في صفحة واحدة. فعّله للمحتوى المتدفق.
• كتلة واحدة أطول من الصفحة. يقسّم المحرك داخليًا أي multiCell يتجاوز نصها الارتفاع القابل للطباعة. لكن الكتلة الواحدة غير القابلة للتقسيم والأطول من المساحة القابلة للاستخدام، مثل صورة طويلة، تُوضع مرة واحدة وتتجاوز الحدود. قسّمها بنفسك.
• لا يزال أول addPage() مطلوبًا. يستدعي cell() الدالة addPage() عند الطلب عندما لا توجد صفحة. ومع ذلك، استدعِ addPage() صراحةً كي يبقى حجم الصفحة الأولى واتجاهها حتميَّين.
• وحدات الهامش. هامش setAutoPageBreak() بالمليمترات في نظام الوحدات الافتراضي، وليس بالنقاط.

الأداء

getNumPages() هي ⁨O⁩(1). تقرأ عدّادًا ولا تُعيد تشغيل التخطيط. تتناسب الذاكرة مع المحتوى المحتفظ به، لا مع عدد الصفحات. يفرّغ المحرك الصفحات المكتملة إلى مخزن الإخراج المؤقت فور اكتمالها — نموذج التدفق أحادي المرور (⁨ADR-001⁩). تغطي ميزانية 2000 ⁨ms⁩ / 64 ⁨MB⁩ المستندات التي تحتوي على بضع مئات من صفحات النص على المضيف المرجعي.

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

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

المطابقة

البيان	المواصفة	البند	⁨reference_id⁩
عنصر Contents للصفحة هو دفق واحد أو مصفوفة مرتّبة ومتسلسلة من التدفقات.	⁨ISO 32000-2⁩	§7.7.3.3
سمة الصفحة القابلة للوراثة والمحذوفة من كائن صفحة تُحَل من عقدة سلف في شجرة الصفحات.	⁨ISO 32000-2⁩	§7.7.3.4
عنصر /ID في المقطع الخلفي هو معرّف ملف مكوّن من سلسلتي بايت (مطلوب في ⁨PDF 2.0⁩).	⁨ISO 32000-2⁩	§7.5.5

ملف قابلية إعادة الإنتاج — بنيوي (لِمَ لا يكون بِتّيًا). يحمل كل مستند محفوظ عنصرًا في المقطع الخلفي /ID تشكّل سلسلتا البايت فيه معرّف ملف (⁨ISO 32000-2⁩ §7.5.5، أعلاه). العنصر الثاني غير ثابت بين عمليات التشغيل، لذلك تختلف البايتات الخام بين عمليات التشغيل حتى مع محتوى متطابق. يقارن إطار الاختبار البنية المُطبَّعة بواسطة ⁨qpdf⁩، التي تجرّد /ID و/CreationDate و/ModDate. تصف هذه الوصفة كيف يُنتج ⁨NextPDF⁩ هذه البنية، ولا تؤكّد المطابقة لـ ⁨ISO 32000-2⁩ كادّعاء شامل.

السياق التجاري

غير منطبق. تكوين المستندات متعددة الصفحات باستخدام فواصل الصفحات التلقائية قدرة من قدرات ⁨Core⁩، دون أي بوابة ⁨Premium.⁩

انظر أيضًا

• وحدة ⁨Document⁩
• إضافة رؤوس وتذييلات متكررة
• الإشارات المرجعية وجدول المحتويات