الانتقال من المكتبات القديمة: TCPDF وFPDF وأمثالها

SpecSpec: ISO 32000-2ISO 32000-2SpecSpec: ISO 19005-4ISO 19005-4SpecSpec: ETSI EN 319 142-1ETSI EN 319 142-1

لمحة سريعة

إن كانت ملفات ⁨PDF⁩ لديك تُولَّد بواسطة ⁨TCPDF⁩ أو ⁨FPDF⁩ أو ⁨mPDF⁩ أو ⁨dompdf⁩، فالشيفرة على الأرجح ما زالت تعمل. وهذا بالضبط هو سبب سهولة إغفال المشكلة. تعمل المكتبة، ويُفتَح الملف، ولا تظهر الفجوة إلا يوم يطلب أحدهم مستندًا موقَّعًا أو قابلًا للأرشفة أو متاحًا للوصول، فيكون الجواب “لا نستطيع من هنا”.

هذه الصفحة هي قصّة الانتقال: ما هي تلك الجدران، ولماذا هي بنيوية لا عرضية، وكيف يمنحك ⁨NextPDF⁩ مسارًا تدريجيًّا للخروج منها — بما في ذلك سطح توافق مع ⁨TCPDF⁩ هو وسيلة مساعدة للانتقال، لا وعدٌ ببديل مطابق بايتًا ببايت يحلّ محلّها فورًا.

لماذا يهمّ هذا

مكتبة ⁨PDF⁩ ليست استدعاء عرض تجريه مرّة واحدة. إنها تبعية تَرِثها مستنداتك ما دامت قائمة. وحين تتوقّف تلك التبعية عن التطوّر، تتوقّف مستنداتك عن القدرة على فعل أشياء جديدة — وتكتشف ذلك في أسوأ لحظة ممكنة، حين يضع العميل أو المدقّق أو الجهة المنظِّمة السقف.

تبدو الجدران هكذا. تطوّر التنسيق: ⁨PDF 2.0⁩ هو الإصدار الحالي من المعيار (SpecSpec: ISO 32000-2ISO 32000-2)، وأيّ كاتب عالق على بنية 1.x متخلّف عن التنسيق الذي تفترضه بقية سلسلة أدواتك. أما التوقيع فضعيف أو ملحَق، وبعيد كثيرًا عن أنماط ⁨PAdES⁩ الأساسية التي تجعل التوقيع صامدًا (SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4). وأما المخرجات الأرشيفية إلى عائلة ⁨PDF/A⁩، والبنية الموسومة لإمكانية الوصول، فهي إمّا غائبة أو هشّة. والواجهة البرمجية نفسها بلا أنواع — اتجاهات نصية، وقيم منطقية موضعية، وقيم افتراضية تكتشفها بالصدفة — فلا يستطيع المترجم مساعدتك، ولا يستطيع المراجِع كذلك.

ليس أيّ من هذه عللًا يمكن ترقيعها. إنها شكل أداة بُنيت لعقد سابق، وعدد من تلك الأدوات لم يعد يتحرّك بنشاط نحو المعايير التي بات على مستنداتك الوفاء بها.

النسخة المختصرة

• مكتبات ⁨PHP⁩ القديمة لإنتاج ⁨PDF⁩ ما زالت في معظمها تعمل. المشكلة في ما يتعذّر عليها عادةً إنتاجه بمطابقة حديثة كاملة: ⁨PDF 2.0⁩، وتوقيعات مطابقة لخط الأساس، و⁨PDF/A⁩ مُتحقَّق منه، وإمكانية وصول موسومة — والدعم عبر المكتبات المذكورة محدود أو غائب.
• ⁨NextPDF⁩ محرّك ⁨PHP 8.4⁩ يكتب ⁨PDF 2.0⁩ افتراضيًّا، بأنواع صارمة، وملفات تعريف أرشيفية، وتوقيع ⁨PAdES⁩ بوصفها مخرجات من الدرجة الأولى.
• لست مضطرًّا إلى إعادة كتابة كل شيء في اليوم الأول. يتيح سطح التوافق مع ⁨TCPDF⁩ للاستدعاءات المألوفة أن تواصل العمل بينما تنقل منطق المستند الذي يهمّ.
• ذلك السطح متوافق مع ⁨TCPDF⁩، لا مطابق له بايتًا ببايت. إنه جسر يعبر بك خلال الانتقال، بفروق سلوكية موثّقة — لا ادّعاء بأن كل سكربت يعمل دون تغيير.
• الاختبار الصادق هو ما إذا كانت القدرات الجديدة تستحقّ الانتقال. ففي بعض أحمال العمل لا تستحقّه، ونقول ذلك بوضوح.

