Безболезненное расширение функционала — достаточно проблематичный вопрос (под «безболезненностью» я понимаю весь спектр удобства для пользователей движка).

Я думаю, вы еще не забыли, что для добавления новых возможностей в версиях до 0.3.1 включительно используются Хаки и Модули. При этом установка любого стороннего творения дело достаточно хитрое и небезопасное, часто требующее ориентирования в архитектуре и особенностях движка. Для преодоления этих проблем в ядро v.0.4 была введена система плагинов:


К чему мы стремились создавая систему плагинов?

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

0. Что такое плагин?

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

В дистрибутиве LS на SVN сейчас имеет один плагин — Profiler. Он достаточно прост, и не демонстрирует всех возможностей системы плагинов, зато вполне рабочий =) Profiler — это визуальная оболочка для просмотров данных профилирования работы движка.

1. Как пользоваться плагинами?

Для начала нужный вам плагин нужно залить целой директорией (!) в папку /plugins/.

Если вы правильно это сделали то на страничке /admin/plugins/ (доступна только администраторам) этот плагин появиться в списке доступных. Формат этого списка приведен на скриншоте (у меня три плагина, только потому что я их сделал для написания статьи, если скачаете версию с SVN — там будет только один).

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

Здесь же в списке вы можете активировать\деактивировать плагин. Если выражаться простым языком — то активируя плагин, вы «включаете» его функционал в общую схему работы движка. Деактивируете = «выключаете». На крайний случай есть возможность удалить не нужный плагин. Внимание! При удалении плагин будет физически удален с сервера, поэтому используйте эту возможность только в крайних случаях =)

Если активация плагина прошла успешно, то система покажет сообщение «Выполнено успешно». В случае ошибки — предупреждение о системной ошибки (или описание ошибки, предусмотренное разработчиком плагина). Также вы можете получить подобное сообщение:


Это означает именно то, что там и написано =) Плагин «Conflict», который я попытался активировать, потребовал от системы изменения шаблона index.tpl (точнее замены его другим), на что система ответила — шаблон уже заменен другим активированным плагином «Test». Такую ситуацию мы назваем «конфликтом плагинов». Для ее решения вам нужно отказаться от одного из конфликтующих плагинов. Конфликтовать плагины могут не только за шаблоны, но и за модули, сущности и экшены.

2. (For developers) Как устроены плагины внутри?

Теперь более подробно основная информация для разработчиков расширений. Итак, мы с вами рассмотрим:

— структура директорий;
— добавление новых элементов функционала;
— сущность делегирования функционала, массив делегатов плагина;
— функции Activate(), Deactivate(), обертка для выполнения операций с базой данных;
— функция инициализации.

Файловая структура плагина во многом повторяет структуру директорий движка. В чем можно убедиться посмотрев на директории плагина Profiler:

В плагине не обязательно должны быть представлены все указанные директории, вы вообще можете планировать сруктуру каталогов как вам удобно. Но есть обязательные требования и некоторые соглашения. Объясню их на примере того же Profiler.

а) Директория плагина должна иметь название вашего плагина в lowercase («profiler»);

б) В корне плагина должен находиться основной функциональный файл, имеющий в названии префикс Plugin и суффикс .class.php: PluginProfiler.class.php. В этом файле должен быть определен класс плагина, имеющий такое же название как и файл (PluginProfiler) и являющийся наследником класса Plugin. Подробнее о содержимом класса плагина мы поговорим ниже;

в) Также в корне должен лежать readme.txt, оформленный по следующему примеру:

Name: Livestreet Profiler Plugin
Author: LiveStreet Developers Team
Homepage: http://livestreet.ru/
Version:  1.0.0
Requires: 0.4.0
Description: Профилирование работы движка LiveStreet-движка.

Я думаю, смысл каждой стоки понятен без пояснений.

