مرجع API للتوافق مع TCPDF

نظرة سريعة

تكشف حزمة nextpdf/compat-legacy صنفًا رئيسيًا واحدًا، هو NextPDF\Compat\Tcpdf\TCPDF. يحاكي هذا الصنف واجهة ⁨API⁩ العامة لـ ⁨TCPDF 6.x⁩، لكنه يُصيّر باستخدام محرك ⁨NextPDF⁩ الحديث. وتتضمن الحزمة أيضًا واجهة دعم صغيرة: LegacyBootstrap لأسماء الأصناف العامة البديلة، وواجهة التهيئة AdaptationConfig/LegacyDefaults، وأصناف جسور داخلية للإخراج والإنشاء واللون والوحدات وتنسيقات الصفحات، واستثناءات التوافق. استخدمها كوسيلة مساعدة على الترحيل، لا كاعتمادية دائمة. يُعَدّ جدول تغطية الدوال المصدر المرجعي لحالة دوال الإصدار القديم كاملةً. توثّق هذه الصفحة فقط الواجهات التي ينبغي لشيفرة التطبيق الاعتماد عليها عن قصد.

ابدأ من هنا: إذا كنت جديدًا على هذه الحزمة، فأنشئ NextPDF\Compat\Tcpdf\TCPDF، وأجرِ استدعاءات ⁨TCPDF⁩ المعتادة (AddPage() وSetFont() وCell())، ثم اختم بـ Output($name, $dest). هذا الصنف هو نقطة الدخول لكل شيء تقريبًا فيما يلي. للاطلاع على نقاط بداية قابلة للتشغيل، راجع المهام الشائعة.

المهام الشائعة

هذه هي مهام الحزمة التي ستستخدمها غالبًا. جرت مطابقة كل مقطع مع مصدر المُحوِّل، وهو يعمل كما هو.

أنتج ملف صيغة المستندات المحمولة (⁨PDF⁩) باستخدام استدعاءات ⁨TCPDF⁩ المألوفة، ثم التقطه كسلسلة نصية لاستخدامه في قائمة انتظار، أو استجابة ⁨HTTP⁩، أو التخزين:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

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

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

ما الذي يفعله: يُنشئ مستند ⁨PDF 2.0⁩ عبر المُحوِّل ذي الشكل المطابق لـ ⁨TCPDF.⁩ ويُعيد البايتات الخام (%PDF...) لأن الوجهة 'S' توجِّه عبر OutputBridge إلى Document::getPdfData() بدلًا من الطباعة المباشرة، لذلك يكون آمنًا داخل عامل معالجة أو وحدة تحكم.

سجّل الأسماء البديلة العامة مرة واحدة عند الإقلاع لتشغيل شيفرة new \TCPDF(...) القائمة دون تعديل المصدر:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

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

ما الذي يفعله: تُسجِّل enableAliases() بصورة آمنة عند التكرار \TCPDF (والمساعدات \TCPDF_STATIC/\TCPDF_FONTS/\TCPDF_COLORS/\TCPDF_IMAGES) فقط حين لا تكون تلك الأسماء معرَّفة مسبقًا. عندئذٍ تعمل الشيفرة القديمة دون تغيير على المُحوِّل.

دقِّق عملية الترحيل بإظهار كل معامل من معاملات ⁨TCPDF⁩ كان المُحوِّل سيُسقِطه بصمت لولا ذلك:

<?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 {
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    fwrite(STDERR, $e->getMessage() . "\n"); // names every ignored parameter
}

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

المُحوِّل الرئيسي

