Первый модуль

Модуль — блок, который администратор размещает в позиции шаблона. Начнём с самого простого: модуль mod_hello выводит одну строку с приветствием. На нём видно, из каких файлов состоит любое расширение Joomla 4 и 5.

Файлы модуля

Создайте в папке modules сайта папку mod_hello и в ней четыре файла:

modules/mod_hello/
├── mod_hello.xml                    манифест
├── services/
│   └── provider.php                 подключение модуля к Joomla
├── src/
│   └── Dispatcher/
│       └── Dispatcher.php           готовит данные
└── tmpl/
    └── default.php                  макет: разметка HTML

Команды для создания файлов в Joomla нет — папки и файлы создают вручную.

Манифест

Файл mod_hello.xml — тот самый, что разобран в прошлом уроке. Важны две его строки:

<namespace path="src">My\Module\Hello</namespace>
 
<files>
    <folder module="mod_hello">services</folder>
    <folder>src</folder>
    <folder>tmpl</folder>
</files>

Первая задаёт пространство имён классов, вторая перечисляет папки модуля.

Провайдер сервисов

Провайдер — файл, с которого Joomla начинает работу с расширением. Он сообщает, где искать классы модуля:

// modules/mod_hello/services/provider.php
defined('_JEXEC') or die;
 
use Joomla\CMS\Extension\Service\Provider\HelperFactory;
use Joomla\CMS\Extension\Service\Provider\Module;
use Joomla\CMS\Extension\Service\Provider\ModuleDispatcherFactory;
use Joomla\DI\Container;
use Joomla\DI\ServiceProviderInterface;
 
return new class () implements ServiceProviderInterface {
    public function register(Container $container): void
    {
        $container->registerServiceProvider(new ModuleDispatcherFactory('\\My\\Module\\Hello'));
        $container->registerServiceProvider(new HelperFactory('\\My\\Module\\Hello\\Site\\Helper'));
        $container->registerServiceProvider(new Module());
    }
};

Файл почти одинаков у всех модулей — меняется только пространство имён. Строка с HelperFactory понадобится в следующем уроке.

Диспетчер

Диспетчер — класс, который готовит данные для макета:

// modules/mod_hello/src/Dispatcher/Dispatcher.php
namespace My\Module\Hello\Site\Dispatcher;
 
defined('_JEXEC') or die;
 
use Joomla\CMS\Dispatcher\AbstractModuleDispatcher;
 
class Dispatcher extends AbstractModuleDispatcher
{
    protected function getLayoutData(): array
    {
        $data = parent::getLayoutData();
 
        $data['greeting'] = 'Привет!';
 
        return $data;
    }
}

Метод getLayoutData() возвращает массив. К пространству имён из манифеста Joomla сама добавляет слово Site — потому что модуль предназначен для сайта.

Макет

<?php
// modules/mod_hello/tmpl/default.php
 
defined('_JEXEC') or die;
?>
<p class="mod-hello"><?php echo htmlspecialchars($greeting, ENT_QUOTES, 'UTF-8'); ?></p>

Каждый ключ массива из диспетчера становится в макете переменной: $data['greeting'] превратился в $greeting.

Строка defined('_JEXEC')

Константа _JEXEC объявлена только при запуске через Joomla. Если открыть файл напрямую по адресу, он сразу остановится. Эту строку ставят в начале каждого файла PHP расширения.

Установка и результат

1. «Система → Установка → Поиск» → «Найти» → отметьте mod_hello → «Установить».
2. «Содержимое → Модули сайта → Создать» → выберите mod_hello.
3. Задайте заголовок «Приветствие», позицию sidebar-right, состояние «Опубликовано».
4. На вкладке «Привязка к меню» выберите «На всех страницах» и сохраните.

Откройте сайт: в правой колонке появился блок «Приветствие» со строкой «Привет!».

Частая ошибка

Пространство имён должно совпадать в трёх местах: в теге namespace манифеста, в провайдере и в самом классе. При опечатке модуль не выводится или показывает ошибку «класс не найден». Сверьте три строки и помните: на сервере с Linux регистр букв в именах папок src/Dispatcher важен.