DomPDF PHP: دليل شامل مع أمثلة عملية

مقدمة عن DomPDF: ما هو ولماذا تحتاجه

DomPDF هي مكتبة PHP قوية وشائعة تُستخدم لإنشاء مستندات PDF من أكواد HTML. الفكرة الأساسية لهذه المكتبة هي تمكين المطورين من إنشاء ملفات PDF باستخدام تقنيات تطوير الويب المألوفة: HTML وCSS وجافا سكريبت (بشكل محدود). بدلاً من تعلم واجهات برمجة تطبيقات معقدة ومنخفضة المستوى للتعامل مع PDF (مثل FPDF أو TCPDF)، يمكنك ببساطة كتابة قالب HTML، وتنسيقه باستخدام CSS، ثم تمريره إلى DomPDF لتحويله.

تستخدم المكتبة محرك عرض يعتمد على DOMPDF (ومن هنا جاء الاسم)، والذي يقوم بتحليل HTML وCSS، وإنشاء تمثيل مرئي للصفحة، ثم تصديره إلى تنسيق PDF. تدعم DomPDF معظم خصائص CSS القياسية، بما في ذلك تحديد المواقع، والتعويم، وFlexbox (جزئياً)، والعمل مع الخطوط والصور والجداول.

لماذا تحتاج هذه المكتبة؟

• أتمتة التقارير: إنشاء الفواتير، والسندات، وأوامر الشحن، والعروض التجارية بناءً على بيانات من قاعدة البيانات.
• إنشاء الشهادات والدبلومات: تصدير سريع لوثائق مخصصة ببيانات فريدة (الاسم، التاريخ، الدورة).
• إنشاء الكتب الإلكترونية والأدلة: تحويل محتوى HTML إلى PDF منسق بشكل جيد للتحميل.
• حفظ صفحات الويب: ميزة "حفظ كـ PDF" لأي محتوى على الموقع.
• التكامل مع أنظمة إدارة المحتوى: WordPress، Laravel، Symfony وغيرها من الأطر تستخدم DomPDF بنشاط لإنشاء المستندات.

الميزة الرئيسية لـ DomPDF مقارنة بالبدائل هي سهولة الاستخدام. إذا كنت تعرف HTML وCSS، فأنت بالفعل تتقن 80% من العمل مع DomPDF.

تثبيت DomPDF

يتم تثبيت DomPDF في مشروع PHP الحديث عبر مدير الحزم Composer. هذه هي الطريقة القياسية لمكتبات PHP.

تأكد من تثبيت Composer على جهازك. ثم قم بتنفيذ الأمر التالي في جذر مشروعك:

composer require dompdf/dompdf

بعد التثبيت الناجح، سيظهر مجلد vendor في مشروعك، وسيتم إضافة سطر التبعية في ملف composer.json. إذا كنت تستخدم إطار عمل (Laravel، Symfony)، فقد يختلف التثبيت قليلاً (على سبيل المثال، عبر موفري الخدمة)، لكن الأمر الأساسي يبقى كما هو.

ملاحظة مهمة: يتطلب DomPDF إصدار PHP 7.1 أو أعلى. يُوصى أيضاً بتثبيت إضافة PHP mbstring للعمل بشكل صحيح مع الترميزات متعددة البايت (UTF-8).

للتحقق من التثبيت، قم بإنشاء ملف test.php وأضف إليه الكود التالي:

<?php
require_once 'vendor/autoload.php'; // تحميل أداة التحميل التلقائي لـ Composer

use Dompdf\Dompdf;

$dompdf = new Dompdf();
$dompdf->loadHtml('<h1>مرحبا بالعالم</h1>');
$dompdf->render();
$dompdf->stream("test.pdf");

?>

إذا تم تحميل ملف PDF يحمل عبارة "مرحبا بالعالم" عند فتح الملف في المتصفح، فهذا يعني أن التثبيت تم بنجاح.

بداية سريعة: أول مستند PDF

لنقم بإنشاء مثال بسيط ولكنه متكامل. سنقوم بإنشاء ملف PDF يحتوي على جدول مع تنسيقات.

<?php
require_once 'vendor/autoload.php';

use Dompdf\Dompdf;
use Dompdf\Options;

// 1. إعداد الخيارات (اختياري)
$options = new Options();
$options->set('defaultFont', 'DejaVu Sans'); // خط يدعم العربية
$options->set('isRemoteEnabled', true); // السماح بتحميل الصور الخارجية

// 2. إنشاء كائن Dompdf
$dompdf = new Dompdf($options);

// 3. محتوى HTML
$html = '
<!DOCTYPE html>
<html>
<head>
    <style>
        body { font-family: DejaVu Sans, sans-serif; direction: rtl; }
        h1 { color: #2c3e50; text-align: center; }
        table { width: 100%; border-collapse: collapse; }
        th, td { border: 1px solid #ddd; padding: 8px; text-align: right; }
        th { background-color: #f2f2f2; }
    </style>
</head>
<body>
    <h1>تقرير المبيعات الشهري</h1>
    <table>
        <tr>
            <th>المنتج</th>
            <th>الكمية</th>
            <th>السعر</th>
        </tr>
        <tr>
            <td>منتج أ</td>
            <td>10</td>
            <td>100 ريال</td>
        </tr>
        <tr>
            <td>منتج ب</td>
            <td>5</td>
            <td>200 ريال</td>
        </tr>
    </table>
</body>
</html>
';

// 4. تحميل HTML
$dompdf->loadHtml($html);

// 5. تحويل إلى PDF
$dompdf->render();

// 6. عرض الملف في المتصفح
$dompdf->stream("تقرير_المبيعات.pdf");

?>

هذا المثال يوضح كيفية إنشاء PDF يحتوي على جدول بسيط مع دعم كامل للغة العربية. لاحظ أننا أضفنا خاصية direction: rtl; في CSS لجعل النص يظهر من اليمين إلى اليسار.