Thumb3x

• Thumb3x - Документация

Thumb3x - Документация

Thumb3x: Современная обработка изображений для MODX 3

Этот компонент был написан, чтобы заполнить пробел в экосистеме MODX 3, где практически отсутствуют современные и надежные инструменты для работы с изображениями. Большинство существующих решений не обновлялись более 10 лет и не используют преимущества новой версии системы.

Ключевые возможности

• Современные форматы: Конвертация в WebP и AVIF "на лету".

• Продвинутый движок: В основе лежит высокопроизводительная библиотека Glide 3.2.

• Интеграция с MODX 3: Полная поддержка "Источников файлов".

• Гибкая обработка: Фильтры, эффекты, водяные знаки и точное позиционирование.

• Поддержка Fenom: Удобный вызов сниппета с передачей параметров в виде массивов.

• Управление кэшем: Ведение лога сгенерированных файлов в базе данных с удобной таблицей в админке.

Стандартный вызов MODX

<img src="[[!Thumb3x? &input=`path/to/image.jpg` &options=`w=300&h=200`]]" alt="">

Вызов через Fenom

{'!Thumb3x' | snippet : [
    'input' => 'path/to/image.jpg',
    'options' => [
        'w' => 300,
        'h' => 200
    ]
]}

Основные параметры сниппета

warning Важно: Любые параметры (q, fm и т.д.), указанные внутри строки &options, всегда имеют наивысший приоритет.

Справочник по параметрам обработки (&options)

Официальная документация Glide

Компонент Thumb3x использует библиотеку Glide для всех операций с изображениями. Это означает, что вы можете использовать любые параметры, которые поддерживает сама библиотека.

Самую полную и актуальную информацию по всем возможным параметрам вы всегда можете найти на официальном сайте: https://glide.thephpleague.com/

Размеры и ориентация

Коррекция и эффекты

Фон и рамка

Водяные знаки

Выходной формат

Развернутые примеры вызова

Пример 1: Наложение водяного знака (стандартный вызов MODX)

Задача: Наложить logo.png в правый нижний угол с отступом и полупрозрачностью.

<img src="[[!Thumb3x?
    &input=`portfolio/image-01.jpg`
    &watermark=`assets/watermark/logo.png`
    &options=`w=1200&mark=logo.png&markpos=bottom-right&markpad=30&markalpha=50`
]]" alt="Портфолио с водяным знаком">

Пример 2: Вызов через Fenom

Задача: Сделать то же самое, используя более читаемый синтаксис Fenom с передачей параметров в виде массива.

{* Определяем параметры для Glide в виде массива *}
{var $params = [
    'w' => 1200,
    'h' => 800,
    'mark' => 'logo.png',
    'markpos' => 'bottom-right',
    'markpad' => 20,
    'markalpha' => 60
]}

{* Вызываем сниппет *}
<img src="{'!Thumb3x' | snippet : [
    'input' => 'portfolio/image-01.jpg',
    'watermark' => 'assets/images/logo.png',
    'options' => $params
]}" alt="Изображение с водяным знаком">

Пояснение: Главное преимущество Fenom здесь — возможность собрать все параметры обработки в аккуратный массив $params, что делает код шаблона намного чище и удобнее для чтения и редактирования.

Схема путей в кэше

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

Исходник:  images/products/253/001.jpg
В кэше:    /assets/components/thumb3x/cache/images/products/253/001.jpg/572c844a39ecf673.webp

Если вы накладываете водяной знак, по такому адресу посетитель легко восстановит путь к оригиналу без знака. Начиная с версии 3.1.0 схему именования можно изменить системной настройкой thumb3x.cache_path_mode.

Значение	Адрес в кэше	Описание
source	…/cache/images/products/253/001.jpg/572c844a39ecf673.webp	(По умолчанию) Штатное поведение Glide и всех версий до 3.1.0. Путь к исходнику виден в адресе.
hashed	…/cache/63/fc/63fca9e1cfecba76209b6eb0d77d479b83c92b92.webp	(Рекомендуется) Имя файла — SHA1-хэш, разложенный по подпапкам. Путь к оригиналу не раскрывается, а файлы кэша равномерно расходятся по 65536 папкам, что заметно облегчает бэкапы и работу с папкой по FTP.
flat	…/cache/63fca9e1cfecba76209b6eb0d77d479b83c92b92.webp	То же, что hashed, но все файлы лежат в одной папке. Подходит для небольших сайтов.

Любое другое или пустое значение трактуется как source, поэтому опечатка в настройке не может сломать сайт. В режимах hashed и flat имя файла совпадает с полем hash в таблице thumb3x_files.

После смены значения полностью очистите кэш — кнопка «Очистить весь кэш» в админке. Ранее созданные изображения продолжат отдаваться по сохранённым в базе адресам, но останутся в прежней схеме и со временем станут мусором на диске. Учтите также, что адреса всех новых изображений изменятся: если сайт работает через CDN, потребуется сбросить её кэш.

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

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

Если задача — действительно закрыть доступ к изображениям без водяного знака, разместите оригиналы вне корня сайта: создайте «Источник файлов» с базовым путём за пределами публичной директории (например {core_path}storage/images/) и укажите его в настройке thumb3x.source_id. Thumb3x читает файлы через файловую систему, а не по HTTP, поэтому обработка продолжит работать, а наружу будет отдаваться только папка кэша — уже с водяным знаком.