Сниппеты в MODX: три приёма для рабочего кода

Сниппет в MODX удобно написать за несколько минут, а потом годами дописывать в него условия, HTML и запросы к базе. Такой код трудно менять и легко сломать. На примере MODX Revolution 2.8.x и 3.x разберём три рабочих приёма: передавать параметры явно, экранировать пользовательский текст и отделять логику от разметки. Синтаксис вызова и основные API-примеры подходят для обеих веток; требования к PHP и отдельные детали проверяйте для своей версии.

Сначала решите, что должен делать сниппет

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

Плейсхолдер — именованное значение, которое MODX подставляет в шаблон или чанк. Он помогает передать готовые данные в разметку, не превращая PHP-файл сниппета в HTML-шаблон.

Перед созданием запишите входы и выходы: какие параметры получает сниппет, что возвращает и кто увидит результат. Это сразу показывает, не пытаетесь ли вы уместить в одном элементе сразу выборку, бизнес-логику и оформление.

Приём 1. Передавайте параметры явно

Вызов сниппета с параметрами читается прямо в MODX-теге. Например, для блока уведомления:

[[!NoticeBlock?
  &title=`График работы`
  &text=`Заказы обрабатываем по будням.`
]]

В диспетчере элементов создайте сниппет NoticeBlock и поместите в его поле PHP-код без открывающего <?php:

$title = (string) ($scriptProperties['title'] ?? '');
$text = (string) ($scriptProperties['text'] ?? '');

$escape = static function ($value) {
    return htmlspecialchars($value, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
};

return '<aside class="notice">'
    . '<h2>' . $escape($title) . '</h2>'
    . '<p>' . $escape($text) . '</p>'
    . '</aside>';

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

Параметры сниппета доступны в массиве $scriptProperties. Явное приведение к строке и значение по умолчанию упрощают обработку пустых или отсутствующих параметров. Экранирование здесь важно: оно не даёт тексту интерпретироваться браузером как HTML. Если же вам нужно намеренно принимать HTML, не применяйте этот пример без изменений: сначала определите допустимый формат и способ очистки.

Приём 2. Отделите PHP от HTML

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

[[!NoticeBlockTpl?
  &title=`График работы`
  &text=`Заказы обрабатываем по будням.`
  &tpl=`NoticeBlockTpl`
]]

В чанке NoticeBlockTpl разместите HTML и плейсхолдеры, например [[+title]] и [[+text]]. В сниппете подготовьте значения и отдайте чанк методом MODX getChunk:

$title = (string) ($scriptProperties['title'] ?? '');
$text = (string) ($scriptProperties['text'] ?? '');

return $modx->getChunk('NoticeBlockTpl', [
    'title' => htmlspecialchars($title, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8'),
    'text' => htmlspecialchars($text, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8'),
]);

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

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

Приём 3. Выбирайте кэшируемость по смыслу

Вызов [[!NoticeBlock]] помечен как некэшируемый: MODX выполняет сниппет при обработке страницы. Вызов [[NoticeBlock]] участвует в кэшировании страницы. Это не просто переключатель скорости — режим должен соответствовать данным.

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

Сниппет должен отвечать за данные и решение, чанк — за HTML. А режим кэширования выбирают по тому, кому и когда можно показывать результат.

Что ломается на практике

• Параметр пустой. Проверьте имя после & в вызове и ключ в $scriptProperties. Регистр и написание должны совпадать.
• Вместо текста видны HTML-сущности. Скорее всего, значение экранировали дважды — в сниппете и ещё раз при выводе.
• Блок не меняется после правки. Очистите кэш MODX и проверьте, какой режим вызова стоит в странице.
• В чанке пустые плейсхолдеры. Сверьте названия ключей массива, переданного в getChunk, с именами плейсхолдеров в чанке.
• PHP выдаёт ошибку. Посмотрите журнал ошибок MODX и PHP, а также версию PHP, которую использует сайт. Не включайте показ ошибок посетителям на рабочем сайте.

Когда выбирать каждый подход

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

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

Что проверить дальше

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