Image Resizing in MODX 3: pThumb + Built-in phpThumb Library Options

phpThumb / pThumb in MODX 3 is a combination of the built-in phpThumb library and the pThumb add-on, which is responsible for cropping, resizing, compressing, and “embellishing” images on the fly, without manually preparing them in the editor. In MODX 3, all this works via the pthumb/phpthumbof snippet and can be called in both the standard template engine and Fenom.

What are phpThumb and pThumb in MODX 3

phpThumb is a built-in PHP library for MODX that can create various options from a single source file: reduced-size previews, cropped banners, images with watermarks, borders, blurs, and more. pThumb is a fork/wrapper of phpThumbOf that makes working with this library easier: it provides a pthumb snippet (and phpthumbof alias), adds settings, cache, resizer support, and speeds up image processing.

Key Points:

• pThumb is installed as a regular Extra from the package manager and completely replaces the deprecated phpThumbOf, maintaining compatibility with old calls.
• In MODX 3, pThumb works stably, supports phpThumb and an alternative resizer engine (based on Imagine) with support for GD, Imagick, and Gmagick. Note: Resizer is automatically installed with pThumb.
• All processing parameters (width, height, cropping, quality, filters, etc.) are set using the options string w=550&h=400&zc=1.

Installing and Basic Configuration of pThumb in MODX 3

pThumb is installed once and can be used in any template, chunk, or snippet.

Installation steps:

• Open “Manage Packages” → find and install pThumb (MODX Extras repository).
• If phpThumbOf was previously installed, it’s best to remove it. pThumb will automatically install it (keeping the snippet name phpthumbof).
• After installation, system settings will appear with the prefix phpthumbof. and pthumb. (the package preserves the namespace).

Recommended base configuration for MODX 3:

• Enable Resizer if Imagick or Gmagick is available on the server (phpthumbof.use_resizer = Yes).
• Specify your image cache directory, for example img/cache (key: pthumb.ptcache_location).
• In pthumb.global_defaults, set: q=70&zc=C — moderate JPEG compression and centered cropping default.

Resizer: Accelerated pThumb Engine

Resizer is a separate class that comes in a separate package and, when enabled in the pThumb settings, replaces the standard phpThumb engine. It is built on the Imagine library and can work with Imagick, Gmagick, or GD.

Pros of Resizer:

• Usually works faster than phpThumb, especially when resizing large JPEGs in bulk.
• All ZC options (zc) work correctly even when using GD.
• Supports additional options:
  • scale — convenient resizing for Retina (scales all sizes internally).
• qmax — the upper limit of JPEG quality for small sources to compensate for the lack of resolution.

Enabling Resizer in MODX 3:

• Set Yes in the system setting phpthumbof.use_resizer.
• If necessary, toggle between call:
  • &useResizer=1 or &useResizer=0 in the pthumb snippet.

For example, to force the resizer to be enabled for only one call:

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


Or the Fenom equivalent via a modifier, if a wrapper is used (in some implementations): [ ... ] — or via a standard snippet call in Fenom, if you call phpthumbof as a snippet.

Cache and SEO-friendly image URLs

pThumb can operate in two cache modes: the classic phpThumbOf style and the new pThumb Cache.

Classic Mode:

• All thumbnails are placed in a single folder (e.g. assets/components/phpthumbof/cache/) with long MD5 filenames.

New pThumb Cache:

• The cache is stored in a separate folder (by default assets/image-cache).
• The directory structure matches part of the original path, and the hash is shortened to 8 characters.
• Example:
  • Original: assets/acme/images/products/whiz-o-matic/exploded-view-1.jpg.
• Thumbnail: /assets/image-cache/products/whiz-o-matic/exploded-view-1.a9b0032f.jpg.

To enable:

• Configure:
  • pthumb.ptcache_location (e.g. assets/image-cache).
• pthumb.images_basedir (e.g. assets/acme/images).
• Enable pthumb.use_ptcache = Yes.

This has a positive impact on SEO and performance: paths are shorter and more understandable, and the static cache is easily served by the web server.

Main phpThumb / pThumb Parameters

All options are specified on one line: w=WIDTH&h=HEIGHT&zc=1&f=webp&q=80, etc. Here are the key parameters most often used in real-world projects.

Dimensions and Orientation:

• w — Maximum image width in pixels.
• h — Maximum height.
• wp, hp — Portrait image limits.
• wl, hl — Landscape image limits.
• ws, hs — Square image limits.

Format and Quality:

• f — Output file format: jpeg, png, gif, webp, etc.
• q — Quality JPEG (1–100, the higher the compression, the lower the compression and the larger the file size).
• scale and qmax have been added to the resizer for Retina and Adaptive quality.

Cropping and scaling:

• zc (zoom-crop) — crops to a specified size, filling both sides. Requires w and h.
  • zc=1 or zc=C — center.
  • zc=TL, TR, BL, BR — corner priority.
