لمحة عامة عن compat-legacy في NextPDF

لمحة سريعة

nextpdf/compat-legacy هو بديل متوافق مع ⁨TCPDF⁩: طبقة توافق تعرض واجهة ⁨TCPDF 6.x⁩ البرمجية العامة على محرك ⁨Portable Document Format⁩ (⁨PDF⁩) 2.0 الخاص بـ ⁨NextPDF.⁩ مهمته واحدة: مساعدة الشيفرة التي تعتمد أصلًا على ⁨TCPDF 6.x⁩ على العمل على محرك ⁨NextPDF⁩ من دون إعادة كتابة، لتتمكن من الترحيل ملفًا تلو الآخر بدلًا من الترحيل دفعة واحدة.

إنه ليس نسخة متفرّعة من ⁨TCPDF⁩، ولا يضمن مطابقة سلوكية له. إنه تنفيذ مستقل يحافظ على تواقيع استدعاءات ⁨TCPDF.⁩ الوصف الدقيق هو: يغطّي 94 من نحو 120 طريقة ⁨TCPDF 6.x⁩ خضعت للاستقصاء عبر التفويض المباشر، بينما تحمل الطرائق المتبقية فروقًا سلوكية موثّقة (انظر /⁨integrations/tcpdf-compat/method-coverage/⁩).

ما هو

أداة ترحيل. تنتمي الحزمة إلى عائلة التوافق في ⁨NextPDF.⁩ وتساعدك على الابتعاد عن مكتبة ⁨PDF⁩ قديمة؛ ولا يُقصد بها أن تصبح اعتمادية دائمة. عامِلها كسقالة تزيلها عند تبنّي الواجهة البرمجية الحديثة.
مُحوّل لسطح الواجهة البرمجية. يوفّر اسم صنف ⁨TCPDF⁩، وأسماء الطرائق، وترتيب المعاملات، والقيم الافتراضية الخاصة بالإصدار 6.2.13. ويفوّض الاستدعاءات إلى نسخة من NextPDF\Core\Document.
تنفيذ مستقل أُنشئ في غرفة نظيفة. لا تنسخ هذه الحزمة شيفرة ⁨TCPDF⁩ المصدرية أو نواتج البناء أو بيانات الخطوط أو أي تعبير آخر قابل لحقوق التأليف، ولا تترجمها. وتستخدم اسم ⁨TCPDF⁩ فقط للدلالة على قابلية التشغيل البيني. يرد البيان المرجعي في ملف NOTICE الخاص بالحزمة.

ما ليس هو

إنه ليس “بديلًا جاهزًا للإحلال” بمُخرَج مطابق على مستوى البايت. في الطرائق المفوّضة، تكون النتيجة المرئية متوافقة، لكن بايتات ⁨PDF⁩ المُصيَّرة تختلف لأن تنفيذ ⁨PDF 2.0⁩ العامل في الأسفل منفصل ومستقل.
إنه ليس “متوافقًا مع ⁨TCPDF⁩ بنسبة 100%”. تقبل مجموعة محددة من الطرائق معاملات قديمة لا يلتزم بها المحرك، أو لا تفعل شيئًا على الإطلاق. هذه الطرائق مُعدّدة ومُختبَرة — انظر /⁨integrations/tcpdf-compat/method-coverage/.⁩
إنه ليس منتج توقيع أو أرشفة بحدّ ذاته. فالتواقيع الرقمية ومطابقة الأرشفة وفق ⁨PDF/A⁩ محصورة في إصدار تجاري من ⁨NextPDF.⁩ ولا تقدّم هذه الوثائق أي ادعاءات بتوقيع معتمد أو مضمون أو صالح قانونيًا.

لماذا الترحيل عبر طبقة توافق

تنطوي إعادة كتابة كل استدعاء لـ ⁨TCPDF⁩ في تطبيق كبير على مخاطرة، ويصعب طرحها تدريجيًا. تتيح لك طبقة التوافق ما يلي:

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

