Перейти к основному содержимому

Создание модуля

Для разработки модуля, необходимо базово ознакомится со структурой каждого модуля. Каждый модуль должен иметь уникальный ключ.

примечание

Ключом модуля выступает название папки и параметр "key" в module.json

Создание модуля​

Чтобы создать базовую структуру модуля, достаточно ввести данную команду:

php flute generate:module

После выполнения данной команды будет создана базовая структура модуля со всеми необходимыми директориями.

ServiceProvider​

В каждом модуле должны быть ServiceProvider'ы. Эти классы обознают загрузку определенных компонентов в систему. Примеры возможностей ServiceProvider'ов:

  1. Подгрузка параметров маршрутизации в движок (роутов)
  2. Подгрузка переводов из модуля в движок
  3. Подгрузка кастомных пунктов в админ-панель
  4. И т.п.

Как Вы уже поняли, возможности сервис провайдеров неограничены, но служат они только для инициализации.

Пример реализации сервис провайдера модуля:

<?php

namespace Flute\Modules\Monitoring\ServiceProviders;

use Flute\Core\Support\ModuleServiceProvider;

class MonitoringServiceProvider extends ModuleServiceProvider
{
    public function boot(\DI\Container $container): void
    {
        // Подгружаем переводы модуля
        $this->loadTranslations('Monitoring');
    }

    public function register(\DI\Container $container): void
    {
    }
}

В каждом ServiceProvider'е должно быть 2 метода:

  • boot - Запускается только тогда, когда модуль активен в системе.
  • register - Запускается независимо от статуса модуля (включен / выключен)
warning

Важное примечание! ServiceProvider не будет вызываться, если модуль не установлен

Extensions​

В каждом ServiceProvider могут быть так называемые расширения (Extensions). Это дополнения к ServiceProvider'у, которые позволяют декомпозировать логику провайдера не некоторые компоненты. Пример:

  • Расширение расширения шаблонизатора
  • Расширение инициализации роутов
  • и т.п.
примечание

На самом деле, ServiceProvider'ы могут спокойно прожить и без расширений. Но расширения позволяют разбить некоторые части кода, что влечет повышение читабельности Вашего проекта.

Пример реализации расширения:

<?php

namespace Flute\Modules\Monitoring\ServiceProviders\Extensions;

use Flute\Modules\Monitoring\Widgets\ServersWidget;

class WidgetExtension implements \Flute\Core\Contracts\ModuleExtensionInterface
{
    public function register() : void
    {
        // В этом расширении, мы регистрируем новый виджет в систему
        widgets()->register(new ServersWidget());
    }
}

Каждое расширение обязано имплементировать интерфейс ModuleExtensionInterface и содержать в себе метод register()

Чтобы инициализировать наше расширение в ServiceProvider, нам нужно добавить его в массив $extensions внутри нашего ServiceProvider'а:

<?php

namespace Flute\Modules\Monitoring\ServiceProviders;

use Flute\Modules\Monitoring\ServiceProviders\Extensions\WidgetExtension;

class MonitoringServiceProvider extends ModuleServiceProvider
{
    public array $extensions = [
        WidgetExtension::class, // Мы добавляем наше расширение сюда
    ];

    /** Остальная логика */
}

Работа с БД​

Для работы модулей могут потребоваться дополнительные таблицы (или расширение уже существующих таблиц). Для этого используются сущности библиотеки Cycle ORM

Сущности​

Каждая сущность должна иметь уникальное название. Все сущности должны находится в папке databases/Entities и начинаться с заглавной буквы.

Примеры реализации сущностей можете посмотреть в app/Core/Database/Entities.

Для того, чтобы наши сущности создавали таблицы в БД, нам нужно выполнять миграции.

Миграции​

Миграция - это процесс создания или удаления таблиц из корневой БД движка.

warning

Миграции будут выполняться только в том случае, если их выполняет Installer функцией importMigrations()!

Миграцию можно создать с помощью команды:

php flute generate:migration

После ввода команды, у вас будет создан файл с миграцией в указанном модуле.

Пример файла миграции:

<?php

class add_servers extends \Spiral\Migrations\Migration
{
     /**
     * Create tables, add columns or insert data here
     */
    public function up()
    {
        $this->table('sample_table')
            ->addColumn('id', 'primary')
            ->addColumn('name', 'string')
            ->create();
    }

    /**
     * Drop created, columns and etc here
     */
    public function down()
    {
        $this->table('sample_table')->drop();
    }
}

Дабы узнать как подробно использовать миграции, можете почитать документацию библиотеки

Переводы​

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

Все переводы находятся в директории модуля i18n/. Ключом каждой папки внутри i18n выступает идентификатор перевода. К примеру i18n/ru/test.php и i18n/en/test.php.

warning

В системе, каждый перевод должен иметь уникальное название файла, т.к. название файла служит ключом перевода.

К примеру у нас есть файл перевода mon_admin.php, и чтобы вызывать фразы из этого перевода достаточно написать:

__('mon_admin.somephrase')

НО! Если мы напишем вместо mon_admin.php - admin.php, то будет ошибка. Старайтесь выбирать уникальные названия для переводов!

Система автоматически определит когда использовать нужный перевод. Вам лишь необходимо импортировать их в ServiceProvider'е.

<?php

class MonitoringServiceProvider extends ModuleServiceProvider
{
    /** Расширения и пр. */

    public function boot(\DI\Container $container): void
    {
        // Мы должны вызвать эту функцию, и все переводы автоматически инициализируются в системе.
        $this->loadTranslations();
    }

    /** Остальной код */
}

Все переводы должны быть в виде PHP массива. Пример:

i18n/ru/mon_test.php
<?php return [
    'some' => 'Какая-то фраза',
    'key' => [
        'what' => 'Что??',
        'ass' => 'Мы можем вызывать это в виде ассоциативных массивов??'
    ]
];

И чтобы вызывать эти переводы в PHP коде можно использовать функцию __():

public function someFunc() 
{
    // Каждый ключ определяется через точку.
    echo __('mon_test.key.ass');
}

Чтобы вызывать переводы в шаблонах, можно использовать @t():

<div>
    Привет @t('mon_test.some')
</div>

Далее, посмотрим пожалуй что такое виджеты.