النصوص والخطوط وأساسيات الصفحة

في الدرس التعليمي الأول عرضتَ صفحةً تحتوي على سطر واحد من النص. أمّا هذه المرّة فتتولّى التحكّم في الصفحة نفسها وفي النص الذي عليها. ستختار حجمًا للصفحة، وتكتب العناوين والفقرات، وتنسّقها باستخدام خطوط المحرّك المبنيّة داخليًا.

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

ستكتب سكربتين صغيرين. يُنتج كلٌّ منهما ملف صيغة المستندات المحمولة (⁨PDF⁩) من صفحة واحدة:

• يعرض 01-text-basics.php صفحةً بحجم ⁨A4⁩ باتجاه عمودي، تحتوي على عنوان ملوَّن، وفقرات ملفوفة، وثلاث عيّنات محاذاة.
• يعرض 02-fonts.php صفحة عيّنات تقارن بين عائلتَي خطوط مبنيّتين داخليًا بأحجام متعدّدة.

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

الخطوة 1: تنسيق النص على صفحة ⁨A4⁩

لكل صفحة حجمٌ واتجاه. فحجم ⁨A4⁩ هو حجم الورق الدولي الشائع، و⁨Letter⁩ نظيره في الولايات المتحدة. والاتجاه إمّا عمودي (منتصب) أو أفقي (على الجنب). وتمرّر كلا الخيارين إلى addPage() عند بدء صفحة.

ثم تتولّى ثلاث طرائق عملية الكتابة. تختار setFont() الخط وحجمه للنص الذي يليها. وتكتب cell() سطرًا واحدًا داخل صندوق غير مرئي. وتلفّ multiCell() النص الأطول على ما يلزم من الأسطر. وفي كلتا الطريقتين، يعني عرضٌ مقداره 0 “استخدام كل المساحة حتى الهامش الأيمن”.

ويتولّى استدعاءان آخران المظهر. تأخذ setTextColor() قيم الأحمر والأخضر والأزرق من 0 إلى 255، وتظل سارية حتى تغيّرها مجددًا. أمّا التعداد Alignment — وهو قائمة ثابتة من الخيارات المسمّاة — فيوفّر Left وCenter وRight وJustify.

أنشئ 01-text-basics.php داخل مجلّد مشروعك:

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Alignment;
use NextPDF\Contracts\Orientation;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\PageSize;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Text basics');
$document->addPage(PageSize::A4(), Orientation::Portrait);

// A colored heading. The values are red, green, and blue, each 0 to 255.
$document->setFont('helvetica', 'B', 20);
$document->setTextColor(30, 64, 175);
$document->cell(0, 14, 'Project kickoff notes', newLine: true);
$document->ln(4);

// Back to black for the body text.
$document->setTextColor(0, 0, 0);
$document->setFont('helvetica', '', 11);
$document->multiCell(
    0,
    7,
    'Welcome to the second tutorial. This paragraph is written with '
        . 'multiCell(), so the engine wraps the words onto as many lines '
        . 'as the page width requires.',
);
$document->ln(4);

$document->multiCell(
    0,
    7,
    'Justified text stretches the spaces so both edges line up. It is a '
        . 'good fit for report bodies and other long passages.',
    align: Alignment::Justify,
);
$document->ln(6);

// One line each: left, centered, and right.
$document->setFont('helvetica', 'I', 11);
$document->cell(0, 8, 'Left-aligned line', newLine: true, align: Alignment::Left);
$document->cell(0, 8, 'Centered line', newLine: true, align: Alignment::Center);
$document->cell(0, 8, 'Right-aligned line', newLine: true, align: Alignment::Right);

$document->save(__DIR__ . '/out/text-basics.pdf');

echo "Wrote out/text-basics.pdf\n";

نفّذه بالأمر php 01-text-basics.php. يطبع السكربت Wrote out/text-basics.pdf، ويظهر الملف في المجلّد الجديد out/.

ما الذي حدث للتو

أنشأ addPage(PageSize::A4(), Orientation::Portrait) الصفحة قبل كتابة أي نص. ومرّر Orientation::Landscape بدلًا من ذلك، فتنقلب الصفحة نفسها على جنبها. وتعمل الأحجام المسمّاة الأخرى، مثل PageSize::A5() أو PageSize::Letter()، بالطريقة نفسها.

اختار setFont('helvetica', 'B', 20) خط ⁨Helvetica⁩ العريض بحجم 20 نقطة. والنقطة (⁨pt⁩) هي وحدة الطباعة التقليدية؛ فكل 72 نقطة تساوي بوصةً واحدة. والعنوان أزرق لأن setTextColor(30, 64, 175) كانت سارية حين كتبه استدعاء cell(). ثم أعاد setTextColor(0, 0, 0) التالي اللون إلى الأسود لكل ما يليه.

لفّ استدعاءا multiCell() فقرتيهما تلقائيًا. ويمدّ الاستدعاء المضبوط تباعد الكلمات لتتحاذى الحافّتان معًا، عدا السطر الأخير من الفقرة. وبين الكتل، أنزل ln() موضع الكتابة إلى الأسفل لإضافة مساحة تنفُّس. وأخيرًا، بنى save() الملف وكتبه داخل out/.

