Плагины в Joomla 5: как делать правильно

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

Сначала определите, что именно должен делать плагин

Плагин подходит для реакции на событие Joomla: подготовить материал, проверить данные перед сохранением, изменить HTML перед выводом или выполнить действие после авторизации. Это не универсальное место для каталога товаров, нескольких страниц админки и всей бизнес-логики сайта.

Перед разработкой сформулируйте задачу одним предложением: «при событии X проверить условие Y и выполнить действие Z». Если в формулировке нет события, возможно, вам нужен другой тип расширения:

• Плагин — подключается к событиям и меняет поведение уже работающей CMS.
• Компонент — отдельная функциональная часть сайта с собственными страницами и маршрутизацией.
• Модуль — блок, который выводится в позиции шаблона.
• Шаблон — отвечает за внешний вид и структуру вывода.

Например, автоматическая подстановка метки в текст материала может быть задачей content-плагина. Личный кабинет с заказами — уже не плагин, даже если его удобно начать с перехвата одного события.

Хороший плагин делает одну вещь в определённый момент. Чем больше событий и скрытых побочных действий он объединяет, тем дороже его обновлять и отлаживать.

Выберите группу и событие

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

Не выбирайте событие по названию, которое звучит похоже. Проверьте в документации Joomla 5.x, когда оно вызывается, какие аргументы получает и что разрешено возвращать. Важны как минимум четыре свойства:

• вызывается ли событие на сайте, в админке или в обоих местах;
• происходит ли оно один раз за запрос или для каждого элемента;
• можно ли менять переданный объект или результат;
• что произойдёт, если обработчик вернёт пустое значение, строку или исключение.

Событие жизненного цикла¹ — это точка, в которой Joomla передаёт управление плагинам: например, перед сохранением материала или при подготовке его содержимого. Один и тот же код в событии «до сохранения» и в событии «после сохранения» может дать разные результаты, потому что данные и транзакция находятся на разных этапах.

Организуйте плагин как расширение Joomla 5.x

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

• манифест XML — имя расширения, группа, версия, файлы и настройки;
• папка services — точка подключения расширения к контейнеру Joomla, если её требует выбранная структура;
• папка src — класс плагина и вспомогательные классы;
• папка языка — переводы названий параметров и сообщений;
• папка медиаресурсов — только если плагину действительно нужны JavaScript, CSS или изображения.

Класс плагина должен отвечать за связывание события с приложением, проверку контекста и вызов отдельной логики. Запросы к базе, форматирование больших ответов и работу с внешним API лучше вынести в сервисы. Так обработчик остаётся коротким, а код можно тестировать без запуска всей страницы Joomla.

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

Параметры и хранение данных

Настройки, которые должен менять администратор, объявляйте в XML-манифесте через поля Joomla. Это касается переключателей, текстовых значений, списков и идентификаторов категорий. Не зашивайте URL сервиса, лимит запросов или идентификатор категории прямо в PHP.

Разделяйте три типа данных:

• настройка — значение, которое задаёт администратор и которое можно получить из параметров плагина;
• состояние — данные, которые меняются во время работы, например время последней синхронизации;
• секрет — ключ внешнего API или пароль.

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

Сравните подходы к размещению логики

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

Защитите обработчик от лишней работы

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

Особенно опасны циклы с запросом на каждой итерации. Если событие вызывается для списка из 50 материалов, пять дополнительных запросов на один материал превращаются в 250 запросов за один просмотр страницы. Загружайте данные пакетно, используйте ограничение по времени и не вызывайте синхронный внешний API из публичного запроса без жёсткого тайм-аута.

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

Проверьте безопасность и совместимость

Входные данные из формы, URL, заголовков и пользовательского контента считайте недоверенными. Используйте штатную валидацию и фильтрацию Joomla, проверяйте права доступа перед административными действиями, а вывод экранируйте в соответствии с контекстом: HTML, атрибут, URL или JavaScript требуют разных правил.

Для запросов, изменяющих состояние, учитывайте CSRF-защиту Joomla. Для SQL используйте API базы данных и параметры запроса, а не склейку строк из пользовательского ввода. Тексты и названия полей отдавайте через языковые константы, чтобы администратор мог переключить язык без изменения PHP.

Проверяйте совместимость с Joomla 5.x и PHP-версией, которую поддерживает ваш проект. Если плагин рассчитан также на Joomla 4.4, явно зафиксируйте это в документации и прогоните тесты на обеих ветках: одинаковое имя события не гарантирует одинаковое поведение всех связанных API.

Что проверить перед установкой на рабочий сайт

1. Установить на копию сайта. Проверьте установку, включение, выключение и удаление. После удаления не должны оставаться таблицы, файлы и настройки, если они не принадлежат другому расширению.
2. Проверить оба приложения. Откройте сайт и панель администратора. Убедитесь, что плагин не выполняется в неподходящем контексте и не ломает сохранение материала.
3. Проверить пустые и ошибочные данные. Протестируйте отсутствие обязательного поля, неверный идентификатор, недоступный внешний сервис и ответ с задержкой.
4. Проверить права. Запустите сценарий обычным пользователем, администратором и пользователем без нужного разрешения.
5. Проверить логи. Убедитесь, что ошибка содержит событие и идентификатор операции, но не содержит пароль, токен и полный пользовательский ввод.
6. Проверить обновление. Установите новую версию поверх старой на копии и убедитесь, что настройки и данные не теряются.

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

Плагин работает на каждой странице

Обычно причина — отсутствие проверки приложения или контекста. Добавьте ранний выход и измерьте число вызовов обработчика. Если один просмотр страницы вызывает тяжёлую ветку десятки раз, ищите событие с более узкой областью применения.

После обновления обработчик не вызывается

Проверьте манифест, группу, класс расширения, пространство имён и регистрацию событий. Сначала сравните структуру с документацией Joomla 5.x, а не копируйте старый пример для Joomla 3.

В админке появляется белая страница

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

Изменённый HTML исчезает

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

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

Соберите минимальный плагин для одного события на копии Joomla 5.x и добавьте к нему журнал вызовов, проверку контекста и тест удаления. Затем измерьте время страницы до и после включения расширения на типичных материалах. В рабочем проекте следите за количеством вызовов обработчика, временем SQL-запросов, ошибками внешних сервисов и тем, что происходит после обновления Joomla.

¹ Событие жизненного цикла — заранее определённая точка работы CMS, в которой расширения могут выполнить свой обработчик или изменить передаваемые данные.