دليل المطوّر لتوافق TCPDF

لمحة سريعة

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

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

حدود البنية المعمارية

الطبقة	مملوكة من	المسؤولية	لا تضع هنا
التطبيق القديم	التطبيق	أبقِ الاستدعاءات القائمة على أسلوب ⁨TCPDF⁩ قيد التشغيل أثناء الهجرة.	ميزات ⁨PDF⁩ الجديدة التي ينبغي أن تستخدم واجهات ⁨NextPDF⁩ الأصلية.
غلاف المُحوِّل	nextpdf/compat-legacy	يعرّض الصنف على هيئة TCPDF وحالة التوافق المشتركة.	عائلات الدوال الكبيرة أو منطق التحويل.
سمات الاهتمامات	nextpdf/compat-legacy	تجميع عائلات الدوال القديمة: النص، الخطوط، الصور، الأمان، النماذج، الصفحات.	سياسة الإخراج العابرة للعائلات.
أصناف الجسر	nextpdf/compat-legacy	تحويل المعطيات والوجهات والألوان والوحدات والصيغ القديمة.	السلوك الخاص بالأعمال.
المحرّك الأساسي	nextpdf/nextpdf	إنشاء المستند الأصلي.	ضمانات التوافق القديمة.

دورة حياة التشغيل

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

جرد الهجرة

ابدأ بجمع كل استدعاء لدالة ⁨TCPDF⁩ في تطبيقك. صنّف كل استدعاء قبل أن تغيّر السلوك.

التصنيف	المعنى	الإجراء
دالة مُحوِّل مدعومة	الدالة موثّقة على أنها مدعومة ولها اختبارات.	أبقِها مؤقتًا، ثم هاجر عند تعديل هذا الجزء.
دالة مُحوِّل جزئية	الدالة موجودة، لكن سلوكها لا يطابق ⁨TCPDF⁩ القديم تمامًا.	أضف اختبارات بيانات مرجعية وتحقّق من الإخراج يدويًا.
دالة غير مدعومة صراحةً	يُطلق المُحوِّل استثناء توافق.	استبدلها بـ ⁨NextPDF⁩ الأصلي أو أزِل الميزة.
غلاف خاص بالأعمال	يُغلّف التطبيق استدعاءات ⁨TCPDF⁩ بالفعل.	هاجر داخليات الغلاف أولًا.
استدعاء حسّاس للامتثال	التوقيع، أو التشفير، أو الوسم، أو ⁨PDF/A⁩، أو إمكانية الوصول، أو سير عمل الفواتير.	هاجر إلى واجهات ⁨NextPDF⁩ الأصلية مع تحقّق مخصّص.

نمط المساهمة في المُحوِّل

أضف دعم التوافق ضمن أصغر عائلة دوال تمتلك ذلك السلوك.

نوع التغيير	أين تُنفّذ	الاختبار المطلوب
دالة إخراج النص	Concerns\AdaptsTextOutput أو اهتمام الخط.	بيانات مرجعية قديمة، إضافةً إلى تأكيد الإخراج الأصلي.
دالة الصفحة أو الهامش	اهتمام الصفحة أو التمَوضُع أو الهامش.	اختبار تحويل الإحداثيات وحالة الصفحة.
دالة الصورة أو الرسم	اهتمام الصورة أو الرسم أو اللون أو التدرّج.	اختبار التحقّق من المدخلات والإخراج ⁨visual/structural.⁩
وجهة الإخراج	OutputBridge.	اختبار ربط الوجهة والمسار غير الآمن.
ميزة غير مدعومة	مصنع الاستثناءات أو جدول تغطية الدوال.	اختبار نوع الاستثناء ورسالته.

لا تضع دالة كبيرة مباشرةً في غلاف المُحوِّل عندما توجد سمة اهتمام مخصّصة لتلك العائلة.

نمط الهجرة الأصلية

استخدم المُحوِّل لتثبيت الشيفرة القديمة، ثم انقل سير العمل المستقر إلى الواجهات الأصلية.

<?php

