WebP в MODX Revolution 2.8: загрузка, превью и изображения в TV

Файл WebP открывается на сайте, но не отображается в файловом менеджере MODX? Или его можно указать в TV-поле изображения, но вместо миниатюры показывается пустое место? Для MODX Revolution 2.8 это не обязательно означает отсутствие поддержки формата.

В версии 2.8.0 формат WebP появился в стандартных списках загружаемых файлов и изображений. Но загрузка, отображение превью в менеджере и генерация уменьшенных изображений — разные операции, которые зависят от разных настроек и библиотек. Это подтверждается документацией MODX 2.8.

Мы столкнулись с похожей ситуацией при работе над блогом SAIT-MODX.BY: WebP-файл размером 46 КБ присутствовал на сервере и распознавался как image/webp, но в административном интерфейсе было неудобно работать с его превью. Ниже — безопасный порядок диагностики перед установкой каких-либо дополнительных компонентов.

Почему WebP может работать на сайте, но не отображаться в MODX

Важно различать четыре этапа:

1. Загрузка: MODX разрешает сохранить файл с расширением .webp.
2. Файловый менеджер: медиаисточник распознаёт файл как изображение и пытается сформировать миниатюру.
3. TV с типом «Изображение»: ресурс использует выбранный медиаисточник и выводит превью.
4. Фронтенд: браузер посетителя открывает исходный WebP или обработанную версию изображения.

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

Шаг 1. Проверьте, разрешён ли WebP для загрузки

В менеджере MODX откройте Система → Системные настройки и найдите параметр upload_files («Разрешённые к загрузке файлы»). В пользовательском списке расширений должен присутствовать webp.

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

Пример фрагмента списка:

jpg,jpeg,png,gif,webp,svg

Это лишь пример расширений, а не рекомендация заменить им весь текущий параметр upload_files. Описание параметра upload_files.

Шаг 2. Настройте imageExtensions в источнике файлов

Это одна из наиболее частых причин отсутствия WebP-превью. Откройте в менеджере Медиа → Источники файлов, выберите тот источник, который реально используется для загрузки картинок, и откройте его настройки.

Проверьте три свойства:

• imageExtensions — перечисляет расширения, для которых источник создаёт миниатюры. Убедитесь, что среди них есть webp.
• allowedFileTypes — если заполнено, ограничивает разрешённые типы файлов; добавьте webp в существующий список, если его там нет.
• thumbnailType — определяет выходной формат миниатюры. Обычно можно оставить png.

Пример imageExtensions:

jpg,jpeg,png,gif,webp

Сохраните источник файлов, очистите кеш MODX и заново откройте файловый менеджер. Параметры basePath и baseUrl при этом без необходимости не меняйте.

Свойства источников описаны в документации MODX по File System Media Source. В обсуждении сообщества добавление webp в imageExtensions помогло восстановить превью одному из пользователей.

Шаг 3. Проверьте поддержку WebP в PHP GD

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

В MODX Console можно выполнить безопасную диагностику только на чтение. Вставьте следующий PHP-код без открывающего тега <?php:

$gd = function_exists('gd_info') ? gd_info() : array();
echo 'PHP: ' . PHP_VERSION . "\n";
echo 'GD: ' . (extension_loaded('gd') ? 'YES' : 'NO') . "\n";
echo 'GD WebP Support: ' . (!empty($gd['WebP Support']) ? 'YES' : 'NO') . "\n";
echo 'imagecreatefromwebp(): ' . (function_exists('imagecreatefromwebp') ? 'YES' : 'NO') . "\n";

Если GD WebP Support: NO, сначала нужно изменить конфигурацию PHP у хостинг-провайдера или в панели управления сервером. Простое добавление расширения в MODX не добавит в GD недостающий кодек.

Наличие функции imagecreatefromwebp() и WebP Support — необходимые диагностические признаки, но реальную генерацию миниатюры стоит проверять на конкретном файле. Описание imagecreatefromwebp в PHP.

Шаг 4. Если GD поддерживает WebP, проверьте phpThumb

Миниатюры в менеджере MODX создаются не самим браузером: в цепочке участвует библиотека phpThumb. Поэтому возможна ситуация, когда исходное изображение в браузере открывается, а превью в менеджере отсутствует.

Сначала проверьте core/cache/logs/error.log. Полезно искать сообщения, связанные с phpthumb, OutputThumbnail() и ошибками обработки изображений.

Особый случай: MODX Revolution 2.8.6 и PHP 7.4. В сообществе MODX задокументирована несовместимость одной из версий phpThumb с PHP 7.4 из-за использования типа mixed. Симптомом может быть отсутствие миниатюр в менеджере, в том числе для обычных изображений. Не стоит автоматически применять чужой патч к любой версии MODX: сначала проверьте точную версию CMS, журнал ошибок и имеющиеся обновления. Описание проблемы в MODX Community.

PHP 7.4 больше не получает обычные обновления безопасности от разработчиков PHP. При планировании обновления версии PHP сначала проверяйте совместимость установленных дополнений и собственного кода сайта.

Шаг 5. Проверьте источник изображений у TV

Если WebP виден в дереве файлов, но не отображается при выборе изображения в ресурсе, проверьте конкретную TV-переменную. Например, в нашем блоге за изображение карточки отвечает TV mikro_img.

Откройте настройки TV, найдите вкладку назначения источников файлов и убедитесь, что нужному контексту назначен именно тот Media Source, в котором вы включили webp. У разных TV могут быть разные источники. Документация: назначение источников для TV.

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

Чего не стоит делать при ошибках WebP

• Не переименовывайте файл photo.webp в photo.png без настоящего преобразования формата.
• Не редактируйте ядро MODX без резервной копии и установленной причины ошибки.
• Не отключайте проверки типов загружаемых файлов ради одного формата.
• Не считайте, что отсутствие картинки в TV означает потерю оригинала.
• Не обновляйте PHP или MODX на рабочем сайте без проверки расширений и дополнений.

Краткий чек-лист по WebP для MODX 2.8

1. Убедитесь, что WebP открывается по прямому URL и действительно имеет формат image/webp.
2. Проверьте upload_files и собственные ограничения загрузки.
3. Добавьте webp в imageExtensions нужного медиаисточника.
4. Убедитесь, что WebP не запрещён в allowedFileTypes, если список заполнен.
5. Проверьте GD WebP Support и imagecreatefromwebp() на сервере.
6. Проверьте источники файлов, назначенные TV, и сообщения phpThumb в логе.
7. Очистите кеш и повторите тест в файловом менеджере.

Вывод: в MODX Revolution 2.8 базовая поддержка WebP уже предусмотрена. Если формат не виден в админке, стоит начать с Media Source и GD, а не сразу устанавливать плагин. Если миниатюры отсутствуют даже для PNG и JPEG, отдельно проверьте phpThumb и совместимость версий.