البدء السريع مع compat-legacy

لمحة سريعة

تنقلك هذه الصفحة من حزمة مثبّتة إلى ملف ⁨PDF⁩ مكتمل، ثم إلى تدقيق الوضع الصارم الذي تنفّذه قبل الترحيل. يطابق كل مقطع برمجي السلوك الذي تؤكده مجموعة اختبارات الحزمة؛ لذلك فالمخرجات المعروضة هنا هي نفسها المخرجات التي تتحقق منها الاختبارات.

قبل أن تبدأ

ثبّت الحزمة وتحقّق من ارتباط المحرّك باتباع /⁨integrations/tcpdf-compat/install/.⁩ تحتاج إلى ⁨PHP 8.4⁩، ويجب حلّ nextpdf/core ^3.0.

1. أنشئ أول مستند لك

غيّر سطر الاستيراد، وأبقِ استدعاءاتك بأسلوب ⁨TCPDF.⁩ هذه هي الواجهة نفسها التي يؤكدها tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php.

examples/quickstart-first.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->SetCreator('Quickstart');
$pdf->SetTitle('First Document');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');

$pdf->Output(__DIR__ . '/quickstart.pdf', 'F');

echo "Wrote quickstart.pdf\n";

نفّذه:

php examples/quickstart-first.php

الملف quickstart.pdf هو ملف ⁨PDF 2.0⁩ صالح. تؤكد مجموعة الاختبارات أن مخرجات السلسلة النصية المطابقة تبدأ بـ %PDF للوجهات S وF وE وكذلك لـ getPDFData().

وجهات الإخراج

يربط Output($name, $dest) رموز وجهات ⁨TCPDF⁩ عبر جسر إخراج آمن. تختبر مجموعة الاختبارات هذا السلوك:

$dest	السلوك	القيمة المُرجَعة
'S'	إرجاع ملف ⁨PDF⁩ كسلسلة نصية	بايتات ⁨PDF⁩ (%PDF…)
'F'	كتابة ملف ⁨PDF⁩ إلى المسار المُعطى	سلسلة نصية فارغة
'E'	إرجاع جسم ⁨MIME⁩ مُرمَّز بصيغة ⁨base64⁩	كتلة Content-Type: application/pdf
'I'	مضمَّن (افتراضي)	وفقاً لجسر الإخراج
'D'	تنزيل	وفقاً لجسر الإخراج

بخلاف ⁨TCPDF⁩ القديم، لا يطبع Output() مباشرةً في مخزن الإخراج النشط. يمكنك استدعاؤه بأمان داخل عامل طابور أو معالج ⁨HTTP⁩ يدير استجابته بنفسه. راجع /⁨integrations/tcpdf-compat/production-usage/.⁩

2. شغّل شيفرة ⁨TCPDF⁩ القائمة دون تغيير

لإجراء ترحيل فعلي، ابدأ بتشغيل شيفرتك الحالية مع تغيير سطر الاستيراد أو الاسم البديل فقط. إذا كانت قاعدة شيفرتك تستدعي new \TCPDF(...) في فضاء الأسماء العام، ففعّل الأسماء البديلة الاختيارية مرة واحدة عند الإقلاع (موضّح في /⁨integrations/tcpdf-compat/boot-and-discovery/⁩):

examples/quickstart-alias.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Legacy code now resolves \TCPDF to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Legacy call site, modern engine');
$pdf->Output(__DIR__ . '/aliased.pdf', 'F');

LegacyBootstrap::enableAliases() دالة عديمة الأثر التراكمي. فهي تسجّل \TCPDF و\TCPDF_STATIC و\TCPDF_FONTS و\TCPDF_COLORS و\TCPDF_IMAGES فقط عندما لا تكون تلك الأصناف موجودة بالفعل. يؤكد اختبار الحزمة tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php أن الأسماء البديلة تُسجَّل، وأن الاستدعاء عديم الأثر التراكمي، وأن new \TCPDF() نسخة من المحوّل. لا تفعّل الأسماء البديلة إذا كانت مكتبة ⁨TCPDF⁩ الفعلية محمّلة في العملية نفسها؛ راجع /⁨integrations/tcpdf-compat/troubleshooting/.⁩

3. التدقيق باستخدام الوضع الصارم

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

examples/quickstart-strict-audit.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\Exception\TcpdfNotImplementedException;
use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->setStrictMode(true);
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);

try {
    // 14 of these parameters are silently ignored by the adapter.
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    // The message names every ignored parameter and a migration hint.
    fwrite(STDERR, $e->getMessage() . "\n");
}

يؤكد اختبار الحزمة tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php أن هذا الاستدعاء بالضبط يطلق استثناءً في الوضع الصارم ويبقى صامتاً في الوضع الافتراضي، وأن الرسالة تتضمن اسم الدالة والمعاملات المتجاهَلة. استخدم الاستثناءات المجمّعة كقائمة عمل للترحيل لديك — راجع /⁨integrations/tcpdf-compat/migration/.⁩

4. الوصول إلى الواجهة البرمجية الحديثة عند الحاجة

تعرض كل نسخة من المحوّل مستند المحرّك الأساسي. استخدمه لاستدعاء دوال ⁨NextPDF⁩ الحديثة التي لا مكافئ لها في ⁨TCPDF⁩:

examples/quickstart-escape-hatch.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call');

// Drop to the modern engine API:
$document = $pdf->getDocument();
$document->setFont('Helvetica', 'B', 16)
    ->cell(0, 10, 'Modern fluent API', newLine: true);

تُرجع getDocument() كائن NextPDF\Core\Document الذي يغلّفه المحوّل. هذا هو مسار الخروج الموصى به: انقل مواضع الاستدعاء لديك إلى الواجهة البرمجية الحديثة واحداً تلو الآخر، حتى تتمكن من إزالة المحوّل.

فروق سلوكية ينبغي توقعها فوراً

• تُرجع MultiCell() القيمة 1، وليس عدد الخلايا المعروضة. تحتاج الشيفرة التي تتفرع بناءً على القيمة المُرجَعة من MultiCell() إلى تعديل.
• تطلق Error() الاستثناء RuntimeException بدلاً من استدعاء die(). يجب أن تلتقط الشيفرة التي اعتمدت على إنهاء العملية هذا الاستثناء.
• تختلف بايتات ⁨PDF⁩ الدقيقة عن مخرجات ⁨TCPDF.⁩ أعد ضبط القيم المرجعية لتأكيدات الاختبار على مستوى البايت بحيث تتحقق من المحتوى المعروض بدلاً من ذلك.

توجد القائمة الكاملة لكل دالة في /⁨integrations/tcpdf-compat/method-coverage/.⁩

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

• /⁨integrations/tcpdf-compat/migration/⁩ — استراتيجية الترحيل الكاملة ملفاً بملف.
• /⁨integrations/tcpdf-compat/configuration/⁩ — الوضع الصارم والقيم الافتراضية وكائن الإعدادات الحديث.
• /⁨integrations/tcpdf-compat/production-usage/⁩ — العمّال ومخازن الإخراج والأداء.
• /⁨integrations/tcpdf-compat/security-and-operations/⁩ — وضعية التشفير والتوقيع.

انظر أيضاً

• tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — مرجع سلوك الإخراج
• tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php — مرجع الوضع الصارم
• docs/TCPDF_COVERAGE.md — مصفوفة التغطية المرجعية