// Temporary compatibility code.
$pdf = new \NextPDF\Compat\Tcpdf\TCPDF();
$pdf->AddPage();
$pdf->SetFont('dejavusans', '', 12);
$pdf->Cell(0, 10, 'Invoice 1234');

// Target native shape.
$document = \NextPDF\Core\Document::createStandalone();
$document->addPage()
    ->setFont('dejavusans', '', 12)
    ->cell(0, 10, 'Invoice 1234');

تعامل مع الهجرة كسلسلة من النقلات السلوكية الصغيرة. يمكن لصفحة ما أن تستمر في استخدام المُحوِّل بينما ينتقل قسم واحد عالي المخاطر إلى الواجهات الأصلية.

نقاط التوسعة

نقطة التوسعة	استخدمها من أجل	القيد
AdaptationConfig	التحكّم في سلوك المُحوِّل أثناء الهجرة.	أبقِ القيم الافتراضية صريحة ومراجَعة.
سمات الاهتمامات	تجميع عائلات الدوال مثل النص أو النماذج أو الصور أو الأمان.	أضف الدوال إلى الاهتمام المناسب، لا إلى غلاف المُحوِّل.
أصناف الجسر	تحويل أشكال المعطيات القديمة إلى قيم النواة.	غطِّ سلوك الجسر باختبارات الهجرة.
CompatAdapterInterface	تجريد على مستوى المُحوِّل لأدوات العمل.	لا تستخدمه بديلًا عن عقود النواة الأصلية في الشيفرة الجديدة.
جدول تغطية الدوال	سجل دعم موجَّه للمطوّرين.	حدّثه عند تغيّر حالة الدعم.

سير عمل الهجرة

1. ثبّت المُحوِّل وشغّل مجموعة الاختبارات القديمة دون تغيير.
2. افتح تغطية الدوال وصنّف كل دالة مُستدعاة.
3. استبدل الدوال غير المدعومة أولًا.
4. انقل المسارات عالية الحجم أو الحسّاسة للامتثال إلى واجهات النواة الأصلية.
5. أضف تغطية بيانات مرجعية لكل عائلة دوال مُهاجَرة.
6. أزِل أسماء التهيئة الأولية المستعارة عندما لا تعتمد عليها أي نقطة دخول للتطبيق.

التعامل مع الإخفاق

الإخفاق	أين ينبغي معالجته	الاستجابة المُوصى بها
دالة غير مدعومة	استثناء المُحوِّل.	استبدل الاستدعاء أو اعزله خلف مُحوِّل على مستوى التطبيق.
تكافؤ جزئي في التخطيط	اختبارات الهجرة والمراجعة البصرية.	وثّق الفرق المقبول قبل الطرح.
وجهة إخراج غير آمنة	OutputBridge وسياسة التخزين على مستوى التطبيق.	ارفض المسارات غير الآمنة وفضّل واجهات الإخراج الأصلية.
عدم تطابق ميزة الأمان	خطة الهجرة الأصلية.	لا تشحن سلوكًا قائمًا على التوافق وحده للمخرجات الخاضعة للتنظيم.
تعارض أسماء التهيئة الأولية المستعارة	التهيئة الأولية للتطبيق.	أزِل الأسماء المستعارة العامة أو حصرها في نقاط الدخول القديمة.

القيم الافتراضية الآمنة

الاهتمام	القيمة الافتراضية	متى تتجاوز
الدوال غير المدعومة	إطلاق استثناء صريح.	لا تُضعف هذا في بيئة الإنتاج.
القيم الافتراضية القديمة	مركزية في LegacyDefaults.	تجاوزها فقط لسلوك هجرة معروف.
ربط الإخراج	يمرّ عبر OutputBridge.	استخدم واجهات الإخراج الأصلية بعد الهجرة.
مصدر التغطية	صفحة تغطية الدوال والاختبارات.	شغّل فحوص التغطية مجددًا بعد كل ترقية للمُحوِّل.
الوضع الصارم	أبقِه مفعّلًا أثناء عمليات تدقيق الهجرة.	عطّله فقط ضمن نافذة توافق قديمة موثّقة.

قائمة تحقّق الاختبار

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