وللاطلاع على كل مُعامل تقبله هذه الطرائق، راجِع تأليف النص باستخدام الخطوط والمحاذاة.

الخطوة 2: الاختيار من بين الخطوط المبنيّة داخليًا

يأتي المحرّك مزوَّدًا بثلاث عائلات نصّية مبنيّة داخليًا: ⁨Helvetica⁩ و⁨Times⁩ و⁨Courier⁩. فـ⁨Helvetica⁩ خطٌّ غير مذيَّل (⁨sans-serif⁩)، أي أن حروفه خالية من الخطوط الطرفية الصغيرة (الذيول، ⁨serifs⁩). و⁨Times⁩ خطٌّ مذيَّل (⁨serif⁩) تسهُل قراءته في المقاطع الطويلة الشبيهة بالمطبوعات. و⁨Courier⁩ خطٌّ ثابت العرض، فيناسب قوائم الشيفرة والإيصالات. ولأن هذه العائلات مبنيّة داخليًا، فإن سكربتاتك لا تحتاج إلى أي ملفات خطوط على الإطلاق.

تجمع وسيطة النمط في setFont() رايات من حرف واحد: 'B' للعريض، و'I' للمائل، و'U' للتسطير. وتعني السلسلة الفارغة النمط العادي، وتتجمّع الرايات معًا، فتُعطي 'BI' عريضًا مائلًا.

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

أنشئ 02-fonts.php بجوار السكربت الأول:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Font sampler');
$document->addPage();

$document->setFont('helvetica', 'B', 20);
$document->cell(0, 14, 'Built-in font sampler', newLine: true);
$document->ln(4);

// Helvetica: a sans-serif face, a solid default for labels and headings.
$document->setFont('helvetica', 'B', 14);
$document->cell(0, 10, 'Helvetica', newLine: true);
foreach ([10, 12, 16] as $size) {
    $document->setFont('helvetica', '', (float) $size);
    $document->cell(0, $size * 0.8, "Helvetica sample at {$size}pt.", newLine: true);
}
$document->setFont('helvetica', 'BI', 12);
$document->cell(0, 9, 'Helvetica bold italic for emphasis.', newLine: true);
$document->ln(6);

// Times: a serif face that suits long, print-like passages.
$document->setFont('times', 'B', 14);
$document->cell(0, 10, 'Times', newLine: true);
foreach ([10, 12, 16] as $size) {
    $document->setFont('times', '', (float) $size);
    $document->cell(0, $size * 0.8, "Times sample at {$size}pt.", newLine: true);
}
$document->setFont('times', 'I', 12);
$document->cell(0, 9, 'Times italic for quotations.', newLine: true);

$document->save(__DIR__ . '/out/font-sampler.pdf');

echo "Wrote out/font-sampler.pdf\n";

نفّذه بالأمر php 02-fonts.php وافتح out/font-sampler.pdf. سترى الجملة النموذجية نفسها تتبدّل هيئتها بين العائلتين وتكبُر عبر ثلاثة أحجام.

ما الذي حدث للتو

استخدم addPage() من دون وسائط إعداد الصفحة الافتراضي بالاتجاه العمودي، فلا يلزم أن يوضّح كل سكربت الحجم صراحةً. وبدّل كل استدعاء لـsetFont() العائلة أو النمط أو الحجم النشط في منتصف الصفحة، ويظل الخط نشطًا حتى الاستدعاء التالي لـsetFont().

تحوّل الحلقات الحجم باستخدام (float) لأن setFont() تتوقّع عددًا عشريًا. وتتناسب ارتفاعات الأسطر مع حجم الخط ($size * 0.8)، فيحصل النص الأكبر على أسطر أعلى ولا يتداخل شيء. جرّب وضع 'courier' مكان 'times' وشغّل السكربت مجددًا لرؤية العائلة الثالثة.

إذا حدث خطأ ما

• عادةً ما يعني خطأ “الفئة غير موجودة” (⁨class not found⁩) أو خطأ التحميل التلقائي (⁨autoload⁩) أن السكربت لم يعثر على vendor/autoload.php. نفّذه داخل مجلّد المشروع الذي يحتوي على vendor/.
• يُطلق اسم عائلة مكتوب خطأً استثناءً يذكر الخط الذي تعذّر العثور عليه. تحقّق من الهجاء: helvetica، وtimes، وcourier.
• يجمع مركز استكشاف الأخطاء وإصلاحها الحلول الشائعة، ويتناول الخطوط والوسم مشكلات الخطوط بتعمّق.
• كل استثناء في المحرّك موثَّق في مرجع الأخطاء، مع السياق الذي يحمله وإجراء التعافي.

التالي

أصبح بإمكانك الآن تشكيل الصفحات، وتنسيق النص، واختيار الخطوط بوعيٍ وقصد. وفي الدرس التعليمي التالي تضع الصور على الصفحة وتنظّم المحتوى بالجداول والقوائم.