أول ملف PDF تنشئه

نظرة سريعة

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

يعمل كلا النهجين على المحرّك نفسه، لذا ينطبق ما تتعلّمه هنا على كل توزيعة.

يوضّح المخطّط أدناه نهجَي التأليف وواجهات النشر الثلاث التي تعيد استخدامهما.

From your code to a PDF file

قبل أن تبدأ

تحتاج إلى تثبيت المحرّك الأساسي وبيئة لتشغيل سكربت ⁨PHP.⁩

تأكّد من أن ⁨PHP 8.4⁩ هو بيئة التشغيل النشطة:
Terminal window
```
php --version
```
ثبّت المحرّك الأساسي في مشروعك إن لم يكن موجودًا بالفعل:
Terminal window
```
composer require nextpdf/core
```
أنشئ ملف عمل باسم first-pdf.php في جذر المشروع.

الخطوط الأربعة عشر القياسية تعمل دون أي إعداد

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

إنشاء ملف ⁨PDF⁩ من ⁨PHP⁩

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

ضع هذا الكود في first-pdf.php. يعلن السكربت عن الأنواع الصارمة، ويحمّل المُحمّل التلقائي، ويبني صفحة واحدة:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$document = Document::createStandalone();
$document->setTitle('My first NextPDF document');
$document->addPage();

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

$document->setFont('helvetica', '', 12);
$document->cell(0, 10, 'This is the first PDF I generated with PHP.', newLine: true);

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

echo "Wrote first-pdf.pdf\n";

شغّل السكربت:
Terminal window
```
php first-pdf.php
```
تأكّد من المُخرَج. من المفترض أن ترى هذا السطر في المُخرَج القياسي وملفًا جديدًا باسم first-pdf.pdf بجانب السكربت:
```
Wrote first-pdf.pdf
```

لقد أنشأت الآن ملف ⁨PDF 2.0⁩ صالحًا. افتحه في أي عارض لترى العنوان والسطر الذي تحته.

⁨save⁩ مقابل ⁨output⁩

تكتب save() المستند إلى مسار ملف. ولإرسال البايتات إلى المتصفّح بدلًا من ذلك، استدعِ output(). ولالتقاط البايتات في الذاكرة، استدعِ getPdfData(). المستند مخصّص للاستخدام مرة واحدة. بعد أن تكتب مستندًا، أنشئ نسخة جديدة للمستند التالي بدلًا من إعادة استخدامه.

عرض ⁨HTML⁩ بصيغة ⁨PDF⁩

تمنحك كتابة الخلايا تحكّمًا دقيقًا. إلا أن التعبير عن معظم المستندات بصيغة ⁨HTML⁩ و⁨CSS⁩ يكون أسرع. يتضمّن المحرّك الأساسي مسار معالجة ⁨HTML⁩ مكتوبًا بلغة ⁨PHP⁩ خالصة. تعرض دالته writeHtml() مقطعًا داخل الصفحة الحالية. وهي لا تستخدم متصفّحًا ولا خدمة خارجية.

أنشئ ملفًا ثانيًا، html-pdf.php، يعرض مقطع ⁨HTML⁩:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$document = Document::createStandalone();
$document->setTitle('HTML to PDF');
$document->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">HTML rendering in NextPDF</h1>
<p>NextPDF renders <strong>HTML content</strong> directly into PDF pages.</p>
<ul>
    <li>Headings, paragraphs, and lists</li>
    <li>Inline <strong>bold</strong> and <em>italic</em></li>
    <li>Inline styles such as color and font-size</li>
</ul>
HTML;

$document->writeHtml($html);

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

echo "Wrote html-pdf.pdf\n";

شغّله:
Terminal window
```
php html-pdf.php
```
تأكّد من سطر المُخرَج والملف الجديد:
```
Wrote html-pdf.pdf
```

تعامل مع مُدخَل ⁨HTML⁩ على أنه غير موثوق

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

يدعم المحرّك عرض مجموعة فرعية من ⁨HTML⁩ و⁨CSS.⁩ قبل أن تعتمد على خاصية ما، راجع مصفوفة دعم ⁨CSS⁩. عندما يتطلّب تخطيط ما دقّة متصفّح كاملة، مثل ⁨flexbox⁩ أو ⁨grid⁩ أو خطوط الويب، ثبّت مُصيّر ⁨Artisan⁩ واستدعِ writeHtmlChrome() بدلًا من ذلك. تُبقي تلك الدالة النصَّ قابلًا للتحديد.

من متحكّم إطار عمل

قد يكون تطبيقك يعمل بالفعل ضمن إطار عمل أو عبر الخادم. ينتقل الاستدعاءان نفساهما إلى تلك البيئة. يبقى المحرّك كما هو، ولا يتغيّر إلا الربط.

توفّر واجهة Pdf مستندًا جديدًا لكل استدعاء. تحوّل PdfResponse المستند إلى استجابة تنزيل:

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Http\Response;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

final class ReportController extends Controller
{
    public function download(): Response
    {
        $document = app(PdfDocumentInterface::class);
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

        return PdfResponse::download($document, 'report.pdf');
    }
}

راجع دليل البدء السريع لـ ⁨Laravel⁩.

تتيح الحزمة خدمة PdfFactory. حدّد تلميح النوع NextPDF\Symfony\Service\PdfFactory في متحكّم، وابنِ مستندًا بالطريقة نفسها، ثم أعِده استجابةً عبر ⁨HTTP.⁩ راجع دليل البدء السريع لـ ⁨Symfony⁩.

عند تشغيل ⁨NextPDF Server⁩، أرسل طلب ⁨POST⁩ يحوي مصفوفة عمليات مرتّبة، فيُعيد الخادم بايتات ⁨PDF⁩:

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

عند تلقّي استجابة 200، يكون المتن هو ملف ⁨PDF.⁩ راجع دليل البدء السريع لـ ⁨Connect⁩.

الخطوات التالية

لقد أنشأت الآن ملف ⁨PDF⁩ بثلاث طرق. استخدم هذه الصفحات للبناء على كل طريقة منها.

عرض HTML في صفحة PDF وصفة HTML الكاملة: العناصر المدعومة، ونموذج البثّ، والوضع الأمني.

اختر مسارك قرّر بين النواة وإطار عمل والخادم، وأي مُصيّر HTML تستخدم.

مرجع المحرّك الأساسي كل دالة في Document ووسائطها وقيمها المُعادة.

كتاب الوصفات وصفات تركّز على المهام للتنسيق والجداول وتقسيم الصفحات والمزيد.