Skip to content

Latest commit

 

History

History
119 lines (87 loc) · 12.9 KB

AddOnStructure.md

File metadata and controls

119 lines (87 loc) · 12.9 KB

Структура плагина

В предыдущих версиях XF было очень мало стандартов и соглашений, связанных с разработкой дополнений. Мы многое сделали, чтобы изменить это в XF 2.0. Давайте рассмотрим некоторые изменения:

Идентификаторы плагина и дополнительные надстройки

Каждый установленный надстройщик должен иметь уникальный идентификатор, и этот идентификатор определяет, где в файловой системе надстройка должна хранить свои файлы. Существует два возможных формата для дополнительного ID.

Первый «простой» тип должен быть одним словом и не содержать каких-либо специальных символов. Например,Demo.

Простые добавочные идентификаторы должны соответствовать следующим правилам:

  • Должен содержать только a-z или A-Z
  • Может содержать 0-9, но не в начале идентификатора
  • Не может содержать никаких специальных символов, таких как слэши, тире или символы подчеркивания

Второй содержит префикс поставщика, поэтому, если вы выпускаете надстройки под конкретным брендом или компанией, это может указывать дополнительный идентификатор. Например, SomeVendor/Demo.

Идентификатор надстройки типа поставщика должен придерживаться следующих правил:

  • Должен содержать только a-z или A-Z
  • Может содержать один символ /, но не в начале или в конце
  • Может содержать 0-9, но не в начале любой части надстройки ID

После того, как вы определили, что такое дополнительный идентификатор, мы точно знаем, где будут храниться файлы для этого надстройки. Все дополнения XF 2.0 хранятся в подкаталоге каталога src / addons.

Если у вас есть простой дополнительный код, например, Demo, файлы для вашего дополнения будут храниться в следующем расположении: src/addons/Demo.

Если у вас есть идентификатор надстройки на основе поставщика, например. SomeVendor/Demo, файлы будут храниться в следующем расположении:src/addons/SomeVendor/Demo.

Выбранный дополнительный идентификатор также станет вашим префиксом пространства имен классов (см. [Пространства имен] (/documentation/GeneralConcepts.md#part4) для получения дополнительной информации).

Рекомендации к строковому формату версии

Сам XF использует принцип MAJOR.MINOR.PATCH (например, 2.0.0 для первой стабильной версии XF2) для своей нумерации версий, и мы рекомендуем использовать аналогичный подход к версированию собственных надстроек. В основных терминах

  • ОСНОВНАЯ версия, когда вы делаете основные изменения функций, особенно изменения, которые нарушают обратную совместимость
  • Версия 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

addon.json - это файл, содержащий несколько фрагментов информации, которые необходимы, чтобы помочь XF 2.0 идентифицировать надстройку и отобразить информацию об этом в Admin CP. Как минимум, ваш файл addon.json должен выглядеть так:

{
	"title": "My Add-on by Some Company",
	"version_string": "2.0.0",
	"version_id": 2000070
}

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

Включение этого файла является обязательным.

Файл hashes.json

hashes.json - это новый способ добавить поддержку системы проверки работоспособности файлов, и лучшая часть - она генерируется автоматически!

Как часть процесса сборки (подробнее об этом позже), мы быстро выполним инвентаризацию всех ваших файлов надстройки и напишем вычисленный хэш содержимого файла.

Файл Setup.php

Setup.php - это новый дом для любого кода, который требуется запускать во время установки, обновления или удаления вашего дополнения.

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

Директория _data

В каталоге _data хранятся основные данные для вашего надстроек. Каждый дополнительный тип данных будет иметь свой собственный XML-файл (а не один для всех типов). Хэши для этих файлов включены внутри hashes.json, поэтому мы можем гарантировать, что надстройка содержит полные и согласованные данные, прежде чем разрешить установку надстройки.

Директория _output

Каталог _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 и т. д. в методах обновления являются дополнительными идентификаторами версий (см. Рекомендуемый формат версии).