г) Конфигурационные файлы нужно хранить в директории /config — при этом они будут автоматически добавляться в основную конфигурацию, с префиксом ключа «plugin.название_вашего_плагина.ключ_конфигурации». Если вам нужно переопределить какое-либо значение существующего в конфигурации ключа либо создать новый ключ в произвольном сегмене, необходимо использовать конструкцию Config::Set(). Пример из плагина Profiler:

$config['per_page']   = 15;  // Число profiler-отчетов на одну страницу

Config::Set('db.table.profiler', '___db.table.prefix___profiler');
Config::Set('router.page.profiler', 'PluginProfiler_ActionProfiler');

return $config;

Как видно из кода, с помощью Config::Set() плагин добавляет новую таблицу базы данных в список таблиц и новое правило роутинга (для нового экшена).

д) Автоматически будут подключены PHP-файлы из директории /include, загружены языковые файлы из /templates/language/, инициализированы хуки из /classes/hooks/;

е) Структура каталогов actions, modules и entity такая же как у движка. Отличие заключается в том, что эти классы в названии должны иметь приставку PluginНазвание. Например, PluginProfiler_ActionProfiler (action`ы должны быть наследниками класса ActionPlugin). Соответственно, вызов функции модуля плагина аналогичны вызову функции модуля движка:

$aResult=$this->PluginProfiler_Profiler_GetReportsByFilter($aFilter,$iPage,Config::Get('plugin.profiler.per_page'));

(вызов функции GetReportsByFilter() модуля Profiler плагина Profiler).

е) templates размещаются аналогично в директории skin, при этом в папке default должны размещаться шаблоны, которые будут использованы плагином в том случае, если текущий skin сайта в плагине не предусмотрен. Для получения пути до корректной директории скина в плагине можно использовать конструкцию

$this->getTemplatePathPlugin()

Теперь о делегировании. Делегирование — это возможность указать системе необходимость использовать вместо одного объекта другой. Сейчас поддерживается четыре типа делегатов: action, module, entity, template. Для делегирования используется функция Delegate модуля Plugin.

Типичные примеры использования:

// Использовать вместо шаблона index.tpl шаблон my_plugin_index.tpl 
$this->Plugin_Delegate('template','index.tpl','my_plugin_index.tpl');
// Использовать вместо модуля User модуль PluginTest_User
// При этом любой вызов $this->User_* будет перенаправлен на $this->PluginTest_User_*
$this->Plugin_Delegate('module','User','PluginTest_User');

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

/**
 * Указанные в массивы делегаты будут переданы движку автоматически 
 * перед инициализацией плагина
 */
protected $aDelegates=array(
	'template'=>array('index.tpl'=>'my_plugin_index.tpl'),
	'action'  =>array('ActionProfile'=>'PluginTest_ActionProfile')
);

«Стратегическими» функциями в классе вашего плагина являются функции:

Activate() — процедуры выполняемые в момент активации плагина. Например, создание таблиц в базе данных, создание нужных каталогов, проверка возможности работы плагина в текущей конфигурации или на данном сервере… Да мало ли, что еще может пригодиться =) Если функция вернет false, то система будет считать, что активация не пройдена, и не занесет плагин в список активированных.

Исходя из того, что наиболее часто выполняемыми операциями активации является выполнение SQL запросов, мы упростили эту процедуру разработчикам плагинов. Для выполнения нужных запросов в БД, вам достаточно сложить их в один файл, а в функции активации вызвать:

$this->ExportSQL(dirname(__FILE__).'/sql.sql');

(пример из плагина Profiler).

Deactivate() — вызывается при деактивации плагина. Тут я думаю все понятно.

Init() — функция инициализации плагина. Думаю к таковым вы уже привыкли =) (инициализацию поддерживают как action`ы, так и module`и).

3. На завершение...

Хотелось показать на конкретном примере, как реализовывать хаки в виде плагинов, но из-за ограничения в размере статьи приходится отложить это на следующую публикацию. В этом есть и положительный момент — вы можете в комментариях указать на тот хак, на примере которого я составлю следующую заметку! Так что, you are welcome.

Как обычно — тестирования, баг-репорты и пожелания приветствуются!