كل شيء حول إضافة Using Composer Packages

إضافة XenForo حزم Composer​

إصدارات XF المتوافقة

2.1 ، 2.2 ، 2.3

العلامة التجارية المرئية

نعم

Composer هي أداة لإدارة التبعيات في PHP. فهي تسمح لك بإعلان المكتبات التي يعتمد عليها مشروعك وستقوم بإدارتها (تثبيتها/تحديثها) نيابة عنك.

يستخدم XenForo v2 Composer خلف الكواليس لتضمين حزم معينة يستخدمها البرنامج الأساسي.

وبصفتنا مطوري إضافات، يمكننا تضمين حزم Composer في إضافاتنا الخاصة والتي سيتم تحميلها تلقائيًا إلى جانب تلك التي يوفرها البرنامج الأساسي.

في XenForo 2.0، كان علينا استخدام نقاط التمديد للقيام بالتحميل التلقائي الخاص بنا - ولكن اعتبارًا من XenForo 2.1، يجعل البرنامج الأساسي من السهل علينا حقًا تضمين حزم Composer.

و يصف هذا البرنامج التعليمي العملية للقيام بذلك وكيفية بناء الإضافات التي تستخدم composer.

لاحظ أن هناك بعض التحذيرات هنا - يمكن أن تكون إدارة التبعيات معقدة، ومن الممكن تمامًا أن تقوم بإدخال أخطاء غير متوقعة في الإضافة الخاصة بك أو الإضافات الأخرى أو حتى في جوهر XenForo باتباع هذا البرنامج التعليمي وتضمين حزم composer.

كما يجب توخي الحذر، ومن المستحسن تجنب هذا النهج إذا لم تكن على دراية بإدارة التبعيات في Composer.

الافتراضات الموضحة في هذا البرنامج التعليمي:

1. لقد قمت بتثبيت Composer على خادم التطوير الخاص بك وأنت على دراية بكيفية استخدامه
2. أنت تفهم كيف تعمل حزم Composer
3. تفترض جميع الأمثلة وجود بيئة Linux تقوم بتشغيل bash، وسوف تحتاج إلى ترجمتها بنفسك لاستخدامها على Windows أو منصات أخرى

حول هذا البرنامج التعليمي

يشرح هذا البرنامج التعليمي مثالاً أساسيًا لإضافة حزمة Composer إلى وظيفة إضافية. يمكن تثبيت الوظيفة الإضافية نفسها حتى تتمكن من رؤية كل التعليمات البرمجية قيد التشغيل وفحص كيفية عملها.

و سنقوم بتثبيت ملحق Carbon API لكائنات DateTime.

لاحظ أن التعليمات الواردة في هذا البرنامج التعليمي خاصة بإصدار XenForo v2.1 والإصدارات الأحدث - يرجى الاطلاع على البرنامج التعليمي السابق الخاص بي استخدام حزم Composer في البرنامج التعليمي لإضافات XenForo 2.0 للحصول على تعليمات للإصدار 2.0، والذي يتطلب جهدًا أكبر بكثير مقارنة بالإصدار 2.1.

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

راجع ملف LICENSE في جذر الوظيفة الإضافية للحصول على معلومات كاملة عن الترخيص وحقوق النشر. بدلاً من ذلك، يمكنك عرض ملف الترخيص في مستودع Git الخاص بكود البرنامج التعليمي: LICENSE .

للعلم، فإن Composer نفسه وحزمة Carbon التي سنقوم بتثبيتها تستخدم أيضًا ترخيص MIT.

البدء

لقد قمت بإنشاء إضافة أساسية تسمى ComposerTutorial. تم

تثبيت XenForo على خادم التطوير الخاص بي في /srv/www/xenforo21- سأشير إلى هذا باسم "جذر XenForo".

تم تثبيت الإضافة الخاصة بي في /srv/www/xenforo21/src/addons/ComposerTutorial- سأشير إلى هذا باسم "جذر الإضافة الخاصة بي".

