Ресайз изображений в MODX 3: pThumb + параметры встроенной библиотеки phpThumb

phpThumb / pThumb в MODX 3 — это связка встроенной библиотеки phpThumb и дополнения pThumb, которая отвечает за обрезку, ресайз, сжатие и «украшения» изображений прямо на лету, без ручной подготовки картинок в редакторе. В MODX 3 всё это работает через сниппет pthumb/phpthumbof и может вызываться как в стандартном шаблонизаторе, так и в Fenom.

Что такое phpThumb и pThumb в MODX 3

phpThumb — это встроенная в MODX библиотека на PHP, которая умеет из одного исходного файла делать разные варианты: уменьшенные превью, обрезанные баннеры, изображения с водяным знаком, рамкой, размытием и т.д. pThumb — это форк/обёртка phpThumbOf, облегчающая работу с этой библиотекой: она даёт сниппет pthumb (и алиас phpthumbof), добавляет настройки, кеш, поддержку Resizer и ускоряет обработку картинок.

Основные моменты:

• pThumb ставится как обычный Extra из пакет-менеджера и полностью заменяет устаревший phpThumbOf, сохраняя совместимость со старыми вызовами.
• В MODX 3 pThumb работает стабильно, поддерживает phpThumb и альтернативный движок Resizer (на Imagine) с поддержкой GD, Imagick, Gmagick. Примечание: Resizer автоматически устанавливается вместе с pThumb.
• Все параметры обработки (ширина, высота, обрезка, качество, фильтры и т.п.) задаются строкой опций вида w=550&h=400&zc=1.

Установка и базовая настройка pThumb в MODX 3

pThumb ставится однажды и дальше используется в любом шаблоне, чанке или сниппете.

Шаги установки:

• Откройте «Управление пакетами» → найдите и установите pThumb (MODX Extras репозиторий).
• Если раньше был установлен phpThumbOf — его лучше удалить, pThumb подставится вместо него сам (сохраняя имя сниппета phpthumbof).
• После установки появятся системные настройки с префиксом phpthumbof. и pthumb. (пакет сохраняет namespace).

Рекомендованный базовый набор настроек для MODX 3:

• Включить Resizer, если на сервере есть Imagick или Gmagick (phpthumbof.use_resizer = Да).
• Указать свой каталог кеша картинок, например img/cache (ключ: pthumb.ptcache_location).
• В pthumb.global_defaults задать: q=70&zc=C — умеренное сжатие JPEG и центрированная обрезка по умолчанию.

Resizer: ускоренный движок pThumb

Resizer — это отдельный класс, который идёт отдельным пакетом и при включении в настройках pThumb заменяет стандартный phpThumb‑движок. Он построен на библиотеке Imagine и умеет работать через Imagick, Gmagick или GD.

Плюсы Resizer:

• Обычно работает быстрее phpThumb, особенно при массовом ресайзе больших JPEG.
• Все ZC‑опции (zc) корректно работают даже при использовании GD.
• Поддерживает дополнительные опции:
  • scale — удобный ресайз для Retina (масштабирует все размеры внутри).
• qmax — верхний предел качества JPEG для мелких исходников, чтобы компенсировать нехватку разрешения.

Включение Resizer в MODX 3:

• В системной настройке phpthumbof.use_resizer указать Yes.
• При необходимости точечно переключать в вызове:
  • &useResizer=1 или &useResizer=0 в сниппете pthumb.

Например, принудительно включить Resizer только для одного вызова:

[[!pthumb?
&input=`[[*image]]`
&options=`w=800&h=450&zc=1&q=70`
&useResizer=`1`
]]


Или Fenom‑аналог через модификатор, если используется обёртка (в некоторых реализациях): [ ... ] — либо через стандартный сниппет‑вызов в Fenom, если вы вызываете phpthumbof как сниппет.

Кеш и SEO‑дружелюбные URL изображений

pThumb умеет работать в двух режимах кеша: классический phpThumbOf стиль и новый pThumb Cache.

Классический режим:

• Все миниатюры складываются в одну папку (например, assets/components/phpthumbof/cache/) с длинными MD5‑именами файлов.

Новый pThumb Cache:

• Кеш хранится в отдельной папке (по умолчанию assets/image-cache).
• Структура директорий повторяет часть пути оригинала и хеш сокращается до 8 символов.
• Пример:
  • Исходник: assets/acme/images/products/whiz-o-matic/exploded-view-1.jpg.