هذا الجدول هو واجهة المُحوِّل المرجعية. استخدمه للعثور على الصنف الذي تُنشئه (TCPDF)، ودوالّ الوضع الصارم ومخارج الطوارئ الخاصة به، والعقد الذي يُنفّذه.

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يُطلِق أو يفشل بـ	ملاحظات
NextPDF\Compat\Tcpdf\TCPDF	تتبع معاملات المُنشئ شكل ⁨TCPDF⁩ القديم عبر ConstructorBridge.	يُنشئ مُحوِّلًا مدعومًا بمستند ⁨NextPDF.⁩	TCPDF	استثناءات التحقق من صحة المُنشئ أو الميزات غير المدعومة.	استخدمه أثناء الترحيل، لا في شيفرة ⁨NextPDF⁩ الأصيلة الجديدة.
TCPDF::getDocument()	لا شيء.	يُعيد مستند ⁨NextPDF⁩ الأساسي.	NextPDF\Core\Document	لا شيء متوقَّع.	استخدمه كمخرج طوارئ لشيفرة الترحيل التي تحتاج إلى المزج بين الاستدعاءات القديمة والأصيلة.
TCPDF::getUnitConverter()	لا شيء.	يُعيد المُحوِّل المُنشأ من الوحدة القديمة.	UnitConverter	لا شيء متوقَّع.	استخدمه لتشخيصات الترحيل، لا لشيفرة التطبيق العادية.
TCPDF::setStrictMode(bool $enabled)	راية الوضع الصارم.	يُمكِّن أو يُعطِّل الفشل الصريح لسلوك التوافق غير المدعوم.	static	لا شيء متوقَّع.	أبقِه مُمكَّنًا أثناء عمليات تدقيق الترحيل.
TCPDF::isStrictMode()	لا شيء.	يُعيد راية الوضع الصارم الحالية.	bool	لا شيء متوقَّع.	مفيد في تأكيدات الاختبار.
دوال TCPDF القديمة	يختلف بحسب الدالة.	الدوال المدعومة تُربَط باستدعاءات مستند النواة؛ والدوال غير المدعومة تفشل صراحةً.	يختلف بحسب الدالة.	TcpdfNotImplementedException أو UnsupportedFeatureException.	تحقّق من تغطية الدوال قبل الاعتماد على دالة.
CompatAdapterInterface::getDocument()	لا شيء.	دالة العقد التي يُنفّذها TCPDF.	Document	لا شيء متوقَّع.	تتيح للأدوات الوصول إلى المستند الأصيل.
CompatAdapterInterface::Output(string $name = '', string $dest = '')	اسم الملف والوجهة القديمة.	يُفوِّض إلى جسر الإخراج.	string	أخطاء كتابة النواة أو الوجهة غير المدعومة.	يحاكي إخراج ⁨TCPDF⁩ القديم؛ ويوفّر تطبيق TCPDF::Output الملموس القيم الافتراضية 'doc.pdf'/'I'.

مجموعات الدوال القديمة

يربط هذا الجدول عائلات دوال ⁨TCPDF⁩ التي يغطّيها المُحوِّل. استعرضه لتحديد موضع استدعاء قديم قبل التحقق من حالته الدقيقة في تغطية الدوال.