كيف يتعامل ⁨NextPDF⁩ مع ذلك

النهج هو جعل الانتقال تسلسلًا لا قفزة. تواصل إنتاج المستندات طوال الطريق، وتستبدل القيود القديمة واحدًا تلو الآخر بدلًا من رهن إصدار كامل على إعادة كتابة شاملة دفعة واحدة.

1. Inventoryاحصِ ما تحتاج مستنداتك فعلًا إلى إصداره — توقيعات، وملفات تعريف أرشيفية، وبنية موسومة، وخطوط — لا مجرّد الاستدعاءات التي تُجريها اليوم.
2. Bridgeاعتمد سطح التوافق مع TCPDF كي تواصل مواضع الاستدعاء القائمة إنتاج الملفات بينما يصبح المحرّك أسفلها NextPDF.
3. Portانقل منطق المستند الذي يهمّ إلى الواجهة البرمجية الأصلية ذات الأنواع، حيث يكون القصد صريحًا ويتحقّق منه المترجم.
4. Upgradeفعّل المخرجات التي يتعذّر على كثير من المكتبات القديمة بلوغها بمطابقة حديثة كاملة: بنية PDF 2.0، وPDF/A مُتحقَّق منه، وتوقيعات PAdES، وإمكانية وصول موسومة.
5. Verifyتحقّق من النتيجة بمدقّق حقيقي، كي يعني 'أرشيفي' أو 'موقَّع' أن أداةً توافق، لا مجرّد أن الملف فُتح.

انتقال تدريجي من مكتبة PDF قديمة: ابدأ على سطح التوافق كي تواصل الاستدعاءات القائمة العمل، ثم انقل منطق المستند إلى الواجهة البرمجية الأصلية ذات الأنواع، ثم فعّل المخرجات المعيارية (PDF 2.0، وPDF/A، وPAdES، وإمكانية الوصول) التي يتعذّر على كثير من المكتبات القديمة إنتاجها بمطابقة حديثة كاملة.

⁨PDF 2.0⁩ هو خط الأساس، لا راية ميزة. يكتب ⁨NextPDF⁩ الإصدار الحالي من التنسيق افتراضيًّا (SpecSpec: ISO 32000-2ISO 32000-2)، ويمكنه تسلسل بنى أقدم حين يطلبها ملف تعريف. أما المكتبة المجمَّدة على بنية 1.x فلا يمكنها بلوغك هنا؛ فهي ليست إعدادًا ينقصها، بل حقبة سبقتها.

الأرشفة وإمكانية الوصول خاصّتان من خصائص الكاتب. إنتاج ملف يقبله المدقّق بوصفه ⁨PDF/A⁩ شيء على المحرّك أن يفعله أثناء الكتابة — ولا يمكن لصقه لاحقًا (SpecSpec: ISO 19005-4ISO 19005-4). والأمر نفسه يصدق على البنية الموسومة التي تجعل ⁨PDF⁩ متاحًا للوصول. يبني ⁨NextPDF⁩ هذه أثناء التوليد، وهي بالضبط الخطوة التي يتعذّر على كثير من الأدوات القديمة اتخاذها — أو تتخذها جزئيًّا فقط، دون ما يقبله المدقّق.

التوقيع يتجاوز سقف خط الأساس. تتبع التوقيعات الإلكترونية المتقدّمة في ⁨PDF⁩ أنماط ⁨PAdES⁩ (SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4)، حيث يغطّي الملخّص نطاق بايتات مُعلَنًا ويحمل التوقيع البيانات الوصفية التي يفحصها المدقّق. ونادرًا ما تبلغ أداةُ توقيعٍ ملحقةٌ ذلك السقف. ويتعامل ⁨NextPDF⁩ معه بوصفه مخرجًا من الدرجة الأولى، لا فكرة متأخّرة.

سطح التوافق هو الجسر، مُصرَّح به بصدق. توجد طبقة التوافق مع ⁨TCPDF⁩ كي تواصل مواضع الاستدعاء القائمة إنتاج المستندات بينما تنقل الأجزاء التي تهمّ. وهي تتبع النموذج نفسه الذي يتبعه كل دليل انتقال في ⁨NextPDF⁩: متوافقة مع المكتبة المصدر، لا مطابقة لها بايتًا ببايت، مع تدوين الفروق السلوكية. وهذا الصدق هو المقصد — فادّعاء “بديل بنسبة 99٪” بصمت هو نوع التخمين الذي بُني هذا المحرّك لرفضه.

Human-factors note:Human-factors note