• Миниатюра: /assets/image-cache/products/whiz-o-matic/exploded-view-1.a9b0032f.jpg.

Для включения:

• Настроить:
  • pthumb.ptcache_location (например, assets/image-cache).
• pthumb.images_basedir (например, assets/acme/images).
• Включить pthumb.use_ptcache = Yes.

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

Основные параметры phpThumb / pThumb

Все опции задаются в одной строке: w=ШИРИНА&h=ВЫСОТА&zc=1&f=webp&q=80 и т.д. Вот ключевые параметры, которые чаще всего используются на реальных проектах.

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

• w — максимальная ширина изображения в пикселях.
• h — максимальная высота.
• wp, hp — ограничения для портретных картинок (portrait).
• wl, hl — ограничения для пейзажных (landscape).
• ws, hs — ограничения для квадратных изображений.

Формат и качество:

• f — формат выходного файла: jpeg, png, gif, webp и т.д.
• q — качество JPEG (1–100, чем выше, тем меньше сжатие и больше размер файла).
• В Resizer добавлены scale и qmax для ретина и адаптивного качества.

Кадрирование и масштабирование:

• zc (zoom-crop) — обрезка под заданный размер, заполняя обе стороны. Требует w и h.
  • zc=1 или zc=C — центр.
  • zc=TL, TR, BL, BR — приоритет угла.
• far — вписать картинку в заданный размер с подложкой (с сохранением пропорций): far=C — центр, far=L,T,R,B и комбинации.
• iar — игнорировать пропорции (растянуть как есть под w и h).
• aoe — разрешить увеличение (upscale), если картинка меньше нужного размера.

Обрезка исходника:

• sx, sy — смещение обрезки (лево/верх); могут быть в пикселях или долях (0–1).
• sw, sh — ширина и высота «исходного прямоугольника» (crop до ресайза).

Фон, цвет и фильтры:

• bg — цвет фона, например bg=FFFFFF или bg=333333/70 (для PNG с прозрачностью, 70%).
• fltr[] — массив фильтров (яркость, контраст, гамма, сепия, насыщенность, размытие, водяной знак, рамки и др.).
• Типичные варианты:
  • fltr[]=gray — сделать ч/б.
  • fltr[]=usm — нерезкая маска (подчёркивание резкости).
  • fltr[]=wmt|Текст|10|LR|FFFFFF|... — текстовый водяной знак.

Все параметры можно посмотреть на github.

Примеры типовых задач с phpThumb / pThumb

Ниже — практические сценарии, которые часто встречаются в проектах на MODX 3.

1. Превью в списке новостей

Стандартный шаблонизатор:

[[+image:pthumb=`w=320&h=200&zc=1&q=70`]]

Fenom:

{$image | pthumb : "w=320&h=200&zc=1&q=70"}

Так получается аккуратная сетка одинаковых картинок.

2. Большой баннер во всю ширину

[[*banner:pthumb=`w=1920&h=600&zc=1&q=75`]]

На Fenom:

{$_modx->resource.banner | pthumb : "w=1920&h=600&zc=1&q=75"}

3. Квадратные превью для галереи

[[+image:pthumb=`w=300&h=300&zc=1&q=80`]]

или в Fenom:

{$image | pthumb : "w=300&h=300&zc=1&q=80"}

4. Чёрно-белые аватарки

[[+avatar:pthumb=`w=150&h=150&zc=1&fltr[]=gray`]]

В Fenom:

{$avatar | pthumb : "w=150&h=150&zc=1&fltr[]=gray"}

Благодаря фильтру gray изображение становится чёрно‑белым.

5. Текстовый водяной знак (phpThumb / Resizer)

[[*image:pthumb=`w=800&h=600&zc=1&fltr[]=wmt|MySite.ru|10|LR|FFFFFF`]]

Здесь wmt — текстовый водяной знак; параметры задают текст, размер шрифта, выравнивание, цвет и т.п.

6. Вызов как сниппета pthumb внутри Fenom

Иногда удобнее вызвать pThumb как обычный сниппет с параметрами массивом (особенно если путь динамический).

MODX классика:
[[!pthumb? &input=`img/photo.jpg` &options=`w=600&h=300&zc=C` ]]
Fenom‑вариант (через runSnippet):
{set $thumb = $_modx->runSnippet('!pthumb', { 'input' : 'img/photo.jpg', 'options' : 'w=600&h=300&zc=C' })} <img src="{$thumb}" alt="">
Такой подход рекомендуют, когда нужно больше контроля, или путь к картинке собирается в PHP‑логике Fenom‑шаблона.

