إعداد compat-legacy

لمحة سريعة

يوفّر لك المهايئ ثلاثة أسطح للتهيئة:

الوضع الصارم — مفتاح للتدقيق يحوّل إسقاط المعاملات بصمت إلى استثناءات. وهو معطّل افتراضيًا.
الثوابت القديمة — ثوابت ⁨TCPDF⁩ من النوع K_* / PDF_*، تُعرَّف تلقائيًا بقيم افتراضية من 6.2.13 حتى تستمر الشيفرة القديمة التي تقرؤها في العمل.
AdaptationConfig — كائن تهيئة حديث وغير قابل للتغيير، يحلّ محلّ التهيئة المعتمدة على الثوابت.

ما زلت تضبط معظم إعدادات المستند عبر دوال ⁨TCPDF⁩ التي تستدعيها بالفعل (SetMargins()، SetFont()، وهكذا). تتناول الأقسام أدناه ما يخصّ طبقة التوافق فقط.

الوضع الصارم

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

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();

$pdf->setStrictMode(true);   // audit: throw on silent parameter loss
$isOn = $pdf->isStrictMode(); // true
$pdf->setStrictMode(false);  // back to backward-compatible default

تتحقّق هذه النتائج ضمن tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php:

الوضع	استُدعيت دالة تتجاهل بصمت	النتيجة
معطّل (افتراضي)	⁨e.g.⁩ `Image()` مع معاملات إضافية	يُنفَّذ؛ ولا يكون للمعاملات المُتجاهَلة أي أثر
مُفعّل	الاستدعاء نفسه	يطرح `TcpdfNotImplementedException` مع تسمية المعاملات المُتجاهَلة
مُفعّل	دالة تتجاهل بصمت استُدعيت بمعاملات مدعومة فقط	لا يطرح (⁨e.g.⁩ `SetProtection([], 'u', 'o', 0, [])`)

الوضع الصارم تراكمي. عندما تدعم دالة ما معاملًا، يستمرّ التفويض؛ ولا يضيف الوضع الصارم إلا حارس استثناء للمعاملات التي تُسقَط. استخدمه في مهمة تكامل مستمر (⁨CI⁩) مخصّصة أو في مرور تدقيق لمرة واحدة، وليس في بيئة الإنتاج. يتبع هذا مبدأ الفشل الصريح من معيار التحقّق من أمن التطبيقات (⁨ASVS⁩) 5.0 الصادر عن مشروع أمن تطبيقات الويب المفتوح عالميًا (⁨OWASP⁩) في معالجة الأخطاء (البند reference_id المُسجَّل في الملحق الجانبي لـ ⁨RAG⁩): يجب أن يكون بمقدور المُستدعِي ملاحظة عدم احترام مقصده.

لا تنشر شيفرة إنتاج والوضع الصارم مُفعّل. فالمعامل المُتجاهَل بصمت هو مشكلة في تجربة المطوّر، لا عطل في وقت التشغيل، كما أنّ استثناءً في مسار تصيير إنتاجي أسوأ من مُخرَج متدهور. دقّق، ثمّ أصلِح، ثمّ عطّله — راجع /⁨integrations/tcpdf-compat/migration/.⁩

ثوابت ⁨TCPDF⁩ القديمة

تقرأ ⁨TCPDF⁩ القديمة التهيئة من ثوابت K_* وPDF_*. يعرّفها المهايئ تلقائيًا وقت الإنشاء فقط إذا لم تكن مُعرّفة مسبقًا، مستخدمًا القيم الافتراضية لـ ⁨TCPDF 6.2.13.⁩ إذا كان تطبيقك يعرّف ثابتًا مسبقًا (على سبيل المثال، K_PATH_FONTS مخصّص)، فستُحفَظ قيمتك.

قيم افتراضية مختارة (القائمة الكاملة: src/Compat/Tcpdf/Config/LegacyDefaults.php):

