تكامل compat-legacy مع NextPDF

نظرة سريعة

استخدم nextpdf/compat-legacy لربط تطبيقك بحيث تعمل شيفرة ⁨TCPDF 6.x⁩ الحالية فوق محرك ⁨NextPDF.⁩ هذه الحزمة أداة ترحيل، وليست طبقة توافق دائمة — أزِلها بعد تبنّي واجهة برمجة التطبيقات (⁨API⁩) الحديثة (راجع /⁨integrations/tcpdf-compat/migration/⁩). إنها بديل متوافق مع ⁨TCPDF⁩، وليست نسخة جاهزة للاستبدال المباشر: 94 من بين نحو 120 من توابع ⁨TCPDF⁩ التي شملها المسح تفوّض العمل مباشرةً. أما التوابع المتبقية، فلها فروق سلوكية موثّقة (راجع /⁨integrations/tcpdf-compat/method-coverage/⁩).

التثبيت

composer require nextpdf/compat-legacy:^3.0

يؤدي هذا إلى حلّ تبعية nextpdf/core ^3.0 بصورة متعدية. للاطلاع على المتطلبات الكاملة وفحص التحقق، راجع /⁨integrations/tcpdf-compat/install/.⁩

الإقلاع والاكتشاف التلقائي

لا توصّل الحزمة المتغيرات العامة أثناء التحميل التلقائي. واستدعاؤها عبر ⁨require⁩ لا ينشئ \TCPDF عاماً. أنت من يحدد كيف تحلّ مواضع الاستدعاء الصنف:

المُفضّل (الاستيرادات الصريحة). حدّث أسطر use/require إلى use NextPDF\Compat\Tcpdf\TCPDF; في كل ملف. هذا الأسلوب واضح لا لبس فيه وسهل البحث عنه.
أسماء بديلة عامة باشتراك اختياري. استدعِ LegacyBootstrap::enableAliases() مرة واحدة عند الإقلاع لتسجيل \TCPDF وأصناف المساعدة الأربعة — فقط إذا لم تكن تلك الأسماء مستخدَمة بالفعل. توضح الصفحة التالية الآلية والخاصية العَطوبية وقاعدة التعارض مع ⁨TCPDF⁩ الحقيقي: /⁨integrations/tcpdf-compat/boot-and-discovery/.⁩

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

// One call at application bootstrap, before any \TCPDF use.
LegacyBootstrap::enableAliases();

ارتباطات الحاوية

لا تتضمن الحزمة مزوّد خدمة أو حزمة خاصة بإطار عمل. طبقة التكامل الرقيقة من مسؤوليتك. اربط مصنعاً يعيد مُحوِّلاً جديداً لكل مستند — وليس نسخة مفردة مشتركة أبداً، لأن كل نسخة تحتفظ بحالة المستند الخاصة بها (راجع /⁨integrations/tcpdf-compat/production-usage/⁩ § ⁨Concurrency⁩).

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use Psr\Container\ContainerInterface;

// Pseudocode for a PSR-11-style container: bind a factory, not a shared instance.
$container->set(TCPDF::class, static function (ContainerInterface $c): TCPDF {
    return new TCPDF('P', 'mm', 'A4');
});

// Each resolution is an independent document context.
$pdf = $container->get(TCPDF::class);

في ⁨Symfony⁩، سجّل المصنع كخدمة غير مشتركة. وفي ⁨Laravel⁩، استخدم bind (وليس singleton) بحيث يحصل كل تحليل على نسخة جديدة. تظل الحزمة نفسها محايدة تجاه إطار العمل.

نشر الإعدادات

لا يوجد ملف إعدادات قابل للنشر خاص بإطار عمل. اضبط المُحوِّل عبر ثوابت K_* / PDF_* القديمة (عرّفها في كود الإقلاع قبل أول إنشاء) أو عبر كائن NextPDF\Compat\Tcpdf\Config\AdaptationConfig الحديث غير القابل للتغيير. راجع /⁨integrations/tcpdf-compat/configuration/.⁩

اختبار دخان مزوّد الخدمة / الحزمة

بعد التوصيل، تحقّق من أن التكامل ينتج ملف ⁨Portable Document Format⁩ (⁨PDF⁩) صالحاً. يعكس هذا واجهة الإخراج التي يؤكدها tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Integration smoke test');

$bytes = $pdf->Output('smoke.pdf', 'S');

assert(str_starts_with($bytes, '%PDF'), 'Integration smoke test failed');
echo "Integration OK\n";

في سياق ⁨Hypertext Transfer Protocol⁩ (⁨HTTP⁩) أو في سياق عامل، استخدم Output(..., 'F') أو 'S'. لا تعتمد على المسار المضمَّن. للاطلاع على الإرشادات التشغيلية الكاملة، راجع /⁨integrations/tcpdf-compat/production-usage/.⁩

نقاط الدخول العامة لواجهة ⁨API⁩

نقطة الدخول	الغرض
`NextPDF\Compat\Tcpdf\TCPDF`	واجهة متوافقة مع ⁨TCPDF.⁩ أنشئ نسخة واحدة لكل مستند.
`TCPDF::getDocument()`	يعيد كائن `NextPDF\Core\Document` المغلَّف — وهو منفذ الخروج إلى واجهة ⁨API⁩ الحديثة.
`TCPDF::setStrictMode(bool)`	مفتاح تدقيق الترحيل (راجع /⁨integrations/tcpdf-compat/configuration/⁩).
`NextPDF\Compat\Tcpdf\LegacyBootstrap::enableAliases()`	أسماء بديلة عامة للأصناف باشتراك اختياري.
`NextPDF\Compat\Tcpdf\Config\AdaptationConfig`	كائن إعدادات حديث غير قابل للتغيير.
`NextPDF\Compat\Contracts\CompatAdapterInterface`	عقد توافق مشترك.

تغطية واجهة ⁨TCPDF API⁩

مصفوفة التغطية المرجعية المُتحقَّق منها بالاختبارات موجودة في الملف docs/TCPDF_COVERAGE.md داخل المستودع. أما الملخص الموجَّه للقارئ — التوابع المعكوسة والمتجاهَلة بصمت وغير المنفَّذة وغير القابلة للتطبيق — فهو /⁨integrations/tcpdf-compat/method-coverage/.⁩ لا تصفها بأنها تنفيذ “بديل جاهز للاستبدال المباشر” أو “متوافق 100%”. صِفها بأنها بديل متوافق مع ⁨TCPDF⁩، بواجهة معروفة ومختبَرة وفروق سلوكية موثّقة.

انظر أيضاً

docs/TCPDF_COVERAGE.md — مصدر التغطية المرجعي في المستودع
/⁨integrations/tcpdf-compat/boot-and-discovery/⁩ — كشف الواجهة وسلوك الأسماء البديلة
/⁨integrations/tcpdf-compat/method-coverage/⁩ — سلوك كل تابع والثغرات
/⁨integrations/tcpdf-compat/migration/⁩ — استراتيجية ترحيل مرحلية
/⁨integrations/tcpdf-compat/production-usage/⁩ — تشغيل المُحوِّل تحت الحِمل
tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — مرجع سلوك الإخراج