إعداد ⁨ionCube Loader⁩ لإصدارات ⁨NextPDF⁩ التجارية

نظرة سريعة

تُسلَّم بعض توزيعات ⁨NextPDF⁩ التجارية على هيئة ⁨PHP⁩ مُرمَّز بـ ⁨ionCube⁩، لذا يجب تثبيت ⁨ionCube Loader⁩ المطابق في وقت تشغيل ⁨PHP⁩ لديك قبل أن يعمل الكود. ينطبق ذلك على:

• إصدارات التقييم من ⁨NextPDF⁩ ⁨Pro⁩ و⁨Enterprise⁩، و
• الإصدار الرسمي (المدفوع) من ⁨NextPDF⁩ ⁨Pro⁩.

أما تسليم الإصدار الرسمي من ⁨NextPDF⁩ ⁨Enterprise⁩، فتعتمد آلية تغليفه على اتفاقيتك. اتبع تعليمات التسليم الواردة في شروط ترخيصك بدلًا من افتراض وقت تشغيل بعينه؛ راجع الترخيص والتفعيل.

هذه الصفحة دليل إعداد عملي: ما هو ⁨ionCube⁩، وكيفية تثبيت ⁨Loader⁩ والتحقق منه، وأين يوضع ملف الترخيص لإصدار ⁨Pro⁩ المدفوع المُرمَّز بـ ⁨ionCube⁩، وكيفية تشغيله في الحاويات، وكيفية إصلاح الأعطال الشائعة. إصدار ⁨PHP⁩ المدعوم هو ⁨8.4⁩، ويجب أن يطابق ⁨Loader⁩ الذي تثبِّته وقت التشغيل ذاك تمامًا.

ما هو ⁨ionCube⁩ ولماذا يستخدمه ⁨NextPDF⁩

⁨ionCube⁩ مُرمِّز ⁨PHP⁩ تجاري يقترن بمكوِّن وقت تشغيل مجاني يسمى ⁨ionCube Loader⁩. هذا ⁨Loader⁩ امتداد ⁨PHP⁩ (⁨Zend⁩). عند بدء تشغيل ⁨PHP⁩، يتيح ⁨Loader⁩ فك ترميز الملفات المُرمَّزة وتنفيذها؛ ودونه لا يمكن تشغيل ملف مُرمَّز، ويُبلِّغ ⁨PHP⁩ عن خطأ في ⁨Loader⁩ بدلًا من ذلك.

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

للحصول على تنزيلات ⁨Loader⁩ والتعليمات الموثوقة الخاصة بكل إصدار، استخدم وثائق المورِّد على ⁨ioncube.com⁩ (وثائق ⁨ionCube Loader⁩ ودليل التثبيت). تغطي هذه الصفحة الإعداد الخاص بـ ⁨NextPDF⁩؛ أما المورِّد فهو مصدر الحقيقة بشأن ⁨Loader⁩ ذاته.

المتطلبات

ثبِّت ⁨ionCube Loader⁩ المطابق لوقت تشغيل ⁨PHP⁩ لديك على كل محور. فعدم التطابق في أي واحد منها هو أكثر أسباب الفشل شيوعًا:

المحور	يجب أن يطابق
إصدار ⁨PHP⁩	⁨8.4⁩ (يتطلب ⁨NextPDF⁩ التجاري >=8.4 <9.0).
نظام التشغيل	نظام التشغيل الذي تستهدفه حزمة ⁨Loader⁩ (⁨Linux⁩ أو ⁨Windows⁩ أو ⁨macOS⁩).
البنية	بنية المعالج للمضيف، وهي عادةً 64-بت (x86-64 أو aarch64).
أمان الخيوط	غير آمن للخيوط (⁨NTS⁩) أو آمن للخيوط (⁨ZTS⁩)، بما يطابق بنية ⁨PHP⁩ لديك.

علاوة على ⁨Loader⁩، تحتاج أيضًا إلى:

• حزمة ⁨NextPDF⁩ التجارية مثبَّتة عبر ⁨Composer⁩ — nextpdf/pro أو nextpdf/enterprise أو حزمة ⁨meta⁩ المسماة nextpdf/premium.
• بالنسبة إلى الإصدارات المدفوعة، ملف الترخيص الخاص بك. أما إصدار ⁨Pro⁩ المدفوع المُرمَّز بـ ⁨ionCube⁩، فراجع وضع ملف الترخيص أدناه.