الخطوة الأولى لإضافة حزمة Composer هي إنشاء composer.json ملف في جذر الإضافة الخاصة بك.

يمكنك إما القيام بذلك يدويًا أو استخدام composer require الأمر للقيام بذلك نيابةً عنك.

$ cd /srv/www/xenforo21/src/addons/ComposerTutorial
$ composer require nesbot/carbon
Using version ^2.25 for nesbot/carbon
./composer.json has been created
Loading composer repositories with package information
Updating dependencies (including require-dev)
Package operations: 4 installs, 0 updates, 0 removals
  - Installing symfony/translation-contracts (v1.1.7): Loading from cache
  - Installing symfony/polyfill-mbstring (v1.12.0): Loading from cache
  - Installing symfony/translation (v4.3.5): Loading from cache
  - Installing nesbot/carbon (2.25.1): Loading from cache
symfony/translation suggests installing symfony/config
symfony/translation suggests installing symfony/yaml
symfony/translation suggests installing psr/log-implementation (To use logging capability in translator)
Writing lock file
Generating autoload files

$ cd /srv/www/xenforo21/src/addons/ComposerTutorial
$ composer require nesbot/carbon
Using version ^2.25 for nesbot/carbon
./composer.json has been created
Loading composer repositories with package information
Updating dependencies (including require-dev)
Package operations: 4 installs, 0 updates, 0 removals
  - Installing symfony/translation-contracts (v1.1.7): Loading from cache
  - Installing symfony/polyfill-mbstring (v1.12.0): Loading from cache
  - Installing symfony/translation (v4.3.5): Loading from cache
  - Installing nesbot/carbon (2.25.1): Loading from cache
symfony/translation suggests installing symfony/config
symfony/translation suggests installing symfony/yaml
symfony/translation suggests installing psr/log-implementation (To use logging capability in translator)
Writing lock file
Generating autoload files

لدينا الآن ملف Composer أساسي تم إنشاؤه في /srv/www/xenforo21/src/addons/ComposerTutorial/composer.json:

{
    "require": {
        "nesbot/carbon": "^2.25"
    }
}

{
    "require": {
        "nesbot/carbon": "^2.25"
    }
}

على الرغم من وجود العشرات من الحقول المتاحة في مخطط composer.json ، إلا أنك في الواقع تحتاج إلى requireالحقل فقط لجعل Composer يعمل.

إذا قمت بإنشاء composer.jsonالملف يدويًا، فستقوم بدلاً من ذلك بتشغيل أمر composer update لتثبيت الحزمة وتبعياتها.

$ cd /srv/www/xenforo21/src/addons/ComposerTutorial
$ composer update

$ cd /srv/www/xenforo21/src/addons/ComposerTutorial
$ composer update

الشيء الآخر الذي لدينا الآن هو vendorمجلد يحتوي على الحزم المثبتة وكل التبعيات.

$ ls -1p /srv/www/xenforo21/src/addons/ComposerTutorial/vendor/
autoload.php
bin/
composer/
nesbot/
symfony/

$ ls -1p /srv/www/xenforo21/src/addons/ComposerTutorial/vendor/
autoload.php
bin/
composer/
nesbot/
symfony/

• 
  يتم إنشاء الملف autoload.phpتلقائيًا بواسطة أوامر الملحن وهو مخصص لتشغيل أداة التحميل التلقائي في مشروع مستقل. لن يكون هذا الملف مناسبًا للاستخدام في XenForo، لذا سنتجاهله.
