1. ما هو TCPDF ولماذا تحتاجه؟

TCPDF (اختصارًا لـ "Transparent Communication PDF") هي مكتبة PHP قوية وواسعة الاستخدام، مصممة لإنشاء مستندات PDF برمجيًا. تُعتبر من أقدم وأكثر المكتبات اكتمالاً في هذا المجال، حيث تمنح المطورين تحكمًا كاملاً في عملية إنشاء PDF دون الحاجة إلى أدوات أو إضافات خارجية (باستثناء إضافة GD القياسية للتعامل مع الصور).

لماذا تحتاج TCPDF؟ في تطوير الويب الحديث، كثيرًا ما نحتاج إلى إنشاء مستندات PDF بشكل ديناميكي: فواتير، إيصالات، تقارير، شهادات، عقود، كتب إلكترونية، وغيرها الكثير. يتيح لك TCPDF حل هذه المهمة من جانب الخادم. يدعم جميع إمكانيات PDF الأساسية، بما في ذلك الخطوط (TrueType، Type1، Unicode)، الصور (JPEG، PNG، GIF، SVG)، محتوى HTML، الجداول، التعليقات التوضيحية، النماذج، الإشارات المرجعية، التشفير، والتوقيعات الرقمية. بفضل دعم Unicode، تتعامل المكتبة بشكل صحيح مع العربية، والروسية، والصينية، والعديد من اللغات الأخرى.

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

2. التثبيت

أسهل طريقة لتثبيت TCPDF هي عبر مدير الحزم Composer. هذه هي الطريقة الموصى بها، حيث يقوم تلقائيًا بتضمين المكتبة وإدارة إصداراتها.

قم بتنفيذ الأمر التالي في المجلد الرئيسي لمشروعك:

composer require tecnickcom/tcpdf

بعد تنفيذ هذا الأمر، سيظهر مجلد vendor في مشروعك، وسيتم إضافة تبعية في ملف composer.json. لاستخدام المكتبة في سكريبت PHP، يجب تضمين أداة التحميل التلقائي الخاصة بـ Composer:

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

إذا كنت لا تستخدم Composer، يمكنك تنزيل الأرشيف من GitHub وتضمين الملف الرئيسي للمكتبة يدويًا:

require_once('/path/to/tcpdf/tcpdf.php');

ومع ذلك، لا يُنصح بالطريقة اليدوية لأنها تعقّد عملية تحديث المكتبة.

3. البداية السريعة — مثال عملي بسيط

لنقم بإنشاء مستند PDF بسيط يعرض النص "مرحبًا بالعالم!". يوضح هذا المثال دورة الحياة الأساسية للعمل مع TCPDF: إنشاء كائن، إضافة صفحة، عرض النص، وحفظ الملف.

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

// 1. إنشاء مستند PDF جديد
// المعاملات: الاتجاه (P - عمودي، L - أفقي)، وحدة القياس (mm)، حجم الصفحة (A4)
$pdf = new TCPDF('P', 'mm', 'A4', true, 'UTF-8', false);

// 2. إزالة الرأس والتذييل الافتراضيين (للتبسيط)
$pdf->setPrintHeader(false);
$pdf->setPrintFooter(false);

// 3. إضافة صفحة
$pdf->AddPage();

// 4. تعيين الخط
$pdf->SetFont('helvetica', 'B', 20);

// 5. عرض النص (x, y, النص)