7. Примеры c <img> в Fenom

1. TV‑поле:
<img src="{$_modx->resource.image | pthumb : 'w=550&h=400&zc=1'}" alt="{$_modx->resource.pagetitle | escape}">
2. Плейсхолдер в списке:
<img src="{$image | pthumb : 'w=245&h=170&zc=1'}" alt="{$pagetitle | escape}">
3. С проверкой наличия картинки:
{if $_modx->resource.image} <img src="{$_modx->resource.image | pthumb : 'w=400&h=300&zc=1'}" alt="{$_modx->resource.pagetitle | escape}"> {else} <img src="/assets/img/no-photo.jpg" alt="Нет фото"> {/if}
Эти конструкции один в один повторяют логику [[if? &is=...]] из классического MODX, только в Fenom‑стиле.

Частые паттерны pThumb в Fenom

1. Использование разных размеров из одного поля

{set $src = $_modx->resource.image} {if $src} {set $big = $src | pthumb : 'w=1200&h=500&zc=1&q=80'} {set $small = $src | pthumb : 'w=400&h=200&zc=1&q=70'} <img src="{$big}" class="banner" alt=""> <img src="{$small}" class="thumb" alt=""> {/if}

2. Ленивые картинки (lazyload)

{set $thumb = $_modx->resource.image | pthumb : 'w=400&h=300&zc=1&q=70'} <img src="/assets/img/placeholder.svg" data-src="{$thumb}" class="lazy" alt="{$_modx->resource.pagetitle | escape}">

Особенности и советы по использованию

Чтобы pThumb/phpThumb в MODX 3 работали максимально эффективно и без сюрпризов:

• Стараться использовать локальные пути (/assets/...), а не полные URL с http://... — такие картинки обрабатываются быстрее и кешируются корректнее.
• Не злоупотреблять фильтрами, особенно тяжёлыми (размытие, сложные рамки) — лучше часть эффектов реализовать CSS.
• Следить за качеством q:
  • Для списка превью 60–75 обычно достаточно.
  • Для основных баннеров и слайдеров лучше 75–85, но ориентироваться на PageSpeed и вес страниц.
• При смене опций на уже сгенерированные картинки (например, изменили q или размеры) кеш можно сбросить через очистку сайта (Clear Cache) или с помощью настройки уровня очистки pThumb Cache.
• Для удалённых изображений (S3 или чужие серверы) pThumb сначала скачивает оригинал в отдельную папку (remote-images), а затем использует локальный кеш, что сильно ускоряет повторные вызовы.

Альтернатива pThumb для MODX 3 — Thumb3x

Для MODX 3 есть современная альтернатива pThumb — Thumb3x, доступная в Modstore. Это отдельный ресайзер изображений, который ориентирован именно на MODX 3 и часто упоминается как более актуальный выбор по сравнению с классическим pThumb/phpThumbOf.

Кратко о Thumb3x:

• Устанавливается из Modstore (пакет «Thumb3x: Современная обработка изображений для MODX 3»).
• Решает ту же задачу: ресайз/кроп/оптимизация картинок «на лету», но реализован с учётом новых версий PHP и MODX 3.
• В обсуждениях сообщества его рекомендуют как «свежую» замену старым резайзерам, особенно когда pThumb уже не обновляется, а проект на современном стеке.

С точки зрения шаблонов:

• Подход тот же: есть сниппет, есть строка опций (ширина, высота, кроп и т.п.).
• В Fenom‑шаблонах Thumb3x вызывается аналогично pThumb: либо как модификатор (если предусмотрен), либо через $_modx->runSnippet(...) с массивом параметров.
• При миграции с pThumb на Thumb3x часто достаточно заменить имя сниппета и подогнать опции под синтаксис Thumb3x (если он чуть отличается).

Заключение

В MODX 3 pThumb остаётся рабочим решением для быстрого старта, особенно если проект небольшой и нужны фильтры phpThumb. Для новых сайтов выбирайте Thumb3x — он быстрее, современнее и лучше интегрируется с Media Source. Fenom упрощает код, а правильный кеш ускоряет сайт в 2–5 раз. Тестируйте PageSpeed после настройки!

Общий совет: начинайте с pThumb + Resizer, при росте трафика мигрируйте на Thumb3x.