• الدليل binهو المكان الذي يتم فيه حفظ الملفات القابلة للتنفيذ والبرامج النصية. لا تحتاج عادةً إلى استخدام هذه الملفات.
• الدليل composerهو المكان الذي توجد فيه ملفات التحميل التلقائي المولدة - من المفيد أن تتعرف على محتويات هذا الدليل لفهم كيفية العثور على الفئات وتحميلها بواسطة Composer. سنستخدم بعض الملفات الموجودة في هذا الدليل لتحديد الفئات والملفات التي نحتاج إلى تمريرها إلى أداة التحميل التلقائي XenForo.
• الدليل nesbotهو المكان الذي يتم فيه تثبيت حزمة Carbon.
• الدليل symfonyهو المكان الذي يتم فيه تثبيت بعض حزم اعتماد Carbon ( symfony/polyfill-mbstringو symfony-translation)

أخيرًا، لدينا composer.lockملف تم إنشاؤه في دليل جذر الوظيفة الإضافية لدينا. يتم إنشاء هذا الملف تلقائيًا بواسطة أوامر Composer ويحتوي على قائمة بالتبعيات (وإصداراتها المحددة!) التي تم حلها منذ composer.json المرة الأولى التي تم فيها تثبيت الحزم. يجب أن تعتبر composer.lockالملف "لقطة زمنية محددة للإصدار" للتبعيات.

أثناء تطوير الوظيفة الإضافية الخاصة بك، يمكنك تشغيل الأمر composer update من جذر الوظيفة الإضافية الخاصة بك لتحديث التبعيات، مما سيؤدي إلى composer.lock تحديث الملف أيضًا إذا تم إصدار إصدارات جديدة. من المهم اختبار الإصدارات الجديدة للتأكد من عدم تضمين أي تغييرات جذرية - على الرغم من أنه إذا كنت تستخدم الإصدار الدلالي ، فلا ينبغي أن يحدث هذا (نظريًا).

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

وفي كلتا الحالتين، سنغطي التثبيت بمزيد من التفصيل لاحقًا. في الوقت الحالي، فقط أدرك أن composer.lockالملف مهم ويجب فحصه في عنصر التحكم في الكود المصدر الخاص بك جنبًا إلى جنب مع ملفك composer.json.

لذا الآن بعد أن قمنا بتثبيت الحزمة والتبعيات، نحتاج إلى جعل XenForo يقوم بالتحميل التلقائي لكل شيء.

XenForo Autoloader

كما ذكرنا سابقًا، يستخدم XenForo Composer خلف الكواليس - على الرغم من أنهم يخفون الملف composer.json عنا، لأننا لسنا بحاجة إلى تثبيت أو تحديث أي حزم أساسية وتبعيات بأنفسنا - فإن عملية الترقية الخاصة بهم تعتني بذلك نيابة عنا. راجع الدليل src/vendor الموجود أسفل جذر XenForo لمعرفة الحزم التي يستخدمها XenForo. يقدم XenForo 2.1 معلمة

جديدة مفيدة يمكننا تعيينها لطلب النظام بتضمين الحزم المطلوبة في أداة التحميل التلقائي. أضف السطر التالي إلى ملفك :addon.jsoncomposer_autoload

إضافة.json

"composer_autoload": "vendor/composer"

"composer_autoload": "vendor/composer"

يخبر هذا برنامج التحميل التلقائي XenForo بتحميل الحزم من الوظيفة الإضافية الخاصة بنا أيضًا - المسار نسبي إلى دليل جذر الوظيفة الإضافية الخاصة بنا ( ie /srv/www/xenforo21/src/addons/ComposerTutorial/vendor/composer).


لذا، addon.json أصبحت الحزمة الخاصة بي لهذا البرنامج التعليمي الآن:

{
    "legacy_addon_id": "",
    "title": "Composer Tutorial",
    "description": "Shows how to include Composer packages in XenForo 2.1 addons",
    "version_id": 2,
    "version_string": "2.0.0",
    "dev": "Simon Hampel",
    "dev_url": "https://bitbucket.org/hampel/",
    "faq_url": "",
    "support_url": "https://bitbucket.org/hampel/xenforo-composer-tutorial/issues",
    "extra_urls": {
        "Git Repository": "https://bitbucket.org/hampel/xenforo-composer-tutorial",
        "Twitter": "https://twitter.com/SimonHampel"
    },
    "require": [],
    "icon": "composer.png",
    "composer_autoload": "vendor/composer"
}