الثابت	الافتراضي	ملاحظة
`PDF_PAGE_FORMAT`	`A4`
`PDF_PAGE_ORIENTATION`	`P`
`PDF_UNIT`	`mm`
`PDF_MARGIN_LEFT` / `RIGHT`	`15`	وحدات المستخدم
`PDF_MARGIN_TOP`	`27`	وحدات المستخدم
`PDF_MARGIN_BOTTOM`	`25`	وحدات المستخدم
`PDF_FONT_NAME_MAIN`	`helvetica`
`PDF_FONT_SIZE_MAIN`	`10`
`K_CELL_HEIGHT_RATIO`	`1.25`
`K_TCPDF_CALLS_IN_HTML`	`false`	مُحصَّن — دائمًا ⁨false⁩؛ لا يمكن للترميز إطلاق تنفيذ ⁨PHP⁩
`K_TCPDF_THROW_EXCEPTION_ERROR`	`true`	مُحصَّن — `Error()` يطرح دائمًا؛ ولا يستدعي `die()` أبدًا
`K_TIMEZONE`	`UTC`

اثنان منها مُثبَّتان عمدًا لأغراض الأمان ولا يمكن تخفيفهما عبر التهيئة: K_TCPDF_CALLS_IN_HTML دائمًا false، وK_TCPDF_THROW_EXCEPTION_ERROR فعليًا دائمًا true. إذا اعتمدت الشيفرة القديمة على أيٍّ من السلوكين القديمين غير الآمنين، فيجب تعديل تلك الشيفرة — راجع /⁨integrations/tcpdf-compat/security-and-operations/.⁩

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

<?php

declare(strict_types=1);

// Define BEFORE constructing the adapter; the adapter will not override it.
define('PDF_CREATOR', 'My Application');
define('PDF_AUTHOR', 'My Application');

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
// Creator and Author are seeded from your constants.

كائن ⁨AdaptationConfig⁩ الحديث

إذا كنت لا تريد الاعتماد على الثوابت العامة، فاستخدم كائن قيمة التهيئة غير القابل للتغيير، NextPDF\Compat\Tcpdf\Config\AdaptationConfig. إنّه final readonly، ويأخذ كلّ حقل فيه افتراضيًا قيمة ⁨TCPDF 6.2.13.⁩ يمكنك إنشاؤه بالحقول التي تريد تغييرها فقط.

يمكنك أيضًا بناؤه من أيّ ثوابت قديمة مُعرّفة حاليًا:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\Config\AdaptationConfig;

// Snapshot the currently-defined legacy constants into an object:
$config = AdaptationConfig::fromLegacyConstants();

echo $config->pageFormat;   // 'A4' unless a constant overrides it
echo $config->fontNameMain; // 'helvetica'
echo $config->marginLeft;   // 15.0

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

ترتيب حلّ التهيئة

عندما يُنشئ المهايئ مستندًا، فإنه يحلّ التهيئة بهذا الترتيب. ولا تتجاوز الخطوات اللاحقة الخطوات السابقة:

وسائط الباني (orientation، unit، format، …) — لها أعلى أسبقية للقيم التي تغطّيها.
الثوابت القديمة المُعرّفة من قِبل التطبيق مسبقًا.
ثوابت ⁨TCPDF 6.2.13⁩ الافتراضية، المُعرّفة تلقائيًا بواسطة LegacyDefaults لأيّ ثابت غير مُعرَّف مسبقًا.

وسائط الباني unicode، وencoding، وdiskcache مقبولة لأجل توافق التوقيع، لكنها لا أثر لها. ⁨NextPDF⁩ دائمًا ⁨Unicode⁩ و⁨UTF-8⁩، ولا يستخدم ذاكرة تخزين مؤقت للصفحات على القرص. راية الباني pdfa مقبولة أيضًا، لكنّ المطابقة الأرشيفية ⁨PDF/A⁩ تتطلّب إصدارًا تجاريًا (راجع /⁨integrations/tcpdf-compat/security-and-operations/⁩).

انظر أيضًا

src/Compat/Tcpdf/Config/LegacyDefaults.php — القيم الافتراضية المرجعية للثوابت
src/Compat/Tcpdf/Config/AdaptationConfig.php — كائن التهيئة الحديث
/⁨integrations/tcpdf-compat/migration/⁩ — ترحيل التهيئة بعيدًا عن الثوابت العامة
/⁨integrations/tcpdf-compat/security-and-operations/⁩ — الرايتان المُحصَّنتان غير القابلتين للتهيئة