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

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

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

Современные форматы: Конвертация в WebP и AVIF "на лету".
Продвинутый движок: В основе лежит высокопроизводительная библиотека Glide 3.0.1.
Интеграция с MODX 3: Полная поддержка Источников файлов и системных настроек.
Гибкая обработка: Фильтры, эффекты, водяные знаки и точное позиционирование.
Поддержка Fenom: Удобный вызов сниппета с передачей параметров в виде массивов.
Управление кэшем: Ведение лога сгенерированных файлов в базе данных с удобной таблицей в админке.

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

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

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

Параметр	Альтернатива	Описание	Пример
`input`	`i`	(Обязательный) Путь к исходному изображению.	&input=`image.jpg`
`options`	`o`	Строка или массив (для Fenom) с параметрами обработки для Glide.	&options=`w=400&fit=crop`
`sourceId`		ID "Источника файлов" для исходного изображения. По умолчанию используется значение из системных настроек.	&sourceId=`2`
`watermark`		Путь к файлу водяного знака. Активирует возможность наложения водяного знака.	&watermark=`assets/logo.png`
`quality`	`q`	(Переопределяется `&options`) Качество по умолчанию.	&quality=`75`
`format`	`fm`	(Переопределяется `&options`) Формат по умолчанию.	&format=`webp`

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

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

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

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

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

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

Параметр	Ключ	Описание	Пример
Ширина	`w`	Ширина итогового изображения в пикселях.	`w=300`
Высота	`h`	Высота итогового изображения в пикселях.	`h=200`
Вписывание	`fit`	Как вписать изображение. Основные значения: `contain`, `max`, `stretch`, `crop`.	`fit=crop`
Обрезка	`crop`	Точное кадрирование: `ширина,высота,x,y`.	`crop=200,150,20,50`
DPR	`dpr`	Множитель для Retina-дисплеев. `dpr=2` вернет картинку вдвое большего размера.	`dpr=2`
Ориентация	`or`	Поворачивает изображение. Значения: `auto`, `0`, `90`, `180`, `270`.	`or=90`
Отражение	`flip`	Отражает изображение. Значения: `v` (вертикально), `h` (горизонтально), `both`.	`flip=h`

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

Параметр	Ключ	Описание	Пример
Яркость	`bri`	Регулировка яркости (-100 до +100).	`bri=20`
Контрастность	`con`	Регулировка контрастности (-100 до +100).	`con=-30`
Гамма	`gam`	Гамма-коррекция (0.1 до 9.99).	`gam=2.2`
Резкость	`sharp`	Усиление резкости (0 до 100).	`sharp=10`
Размытие	`blur`	Размытие по Гауссу (0 до 100).	`blur=15`
Пикселизация	`pixel`	Эффект пикселизации (0 до 1000).	`pixel=10`
Фильтр	`filt`	Применяет фильтр: `greyscale` или `sepia`.	`filt=greyscale`

Фон и рамка

Параметр	Ключ	Описание	Пример
Фон	`bg`	Цвет фона. Формат: `RRGGBB`.	`bg=CCCCCC`
Рамка	`border`	Добавляет рамку. Формат: `ширина,цвет,тип`. Тип: `overlay` или `shrink`.	`border=5,000000,overlay`

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

Параметр	Ключ	Описание	Пример
Путь	`mark`	(Обязательный) Имя файла водяного знака.	`mark=logo.png`
Ширина	`markw`	Ширина водяного знака (в px или %).	`markw=15w`
Высота	`markh`	Высота водяного знака (в px или %).	`markh=50`
Отступ X	`markx`	Отступ по горизонтали (отрицательные значения - от правого края).	`markx=-20`
Отступ Y	`marky`	Отступ по вертикали (отрицательные значения - от нижнего края).	`marky=-20`
Отступы	`markpad`	Отступы со всех сторон.	`markpad=10`
Позиция	`markpos`	Позиция: `top-left`, `center`, `bottom-right` и т.д.	`markpos=top-left`
Прозрачность	`markalpha`	Прозрачность водяного знака (0-100).	`markalpha=50`

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

Параметр	Ключ	Описание	Значения	Пример
Формат	`fm`	Формат итогового изображения.	`jpg`, `png`, `gif`, `webp`, `avif`	`fm=webp`
Качество	`q`	Качество для `jpg`, `webp`, `avif`.	`0` до `100`	`q=80`

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

Пример 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, что делает код шаблона намного чище и удобнее для чтения и редактирования.