لقراءة قيم بنيتك الحالية، شغِّل php -i (أو استدعِ phpinfo()) وتحقق من أسطر PHP Version وArchitecture وThread Safety. في معظم عمليات نشر ⁨CLI⁩ و⁨PHP-FPM⁩ يكون أمان الخيوط معطَّلًا (⁨NTS⁩)؛ بينما يكون ⁨Apache⁩ الكلاسيكي بنمط mod_php على بعض المنصات ⁨ZTS⁩. نزِّل حزمة ⁨Loader⁩ لتلك القيم بالضبط.

تثبيت ⁨Loader⁩

الخطوات أدناه هي المسار العام. ارجع إلى وثائق ⁨ionCube Loader⁩ على ⁨ioncube.com⁩ للاطلاع على أسماء الملفات الدقيقة وبنية الأدلة في الحزمة الحالية.

1. نزِّل حزمة ⁨Loader⁩ المطابقة لبيئتك (⁨PHP 8.4⁩، ونظام تشغيلك، والبنية، و⁨NTS⁩/⁨ZTS⁩). تحتوي الحزمة على ملف ⁨loader⁩ واحد لكل إصدار من ⁨PHP⁩ ولكل صيغة من أمان الخيوط.

2. ضع ملف ⁨loader⁩ في دليل امتدادات ⁨PHP⁩. استخدم extension_dir المُبلَّغ عنه من php -i. على ⁨Linux⁩/⁨macOS⁩ يكون الملف ioncube_loader_<os>_8.4.so (استخدم ..._8.4_ts.so لبنية ⁨ZTS⁩)؛ وعلى ⁨Windows⁩ يكون ioncube_loader_win_8.4.dll (أو صيغة ⁨ZTS⁩ المسماة ..._ts.dll).

3. سجِّله في php.ini بوصفه zend_extension. يجب أن يُحمَّل ⁨ionCube Loader⁩ بوصفه zend_extension، لا extension عادي، وينبغي أن يُحمَّل قبل الامتدادات الأخرى. أضف سطرًا واحدًا، مستخدمًا مسارًا مطلقًا إلى ملف ⁨loader⁩:

   zend_extension=/full/path/to/ioncube_loader_lin_8.4.so

   على ⁨Windows⁩، استخدم المسار الكامل إلى ملف .dll:

   zend_extension="C:\php\ext\ioncube_loader_win_8.4.dll"

   إذا كانت منصتك تستخدم أدلة تضمين بنمط conf.d، فضع هذا السطر في ملف يُقرأ مبكرًا (مثلًا 00-ioncube.ini) كي يُهيَّأ ⁨Loader⁩ قبل الامتدادات الأخرى.

4. أعد تشغيل وقت تشغيل ⁨PHP⁩. أعد تشغيل ⁨PHP-FPM⁩، أو خادم الويب لديك (⁨Apache⁩/⁨Nginx⁩)، أو ببساطة أعد تشغيل ⁨CLI⁩ — أيًّا كان ما يشغِّل تطبيقك. تحتفظ العملية طويلة الأمد بالتهيئة القديمة حتى إعادة تشغيلها.

التحقق

تأكد من أن ⁨Loader⁩ نشط قبل محاولة تحميل ⁨NextPDF⁩.

أولًا، تحقق من لافتة إصدار ⁨PHP⁩. عند تثبيت ⁨Loader⁩، يُلحِق php -v سطرًا يسميه:

php -v

PHP 8.4.x (cli) ...
    with Zend OPcache v8.4.x, ...
    with the ionCube PHP Loader ...

عبارة “with the ionCube PHP Loader” هي الإشارة إلى أن ⁨Loader⁩ نشط لوقت التشغيل ذاك. أما في عملية نشر ويب (⁨FPM⁩ / mod_php)، فلا تكفي لافتة ⁨CLI⁩ — إذ يمكن لذلك الوقت أن يستخدم ملف php.ini مختلفًا. تأكد من وقت تشغيل الويب عبر سكربت صغير يقدِّمه خادم الويب:

<?php
// loader-check.php — delete after verifying.
var_dump(extension_loaded('ionCube Loader'));
phpinfo(); // The output includes an "ionCube PHP Loader" section when active.

أخيرًا، تأكد من أن صنف ⁨NextPDF⁩ التجاري يُحمَّل فعليًا عبر مُحمِّل التحميل التلقائي في ⁨Composer⁩. يثبت ذلك أن الكود المُرمَّز يعمل من البداية إلى النهاية:

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