المجموعة	رموز تمثيلية	السلوك الافتراضي	ملاحظات
دورة الحياة والإخراج	Open(), Close(), Output(), getPDFData()	يحافظ على دورة حياة مستند ذي شكل مطابق لـ ⁨TCPDF⁩ فوق مستند أصيل.	فضّل واجهات الإخراج الأصيلة بعد اكتمال الترحيل.
البيانات الوصفية	SetTitle(), SetAuthor(), SetSubject(), SetKeywords(), SetCreator()	يربط واضعات البيانات الوصفية بالمستند الأساسي.	أبقِ تطبيع البيانات الوصفية في شيفرة التطبيق.
الصفحات والتموضع	AddPage(), setPage(), lastPage(), GetX(), SetXY()	يحوّل الوحدات والإحداثيات القديمة إلى عمليات صفحات أصيلة.	تحقّق بصريًا من التموضع المطلق بعد الترحيل.
الهوامش والتخطيط	SetMargins(), SetAutoPageBreak(), setCellPaddings(), getMargins()	يُخزِّن حالة التوافق ويربط القيم المدعومة.	قد يتطلب سلوك فواصل صفحات ⁨TCPDF⁩ المعقّد مراجعةً يدوية.
الخطوط والنصوص	SetFont(), AddFont(), Cell(), MultiCell(), Write(), Text()	يوجِّه عمليات النصوص الشائعة إلى واجهات الخطوط والنصوص الأصيلة.	تحقّق من سلوك ⁨CJK⁩ والترميز باستخدام خطوط الإنتاج.
⁨HTML⁩	writeHTML(), writeHTMLCell(), fixHTMLCode()	يمرّر ⁨HTML⁩ المدعوم إلى خط أنابيب ⁨HTML⁩ الأصيل.	المُصيّر الأصيل ليس نسخة كاملة من ⁨HTML⁩ الخاص بـ ⁨TCPDF.⁩
الصور والرسم	Image(), Line(), Rect(), Circle(), SetDrawColor()	يربط عمليات الرسوميات المدعومة عبر مكوّنات المُحوِّل المختصة.	التنسيقات المتجهة أو الخاصة غير المدعومة تفشل صراحةً.
التنقّل والتعليقات التوضيحية	Bookmark(), AddLink(), SetLink(), Annotation()	يحافظ على استدعاءات التنقّل الشائعة حيث تكون مربوطة.	تحقّق من صحة المخططات والروابط المُولَّدة.
الأمن والتواقيع	SetProtection(), setSignature(), setTimeStamp(), setUserRights()	يربط استدعاءات الأمن القديمة المدعومة بالميزات الأصيلة.	تعامل مع المُخرَجات التشفيرية كبوابة تحقُّق منفصلة.
النماذج والقوالب والتحويلات	TextField(), startTemplate(), StartTransform(), Rotate(), Scale()	يُنفّذ المجموعات الفرعية المدعومة ويفشل بوضوح عند السلوك غير المدعوم.	دقِّق كل استدعاء مقابل تغطية الدوال قبل الطرح.

التمهيد والتهيئة

استخدم هذا الجدول حين تدمج المُحوِّل في مسار إقلاع تطبيق، أو تُسجّل الأسماء البديلة العامة، أو تختار بين الثوابت القديمة وAdaptationConfig الحديث.

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يُطلِق أو يفشل بـ	ملاحظات
LegacyBootstrap::enableAliases()	لا شيء.	يُسجِّل الأسماء البديلة للتوافق مرة واحدة.	void	أخطاء التحميل التلقائي أو البيئة.	استخدمها فقط حين تتوقع الشيفرة القديمة وجود أسماء ⁨TCPDF⁩ في النطاق العام.
LegacyBootstrap::isRegistered()	لا شيء.	يُبلِّغ عمّا إذا كانت الأسماء البديلة قد سُجِّلت.	bool	لا شيء متوقَّع.	مفيد في اختبارات التمهيد.
LegacyBootstrap::resetForTesting()	لا شيء.	يمسح حالة التسجيل من أجل الاختبارات.	void	لا شيء متوقَّع.	مساعد مخصص للاختبار فقط.
AdaptationConfig	رايات المُحوِّل وضوابط الترحيل.	يستخدم القيم الافتراضية للحزمة عند حذفها.	AdaptationConfig	قيم خيارات غير صالحة.	أبقِ التهيئة صريحة أثناء عمليات تدقيق الترحيل.
AdaptationConfig::fromLegacyConstants()	لا شيء.	يقرأ الثوابت القديمة المعروفة ويبني كائن تهيئة.	AdaptationConfig	قيم ثوابت قديمة غير صالحة.	مساعد انتقالي للتطبيقات القديمة الكبيرة.
LegacyDefaults	لا شيء.	يوفّر القيم الافتراضية القديمة.	القيم الافتراضية.	لا شيء متوقَّع.	مكان مركزي للقيم الافتراضية للتوافق.

الجسور والمساعدات