{
    "legacy_addon_id": "",
    "title": "Composer Tutorial",
    "description": "Shows how to include Composer packages in XenForo 2.1 addons",
    "version_id": 2,
    "version_string": "2.0.0",
    "dev": "Simon Hampel",
    "dev_url": "https://bitbucket.org/hampel/",
    "faq_url": "",
    "support_url": "https://bitbucket.org/hampel/xenforo-composer-tutorial/issues",
    "extra_urls": {
        "Git Repository": "https://bitbucket.org/hampel/xenforo-composer-tutorial",
        "Twitter": "https://twitter.com/SimonHampel"
    },
    "require": [],
    "icon": "composer.png",
    "composer_autoload": "vendor/composer"
}

ترتيب تحميل الفئات

توجد طريقة لتجاوز ترتيب تحميل الفئات في المواقف التي تتطلب فيها الوظائف الإضافية المتعددة إصدارات مختلفة من حزم Composer وتحتاج إلى تحميل الإصدار الخاص بك أولاً.

ومع ذلك، فإن هذا يتجاوز نطاق هذا البرنامج التعليمي، لذا لن أخوض في التفاصيل هنا.

التحكم في المصدر

عند استخدام التحكم في المصدر، لا تريد عمومًا التحقق من دليل البائع - يمكن إعادة بنائه إما في وقت البناء إذا كنت تقوم بتعبئة ملف .zip للوظيفة الإضافية، أو في وقت النشر إذا كنت تستخدم أدوات النشر الآلية.

على هذا النحو، .gitignore يحتوي ملفي على التوجيهات التالية:
[الرمز]_data/
_الإصدارات/
البائع/[/CODE]

• يحتوي الدليل _dataعلى الملفات اللازمة لتثبيت الوظيفة الإضافية في الإنتاج. سيتم تضمين هذا في ملف .zip الخاص بالبناء ولكنه ليس ضروريًا لأغراض التطوير (نحتاج إلى _outputالدليل بدلاً من ذلك).
• الدليل _releasesهو المكان الذي يتم فيه وضع ملفات .zip لبناء الوظيفة الإضافية الخاصة بنا - لا نريدها في التحكم بالمصدر
• الدليل vendorهو المكان الذي يتم فيه تثبيت حزم Composer المطلوبة. ويمكن إعادة بناء هذا في أي وقت بناءً على محتويات الملف composer.lock، وبالتالي فهو غير ضروري في التحكم في المصدر

فيما يلي قائمة بالملفات المهمة التي أقوم بتسجيلها في عنصر التحكم بالمصدر - بالإضافة إلى أي كود مصدر:

• .gitignoreكما هو مذكور أعلاه - يخبرنا بما لا يجب التحقق منه في التحكم في المصدر
• addon.json- ملف تعريف الوظيفة الإضافية لدينا
• build.json- تعليمات حول كيفية بناء حزمة الوظائف الإضافية الخاصة بنا للنشر - راجع المزيد حول هذا أدناه
• composer.json- ملف Composer الخاص بنا الذي يحدد الحزم التي نستخدمها
• composer.lock- ملف Composer الذي يخبرنا بإصدارات الحزم التي نستخدمها (واختبرناها!)
• _output- مخرجات التطوير لدينا، المطلوبة لتثبيت الوظيفة الإضافية على خادم التطوير الخاص بنا

تعبئة الوظيفة الإضافية

لدينا خطوة إضافية واحدة مطلوبة قبل أن نتمكن من تعبئة الوظيفة الإضافية. نحتاج إلى إعطاء عملية بناء الوظيفة الإضافية بعض التعليمات حول كيفية تثبيت حزم Composer المطلوبة.