• far — fit the image to the specified size with the background (preserving the proportions): far=C — center, far=L,T,R,B and combinations.
• iar — ignore proportions (stretch as is to fit w and h).
• aoe — allow upscaling if the image is smaller than the required size.

Cropping the source:

• sx, sy — crop offset (left/top); Can be in pixels or fractions (0–1).
• sw, sh — width and height of the “original rectangle” (crop before resizing).

Background, color, and filters:

• bg — background color, for example bg=FFFFFF or bg=333333/70 (for PNG with transparency, 70%).
• fltr[] — array of filters (brightness, contrast, gamma, sepia, saturation, blur, watermark, frames, etc.).
• Typical options:
  • fltr[]=gray — make black and white.
  • fltr[]=usm — unsharp mask (sharpness enhancement).
  • fltr[]=wmt|Text|10|LR|FFFFFF|... — text watermark.

All parameters can be found on github.

Examples of typical tasks with phpThumb / pThumb

Below are practical scenarios that are often encountered in MODX 3 projects.

1. Preview in the news list

Standard template engine:

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

Fenom:

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

This creates a neat grid of identical images.

2. Large full-width banner

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

On Fenom:

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

3. Square previews for the gallery

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

or in Fenom:

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

4. Black and White Avatars

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

In Fenom:

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

The gray filter turns the image black and white.

5. Text Watermark (phpThumb / Resizer)

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

Here wmt is a text watermark; the parameters define the text, font size, alignment, color, etc.

6. Calling pthumb as a snippet within Fenom

Sometimes it’s more convenient to call pThumb as a regular snippet with array parameters (especially if the path is dynamic).

MODX classic:
[[!pthumb? &input=`img/photo.jpg` &options=`w=600&h=300&zc=C` ]]
Fenom option (via runSnippet):
{set $thumb = $_modx->runSnippet('!pthumb', { 'input' : 'img/photo.jpg', 'options' : 'w=600&h=300&zc=C' })} <img src="{$thumb}" alt="">
This approach is recommended when more control is needed, or when the image path is assembled in the PHP logic of the Fenom template.

7. Examples with <img> in Fenom

1. TV field:
<img src="{$_modx->resource.image | pthumb : 'w=550&h=400&zc=1'}" alt="{$_modx->resource.pagetitle | escape}">
2. Placeholder in the list:
<img src="{$image | pthumb : 'w=245&h=170&zc=1'}" alt="{$pagetitle | escape}">
3. With image availability check:
{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="No photo"> {/if}
These constructs are identical to the [[if? &is=...]] logic from classic MODX, only in Fenom style.

Common pThumb Patterns in Fenom

1. Using Different Sizes from a Single Field

{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. Lazy pictures (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}">

Features and Usage Tips

To ensure pThumb/phpThumb in MODX 3 works as efficiently as possible and avoids surprises:

• Try to use local paths (/assets/...) rather than full URLs with http://... — these images are processed faster and cached more correctly.
• Avoid overusing filters, especially heavy ones (blur, complex borders) — it’s better to implement some effects in CSS.
• Monitor the quality of q:
  • For a list of previews, 60–75 is usually sufficient.
  • For main banners and sliders, 75–85 is better, but consider PageSpeed ​​and page weight.
• When changing options for pre-generated images (for example, (If you changed the q or dimensions), the cache can be reset by clearing the site (Clear Cache) or by adjusting the pThumb Cache clearing level.
• For remote images (S3 or other servers), pThumb first downloads the original to a separate folder (remote-images) and then uses the local cache, which significantly speeds up repeated requests.

pThumb Alternative for MODX 3 — Thumb3x

For MODX 3, there is a modern alternative to pThumb — Thumb3x, available in the Modstore. This is a standalone image resizer specifically designed for MODX 3 and is often cited as a more modern choice than the classic pThumb/phpThumbOf.

Briefly about Thumb3x:

• Installed from the Modstore (package “Thumb3x: Modern Image Processing for MODX 3”).
• It solves the same problem: on-the-fly image resizing/cropping/optimization, but is implemented with new versions of PHP and MODX 3 in mind.
• In community discussions, it is recommended as a “fresh” replacement for older resizers, especially when pThumb is no longer updated and the project uses a modern stack.

From a template perspective:

• The approach is the same: there is a snippet, there is a string of options (width, height, crop, etc.).
• In Fenom templates, Thumb3x is called similarly to pThumb: either as a modifier (if provided) or via $_modx->runSnippet(...) with an array of parameters.
• When migrating from pThumb to Thumb3x, it’s often enough to replace the snippet name and adjust the options to fit the Thumb3x syntax (if it’s slightly different).

​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​

Conclusion

In MODX 3, pThumb remains a viable solution for a quick start, especially if your project is small and requires phpThumb filters. For new sites, choose Thumb3x—it’s faster, more modern, and integrates better with Media Source. Fenom simplifies code, and a proper cache speeds up your site by 2-5x. Test PageSpeed ​​after setup!

General advice: start with pThumb + Resizer, and migrate to Thumb3x as your traffic grows.