// A premium class resolves only when the Loader can decode the package.
var_dump(class_exists(\NextPDF\Pro\Document\PdfPortfolio::class));

إذا سمى php -v ⁨Loader⁩، وأظهر phpinfo() للويب قسم ⁨ionCube⁩، وتحقق صنف ⁨Pro⁩، فإن ⁨Loader⁩ مُعدٌّ بشكل صحيح.

وضع ملف الترخيص (إصدار ⁨Pro⁩ المدفوع المُرمَّز بـ ⁨ionCube⁩)

يستخدم ⁨ionCube⁩ نموذج ترخيص بسيطًا: يتحقق الكود المُرمَّز من وجود ملف ترخيص وقت التشغيل، ويرفض العمل عندما يكون الملف مفقودًا أو غير قابل للقراءة أو منتهيًا. ينطبق هذا على إصدار ⁨Pro⁩ المدفوع المُرمَّز بـ ⁨ionCube⁩ — إذ تضع له ملف الترخيص الذي يوفره شراؤك في موضع يجده وقت التشغيل.

آلية ملف ترخيص ⁨ionCube⁩ هذه خاصة بالإصدار المُرمَّز بـ ⁨ionCube⁩. ولا يُفترض هنا أن تسليم الإصدار الرسمي من ⁨NextPDF⁩ ⁨Enterprise⁩ مُرمَّز بـ ⁨ionCube⁩؛ إذ تحكم تغليفه ومعالجة ترخيصه شروط ترخيصك — راجع الترخيص والتفعيل.

المسارات الدقيقة خاصة بالبيئة، لذا أبقِ هذا عامًا:

• ضع ملف الترخيص في الموضع الذي تحدده تعليمات تسليم ⁨NextPDF⁩ لديك — وعادةً بجوار الحزمة المُرمَّزة أو في دليل يستطيع التطبيق قراءته. تأكد من أن مستخدم عملية ⁨PHP⁩ يملك إذن القراءة.
• لا تُعِد تسمية الملف ما لم تنص تعليماتك على ذلك؛ فإن ⁨loader⁩ يبحث عن اسم محدد.
• في الحاويات وعمليات النشر للقراءة فقط، ضمِّن ملف الترخيص أو انسخه داخل الصورة، أو ضمِّنه في مسار قابل للكتابة والقراءة يراه وقت التشغيل (راجع ⁨Docker⁩ والحاويات).

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

استكشاف الأخطاء وإصلاحها

”⁨Loader not installed⁩” / “⁨Failed loading … ioncube_loader⁩”

⁨Loader⁩ غير نشط في وقت التشغيل الذي شغَّل الكود، أو أن المسار خاطئ. أعد التحقق من أن سطر zend_extension يشير إلى ملف موجود بمسار مطلق، وأنك أعدت تشغيل وقت التشغيل، وأنك تحققت من وقت التشغيل نفسه (⁨CLI⁩ مقابل ⁨FPM⁩) عبر php -v / phpinfo(). عادةً ما تعني رسالة Failed loading أن الملف موجود لكنه لا يطابق بنية ⁨PHP⁩ (راجع البند التالي).

عدم تطابق إصدار ⁨PHP⁩ أو ⁨NTS⁩/⁨ZTS⁩ أو البنية

لن يُحمَّل ⁨Loader⁩ المبني لإصدار ⁨PHP⁩ مختلف، أو لنمط أمان خيوط مختلف، أو لبنية مختلفة. تأكد من PHP Version وThread Safety وArchitecture من php -i، ثم ثبِّت ملف ⁨Loader⁩ لـ ⁨PHP 8.4⁩ بما يطابق ⁨NTS⁩/⁨ZTS⁩ وعدد البتات. لاحقة 8.4 مقابل 8.4_ts (أو _ts.dll) هي محدِّد أمان الخيوط — واستخدام اللاحقة الخاطئة خطأ متكرر.

ترتيب تحميل ⁨Loader⁩

يجب أن يكون ⁨ionCube Loader⁩ من نوع zend_extension وأن يُهيَّأ قبل الامتدادات الأخرى. إذا رأيت تحذيرات بشأن تحميل ⁨Loader⁩ بعد الامتدادات الأخرى، فحرِّك سطر zend_extension الخاص به إلى موضع أبكر — أو، مع بنية conf.d، امنح ملف تضمينه اسمًا يأتي أولًا في الترتيب (مثلًا 00-ioncube.ini).

