- Совместимость с XenForo
- 1.2
- 1.3
- 1.4
- 1.5
- Видимый копирайт
- Нет
Для работы данного плагина у Вас должен быть установлен [CMF] Core.
CMF Development - Разработка дополнений с VCS
=============================================
Основные проблемы при разработке дополнений под XenForo
-------------------------------------------------------
При разработке и поддержке дополнений для XenForo основные проблемы с которыми сталкивается разработчик:
1. Невозможность простого использования репозитариев для каждого отдельного дополнения (все находятся в одном дереве, что не дает нормально использовать функционал IDE по работе с системами контроля версий)
2. Невозможность использовать системы контроля версий для шаблонов и фраз.
Все эти проблемы и неудобства позволяет решить это дополнение
Автозагрузчик WHM_Development_Autoloader
========================================
Общие положения
---------------
Ядро для работы и реализации функционала использует собственный автозагрузчик классов и собственный аналог реестра очень похож на реестр XenForo_Application, но со своими особенностями.
Для включения полного функционала ядра, кроме установки дополнения через админку, надо включить подмену стандартного автозагрузчика XenForo.
Самый ранний вариант без правки оригинальных файлов - это добавление инициализации автозагрузчика в `config.php`, которое никак не повлияет на обновление форума или на установку каких либо сторонних хаков и инициализируется приложением достаточно рано чтобы была возможность перехватить практически любой класс после его загрузки.
Режим разработки. Отдельная папка для каждого аддона.
-----------------------------------------------------
При разработке удобно когда каждый аддон лежит в полностью своей папке, что практически не осуществимо в текущей структуре папок XenForo (php, js и стили - все в разных папках).
Для этого у автолоадера есть режим поиска файлов в папке по альтернативному пути, причем внутри файлы хака могут располагаться исходя из нескольких вариантов соглашений (связано с тем что разработчики как только не называют свои классы при создании расширения).
Настройка автозагрузчика делается через метод `configure`.
#### [пример config-а с комментариями.](config.php.md)
------
Если автозагрузчик не находит класс по альтернативному пути, то он ищет его по первоначальному пути, т.е. в `/library/`.
### Соглашения по структуре и именованию папок дополнений
Разработчики при наименовании своих дополнений обычно используют 2 варианта наименования классов короткий и длинный:
1. Короткий - `AddOnName_SubClass` (соответсвенно хранится в `/library/AddOnName/SubClass.php`)
2. Длинный - `Author_AddOnName_SubClass` (соответсвенно хранится в `/library/Author/AddOnName/SubClass.php`)
Соотвественно id дополнения на основе названия классов можно считать `addonname` и `author_addonname` (для удобства http редиректов будут в нижнем регистре).
После чего простая последовательная проверка на наличие папок `author_addonname` и `addonname` позволяет точно сказать по какому соглашению проименованы классы в аддоне.
Учитывая уже сложившуюся структуру SVN репозиториев для CMF, когда файлы классов лежат в 1 папке `/library/CMF/AddonName/` (т.е. длинное наименование), а все дополнительные файлы (js/xml/style) лежат в `/library/CMF/AddonName/_Extras/`, то автозагрузчик обрабатывает и этот вариант хранения готового дополнения.
Т.е. дополнения с длинным наименованиями можно хранить так:
+ **Расположение по умолчанию:**
+ xml файлов с аддоном и языками может вообще не быть в папках
~~~
/library/CMF/SomeAddon/Model/Forum.php
/library/CMF/SomeAddon/Model/Thread.php
/library/CMF/SomeAddon/Listener.php
/js/cmf/someaddon/thread.js
/styles/cmf/someaddon/image.jpg
~~~
+ **CMF-соглашение:**
+ папка дополнения первые 2 части класса через подчеркивание в нижнем регистре
+ остальная часть пути класса как в library
+ все остальное лежит в _Extras
+ xml лежит в _Extras
~~~
/addons/cmf_someaddon/Model/Forum.php
/addons/cmf_someaddon/Model/Thread.php
/addons/cmf_someaddon/Listener.php
/addons/cmf_someaddon/_Extras/js/cmf/someaddon/thread.js
/addons/cmf_someaddon/_Extras/styles/cmf/someaddon/image.jpg
/addons/cmf_someaddon/_Extras/xml/language.xml
~~~
+ **FullPath-соглашение:**
+ папка дополнения первые 2 части класса через подчеркивание в нижнем регистре
+ все кроме xml лежит в upload по полному пути
+
~~~
/addons/cmf_someaddon/upload/library/CMF/SomeAddon/Model/Forum.php
/addons/cmf_someaddon/upload/library/CMF/SomeAddon/Model/Thread.php
/addons/cmf_someaddon/upload/library/CMF/SomeAddon/Listener.php
/addons/cmf_someaddon/upload/js/cmf/someaddon/thread.js
/addons/cmf_someaddon/upload/styles/cmf/someaddon/image.jpg
/addons/cmf_someaddon/xml/language.xml
~~~
Для дополнений с **коротким** стилем наименования используется только **FullPath-соглашение** только в качестве имени папки используется первая часть класса.
Во всех соглашениях за счет нижнего регистра названия аддона и присутствия частей названия аддона в путях к статическим файлам, легко сделать редирект с `/(js|styles)/` на соответствующую папку аддона.
### Привязка классов к определенному дополнению
Если дополнение использует сторонние классы, с другим префиксом/неймспейсом (типичный пример дополнение `TMS` использует сторонние классы `Diff_*`), то может понадобиться принудительно указать в какой папке искать класс с заданным префиксом.
Режим разработчика
==================
Все дополнения (включая CMF_Core и CMF_Development) находятся в папке /.repos/ (путь настраиваемый).
Автоэкспорт шаблонов и фраз включен.
Добавить в config.php:
~~~php
//Включение недокументированной настройки XenForo для автоэкспорта шаблонов
$config['development']['directory'] = '.';
//Обязательное включение режима отладки
$config['debug']=true;
//Загрузка измененного автолоадера
~~~
Пример настройки locations для nginx
====================================
Пусть все аддоны нахолдятся в папке `/.repos/`
Тогда для поддержки всех вариантов соглашений в конфиг надо добавить:
~~~
~~~
CMF Development - Разработка дополнений с VCS
=============================================
Основные проблемы при разработке дополнений под XenForo
-------------------------------------------------------
При разработке и поддержке дополнений для XenForo основные проблемы с которыми сталкивается разработчик:
1. Невозможность простого использования репозитариев для каждого отдельного дополнения (все находятся в одном дереве, что не дает нормально использовать функционал IDE по работе с системами контроля версий)
2. Невозможность использовать системы контроля версий для шаблонов и фраз.
Все эти проблемы и неудобства позволяет решить это дополнение
Автозагрузчик WHM_Development_Autoloader
========================================
Общие положения
---------------
Ядро для работы и реализации функционала использует собственный автозагрузчик классов и собственный аналог реестра очень похож на реестр XenForo_Application, но со своими особенностями.
Для включения полного функционала ядра, кроме установки дополнения через админку, надо включить подмену стандартного автозагрузчика XenForo.
Самый ранний вариант без правки оригинальных файлов - это добавление инициализации автозагрузчика в `config.php`, которое никак не повлияет на обновление форума или на установку каких либо сторонних хаков и инициализируется приложением достаточно рано чтобы была возможность перехватить практически любой класс после его загрузки.
Режим разработки. Отдельная папка для каждого аддона.
-----------------------------------------------------
При разработке удобно когда каждый аддон лежит в полностью своей папке, что практически не осуществимо в текущей структуре папок XenForo (php, js и стили - все в разных папках).
Для этого у автолоадера есть режим поиска файлов в папке по альтернативному пути, причем внутри файлы хака могут располагаться исходя из нескольких вариантов соглашений (связано с тем что разработчики как только не называют свои классы при создании расширения).
Настройка автозагрузчика делается через метод `configure`.
#### [пример config-а с комментариями.](config.php.md)
------
Если автозагрузчик не находит класс по альтернативному пути, то он ищет его по первоначальному пути, т.е. в `/library/`.
### Соглашения по структуре и именованию папок дополнений
Разработчики при наименовании своих дополнений обычно используют 2 варианта наименования классов короткий и длинный:
1. Короткий - `AddOnName_SubClass` (соответсвенно хранится в `/library/AddOnName/SubClass.php`)
2. Длинный - `Author_AddOnName_SubClass` (соответсвенно хранится в `/library/Author/AddOnName/SubClass.php`)
Соотвественно id дополнения на основе названия классов можно считать `addonname` и `author_addonname` (для удобства http редиректов будут в нижнем регистре).
После чего простая последовательная проверка на наличие папок `author_addonname` и `addonname` позволяет точно сказать по какому соглашению проименованы классы в аддоне.
Учитывая уже сложившуюся структуру SVN репозиториев для CMF, когда файлы классов лежат в 1 папке `/library/CMF/AddonName/` (т.е. длинное наименование), а все дополнительные файлы (js/xml/style) лежат в `/library/CMF/AddonName/_Extras/`, то автозагрузчик обрабатывает и этот вариант хранения готового дополнения.
Т.е. дополнения с длинным наименованиями можно хранить так:
+ **Расположение по умолчанию:**
+ xml файлов с аддоном и языками может вообще не быть в папках
~~~
/library/CMF/SomeAddon/Model/Forum.php
/library/CMF/SomeAddon/Model/Thread.php
/library/CMF/SomeAddon/Listener.php
/js/cmf/someaddon/thread.js
/styles/cmf/someaddon/image.jpg
~~~
+ **CMF-соглашение:**
+ папка дополнения первые 2 части класса через подчеркивание в нижнем регистре
+ остальная часть пути класса как в library
+ все остальное лежит в _Extras
+ xml лежит в _Extras
~~~
/addons/cmf_someaddon/Model/Forum.php
/addons/cmf_someaddon/Model/Thread.php
/addons/cmf_someaddon/Listener.php
/addons/cmf_someaddon/_Extras/js/cmf/someaddon/thread.js
/addons/cmf_someaddon/_Extras/styles/cmf/someaddon/image.jpg
/addons/cmf_someaddon/_Extras/xml/language.xml
~~~
+ **FullPath-соглашение:**
+ папка дополнения первые 2 части класса через подчеркивание в нижнем регистре
+ все кроме xml лежит в upload по полному пути
+
~~~
/addons/cmf_someaddon/upload/library/CMF/SomeAddon/Model/Forum.php
/addons/cmf_someaddon/upload/library/CMF/SomeAddon/Model/Thread.php
/addons/cmf_someaddon/upload/library/CMF/SomeAddon/Listener.php
/addons/cmf_someaddon/upload/js/cmf/someaddon/thread.js
/addons/cmf_someaddon/upload/styles/cmf/someaddon/image.jpg
/addons/cmf_someaddon/xml/language.xml
~~~
Для дополнений с **коротким** стилем наименования используется только **FullPath-соглашение** только в качестве имени папки используется первая часть класса.
Во всех соглашениях за счет нижнего регистра названия аддона и присутствия частей названия аддона в путях к статическим файлам, легко сделать редирект с `/(js|styles)/` на соответствующую папку аддона.
### Привязка классов к определенному дополнению
Если дополнение использует сторонние классы, с другим префиксом/неймспейсом (типичный пример дополнение `TMS` использует сторонние классы `Diff_*`), то может понадобиться принудительно указать в какой папке искать класс с заданным префиксом.
Режим разработчика
==================
Все дополнения (включая CMF_Core и CMF_Development) находятся в папке /.repos/ (путь настраиваемый).
Автоэкспорт шаблонов и фраз включен.
Добавить в config.php:
~~~php
//Включение недокументированной настройки XenForo для автоэкспорта шаблонов
$config['development']['directory'] = '.';
//Обязательное включение режима отладки
$config['debug']=true;
//Загрузка измененного автолоадера
PHP:
if (!class_exists('CMF_Development_Autoloader', false))
{
//необходим ручной include файлов
include(realpath(dirname(__FILE__) . '/..') . '/.repos/cmf_core/upload/library/CMF/Core/Autoloader.php');
include(realpath(dirname(__FILE__) . '/..') . '/.repos/cmf_development/upload/library/CMF/Development/Autoloader.php');
CMF_Development_Autoloader::getProxy()->configure(array(
//---------------------------------------
// настройки размещения дополнений
//---------------------------------------
'addon' => array(
'dir' => '.repos',
'map' => array( //список путей как для префиксов классов, так и для id дополнений
'Diff' => 'tms', //Искать классы Diff_* в папке tms (дополнение TMS)
'SomeAddon_Id' => 'some_addon' //Для дополнения с id SomeAddon_Id искать папки для автоэкспорта по пути some_addon
)
),
//---------------------------------------
// настройки автоэкспорта
//---------------------------------------
//пользовательские стили (style_id > 0)
'style' => array(
'dir' => '.repos', //путь размещения пользовательских стилей
'map' => array(
1 => 'xenforo_default_style' //цифровой_id_стиля => путь
'1-SomeAddonId' => 'someAddonId_default_style' //цифровой_id_стиля-id_дополнения => путь
)
),
//настройки фраз пользовательских языков (language_id > 0)
'language' => array(
'dir' => '.repos', //путь размещения пользовательских языков
'map' => array(
2 => 'language_russian', //цифровой_id_языка => путь
'2-XenForo' => 'xenforo_language_russian/development' //цифровой_id_языка-id_дополнения => путь
)
),
//путь для размещения всех мастер-данных (фразы и шаблоны)
'fileOutput' => 'development', //если пусто используется путь file_output (по умолчанию для XenForo)
//Создавать файлы при импорте/обновлении дополнений и XenForo (по умолчению отключено)
'createOnImport' => true,
//автоматически создавать папки
'autoCreateDirs' => true
));
}
Пример настройки locations для nginx
====================================
Пусть все аддоны нахолдятся в папке `/.repos/`
Тогда для поддержки всех вариантов соглашений в конфиг надо добавить:
~~~
Код:
location ~ ^/.repos/ {
internal;
}
location ~ ^/(js|styles)/([a-z]+)/([a-z]+)/([a-z]+)/(.+)$ {
try_files
/.repos/$2_$3_$4/upload/$1/$2/$3/$4/$5
/.repos/$2_$3_$4/_Extras/$1/$2/$3/$4/$5
/.repos/$2_$3/upload/$1/$2/$3/$4/$5
/.repos/$2_$3/_Extras/$1/$2/$3/$4/$5
/.repos/$2/upload/$1/$2/$3/$4/$5
/.repos/$2/_Extras/$1/$2/$3/$4/$5
$uri =404;
}
location ~ ^/(js|styles)/([a-z]+)/([a-z]+)/(.+)$ {
try_files
/.repos/$2_$3/upload/$1/$2/$3/$4
/.repos/$2_$3/_Extras/$1/$2/$3/$4
/.repos/$2/upload/$1/$2/$3/$4
/.repos/$2/_Extras/$1/$2/$3/$4
$uri =404;
}
location ~ ^/(js|styles)/([a-z]+)/(.+)$ {
try_files
/.repos/$2/upload/$1/$2/$3
/.repos/$2/_Extras/$1/$2/$3
$uri =404;
}