إعداد NextPDF وعرض أول ملف PDF لك

⁨NextPDF⁩ مكتبة ⁨PHP⁩ تُنشئ ملفات ⁨PDF⁩ (صيغة المستندات المحمولة). في هذا الدرس التعليمي، تثبّتها داخل مجلّد فارغ وتعرض أول مستند من صفحة واحدة. تحتاج إلى طرفية وقرابة عشر دقائق.

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

ستبني مشروعًا صغيرًا يحتوي على سكربت واحد، هو 01-hello.php. يعرض هذا السكربت صفحة واحدة تتضمّن سطر عنوان عريض وفقرة واحدة. ويحفظ النتيجة باسم out/hello.pdf. وفي أثناء ذلك، تتعلّم أمرين يؤكّدان أنّ تثبيتك سليم.

تعلّمك هذه الصفحة مسار تثبيت واحدًا: مجلّد فارغ مع حزمة المحرّك. توجد مسارات أخرى، مثل مُحوّلات أطر العمل، والمُصيّرات المعتمدة على المتصفّح، وعميل ⁨Python⁩. وتجدها في التثبيت واختر مسارك. ولا تحتاج إليها اليوم.

الخطوة 1: أنشئ مشروعًا وثبّت ⁨NextPDF⁩

⁨Composer⁩ هو مدير الحزم الخاص بـ ⁨PHP⁩. يُنزّل المكتبات إلى مشروعك ويُولّد مُحمّلًا تلقائيًا (autoloader). والمُحمّل التلقائي ملف ⁨PHP⁩ صغير يعثر لك على أصناف المكتبة، فلا تكتب أبدًا قوائم طويلة من عبارات التضمين.

افتح طرفية ونفّذ هذه الأوامر الثلاثة:

mkdir hello-nextpdf
cd hello-nextpdf
composer require nextpdf/core

يطبع ⁨Composer⁩ تقدّم العملية أثناء تحليله الحزم وتنزيلها. وتختلف الأسطر الدقيقة باختلاف إصدار ⁨Composer⁩ لديك وذاكرتك المؤقّتة المحلّية. ينتهي التثبيت الناجح دون نصّ خطأ، ويبدو تقريبًا كما يلي:

./composer.json has been created
Running composer update nextpdf/core
Loading composer repositories with package information
Updating dependencies
Lock file operations: ... installs, 0 updates, 0 removals
...
Generating autoload files

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

أنشأ ⁨Composer⁩ ثلاثة أشياء في مجلّدك. يسجّل composer.json أنّ مشروعك يعتمد على المحرّك. ويثبّت composer.lock الإصدار الدقيق الذي ثبّته، بحيث يحلّ أي تثبيت لاحق الشيفرة نفسها. ويحتوي مجلّد vendor/ على الحزم المُنزّلة، بما في ذلك vendor/autoload.php. يحمّل سكربتك ذلك الملف الواحد، فيصبح كل صنف من أصناف المحرّك متاحًا.

تحقّق ⁨Composer⁩ أيضًا من إعداد ⁨PHP⁩ لديك أثناء التثبيت. يُصرّح المحرّك بامتدادات ⁨PHP⁩ التي يحتاج إليها. والامتدادات وحدات اختيارية مبنيّة داخل ⁨PHP⁩. إذا كان أحدها مفقودًا، توقّف ⁨Composer⁩ وسمّاه بدلًا من أن يترك لك تثبيتًا معطوبًا.

الخطوة 2: اعرض أول ملف ⁨PDF⁩ لك

أنشئ ملفًا باسم 01-hello.php بجوار composer.json. الصق فيه هذا البرنامج الكامل:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Hello from NextPDF');
$document->addPage();

$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello from NextPDF', newLine: true);

$document->setFont('helvetica', '', 12);
$document->cell(0, 10, 'This page came from a short PHP script and the built-in fonts.', newLine: true);

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

echo "Wrote out/hello.pdf\n";

نفّذه:

php 01-hello.php

من المفترض أن ترى سطرًا واحدًا بالضبط:

Wrote out/hello.pdf

افتح out/hello.pdf في أي عارض ⁨PDF.⁩ سترى سطر العنوان العريض والفقرة تحته، وتعرض معظم العارضات ⁨“Hello from NextPDF”⁩ في عنوان نافذتها.

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

تابع السكربت من أعلاه إلى أسفله:

