ПЛАГИН xF2 Using Composer Packages in XenForo 2+ Addons Tutorial
- Плагины xF2.x.x
- 0 Скачиваний
- 0 Оценка
Composer - это инструмент для управления зависимостями в PHP. Он позволяет вам объявлять библиотеки, от которых зависит ваш проект, и управлять ими (устанавливать / обновлять) за вас.
XenForo v2 использует Composer за кулисами для включения определенных пакетов, используемых основным программным обеспечением. Как разработчики дополнений, мы можем включать пакеты Composer в наши собственные дополнения, которые будут загружаться автоматически наряду с теми, которые предоставляются ядром.
В XenForo 2.0 нам приходилось использовать точки расширения, чтобы выполнять нашу собственную автозагрузку, но начиная с XenForo 2.1, основное программное обеспечение действительно упрощает включение пакетов Composer. В этом руководстве описывается процесс для этого и как создавать свои дополнения, использующие composer.
Обратите внимание, что здесь есть некоторые предостережения - управление зависимостями может быть сложным, и вы вполне можете внести неожиданные ошибки в свой аддон, другие дополнения или даже в ядро XenForo, следуя этому руководству и включая пакеты composer. Необходимо соблюдать осторожность, и вам настоятельно рекомендуется избегать этого подхода, если вы еще не знакомы с управлением зависимостями Composer.
Предположения, сделанные в этом руководстве:
В этом руководстве рассматривается базовый пример добавления пакета Composer в дополнение. Само дополнение можно установить, поэтому вы можете увидеть весь работающий код и изучить, как он работает. Мы установим расширение Carbon API для объектов DateTime.
Обратите внимание, что инструкции в этом руководстве относятся только к XenForo версии v2.1 и более поздним версиям - пожалуйста, ознакомьтесь с моим предыдущим руководством по использованию пакетов Composer в XenForo версии 2.0 Addons Tutorial для получения инструкций для версии v2.0, которая требует немного больше усилий по сравнению с версией v2.1.
Весь код в этом руководстве лицензирован по лицензии MIT, которая, по сути, позволяет вам использовать (или изменять!) Код для любых целей (включая коммерческие) бесплатно, при единственном условии, что вы включите соответствующее уведомление об авторских правах и разрешениях.
Смотрите LICENSE файл в корневом каталоге addon для получения полной информации о лицензии и авторских правах. Кроме того, вы можете просмотреть файл лицензии в репозитории Git для получения кода руководства: ЛИЦЕНЗИЯ.
К вашему СВЕДЕНИЮ, сам Composer и пакет Carbon, который мы установим, также используют лицензию MIT.
Приступая к работе
Я создал базовый аддон под названием ComposerTutorial.
XenForo установлен на моем сервере разработки по адресу /srv/www/xenforo21 - я буду называть это "XenForo root". Мой аддон установлен по адресу /srv/www/xenforo21/src/addons/ComposerTutorial - я буду называть это своим "корнем аддона".
Первым шагом к добавлению пакета Composer является создание composer.json файла в корневом каталоге вашего дополнения. Вы можете сделать это вручную или использовать composer require команду, которая сделает это за вас.
Теперь у нас есть базовый файл Composer, созданный на
Хотя в схеме composer.json доступны десятки полей, на самом деле вам нужно только require поле, чтобы заставить Composer работать.
Если вы создали свой composer.json файл вручную, вам следует вместо этого запустить composer update команду для установки пакета и его зависимостей.
Еще одна вещь, которая у нас теперь есть, - это
Наконец, у нас есть
Во время разработки вашего аддона вы можете запустить
Однако в производственной среде мы никогда не запускаем команду
В любом случае, позже мы рассмотрим установку более подробно. А пока просто признайте, что
Итак, теперь, когда у нас установлен наш пакет и зависимости, нам нужно заставить XenForo все загрузить автоматически.
Автозагрузчик XenForo
Как упоминалось ранее, XenForo использует Composer за кулисами - хотя они скрывают от нас
В XenForo 2.1 представлен удобный новый
Добавьте следующую строку в свой
Это указывает автозагрузчику XenForo также загружать пакеты из нашего аддона - путь указан относительно корневого каталога нашего аддона (т.е.
Итак, мой addon.json для этого учебного пакета теперь становится:
Порядок загрузки классов
Существует способ переопределить порядок загрузки классов в ситуации, когда для нескольких дополнений требуются разные версии пакетов Composer, и вам нужно сначала загрузить свою версию. Однако это выходит за рамки данного руководства, поэтому я не буду здесь вдаваться в подробности.
Управление версиями
При использовании системы управления версиями обычно не требуется проверять
Таким образом, мой
Упаковка дополнения
Нам необходимо выполнить еще один шаг, прежде чем мы сможем упаковать дополнение. Нам нужно дать процессу сборки дополнения несколько инструкций о том, как установить необходимые пакеты Composer.
Для этого мы можем использовать
При использовании пакетов Composer мой
Процесс сборки ядра начинается с создания копии ваших файлов дополнений во временном
Наш build.json файл сообщает процессу сборки выполнить composer install команду, используя расположение наших временных файлов дополнений в
На этом этапе мы добавим два важных параметра:
Вы можете увидеть результаты команд composer вместе с результатами сборки.
Это все, что нам нужно сделать - наш zip-файл дополнения теперь собран с использованием определенных версий протестированных нами пакетов Composer и оптимизирован для производственного использования.
Тестирование этого обучающего дополнения
Я приложил созданное дополнение к этому руководству, чтобы вы могли установить его, посмотреть код и поэкспериментировать с другими пакетами.
После установки перейдите на
Вы также можете клонировать репозиторий git для кода руководства - Руководство по XenForo Composer
Необязательно Setup.php проверка требований
Если ваш процесс сборки работает правильно, ваша папка поставщика должна быть создана, а все зависимости установлены и включены в файл выпуска, готовый к развертыванию.
Однако, если вы используете систему управления версиями и клонируете свой репозиторий, вы должны не забыть установить зависимости от поставщика, запустив
Если вы попытаетесь установить аддон, у которого есть зависимости composer, но ваша папка поставщика не существует, вы можете нарушить работу вашего форума довольно неприятным образом (для исправления этого потребуется вручную обновить базу данных!).
В качестве проверки безопасности вы можете захотеть выполнить простую проверку наличия папки vendor при попытке установки вашего аддона - мы можем сделать это, добавив
Волшебство заключается в
Этот последний шаг на самом деле не обязателен, но его может быть полезно включить, на всякий случай!
К сожалению, сами зависимости
XenForo v2 использует Composer за кулисами для включения определенных пакетов, используемых основным программным обеспечением. Как разработчики дополнений, мы можем включать пакеты Composer в наши собственные дополнения, которые будут загружаться автоматически наряду с теми, которые предоставляются ядром.
В XenForo 2.0 нам приходилось использовать точки расширения, чтобы выполнять нашу собственную автозагрузку, но начиная с XenForo 2.1, основное программное обеспечение действительно упрощает включение пакетов Composer. В этом руководстве описывается процесс для этого и как создавать свои дополнения, использующие composer.
Обратите внимание, что здесь есть некоторые предостережения - управление зависимостями может быть сложным, и вы вполне можете внести неожиданные ошибки в свой аддон, другие дополнения или даже в ядро XenForo, следуя этому руководству и включая пакеты composer. Необходимо соблюдать осторожность, и вам настоятельно рекомендуется избегать этого подхода, если вы еще не знакомы с управлением зависимостями Composer.
Предположения, сделанные в этом руководстве:
- у вас установлен Composer на вашем сервере разработки, и вы знакомы с тем, как им пользоваться
- вы понимаете, как работают пакеты Composer
- все примеры предполагают среду Linux под управлением bash, вам нужно будет самостоятельно перевести их для использования в Windows или других платформах
В этом руководстве рассматривается базовый пример добавления пакета Composer в дополнение. Само дополнение можно установить, поэтому вы можете увидеть весь работающий код и изучить, как он работает. Мы установим расширение Carbon API для объектов DateTime.
Обратите внимание, что инструкции в этом руководстве относятся только к XenForo версии v2.1 и более поздним версиям - пожалуйста, ознакомьтесь с моим предыдущим руководством по использованию пакетов Composer в XenForo версии 2.0 Addons Tutorial для получения инструкций для версии v2.0, которая требует немного больше усилий по сравнению с версией v2.1.
Весь код в этом руководстве лицензирован по лицензии MIT, которая, по сути, позволяет вам использовать (или изменять!) Код для любых целей (включая коммерческие) бесплатно, при единственном условии, что вы включите соответствующее уведомление об авторских правах и разрешениях.
Смотрите LICENSE файл в корневом каталоге addon для получения полной информации о лицензии и авторских правах. Кроме того, вы можете просмотреть файл лицензии в репозитории Git для получения кода руководства: ЛИЦЕНЗИЯ.
К вашему СВЕДЕНИЮ, сам Composer и пакет Carbon, который мы установим, также используют лицензию MIT.
Приступая к работе
Я создал базовый аддон под названием ComposerTutorial.
XenForo установлен на моем сервере разработки по адресу /srv/www/xenforo21 - я буду называть это "XenForo root". Мой аддон установлен по адресу /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:Хотя в схеме composer.json доступны десятки полей, на самом деле вам нужно только require поле, чтобы заставить Composer работать.
Если вы создали свой 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 файл также будет обновлен, если были выпущены новые версии. Важно проверить, что новые версии не содержат каких-либо критических изменений - хотя при использовании семантического управления версиями этого (теоретически) не должно произойти.Однако в производственной среде мы никогда не запускаем команду
composer update - мы хотим убедиться, что работаем с версиями протестированных нами пакетов. Вместо этого мы запускаем composer install команду, которая использует composer.lock файл для установки точно указанных версий.В любом случае, позже мы рассмотрим установку более подробно. А пока просто признайте, что
composer.lock файл важен и его следует проверить в элементе управления исходным кодом вместе с вашим composer.json файлом.Итак, теперь, когда у нас установлен наш пакет и зависимости, нам нужно заставить XenForo все загрузить автоматически.
Автозагрузчик XenForo
Как упоминалось ранее, 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 каталог, который можно перестроить либо во время сборки, если упакован файл addon .zip, либо во время развертывания, если используются инструменты автоматического развертывания.Таким образом, мой
.gitignore файл содержит следующие директивы:
Код:
_data/
_releases/
vendor/- в _data каталоге содержатся файлы, необходимые для установки дополнения в рабочей среде. Они будут упакованы в файл build .zip, но не являются необходимыми для целей разработки (вместо этого нам нужен
_outputкаталог). - в
_releasesкаталоге хранятся файлы build .zip нашего аддона - они нам не нужны в системе управления версиями - в
vendorкаталоге установлены необходимые пакеты Composer. Их можно в любое время перестроить на основе содержимогоcomposer.lockфайла, поэтому в системе управления версиями они не требуются.
.gitignoreкак указано выше, указывает нам, что не следует проверять в системе управления версиямиaddon.json- наш файл определения дополненияbuild.json- инструкции по созданию нашего пакета дополнений для развертывания - подробнее об этом нижеcomposer.json- наш файл Composer, определяющий используемые нами пакетыcomposer.lock- файл Composer, который сообщает нам, какие версии пакетов мы используем (и тестировали!)_output- результаты нашей разработки, необходимые для установки дополнения на наш сервер разработки
Упаковка дополнения
Нам необходимо выполнить еще один шаг, прежде чем мы сможем упаковать дополнение. Нам нужно дать процессу сборки дополнения несколько инструкций о том, как установить необходимые пакеты Composer.
Для этого мы можем использовать
build.json файл, который содержит ряд директив, которые выполняются в процессе сборки.При использовании пакетов Composer мой
build.json файл выглядит следующим образом:
JSON:
{
"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 в файлы classmap, чтобы получить более быстрый автозагрузчик, который настоятельно рекомендуется для производственного использования
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 > Tools > Test Composer Tutorial страницу, и вы увидите некоторые выходные данные, сгенерированные Carbon.Вы также можете клонировать репозиторий git для кода руководства - Руководство по XenForo Composer
Необязательно Setup.php проверка требований
Если ваш процесс сборки работает правильно, ваша папка поставщика должна быть создана, а все зависимости установлены и включены в файл выпуска, готовый к развертыванию.
Однако, если вы используете систему управления версиями и клонируете свой репозиторий, вы должны не забыть установить зависимости от поставщика, запустив
composer install (или composer update если вы все еще разрабатываете), прежде чем пытаться установить дополнение.Если вы попытаетесь установить аддон, у которого есть зависимости composer, но ваша папка поставщика не существует, вы можете нарушить работу вашего форума довольно неприятным образом (для исправления этого потребуется вручную обновить базу данных!).
В качестве проверки безопасности вы можете захотеть выполнить простую проверку наличия папки vendor при попытке установки вашего аддона - мы можем сделать это, добавив
Setup.php файл в корневой каталог вашего аддона (возможно, он у вас уже есть).
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";
}
}
}Волшебство заключается в
checkRequirements функции, которая просто проверяет, существует ли каталог поставщика, и предотвращает продолжение установки дополнения, если это не так.Этот последний шаг на самом деле не обязателен, но его может быть полезно включить, на всякий случай!
К сожалению, сами зависимости
compose недоступны функции checkRequirements - composer на данный момент не запущен, поэтому вы не можете проверить, доступны ли какие-либо конкретные классы. Хотя вы могли бы проверить наличие определенных файлов.
