Использование пакетов Composer в XenForo 2.1+ Addons Tutorial

Совместимость с XenForo

Перевод статьи на оффе -

У Вас недостаточно прав для просмотра ссылок. Вход или Регистрация

Заранее извиняюсь, если есть неточности в переводе, готов поправить если укажите.

У Вас недостаточно прав для просмотра ссылок. Вход или Регистрация

- это инструмент для управления зависимостями в PHP. Он позволяет вам объявлять библиотеки, от которых зависит ваш проект, и будет управлять (устанавливать /обновлять) их за вас.

XenForo v2 использует Composer для включения определенных пакетов, используемых основным программным обеспечением. Как разработчики аддонов, мы можем включать пакеты Composer в наши собственные аддоны, которые будут автоматически загружаться вместе с теми, которые предоставляет ядро.

В XenForo 2.0 нам приходилось использовать точки расширения для собственной автозагрузки, но начиная с XenForo 2.1, базовое программное обеспечение значительно упрощает включение пакетов Composer. В этом руководстве описан процесс, который нужно сделать, и как создать аддоны, которые используют composer.

Обратите внимание, что здесь есть несколько предостережений - управление зависимостями может быть сложным, и вы, следуя этому учебному пособию и включая пакеты composer, вполне можете внести непредвиденные ошибки в ваше дополнение, чужие дополнения или даже в ядро XenForo. Необходимо соблюдать осторожность, и вам следует избегать такого подхода, если вы еще не знакомы с управлением зависимостями Composer.

Прежде чем начать, убедитесь что:

1. На вашем сервере разработки

У Вас недостаточно прав для просмотра ссылок. Вход или Регистрация

, и вы знакомы с его использованием
2. Вы понимаете, как работают

У Вас недостаточно прав для просмотра ссылок. Вход или Регистрация

3. Во всех примерах предполагается, что среда Linux работает под управлением bash, вам нужно будет перевести их для использования на Windows или других платформах самостоятельно

Об этом уроке

В этом руководстве описан базовый пример добавления пакета Composer в дополнение. Сам аддон можно установить, чтобы вы могли увидеть весь код в действии и изучить, как он работает. Мы установим расширение

У Вас недостаточно прав для просмотра ссылок. Вход или Регистрация

API для объектов DateTime.

Обратите внимание, что инструкции в этом учебнике относятся к XenForo v2.1. Мой предыдущий учебник

У Вас недостаточно прав для просмотра ссылок. Вход или Регистрация

, который требует немного больше усилий по сравнению с v2.1.

Весь код в этом руководстве лицензируется по лицензии

У Вас недостаточно прав для просмотра ссылок. Вход или Регистрация

, которая по существу позволяет вам использовать (или изменять!) код для любых целей (включая коммерческие) бесплатно, с единственным условием, что вы включаете соответствующее

У Вас недостаточно прав для просмотра ссылок. Вход или Регистрация

Для полной информации о лицензии и авторских правах, смотрите файл LICENSE в корне аддона. Кроме того, вы можете просмотреть файл лицензии в репозитории Git:

У Вас недостаточно прав для просмотра ссылок. Вход или Регистрация

.

К сведению, сам Composer и пакет Carbon, который мы будем устанавливать, также используют лицензию MIT.

Начинаем

Я создал базовое дополнение под названием ComposerTutorial.

XenForo установлен на моем dev сервере по адресу /srv/www/xenforo21 - я буду называть это «корнем XenForo». Мой аддон установлен в /srv/www/xenforo21/src/addons/ComposerTutorial - я буду называть это моим «корнем аддона».

Первым шагом для добавления пакета Composer является создание файла composer.json в корне вашего аддона. Вы можете сделать это вручную или использовать команду composer require , чтобы сделать это за вас.

Bash:

$ 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

JSON:

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

Несмотря на то, что в

У Вас недостаточно прав для просмотра ссылок. Вход или Регистрация

доступны десятки полей, на самом деле для работы Composer вам нужно только require.

Если вы создали свой файл composer.json вручную, вы должны запустить команду composer update , чтобы установить пакет и его зависимости.

Bash:

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

Другая вещь, которую мы сейчас имеем, это папка vendor, содержащая установленные пакеты и все зависимости.

Bash:

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

Файл autoload.php автоматически генерируется командами composer и предназначен для запуска автозагрузчика в автономном проекте. Это не подходит для использования в 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, если будут выпущены новые версии. Важно проверить, что новые версии не содержат каких-либо критических изменений - хотя при использовании семантического контроля версий это (теоретически) не должно происходить.

Однако в производственной среде мы никогда не запускаем команду omposer update - мы хотим убедиться, что мы работаем с версиями пакетов, которые мы тестировали. Вместо этого мы запускаем команду composer install, которая опирается на файл composer.lock для установки именно указанных версий.

В любом случае, мы рассмотрим установку более подробно позже. А пока просто знайте, что файл composer.lock важен и должен быть включен в ваш элемент управления исходным кодом вместе с файлом composer.json.

Теперь, когда у нас установлены пакет и зависимости, нам нужно, чтобы XenForo автоматически загружал все.

