من HTML إلى PDF، المسار السهل

حتى الآن في هذا المسار، بنيتَ الصفحات استدعاءً تلو الآخر. لكن وصف كثير من المستندات بالترميز — وهو صيغة النص القائمة على الوسوم المستخدَمة في صفحات الويب — يكون أسرع. في هذا الدرس التعليمي، تُمرّر إلى ⁨NextPDF⁩ بعض لغة ترميز النص الفائق (⁨HTML⁩)، فيرسم المحرّك الصفحة نيابةً عنك.

ما الذي ستبنيه

تقرير من صفحة واحدة يُعرَض من سلسلة ⁨HTML⁩ واحدة. يتضمّن عنوانًا ملوّنًا، وفقرة قصيرة، وجدولًا فيه صف للمجاميع. تنسّقه بأوراق الأنماط المتتالية (⁨CSS⁩)، وهي لغة القواعد التي تتحكّم في مظهر الترميز. في الدروس التعليمية السابقة، استخدمتَ واجهة برمجة التطبيقات (⁨API⁩) السلسة، أي استدعاءات الدوال المتسلسلة. أما هنا، فتصف التخطيط بالترميز بدلًا من ذلك، ويعرضه المحرّك نفسه.

الخطوة ⁨1⁩: عرض تقرير منسّق من ⁨HTML⁩

أنشئ ملفًا باسم 01-html.php في مجلد مشروعك، بجانب vendor. الصق فيه هذا السكربت الكامل:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Monthly reading report');
$document->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">Monthly reading report</h1>

<p>This report was rendered from <strong>HTML</strong> with inline
<em>CSS</em>. The table below lists two books and their page counts.</p>

<table border="1" cellpadding="5" cellspacing="0" style="width: 100%;">
    <thead>
        <tr style="background-color: #1E3A8A; color: #FFFFFF;">
            <th style="width: 55%;">Title</th>
            <th style="width: 20%; text-align: center;">Format</th>
            <th style="width: 25%; text-align: right;">Pages</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>The Paper Trail</td>
            <td style="text-align: center;">Hardcover</td>
            <td style="text-align: right;">312</td>
        </tr>
        <tr style="background-color: #F8FAFC;">
            <td>Ink and Bytes</td>
            <td style="text-align: center;">Paperback</td>
            <td style="text-align: right;">248</td>
        </tr>
    </tbody>
    <tfoot>
        <tr style="font-weight: bold;">
            <td colspan="2" style="text-align: right;">Total pages:</td>
            <td style="text-align: right;">560</td>
        </tr>
    </tfoot>
</table>
HTML;

$document->writeHtml($html);

$document->save(__DIR__ . '/out/reading-report.pdf');

echo "Wrote out/reading-report.pdf\n";

شغّل السكربت من مجلد المشروع:

php 01-html.php

من المفترض أن ترى سطرًا واحدًا في المُخرَج:

Wrote out/reading-report.pdf

افتح out/reading-report.pdf في أي عارض لصيغة المستندات المحمولة (⁨PDF⁩). العنوان أزرق داكن، وصف رأس الجدول مملوء باللون نفسه.

ماذا حدث للتو

تُنشئ @mkdir(__DIR__ . '/out'); مجلد المُخرَجات. تُخفي علامة @ التحذير عندما يكون المجلد موجودًا مسبقًا، فتبقى عمليات التشغيل المتكرّرة صامتة.
تعمل Document::createStandalone() وsetTitle() وaddPage() تمامًا كما في الدروس التعليمية السابقة. الانتقال إلى الترميز لا يغيّر شيئًا في إعداد المستند.
تقرأ writeHtml() سلسلتك مرة واحدة، من الأعلى إلى الأسفل، وترسم كل عنصر عند الموضع الحالي. تتحوّل العناوين والفقرات إلى نص منسّق. ويتحوّل الجدول إلى صفوف مقيسة من الخلايا المحدّدة بحدود.
تحمل سمات style المضمّنة أنماط ⁨CSS⁩. يفهم المحرّك الخصائص الشائعة مثل color وbackground-color وtext-align وwidth.
لا يتدخّل أي متصفّح ولا أي برنامج إضافي. مسار المعالجة هو ⁨PHP⁩ خالص داخل المحرّك، لذا يعمل السكربت أينما يعمل تثبيت ⁨Composer⁩ لديك.

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

متى تستخدم ⁨HTML⁩ ومتى تستخدم واجهة ⁨API⁩ السلسة

يعمل كلا المسارين على المحرّك نفسه، لذا اختر ما يناسب المستند.

اختر writeHtml() عندما يُقرأ المستند كصفحة ويب: عناوين وفقرات وقوائم وجداول. الترميز أسرع في الكتابة وأسهل على زملائك في التحرير.
اختر واجهة ⁨API⁩ السلسة عندما تحتاج إلى وضع دقيق، مثل المواضع الثابتة أو الخلايا المقيسة بدقّة. يمنحك الترميز الانسياب؛ وتمنحك الاستدعاءات السلسة التحكّم.
راجع مصفوفة دعم ⁨CSS⁩ قبل الاعتماد على خاصية ما. عندما لا يكون النمط مُغطّى، ابنِ ذلك الجزء بالاستدعاءات السلسة بدلًا من ذلك.

حدّ الأمان

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

إذا حدث خطأ ما

عادةً ما يعني Failed to open stream: No such file or directory أن السكربت لا يستطيع العثور على vendor/autoload.php. شغّله من المجلد الذي شغّلت ⁨Composer⁩ فيه.
عادةً ما يكون النمط المفقود خاصية خارج المجموعة الفرعية المدعومة. يتخطّى المحرّك ما لا يدعمه بدلًا من أن يفشل. قارن ترميزك بـ مصفوفة دعم ⁨CSS⁩.
أي استثناء يقع أثناء العرض يذكر المشكلة بالضبط. ابحث عنه في مرجع أخطاء العرض والإدخال/الإخراج.

ولأي أمر آخر، ابدأ بـدليل استكشاف الأخطاء وإصلاحها.

يمكنك الآن بناء المستندات استدعاءً تلو الآخر ومن الترميز. أكمل المسار بصفحة إلى أين تذهب بعد ذلك. فهي ترسم خريطةً لكتاب الوصفات والمرجع والأدلّة التي ستستخدمها بعد هذا المسار.