• يحمّل require مُحمّل ⁨Composer⁩ التلقائي، فيُحَلّ الصنف Document.
• يُنشئ @mkdir مجلّد out/. وتُبقي علامة @ البادئة السكربت صامتًا عندما يكون المجلّد موجودًا بالفعل، فتستطيع تشغيله مرّة أخرى.
• يُعيد Document::createStandalone() مستندًا جديدًا. وهو مصمّم لسكربتات سطر الأوامر القصيرة، تمامًا مثل هذا السكربت.
• يضبط setTitle() عنوان المستند، الذي تعرضه العارضات في عنوان النافذة.
• يضيف addPage() صفحة فارغة واحدة، ويضع المؤشّر في أعلى اليسار.
• يختار setFont() عائلة خطّ ونمطًا وحجمًا بالنقاط. والنقاط هي الوحدة القياسية لأحجام الخطوط في الطباعة. تعني 'B' العريض، وتعني '' العادي. والعائلة المسمّاة helvetica مبنيّة داخليًا، فلا تحتاج إلى أي ملفات خطوط.
• يكتب cell() سطرًا واحدًا من النص عند المؤشّر. ويعني العرض 0 “الامتداد حتى الهامش الأيمن”. وينقل newLine: true المؤشّر إلى الأسفل بعد ذلك، كأنّك تضغط مفتاح ⁨Enter⁩.
• يبني save() ملف ⁨PDF⁩ النهائي ويكتبه إلى القرص.

مستند واحد يُنتج ملفًا واحدًا. وعندما تحتاج إلى ملف ⁨PDF⁩ ثانٍ، أنشئ مستندًا جديدًا بدلًا من إعادة استخدام القديم.

الخطوة 3: تحقّق من إعدادك

يؤكّد فحصان سريعان أنّ هذا التثبيت سيظلّ يعمل إلى ما بعد سكربت واحد.

أولًا، اسرد الامتدادات التي يحملها ⁨PHP⁩ لديك:

php -m

افحص القائمة بحثًا عن curl وgd وintl وmbstring وopenssl وzlib. يعتمد المحرّك على هذه الستّة. وقد تحقّق منها ⁨Composer⁩ بالفعل في الخطوة 1، لذا ينبغي أن تظهر جميعها.

ثانيًا، شغّل فحص السلامة الخاص بالمحرّك:

vendor/bin/nextpdf doctor

على نظام ⁨Windows⁩، استدعِ vendor\bin\nextpdf doctor بدلًا من ذلك. يفحص الأمر إصدار ⁨PHP⁩ لديك، والامتدادات، والمجلّد المؤقّت، والإعداد. ويطبع كل فحص [OK] أو [WARN] أو [FAIL]، متبوعًا بحكم إجمالي واحد.

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

اقرأ كتلة Extensions أولًا. ستّة أسطر [OK] تحمل الأسماء curl وgd وintl وmbstring وopenssl وzlib تعني أنّ تثبيتك جاهز لكل درس تعليمي يليه.

يسرد التقرير أيضًا قدرات المحرّك. في تثبيت ⁨Core⁩ المجّاني، تطبع القدرات التي تنتمي إلى الحزم التجارية [FAIL] مع رسالة تسمّي الحزمة التي توفّرها. وهذا متوقّع هنا، وقد يحوّل الحكم الإجمالي إلى UNHEALTHY رغم أنّ إعداد ⁨Core⁩ لديك سليم. وفي هذه الدروس التعليمية، تظلّ كتلة ⁨Extensions⁩ هي المؤشّر المهمّ.

إذا حدث خطأ ما

طابق العَرَض الذي يظهر لديك مع هذه الحالات الشائعة أولًا:

• تعني composer: command not found أنّ ⁨Composer⁩ مفقود أو غير موجود في PATH لديك. ثبّته من getcomposer.org، ثم كرّر الخطوة 1.
• تعني Failed opening required '.../vendor/autoload.php' أنّ السكربت شُغّل خارج مجلّد المشروع، أو أنّ التثبيت لم يكتمل. انتقل إلى المجلّد من الخطوة 1 ونفّذ composer install.
• إذا توقّف ⁨Composer⁩ أثناء الخطوة 1 وسمّى امتداد ⁨PHP⁩ مفقودًا، فمكّن ذلك الامتداد في php.ini لديك. تأكّد منه باستخدام php -m، ثم كرّر التثبيت.
• يسمّي سطر [FAIL] في كتلة Extensions الخاصة بالأداة doctor امتداد ⁨PHP⁩ مفقودًا. مكّنه في php.ini، وتأكّد باستخدام php -m، وشغّل الأداة doctor مرّة أخرى. أمّا أسطر [FAIL] الخاصة بالقدرات والتي تسمّي حزمة تجارية فمتوقّعة في تثبيت ⁨Core⁩ ولا تتطلّب أي إجراء هنا.

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

التالي

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