XenForo Autoloader

Как упоминалось ранее, XenForo использует Composer - хотя они скрывают от нас файл composer.json, потому что нам не нужно устанавливать или обновлять какие-либо основные пакеты и зависимости самостоятельно - их процесс обновления позаботится об этом за нас. Смотрите каталог src/vendor в корне XenForo, чтобы увидеть пакеты, используемые XenForo.

В XenForo 2.1 представлен addon.json с новым параметром composer_autoload, который мы можем задать, чтобы система попросила включить необходимые пакеты в автозагрузчик.

Добавьте следующую строку в ваш файл addon.json:

JSON:

"composer_autoload": "vendor/composer"

Это говорит автозагрузчику XenForo загружать пакеты и из нашего аддона - путь относительно нашего корневого каталога аддона (то есть /srv/www/xenforo21/src/addons/ComposerTutorial/vendor/composer ).

Так что мой addon.json для этого учебного пакета теперь становится:

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"
}

Порядок загрузки класса

Существует способ переопределить порядок загрузки классов в ситуации, когда для нескольких надстроек требуются разные версии пакетов Composer, и вам необходимо сначала загрузить свою версию. Однако это выходит за рамки данного руководства, поэтому я не буду вдаваться в подробности.

Управления источником

При использовании управления исходным кодом обычно не требуется проверять каталог vendor - его можно перестроить либо во время сборки, если упакован дополнительный файл .zip, либо во время развертывания, если используются средства автоматического развертывания.

Таким образом, мой файл .gitignore содержит следующие директивы:

Код:

_data/
_releases/
vendor/

Каталог _data содержит файлы, необходимые для установки аддона в рабочем режиме. Он будет упакован в файл сборки .zip, но не нужен для целей разработки (вместо этого нам нужен каталог _output).
каталог _releases - это то место, где находятся наши ZIP-файлы сборки аддона - мы не хотим, чтобы они находились в управлении исходным кодом
В каталоге vendor находятся наши необходимые пакеты Composer. Это может быть восстановлено в любое время на основе содержимого файла composer.lock и поэтому не требуется в системе контроля версий

Вот список важных файлов, которые я проверяю для контроля версий - в дополнение к любому исходному коду:

.gitignore как выше - говорит нам, что не нужно проверять в системе контроля версий
addon.json - наш файл определения аддона
build.json - инструкции по сборке пакета расширения для развертывания - подробнее об этом ниже
composer.json - наш файл Composer, определяющий используемые нами пакеты
composer.lock - файл Composer, который сообщает нам, какие версии пакетов мы используем (и протестировали!)
_output - наш результат разработки, необходимый для установки аддона на нашем dev сервере

Упаковка аддона

У нас есть еще один необходимый шаг, прежде чем мы сможем упаковать аддон. Нам нужно дать процессу сборки аддона несколько инструкций о том, как установить наши необходимые пакеты Composer.

Для этого мы можем использовать файл build.json, который содержит серию директив, которые выполняются в процессе сборки.

При использовании пакетов Composer мой файл build.json выглядит следующим образом:

JSON:

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

Процесс сборки ядра начинается с создания копии ваших файлов дополнений во временном каталоге _build. Мы можем манипулировать этими скопированными файлами, чтобы подготовить их к использованию.

Наш файл build.json сообщает процессу сборки, что нужно выполнить команду composer install , используя расположение наших временных файлов дополнений в каталоге _build.

На этом этапе мы добавим два важных параметра:

--no-dev инструктирует Composer удалить любые зависимости разработки, которые мы могли включить в нашу разработку. Например, если мы используем инфраструктуру модульного тестирования, такую как PHPUnit - нам это не нужно в продакшене, мы бы включили его с помощью директивы require-dev в наш файл composer.json. Эта команда удаляет все пакеты require-dev.
--optimize-autoloader преобразует автозагрузку PSR-0/4 в файлы классов, чтобы получить более быстрый автозагрузчик, что настоятельно рекомендуется.

Итак, теперь, когда мы вернемся к нашему корню XenForo и запустим команду сборки addon, он оптимизирует наш код автозагрузчика для нас, готовых для использования в продакшене.

Bash:

$ 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.

Вы можете увидеть вывод команд Composer вместе с выводом сборки.

Это все, что нам нужно сделать - наш аддон zip-файл теперь собран с конкретными версиями пакетов Composer, которые мы тестировали, и оптимизирован для продакшена.

Тестирование этого учебного дополнения

Я приложил встроенное дополнение к этому руководству, чтобы вы могли установить его, посмотреть на код и поэкспериментировать с другими пакетами.

После установки перейдите на страницу Admin> Инструменты> Test Composer Tutorial, и вы увидите некоторые результаты, сгенерированные Carbon.

Вы также можете клонировать git-репозиторий для учебного кода -

У Вас недостаточно прав для просмотра ссылок. Вход или Регистрация

Реакции: Alex Fair, ZloyDed, Captain и 3 других

Использование пакетов Composer в XenForo 2.1+ Addons Tutorial 2

Другие ресурсы пользователя artscripts

Поделиться ресурсом

Мы ценим вашу конфиденциальность