تُشغِّل أصناف التحويل الداخلية هذه المُحوِّل. استخدم هذا الجدول حين تساهم في تغطية المُحوِّل أو تشخّص طريقة ترجمة وسيط قديم. في شيفرة التطبيق اليومية، فضّل واجهة المُحوِّل العامة.

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يُطلِق أو يفشل بـ	ملاحظات
ConstructorBridge	قائمة وسائط مُنشئ قديمة.	يُسوّي الخيارات القديمة إلى تهيئة ⁨NextPDF.⁩	بيانات المُنشئ.	قيم وسائط قديمة غير صالحة.	يُستخدَم داخليًا بواسطة المُحوِّل.
CellParameterAdapter	معاملات خلية ⁨TCPDF.⁩	يربط الوسائط الموضعية القديمة بخيارات تخطيط نص النواة.	معاملات مُكيَّفة.	أبعاد أو محاذاة غير صالحة.	فضّل دوال النواة الأصيلة في الشيفرة الجديدة.
OutputBridge::dispatch(Document $document, string $filename, string $dest)	المستند الأصيل واسم الملف والوجهة القديمة.	يربط سلوك ⁨inline/download/⁩الحفظ بواجهات إخراج ⁨NextPDF.⁩	string	أخطاء كتابة النواة؛ والوجهة غير المدعومة.	تحقّق من صحة أسماء الملفات وجذور التخزين قبل الإخراج.
OutputBridge::resolveDestination(string $dest)	رمز الوجهة القديمة.	يحوّل الوجهة إلى وجهة إخراج أصيلة.	OutputDestination	أخطاء الوجهة غير المدعومة.	يُبقي ربط الوجهات مركزيًا.
ColorTranslator	وسائط لون ⁨TCPDF.⁩	يُسوّي صيغ الألوان القديمة.	قيمة لون النواة.	قيم ألوان غير صالحة.	تستخدمه مكوّنات اللون والرسم.
PageFormatResolver	مُدخَل تنسيق صفحة قديم.	يربط الأسماء المعروفة بأحجام صفحات النواة.	قيمة تنسيق الصفحة.	تنسيق غير معروف.	استخدم أحجام صفحات أصيلة وصريحة بعد الترحيل.
UnitConverter	قيم القياس والوحدات القديمة.	يحوّل إلى وحدات النواة.	قيمة عددية.	وحدة غير صالحة.	يساعد على الحفاظ على سلوك التخطيط القديم.

الاستثناءات

استخدم هذا الجدول حين يفشل استدعاء ترحيل بوضوح. فهو يفصل حالات الفشل “غير المُنفَّذة” عن “المعروفة لكن غير المدعومة” ويُظهِر مسار الاسترداد.

الرمز	المعنى	الاسترداد
TcpdfNotImplementedException	المُحوِّل لا يُنفّذ عمدًا الدالة القديمة المطلوبة.	استبدل الاستدعاء بواجهة ⁨NextPDF⁩ الأصيلة أو أزِل الاعتمادية.
TcpdfNotImplementedException::forSilentIgnore()	استدعاء قديم كان سيُتجاهَل سابقًا، لكنه يُظهَر من أجل وضوح الترحيل.	قرّر ما إذا كان سلوك عدم التنفيذ الصريح مقبولًا.
TcpdfNotImplementedException::forUnimplemented()	استدعاء قديم ليس له مسار مُحوِّل مُنفَّذ.	استبدل الاستدعاء أو اعزله خلف شيفرة الترحيل.
UnsupportedFeatureException	الميزة القديمة معروفة لكنها غير مدعومة ضمن حدود المُحوِّل.	راجع إرشادات الترحيل واعزل الميزة خلف مُحوِّل على مستوى التطبيق.
UnsupportedFeatureException::forMethod()	يُنشئ خطأ ميزة غير مدعومة خاصًّا بدالة معيّنة.	استخدمه في مساهمات التوافق للحفاظ على اتساق رسائل الفشل.

ملاحظات التطوير

• تعامل مع المُحوِّل كأداة ترحيل. ينبغي للشيفرة الجديدة أن تستهدف واجهات نواة ⁨NextPDF⁩ مباشرةً.
• ينبغي للسلوك غير المدعوم أن يفشل بوضوح. لا تلتقط استثناءات التوافق وتستمر بمستند جزئي ما لم يقبل التطبيق تلك المخاطرة صراحةً.
• أبقِ تغييرات الترحيل صغيرة وتحقّق من كل دالة قديمة مقابل جدول التغطية.