سبب الانتقال نادرًا ما يكون الشيفرة التي لديك اليوم؛ بل المستند الذي سيُطلَب منك غدًا. القابلية للصيانة خاصّة جودة مُسمّاة — مدى سهولة تحليل النظام وتغييره مع تبدّل الحاجات (SpecSpec: ISO/IEC 25010, §3.6ISO/IEC 25010 §3.6). والتبعية التي توقّفت عن التطوّر تُضعفها بهدوء، ولا تشعر بالكلفة إلا حين يصل متطلّب جديد فيكون الجواب “ليس من هنا”. الانتقال التدريجي يدفع تلك الكلفة وفق جدولك، بينما تتدفّق المستندات، بدلًا من دفعها كلّها دفعة واحدة تحت ضغط موعد نهائي.

مثال عملي

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

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use NextPDF\Contracts\Orientation;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\PageSize;

// 1) The bridge: a familiar TCPDF-shaped call keeps producing a file
//    while the engine underneath is already NextPDF. Behaviour is
//    compatible, not byte-identical — differences are documented.
$legacy = new TCPDF();
$legacy->AddPage();
$legacy->SetFont('helvetica', 'B', 16);
$legacy->Cell(0, 12, 'Migrated invoice', ln: 1);
$bridgedBytes = $legacy->Output('', 'S');

// 2) The destination: the same document expressed natively, where intent
//    is typed and the engine can emit what many legacy tools cannot.
$document = Document::createStandalone();
$document->setTitle('Migrated invoice');
$document->addPage(PageSize::a4(), Orientation::Portrait);
$document->setFont('helvetica', 'B', 16);
$document->cell(0, 12, 'Migrated invoice', newLine: true);

// Bytes only, no HTTP headers, no file side effect — stated, not inferred.
$nativeBytes = $document->output(dest: OutputDestination::String);

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

سوء فهم شائع

الأمل المتكرّر هو “لا بدّ من وجود راية تجعل مكتبتي القديمة تنتج ⁨PDF 2.0⁩ وتوقيعات”. لا وجود لها. فهذه ليست خيارات نسيت مكتبة ناضجة كشفها؛ إنها قدرات لم تُبنَ بنيتها حولها أصلًا. لا يمكنك التوصّل عبر الإعداد إلى إصدار تنسيق أو نمط توقيع لا يطبّقه كاتب.

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

الحدود والقيود

TCPDF-compatibility surface as a migration aid — edition availability

Edition	Availability
Core	○ سطح التوافق متوافق مع TCPDF، لا مطابق له بايتًا ببايت. وهو يغطّي مجموعة فرعية موثَّقة من الواجهة البرمجية كي تواصل مواضع الاستدعاء القائمة إنتاج الملفات أثناء الانتقال. إنه جسر، لا بديل مطابق: بعض السلوكيات تختلف وبعض الاستدعاءات غير مدعومة، وجميعها مُدرَجة في صفحات تغطية الدوال والانتقال. الوجهة هي الواجهة البرمجية الأصلية ذات الأنواع، حيث يقيم المخرَج المعياري.
Pro	●Available
Enterprise	●Available

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

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

مستندات ذات صلة

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

مسرد المصطلحات

• ⁨PDF 2.0⁩ — الإصدار الحالي من معيار تنسيق المستندات المحمولة (⁨ISO 32000-2⁩). يُوسَّع عند أول استخدام؛ التنسيق الذي يكتبه ⁨NextPDF⁩ افتراضيًّا.
• ⁨PDF/A⁩ — عائلة المطابقة الأرشيفية (سلسلة ⁨ISO 19005⁩) التي تحدّد ما يجعل ملف ⁨PDF⁩ آمنًا للحفظ على المدى الطويل. خاصّة على الكاتب إنتاجها، لا خاصّة يضيفها المستدعي لاحقًا.
• ⁨PAdES⁩ — التوقيعات الإلكترونية المتقدّمة لـ⁨PDF⁩ (⁨PDF⁩ Advanced Electronic Signatures)، عائلة نمط ⁨ETSI⁩ (⁨EN 319 142⁩) لتضمين توقيعات معيارية في ⁨PDF⁩. يُوسَّع عند أول استخدام؛ ومُغطّى بتعمّق في صفحات التوقيع.
• سطح التوافق — طبقة واجهة برمجية مصوغة على شكل مكتبة مصدر (هنا، ⁨TCPDF⁩) تتيح لمواضع الاستدعاء القائمة مواصلة العمل أثناء الانتقال. متوافقة مع الأصل، لا مطابقة له بايتًا ببايت — جسر، لا بديل مطابق.
• البديل المطابق — بديل يشغّل الشيفرة القائمة دون تغيير. سطح التوافق مع ⁨TCPDF⁩ لا يُوصَف بهذا الوصف عمدًا؛ بل هو وسيلة مساعدة للانتقال موثَّقة، بفروق سلوكية معروفة.