يستخدم ⁨CLI⁩ و⁨FPM⁩ وخادم الويب ملفات php.ini مختلفة

كثيرًا ما يُحمِّل ⁨PHP⁩ ملف php.ini مختلفًا لـ ⁨CLI⁩ عن ذلك المُحمَّل لـ ⁨PHP-FPM⁩ أو mod_php. وتهيئة ⁨CLI⁩ وحدها تترك وقت تشغيل الويب دون ⁨Loader⁩ (أو العكس). شغِّل php --ini لمعرفة الملف الذي يستخدمه ⁨CLI⁩، وتحقق من سطر Loaded Configuration File في ناتج phpinfo() للويب. أضف سطر zend_extension إلى كل ملف php.ini يشغِّل ⁨NextPDF⁩، وأعد تشغيل كل وقت تشغيل.

ملف الترخيص غير موجود أو منتهٍ

بالنسبة إلى إصدار ⁨Pro⁩ المدفوع المُرمَّز بـ ⁨ionCube⁩، يوقِف ملفُ ترخيص مفقود أو غير قابل للقراءة أو منتهٍ تشغيلَ الكود المُرمَّز. تحقق من أن الملف في الموضع المتوقع، وأن مستخدم عملية ⁨PHP⁩ يستطيع قراءته، وأنه لم ينتهِ. لأسئلة التجديد والمدة، راجع الترخيص والتفعيل واتفاقية ترخيصك.

تفاعلات ⁨OPcache⁩

يخزِّن ⁨OPcache⁩ السكربتات المُترجَمة مؤقتًا، لكن الملفات المُرمَّزة بـ ⁨ionCube⁩ يفك ترميزها ⁨Loader⁩ وقت التشغيل. إذا غيَّرت ⁨Loader⁩ أو تهيئته وظل وقت التشغيل يتصرف كأنه غائب، فأعد تشغيل وقت تشغيل ⁨PHP⁩ (وهو ما يمسح ⁨OPcache⁩) بدلًا من الاعتماد على إعادة تحميل ساخنة. أبقِ zend_extension الخاص بـ ⁨ionCube⁩ مسجَّلًا كي يُحمَّل قبل ⁨OPcache⁩؛ فالاثنان يتعايشان، وينبغي أن يُدرِج php -v كليهما.

⁨Docker⁩ والحاويات

في عملية نشر بالحاويات، ثبِّت ⁨Loader⁩ داخل الصورة، وتأكد من أنه يطابق بنية ⁨PHP⁩ في الحاوية — لا بنية مضيفك. تُثبِّت الصورة الأساسية إصدار ⁨PHP⁩ ونظام التشغيل والبنية ونمط أمان الخيوط، لذا نزِّل حزمة ⁨Loader⁩ لتلك القيم.

بناء صورة نموذجي:

1. ابدأ من صورة أساسية لـ ⁨PHP⁩ ⁨8.4⁩ (لاحظ ما إذا كانت ⁨NTS⁩ أم ⁨ZTS⁩ — فالوسوم الرسمية php:8.4-cli / 8.4-fpm / 8.4-apache هي ⁨NTS⁩، بينما الوسوم التي تتضمن zts آمنة للخيوط؛ اختر ⁨Loader⁩ ليطابقها).
2. أضف ملف ⁨ionCube Loader⁩ المطابق إلى extension_dir الخاص بالصورة.
3. اكتب سطر zend_extension=... في ملف php.ini الخاص بالصورة (أو في ملف تضمين بنمط conf.d).
4. بالنسبة إلى إصدار ⁨Pro⁩ المدفوع المُرمَّز بـ ⁨ionCube⁩، وفِّر ملف الترخيص بنسخه داخل الصورة أو بتضمينه وقت التشغيل في مسار تستطيع الحاوية قراءته.

ولأن ⁨Loader⁩ مبني داخل الصورة، تعمل الحاوية نفسها بصورة متطابقة في كل مكان. وإذا رقَّيت لاحقًا إصدار ⁨PHP⁩ في الصورة الأساسية، فاستبدل ملف ⁨Loader⁩ بالبنية التي تطابق وقت التشغيل الجديد.

انظر أيضًا

• الترخيص والتفعيل
• ⁨NextPDF Premium⁩
• اختر مسارك