Сниппет в MODX: сравниваем варианты и выбираем

В MODX Revolution сниппет можно хранить прямо в менеджере или вынести в отдельный PHP-файл. Первый вариант быстрее настроить, второй удобнее поддерживать вместе с кодом сайта. Ниже — два рабочих подхода для MODX 2.x и 3.x: сделаем сниппет, который принимает имя и выводит приветствие, сравним их цену и разберём типичные ошибки.

Сначала определите, что именно будет делать сниппет

Сниппет — небольшой PHP-код, который MODX запускает при обработке страницы. Он подходит для динамического вывода или логики, которую нельзя выразить одним чанком. Если нужно только повторно использовать кусок HTML, обычно достаточно чанка: PHP в сниппете добавляет возможности, но заодно требует аккуратной работы с вводом и правами.

Пример ниже рассчитан на MODX Revolution 2.x и 3.x. В нём нет обращения к базе данных и сторонних библиотек. Перед правкой на рабочем сайте сделайте резервную копию элемента или файла.

Вариант 1: код прямо в менеджере MODX

Создайте элемент типа «Сниппет» в разделе «Элементы» менеджера и назовите его Hello. В поле кода вставьте:

<?php
$name = trim((string) ($name ?? ''));

if ($name === '') {
    $name = 'гость';
}

return 'Здравствуйте, ' . htmlspecialchars(
    $name,
    ENT_QUOTES | ENT_SUBSTITUTE,
    'UTF-8'
) . '!';

Сохраните элемент. Вызовите его в содержимом ресурса так:

[[!Hello? &name=`Анна`]]

Откройте ресурс на сайте: в результате должно появиться «Здравствуйте, Анна!». Вызов с восклицательным знаком выполняется некэшируемым — это важно, если результат зависит от переданного значения или текущего состояния страницы.

Сниппет должен вернуть строку через return. Если только вывести её через echo, можно получить неожиданное поведение при обработке страницы. htmlspecialchars экранирует значение перед вставкой в HTML: без него ввод вроде HTML-тега может стать частью разметки.

Вариант 2: статический сниппет в файле

Когда код нужно хранить в Git и редактировать в привычном редакторе, вынесите его в файл. В MODX создайте сниппет и включите для элемента режим статического файла, затем укажите путь к PHP-файлу согласно настройкам вашего сайта. Сам файл должен содержать тот же код, что и в первом варианте. Точный путь зависит от структуры проекта и настроек источника файлов, поэтому не подставляйте путь из чужой инструкции вслепую.

Вызов на странице остаётся прежним: [[!Hello? &name=`Анна`]]. После изменения файла проверьте, что MODX читает именно его, а не сохранённый в элементе прежний код. На тестовом ресурсе должно появиться то же приветствие.

Выбирайте не «самый правильный» способ, а тот, у которого в вашей команде есть один понятный источник истины: менеджер MODX или репозиторий проекта.

Как выбрать подход

Оставьте код в менеджере, если он маленький

Для короткого сниппета, который меняет один администратор сайта и не проходит отдельный процесс релиза, менеджер обычно проще. Не нужно выяснять, как устроен доступ к файлам на хостинге. Цена простоты — изменения не попадут в Git автоматически. Зафиксируйте их в принятом в проекте процессе переноса, иначе тестовый и рабочий сайты со временем разойдутся.

Выносите код в файл, если он часть разработки

Файл выигрывает, если сниппет регулярно меняется, его ревьюят и разворачивают вместе с остальным кодом. Это не отменяет настройку элемента MODX: статический файл должен быть связан со сниппетом, а путь — доступен системе. Цена подхода — дополнительная настройка и риск редактировать не ту копию.

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

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

• На странице виден текст «Здравствуйте, гость!». Параметр не передан, его имя отличается от переменной в коде или вызов изменён. Сверьте name в вызове и $name в сниппете.
• Вместо результата пусто. Проверьте, сохранён ли элемент, правильно ли набран его вызов и нет ли PHP-ошибки. Посмотрите журнал ошибок MODX и PHP на сервере; не показывайте посетителям подробности ошибок.
• Файл не обновился после правки. Убедитесь, что редактируете файл, связанный со сниппетом, и очистите кэш сайта после изменения. Для проверки используйте тестовую страницу и затем повторно загрузите её.
• В ответе появляется исходный PHP-код или ошибка разбора. Проверьте, что код сохранён в элементе типа «Сниппет», а не в чанке, и что файл содержит корректный PHP-синтаксис.
• В выводе видны символы вместо русских букв. Сохраните файл в UTF-8 и проверьте, что в коде используется та же кодировка при экранировании.

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

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

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