يمكننا استخدام build.json الملف لهذا الغرض - والذي يحتوي على سلسلة من التوجيهات التي يتم تنفيذها أثناء عملية البناء.

عند استخدام حزم Composer، build.jsonيبدو ملفي على النحو التالي:

{
    "exec": [
        "composer install --working-dir=_build/upload/src/addons/{addon_id}/ --no-dev --optimize-autoloader"
    ]
}

{
    "exec": [
        "composer install --working-dir=_build/upload/src/addons/{addon_id}/ --no-dev --optimize-autoloader"
    ]
}

يتم استبدال الكود { addon_id} تلقائيًا بعملية البناء - لا حاجة لاستخدام معرف الوظيفة الإضافية الفعلي الخاص بك، فقط استخدم السلسلة أعلاه حرفيًا بما في ذلك الأقواس المتعرجة.

تبدأ عملية البناء الأساسية بإنشاء نسخة من ملفات الوظيفة الإضافية الخاصة بك في _buildالدليل المؤقت. يمكننا معالجة هذه الملفات المنسوخة لتجهيزها للاستخدام الإنتاجي. يخبر

ملفنا build.jsonعملية البناء بتنفيذ composer installالأمر باستخدام موقع ملفات الوظيفة الإضافية المؤقتة الخاصة بنا في _buildالدليل.

نضيف معلمتين مهمتين في هذه المرحلة:

• --no-devيوجه Composer لإزالة أي تبعيات تطويرية ربما قمنا بتضمينها أثناء التطوير. على سبيل المثال، إذا استخدمنا إطار عمل لاختبار الوحدات مثل PHPUnit - فلن نحتاج إلى ذلك في الإنتاج، وسنقوم بتضمينه عبر توجيه require-dev في ملفنا composer.json. يحذف هذا الأمر جميع حزم require-dev.
• --optimize-autoloader يحول التحميل التلقائي لـ PSR-0/4 إلى ملفات خريطة فئة للحصول على محمل تلقائي أسرع، وهو أمر يوصى به بشدة للاستخدام في الإنتاج

لذا الآن، عندما نعود إلى جذر XenForo ونقوم بتشغيل أمر إنشاء الوظيفة الإضافية، فسوف يعمل ذلك على تحسين كود التحميل التلقائي لدينا حتى يكون جاهزًا للاستخدام في الإنتاج.

$ cd /srv/www/xenforo21
$ php cmd.php xf-addon:build-release ComposerTutorial

Performing add-on export.

Exporting data for Composer Tutorial to /srv/www/xenforo21/src/addons/ComposerTutorial/_data.
26/26 [============================] 100%
Written successfully.
Attempting to validate addon.json file...
JSON file validates successfully!

Building release ZIP.
Loading composer repositories with package information
Installing dependencies from lock file
Nothing to install or update
Generating optimized autoload files

Writing release ZIP to /srv/www/xenforo21/src/addons/ComposerTutorial/_releases.

Release written successfully.

$ cd /srv/www/xenforo21
$ php cmd.php xf-addon:build-release ComposerTutorial

Performing add-on export.

Exporting data for Composer Tutorial to /srv/www/xenforo21/src/addons/ComposerTutorial/_data.
26/26 [============================] 100%
Written successfully.
Attempting to validate addon.json file...
JSON file validates successfully!

Building release ZIP.
Loading composer repositories with package information
Installing dependencies from lock file
Nothing to install or update
Generating optimized autoload files

Writing release ZIP to /srv/www/xenforo21/src/addons/ComposerTutorial/_releases.

Release written successfully.

يمكنك رؤية مخرجات أوامر الملحن مع مخرجات البناء.

هذا كل ما نحتاج إلى القيام به - تم الآن إنشاء ملف zip الخاص بالوظيفة الإضافية لدينا باستخدام الإصدارات المحددة من حزم Composer التي اختبرناها وتم تحسينها للاستخدام في الإنتاج.

