В предыдущих версиях XF было очень мало стандартов и соглашений, касающихся разработки плагинов. Мы многое сделали, чтобы изменить это в XF 2.0. Давайте посмотрим на некоторые изменения:
Каждый установленный плагин должен иметь уникальный идентификатор, и этот идентификатор определяет, где плагин хранит свои файлы. Существует два формата идентификатора дополнения.
Первый тип - «простой» состоит из одного слова. Это слово не содержит какие-либо специальные символы! Например, Demo
Данный идентификатор плагина должен соответствовать следующим правилам:
- Должен содержать только a-z или A-Z
- Может содержать 0-9, но не в начале идентификатора
- Не может содержать никаких специальных символов, таких как слэши, тире или символы подчеркивания
Второй тип - содержит префикс, если вы выпускаете плагины под конкретным брендом или компанией, на это указывает дополнительный идентификатор. Например, SomeVendor/Demo.
Идентификатор плагина с префиксом должен придерживаться следующих правил:
- Должен содержать только a-z или A-Z
- Может содержать один символ
/, но не в начале или в конце - Может содержать 0-9, но не в начале любой части идентификатора плагина
После выбора своего префикса, мы будем знать, где хранятся файлы для этого плагина. Все плагины XF 2.0 находятся по пути src / addons.
Если ваш идентификатор плагина, например, Demo, файлы вашего плагина будут находится в следующем расположении: src/addons/Demo.
Если ваш идентификатор плагина с префиксом, например. SomeVendor/Demo, файлы будут находится в следующем расположении:src/addons/SomeVendor/Demo.
Выбранный идентификатор также станет вашим префиксом пространства имен классов (см. Пространства имен для получения дополнительной информации).
XF для нумерации версий использует принцип MAJOR.MINOR.PATCH (пример, 2.0.0 для первой стабильной версии XF2), мы рекомендуем использовать аналогичный подход к версированию собственных дополнений. Увеличивайте
- MAJOR версию, когда вы делаете большие изменения функционала, особенно изменения, которые нарушают обратную совместимость
- MINOR версию, когда вы добавляете обратно совместимый функционал
- PATCH версию, когда вы делаете исправления ошибок с обратной совместимостью
Идентификатор версии плагина - это целое число, которое используются для внутреннего сравнения версий. Это позволяет более легко обнаруживать, когда одна версия старше другой. Каждая новая версия вашего дополнения должна увеличивать идентификатор версии как минимум на 1, но правила, которое мы используем внутри самой XF, применимы также и для плагинов. Мы используем идентификаторы версий в формате aabbccde.
aaпредставляет основную версиюbbпредставляет второстепенную версиюccпредставляет версию патчаdпредставляет состояние, например.1для альфа-релизов,3для бета-релизов,5для кандидатов на выпуск и7для стабильных выпусковeпредставляет состояние версии
Например, плагин с версией 1.7.3 кандидат на выпуск 4 будет иметь идентификатор 1070354. Окончательный стабильный релиз XF2 имеет идентификатор 2000070. Версия 1.5.0 Beta 3 из XF имела идентификатор 1050033. Стабильная версия 99.99.99 будет иметь идентификатор 99999970 ... и, думаю, вам стоит остановится 😉
В директории плагина есть файлы и директории, которые имеют особое значение.
addon.json - это файл, содержащий информацию, которая идентифицирует плагин и отображает информацию о нём в Admin CP. Как минимум, ваш addon.json должен выглядеть так:
{
"title": "My Add-on by Some Company",
"version_string": "2.0.0",
"version_id": 2000070,
"dev": "Some Company"
}Базовый файл будет создан для вас автоматически при создании плагина.
Вы также можете проверить ваш addon.json файл.
| Свойства | Описание |
|---|---|
legacy_addon_id |
Используется для обработки изменений идентификатора плагина при обновлении с XenForo 1 до XenForo 2. |
title |
Название плагина. Оно отображается в ACP. |
description |
Описние вашего плагина. Оно отображается в ACP |
version_id |
Идентификатор, используемый XenForo для отслеживания обновлений вашего плагина. Он должен увеличиватся при каждом релизе. |
version_string |
Человеко-читаемая версия аддона. Будет отображаться в ACP вместо свойства version_id. |
dev |
Имя разработчика плагина. Оно отображается в ACP. |
dev_url |
Если задано, имя разработчика будет отображаться в ACP как гиперссылка. |
faq_url |
Если задано, гиперссылка "FAQ" будет отображаться в панели ACP |
support_url |
Если задано, гиперссылка "поддержка" будет отображаться в ACP. |
extra_urls |
Позволяет отображать другие ссылки, связанные с плагином (ссылки на сообщения об ошибках, руководство - все, что вам хочется). Массив объектов JSON, где ключ - текст ссылки, а значение - ссылка. |
require |
Набор требований, которые должны быть выполнены, перед установкой плагина. Смотрите 'Свойства требований' для дополнительной информации. |
icon |
TЗначок плагина. Это имя иконки FontAwesome (например, fa-shopping-bag, или путь до файла картинки.) |
Свойство require - это стандартный способ блокировки установки или обновления плагина, если среда не поддерживает или не соответствует требованиям.
Вы можете использовать его для того, чтобы сначала были установлены другие плагины, присутствовали или были включены определенные расширения PHP, и/или для указания минимальной версии PHP.
Вот пример фрагмента:
...
"require": {
"XF": [2000010, "XenForo 2.0.0+"],
"php": ["5.4.0", "PHP 5.4.0+"],
"php-ext/json": ["*", "JSON extension"]
}
...Каждое требование - это именованный массив:
- Имя массива является идентификатором продукта (например,
XFилиphp). - Первый элемент массива - это версия продукта (например,
2000010или5.4.0). Вы можете использовать*, чтобы ссылаться на любую версию продукта. - Второй элемент - человеко-читаемый текст требования, это используется в сообщениях. (например,
XenForo 2.0.0+илиPHP 5.4.0+).
Вот сводка поддерживаемых идентификаторов:
| Название продукта/требования | Относится к... | Значение |
|---|---|---|
XF |
Установленная версия XenForo. | Идентификатор версии XenForo, например 200010.Вы можете узнать текущую версию XenForo, проверив верхнюю часть файла /src/XF.php для определения $versionIdили напечатав значение\XF::$versionId. |
php |
Версия PHP. | Версия PHP, например, 5.4.0.Рекомендуется держать это как можно ниже; Обновление версии PHP может быть довольно сложной задачей, особенно если другие плагины конфликтуют с более новыми версиями PHP. |
php-ext/(extension name) |
Расширение PHP - где (extension name) это имя расширения. |
Версия расширения PHP. Это проверяется с помощью функции PHP version_compareтак что это работает даже для строк версии в официальном полном формате PHP, как 7.1.19-1+ubuntu16.04.1+deb.sury.org+1. |
(any addon ID) |
Плагин XenForo, такой как Demo/Addon.Если вы не уверены относительно идентификатора плагина проверьте его файл addon.json. |
Идентификатор версии плагина. Вы можете обратиться к рекомендованному формату версирования для получения дополнительной информации. |
hashes.json - это новый способ добавить поддержку системы проверки работоспособности файлов, и приятная новость - он генерируется автоматически!
Как часть процесса сборки (подробнее об этом позже), мы быстро выполним инвентаризацию всех ваших файлов плагина и вычислим хэш содержимого файлов.
Setup.php - это новый дом для любого кода, который запускается во время установки, обновления или удаления вашего плагина.
Мы поговорим подробнее о том, как создать класс установки ниже.
В каталоге _data хранятся основные данные для вашего плагина. Каждый дополнительный тип данных будет иметь свой собственный XML-файл (а не один для всех типов). Хэши для этих файлов так же находятся внутри hashes.json, поэтому мы можем гарантировать, что все файлы будут проверены перед установкой.
Каталог _output не требуется для успешной установки плагина и не должен включаться при выпуске плагина. Этот каталог предназначен исключительно для целей разработки и используется только в том случае, если включен режим разработки (см. Включение режима разработчика).
Каждый элемент дополнительных данных хранится в отдельном файле. В основном они хранятся в виде файлов JSON, но в случае фраз они хранятся в виде файлов TXT, а для шаблонов они хранятся в виде файлов HTML/CSS/LESS. Все типы шаблонов редактируются непосредственно в файловой системе, а изменения, внесенные в эти файлы, автоматически записываются в базу данных при загрузке.
Чтобы создать класс установки для вашего плагина, все, что вам нужно сделать, это создать файл с именем Setup.php в корне каталога вашего дополнения.
Класс Setup должен расширять \XF\AddOn\AbstractSetup, который требует, как минимум, реализацию методов install(), upgrade() и uninstall(). Простой класс установки плагина выглядит так:
<?php
namespace Demo;
class Setup extends \XF\AddOn\AbstractSetup
{
public function install(array $stepParams = [])
{
$this->schemaManager()->createTable('xf_demo', function(\XF\Db\Schema\Create $table)
{
$table->addColumn('demo_id', 'int');
});
}
public function upgrade(array $stepParams = [])
{
if ($this->addOn->version_id < 1000170)
{
$this->schemaManager()->alterTable('xf_demo', function(\XF\Db\Schema\Alter $table)
{
$table->addColumn('foo', 'varchar', 10)->setDefault('');
});
}
}
public function uninstall(array $stepParams = [])
{
$this->schemaManager()->dropTable('xf_demo');
}
}Класс Setup также поддерживает выполнение каждого из действий в разных шагах. Чтобы реализовать это поведение, ваш класс Setup может использовать свойства «StepRunnerInstallTrait», «StepRunnerUpgradeTrait» и/или «StepRunnerUninstallTrait».
Они автоматически реализуют требуемые методы, и вам просто нужно добавить соответствующие шаги, например. installStep1(), upgrade1000170Step1(), upgrade1000170Step2() и uninstallStep1(), где 1000170 и т. д. в методах обновления являются дополнительными идентификаторами версий (см. Рекомендуемый формат версии).