Модуль Joomla: рабочие приёмы разработки и типичные ошибки

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

Сначала выберите границу модуля

Модуль подходит для самостоятельного блока, который администратор может разместить в позиции шаблона, включить или выключить и настроить через параметры. Если задача меняет содержимое страницы по маршруту или добавляет обработчик события, проверьте, не подходит ли для неё компонент или плагин. Не превращайте модуль в мини-компонент: это усложняет поддержку и установку.

Примеры ниже используют классический формат модуля с PHP-файлом входа и helper-классом. Он подходит для Joomla 4.x и 5.x; для нового проекта сверяйте требования целевой версии с документацией Joomla. Расширение устанавливается через менеджер расширений, а не копированием файлов на работающий сайт.

Соберите минимальную структуру

Для модуля с именем mod_notice подготовьте папку с такими файлами:

• mod_notice.php — точка входа;
• helper.php — получение данных;
• tmpl/default.php — разметка;
• mod_notice.xml — манифест установки.

Имена важны: Joomla ищет манифест и файлы по соглашениям расширения. В примере helper получает текст из параметров, а шаблон выводит его.

Точка входа и helper

В mod_notice.php не размещайте всю бизнес-логику. Оставьте загрузку helper и передачу данных шаблону:

<?php
defined('_JEXEC') or die;

use Joomla\CMS\Helper\ModuleHelper;

require_once __DIR__ . '/helper.php';

$text = ModNoticeHelper::getText($params);
require ModuleHelper::getLayoutPath('mod_notice', $params->get('layout', 'default'));

В helper.php определите класс с именем, связанным с модулем:

<?php
defined('_JEXEC') or die;

use Joomla\Registry\Registry;

class ModNoticeHelper
{
    public static function getText(Registry $params): string
    {
        return trim((string) $params->get('text', ''));
    }
}

В tmpl/default.php выведите значение с HTML-экранированием:

<?php
defined('_JEXEC') or die;

use Joomla\CMS\HTML\HTMLHelper;
?>
<div class="mod-notice">
    <?php echo HTMLHelper::_('string.truncate', htmlspecialchars($text, ENT_QUOTES, 'UTF-8'), 300); ?>
</div>

Здесь есть лишняя для простого блока операция усечения: если ограничение длины не нужно, уберите её и оставьте экранирование. Не выводите пользовательский текст напрямую: HTML в параметре может изменить разметку страницы.

Манифест и установка

Манифест описывает тип расширения, версию, точку входа и файлы, которые Joomla должна скопировать. Минимальный каркас выглядит так:

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" client="site" method="upgrade">
    <name>mod_notice</name>
    <version>1.0.0</version>
    <description>Notice module</description>
    <files>
        <filename module="mod_notice">mod_notice.php</filename>
        <filename>helper.php</filename>
        <folder>tmpl</folder>
    </files>
    <config>
        <fields name="params">
            <fieldset name="basic">
                <field name="text" type="text" label="Text" />
            </fieldset>
        </fields>
    </config>
</extension>

Соберите ZIP так, чтобы mod_notice.xml лежал в корне архива, а не внутри дополнительной папки. Установите его в тестовой Joomla, создайте экземпляр модуля, заполните параметр, выберите позицию шаблона и опубликуйте. Проверка установки важнее проверки локальной папки: манифест может не включить файл, который у вас на диске есть.

Где размещать логику и разметку

Есть три практических подхода. Для короткого статического блока хватит точки входа и шаблона. Если нужно получить данные или преобразовать параметры, вынесите это в helper. Если модуль растёт, использует несколько классов и должен жить в долгую, переходите на структуру с пространствами имён и сервисами, ориентируясь на актуальный образец Joomla для выбранной версии.

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

Самая дорогая ошибка модуля — не сложный PHP, а расхождение между именем расширения, манифестом и путём к шаблону. Проверяйте эти три вещи до поиска загадочной ошибки в Joomla.

Что ломается чаще всего

• Модуль не устанавливается. Проверьте, что XML-файл лежит в корне ZIP и его имя соответствует имени модуля.
• После установки блок пустой. Убедитесь, что создан и опубликован экземпляр модуля, выбраны позиция и пункты меню. Установка расширения сама по себе не размещает блок на сайте.
• Не найден файл шаблона. Проверьте, что папка tmpl включена в манифест, а имя макета совпадает с файлом.
• Параметр не читается. Сверьте имя поля в XML с ключом, который передаёте в get().
• На странице появляется PHP-ошибка. Посмотрите журнал ошибок сайта и проверьте синтаксис на версии PHP, которую поддерживает ваша Joomla. Не отключайте сообщения об ошибках на продакшене ради маскировки проблемы.

При обновлении версии Joomla проверяйте модуль на копии сайта. Особое внимание уделите устаревшим вызовам, пространствам имён и версии PHP: совместимость зависит не только от Joomla, но и от окружения хостинга.

Что делать дальше

Перед публикацией установите ZIP на чистую тестовую копию, проверьте создание экземпляра, вывод параметров и отображение на мобильном шаблоне. Затем проверьте обновление поверх предыдущей версии и удаление расширения. Если модуль хранит собственные данные или добавляет файлы вне своей папки, отдельно спроектируйте процедуру обновления и удаления.

Сноска. Манифест — XML-файл, по которому Joomla узнаёт тип расширения, его файлы и параметры установки.