Создание новых модулей для платформы TaskOn

Создание любого модуля платформы стоит начать с кодогенератора Gii.

Модули платформы должны быть расположены в директории common/modules.

После генерации получаем следующую структуру модуля:

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

Файлы конфигурации модуля названы в соответствии с ID приложением, к которому они относятся. Common - общая конфигурация для всех приложений. Файлы с постфиксом -local в названии, как и основные конфигурационные файлы приложений с таким постфиксом, считаются локальными файлами конфигурации и не попадают в гит.

Слияние конфигурационных файлов приложения платформы происходит в следующем приоритете (по убыванию):

1. Локальная конфигурация приложения.
2. Конфигурация приложения.
3. Локальная конфигурация common.
4. Конфигурация common.
5. Локальная конфигурация приложения активных модулей.
6. Конфигурация приложения активных модулей.
7. Локальная конфигурация активных модулей common.
8. Конфигурация активных модулей common.

Т.е в случае слияния разных значений в одинаковых ключах массива конфигурации низкий приоритет заменится более высоким.

Помимо конфигураций приложений в папке config содержится файл, необходимый для инструмента управления зависимостями в PHP, Composer - composer.json. Он в свою очередь сливается с основным файлом composer.json, находящимся в корне проекта, в момент обновления или установки зависимостей PHP через инструмент Composer.

Данная механика позволяет не терять регистрацию зависимостей при подключении модуля платформы в уже развернутом проекте, атакже не устанавливать те зависимости, которые необходимы только для определенного модуля, а не для всей платформы в целом. Например, модулю Import для корректной работы необходимо расширение phpoffice/phpexcel, которое используется только внутри самого модуля.

Зависимости модулей

Помимо зависимостей в PHP у модулей могут появиться зависимости в других модулях платформы. Например, модуль “Контент” разработан таким образом, что не может корректно работать без модуля “Языки”. Для того, чтобы перед подключением модуля осуществлялось подключение всех его зависимых модулей, необходимо реализовать метод getDependencies в главном классе модуля:

/**
 * @inheritdoc
 */
public function getDependencies()
{
    return ['language', 'rbac'];
}

Метод должен возвращать массив ID модулей, от которых зависит текущий модуль.

Подключения модулей

Для добавления нового модуля в проект необходимо:

1. Скопировать папку самого модуля и модулей от которых он зависит в директорию common/modules.
2. Зайти в раздел Система -> Модули (/main/module/manage) и нажать на “+”, чтобы подключить добавленный модуль:
   

В момент включения модуля через Панель управления происходит применение его миграций. А вот в момент отключения откат миграций модуля не происходит. Это сделано с целью сохранения данных в БД в случае случайного отключения модуля.

Если надо удалить данные, добавленные через модуль, то для этого рекомендуется создать отдельную миграцию для очистки (в папке migrations).

Меню в панели управления

Для того, чтобы вывести какие-либо ссылки в меню панели управления, необходимо реализовать метод menu() главного класса модуля. Метод должен вернуть массив, который будет обработан виджетом backend\widgets\Menu. Данный виджет является наследником класса yii\widgets\Menu, и для того, чтобы разобраться со структурой массива, необходимо ознакомиться с атрибутом items этого класса.

Помимо основных параметров, которые можно использовать в массиве items класса yii\widgets\Menu, в массиве items класса backend\widgets\Menu присутствуют дополнительные, которые можно применить к элементам:

• icon - css класс иконки;
• order - вес элемента меню для сортировки. Сортировка работает только для элементов верхнего уровня;
• urlActive - массив роутов, на которых данный пункт будет считаться активным помимо основного роута, указанного в параметре url.

/**
 * @return array
 * @link http://www.yiiframework.com/doc-2.0/yii-widgets-menu.html
 */
public function menu()
{
    return [
        [
            'label' => static::t('module_users'),
            'url' => 'javascript:;',
            'items' => [
                [
                    'label' => static::t('user_list'),
                    'url' => ['/users/user/manage'],
                    'urlActive' => [
                        ['/users/user/create'],
                        ['/users/user/update'],
                        ['/users/user/view']
                    ],
                ],
                [
                    'label' => static::t('login_history_manage_title'),
                    'url' => ['/users/login-history/manage']
                ],
                [
                    'label' => Yii::t('app', 'settings'),
                    'url' => ['/users/settings/index'],
                    'urlActive' => [
                        ['/users/typical-password/manage'],
                        ['/users/typical-password/create'],
                        ['/users/typical-password/update'],
                    ],
                ],
            ],
            'icon' => 'fa fa-users',
            'order' => 5
        ],
    ];
}

Пример меню модуля “Пользователи”

Миграции модуля

Миграции модулей платформы должны располагаться в директории migrations самих модулей. Данная директория включена в список директорий, которые используются для применения миграций в момент вызова консольной команды php yii migrate или при включении модуля через панель управления.

Это означает, что нет необходимости указывать --migrationPath в момент вызова команды php yii migrate для того, чтобы применить новые миграции из модулей. Но если все же необходимо применить или откатить миграции только из конкретной директории, необходимо помимо --migrationPath (указывается в виде алиаса с @, например, @common/modules/users/migrations) указать параметр --disableLookup=true.

Важно! Для того, чтобы иметь возможность отключить и удалить какой-либо модуль из проекта, необходимо всегда и во всех миграциях реализовывать метод down() или safeDown(). То есть миграции модулей не должны быть необратимыми.