اختبار الوظيفة الإضافية التعليمية هذه

لقد أرفقت الوظيفة الإضافية المبنية بهذا البرنامج التعليمي حتى تتمكن من تثبيتها وإلقاء نظرة على الكود والتجربة مع حزم أخرى.

بمجرد التثبيت، انتقل إلى Admin > Tools > Test Composerصفحة البرنامج التعليمي وستشاهد بعض المخرجات التي تم إنشاؤها بواسطة Carbon.

يمكنك أيضًا استنساخ مستودع git لكود البرنامج التعليمي - برنامج XenForo Composer التعليمي

التحقق من متطلبات Setup.php الاختيارية

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

ومع ذلك، إذا كنت تستخدم التحكم في المصدر واستنساخ المستودع الخاص بك - يجب أن تتذكر تثبيت تبعيات البائع عن طريق تشغيل composer install (أو composer update إذا كنت لا تزال قيد التطوير) قبل محاولة تثبيت الوظيفة الإضافية.

إذا حاولت تثبيت إضافة تحتوي على تبعيات composer ولكن مجلد vendor الخاص بك غير موجود، فقد يتسبب ذلك في تعطل المنتدى بطريقة غير سارة إلى حد ما (يتطلب تحديث قاعدة البيانات يدويًا لإصلاح المشكلة!).

كإجراء أمان، قد ترغب في إجراء تحقق بسيط من وجود مجلد vendor عند محاولة تثبيت الإضافة الخاصة بك - يمكننا القيام بذلك عن طريق إضافة ملف Setup.phpإلى جذر الإضافة الخاصة بك (قد يكون لديك بالفعل واحد).

<?php namespace ComposerTutorial;

use XF\AddOn\AbstractSetup;
use XF\Db\Schema\Create;

class Setup extends AbstractSetup
{
    public function install(array $stepParams = [])
    {
        // Nothing to do yet
    }

    public function upgrade(array $stepParams = [])
    {
        // Nothing to do yet
    }

    public function uninstall(array $stepParams = [])
    {
        // Nothing to do yet
    }

    public function checkRequirements(&$errors = [], &$warnings = [])
    {
        $vendorDirectory = sprintf("%s/vendor", $this->addOn->getAddOnDirectory());
        if (!file_exists($vendorDirectory))
        {
            $errors[] = "vendor folder does not exist - cannot proceed with addon install";
        }
    }
}

<?php namespace ComposerTutorial;

use XF\AddOn\AbstractSetup;
use XF\Db\Schema\Create;

class Setup extends AbstractSetup
{
    public function install(array $stepParams = [])
    {
        // Nothing to do yet
    }

    public function upgrade(array $stepParams = [])
    {
        // Nothing to do yet
    }

    public function uninstall(array $stepParams = [])
    {
        // Nothing to do yet
    }

    public function checkRequirements(&$errors = [], &$warnings = [])
    {
        $vendorDirectory = sprintf("%s/vendor", $this->addOn->getAddOnDirectory());
        if (!file_exists($vendorDirectory))
        {
            $errors[] = "vendor folder does not exist - cannot proceed with addon install";
        }
    }
}

السحر يكمن في checkRequirementsالوظيفة التي تتحقق ببساطة من وجود دليل البائع وتمنع تثبيت الوظيفة الإضافية من الاستمرار إذا لم يكن موجودًا.

هذه الخطوة الأخيرة ليست مطلوبة حقًا - ولكن يمكن أن تكون مفيدة للتضمين، فقط في حالة!

لسوء الحظ، فإن تبعيات compose نفسها غير متاحة لوظيفة checkRequirements - لم يتم تشغيل composer في هذه المرحلة، لذلك لا يمكنك التحقق من توفر أي فئات محددة. يمكنك التحقق من ملفات معينة على الرغم من ذلك.