الحالة النهائية هي استخدام واجهة NextPDF\Core\Document البرمجية الحديثة مع إزالة طبقة التوافق. انظر /⁨integrations/tcpdf-compat/migration/⁩ للاطلاع على الاستراتيجية الكاملة.

ما الذي تكسبه على محرك ⁨NextPDF⁩

عندما يفوّض المُحوّل استدعاء ⁨TCPDF⁩، يعمل الاستدعاء على محرك ⁨PDF 2.0⁩ (⁨ISO 32000-2⁩)، مع توفّر تشفير المعالج القياسي ⁨Advanced Encryption Standard⁩ (⁨AES⁩)-256 وأمان أنواع ⁨PHPStan⁩ بالمستوى 10 عبر المُحوّل بالكامل. يُكتب المُخرَج دائمًا بصيغة ⁨PDF 2.0⁩؛ ولا يمكن للمُحوّل استهداف إصدارات ⁨PDF⁩ أقدم (انظر /⁨integrations/tcpdf-compat/method-coverage/⁩ §4).

يُصلّب المُحوّل عدة سلوكيات تاريخية في ⁨TCPDF 6.2.13⁩:

السلوك القديم	سلوك المُحوّل
`Error()` يستدعي `die()` ويُنهي العملية بصمت	`Error()` يطرح `RuntimeException` — يمكن ملاحظته والتقاطه
طريقة ⁨HTML⁩ يمكنها تنفيذ ⁨PHP⁩ من التوصيف	منفذ التهرّب هذا مُعطَّل — لا يمكن للتوصيف إطلاق تنفيذ ⁨PHP⁩
`Output()` يطبع مباشرةً ويمكن أن يُفسد دفقات إخراج العامل	يمر المُخرَج عبر جسر وجهة آمن
تكرار ⁨header/footer⁩ غير محمي	محمي ضد التكرار

النطاق والإصدارات

تُشحن طبقة التوافق ضمن توزيعة ⁨core⁩ (nextpdf/compat-legacy، التي تتطلّب nextpdf/core ^3.0). يتوفّر التشفير عبر المعالج القياسي في ⁨core.⁩ وتتطلّب التواقيع الرقمية ومطابقة الأرشفة وفق ⁨PDF/A⁩ إصدارًا تجاريًا من ⁨NextPDF⁩؛ يكشف المُحوّل نقاط الدخول، لكن مسار ⁨core⁩ ليس منتج توقيع. انظر /⁨integrations/tcpdf-compat/security-and-operations/⁩ للاطلاع على البيان الدقيق.

إلى أين تذهب بعد ذلك

/⁨integrations/tcpdf-compat/install/⁩ — ثبّت الحزمة وتحقّق من ارتباط المحرك.
/⁨integrations/tcpdf-compat/quickstart/⁩ — أنشئ أول مستند قابل للتشغيل ومدعوم باختبارات.
/⁨integrations/tcpdf-compat/method-coverage/⁩ — اطّلع بالضبط على ما تفعله كل طريقة ⁨TCPDF⁩ هنا.
/⁨integrations/tcpdf-compat/migration/⁩ — خطّط لاستراتيجية الترحيل ملفًا تلو الآخر.
/⁨integrations/tcpdf-compat/configuration/⁩ — اضبط الوضع الصارم وإعدادات المُحوّل.
/⁨integrations/tcpdf-compat/production-usage/⁩ — شغّل المُحوّل تحت الحِمل وداخل العوامل.
/⁨integrations/tcpdf-compat/security-and-operations/⁩ — راجع التشفير وحالة التوقيع والتصليب.
/⁨integrations/tcpdf-compat/troubleshooting/⁩ — أصلح أعطال الترحيل الشائعة.
/⁨integrations/tcpdf-compat/integration/⁩ / /⁨integrations/tcpdf-compat/boot-and-discovery/⁩ — اربط الواجهة بتطبيق وسجّل أسماء الأصناف العامة المستعارة.

انظر أيضًا

docs/TCPDF_COVERAGE.md — مصفوفة التغطية المرجعية (داخل المستودع)
ملف NOTICE الخاص بالحزمة — بيان التنفيذ المستقل