Thumb3x Documentation

This component was written to fill a gap in the MODX 3 ecosystem, where modern and reliable tools for working with images are virtually absent. Most existing solutions have not been updated in over 10 years and do not take advantage of the new system version.

Key Features

Modern Formats: On-the-fly conversion to WebP and AVIF.
Advanced Engine: Based on the high-performance Glide 3.2 library.
MODX 3 Integration: Full support for Media Sources and System Settings.
Flexible Processing: Filters, effects, watermarks, and precise positioning.
Fenom Support: Convenient snippet calls by passing parameters as arrays.
Cache Management: Logging of generated files in the database with a convenient grid in the manager.

<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
    ]
]}

Main Snippet Parameters

Parameter	Alias	Description	Example
`input`	`i`	(Required) Path to the source image.	&input=`image.jpg`
`options`	`o`	String or array (for Fenom) with processing parameters for Glide.	&options=`w=400&fit=crop`
`sourceId`		The Media Source ID for the source image. Defaults to the value from System Settings.	&sourceId=`2`
`watermark`		Path to the watermark file. Activates the watermarking functionality.	&watermark=`assets/logo.png`
`quality`	`q`	(Overridden by `&options`) Default quality.	&quality=`75`
`format`	`fm`	(Overridden by `&options`) Default format.	&format=`webp`

Important: Any parameters (`q`, `fm`, etc.) specified inside the &options string always have the highest priority.

Processing Parameters Reference (`&options`)

Official Glide Documentation

The Thumb3x component uses the Glide library for all image operations. This means you can use any parameter that the library itself supports.

The most complete and up-to-date information on all possible parameters can always be found on the official website:
https://glide.thephpleague.com/

Sizing & Orientation

Parameter	Key	Description	Example
Width	`w`	The width of the output image in pixels.	`w=300`
Height	`h`	The height of the output image in pixels.	`h=200`
Fit	`fit`	How the image is fitted to its target dimensions. Main values: `contain`, `max`, `stretch`, `crop`.	`fit=crop`
Crop	`crop`	Precise cropping: `width,height,x,y`.	`crop=200,150,20,50`
DPR	`dpr`	Device Pixel Ratio. `dpr=2` will return an image twice as large for Retina displays.	`dpr=2`
Orientation	`or`	Rotates the image. Values: `auto`, `0`, `90`, `180`, `270`.	`or=90`
Flip	`flip`	Flips the image. Values: `v` (vertically), `h` (horizontally), `both`.	`flip=h`

Adjustments & Effects

Parameter	Key	Description	Example
Brightness	`bri`	Adjusts brightness (-100 to +100).	`bri=20`
Contrast	`con`	Adjusts contrast (-100 to +100).	`con=-30`
Gamma	`gam`	Gamma correction (0.1 to 9.99).	`gam=2.2`
Sharpen	`sharp`	Sharpens the image (0 to 100).	`sharp=10`
Blur	`blur`	Applies a Gaussian blur (0 to 100).	`blur=15`
Pixelate	`pixel`	Applies a pixelation effect (0 to 1000).	`pixel=10`
Filter	`filt`	Applies a filter: `greyscale` or `sepia`.	`filt=greyscale`

Background & Border

Parameter	Key	Description	Example
Background	`bg`	Sets the background color. Format: `RRGGBB`.	`bg=CCCCCC`
Border	`border`	Adds a border. Format: `width,color,type`. Type: `overlay` or `shrink`.	`border=5,000000,overlay`

Watermarks

Parameter	Key	Description	Example
Path	`mark`	(Required) The watermark's filename.	`mark=logo.png`
Width	`markw`	Watermark width (in px or %).	`markw=15w`
Height	`markh`	Watermark height (in px or %).	`markh=50`
X-Offset	`markx`	Horizontal offset (negative values from the right edge).	`markx=-20`
Y-Offset	`marky`	Vertical offset (negative values from the bottom edge).	`marky=-20`
Padding	`markpad`	Padding on all sides.	`markpad=10`
Position	`markpos`	Position: `top-left`, `center`, `bottom-right`, etc.	`markpos=top-left`
Alpha	`markalpha`	Watermark opacity (0-100).	`markalpha=50`

Output Format

Parameter	Key	Description	Values	Example
Format	`fm`	The output image format.	`jpg`, `png`, `gif`, `webp`, `avif`	`fm=webp`
Quality	`q`	Quality for `jpg`, `webp`, `avif`.	`0` to `100`	`q=80`

Detailed Usage Examples

Example 1: Applying a Watermark (Standard MODX Call)

Task: Apply logo.png to the bottom-right corner with padding and semi-transparency.

<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="Portfolio with watermark">

Example 2: Advanced Fenom Call

Task: Resize the image, crop it to a square, apply a sepia filter, and convert to WebP with 75 quality.

{var $params = [
    'w' => 300,
    'h' => 300,
    'fit' => 'crop',
    'filt' => 'sepia',
    'q' => 75,
    'fm' => 'webp'
]}

<img src="{'!Thumb3x' | snippet : [
    'input' => 'path/to/avatar.jpg',
    'options' => $params
]}" alt="Avatar in sepia">

Cache Path Scheme

By default Glide builds the cache file name from the path of the source image. That is convenient while debugging, but it also means the location of the original is visible right in the thumbnail URL:

Source:  images/products/253/001.jpg
Cached:  /assets/components/thumb3x/cache/images/products/253/001.jpg/572c844a39ecf673.webp

If you apply a watermark, such a URL lets a visitor trivially work out the path to the unwatermarked original. As of version 3.1.0 the naming scheme can be changed with the thumb3x.cache_path_mode system setting.

Value	Resulting cache URL	Description
`source`	`…/cache/images/products/253/001.jpg/572c844a39ecf673.webp`	(Default) The standard Glide behaviour, and that of every version before 3.1.0. The source path is visible in the URL.
`hashed`	`…/cache/63/fc/63fca9e1cfecba76209b6eb0d77d479b83c92b92.webp`	(Recommended) The file name is a SHA1 hash spread across subfolders. The original path is never exposed, and cache files are distributed evenly over 65536 folders, which makes backups and FTP browsing far more manageable.
`flat`	`…/cache/63fca9e1cfecba76209b6eb0d77d479b83c92b92.webp`	Same as `hashed`, but every file sits in a single folder. Fine for smaller sites.

Any other or empty value is treated as source, so a typo in the setting cannot break the site. In hashed and flat mode the file name matches the hash column of the thumb3x_files table.

Truncate the cache completely after changing this value — the "Clear entire cache" button in the manager. Previously generated images keep being served from the URLs stored in the database, but they stay in the old scheme and eventually become dead weight on disk. Note also that the URLs of all new images change: if the site runs behind a CDN, its cache has to be purged.

Upgrading from earlier versions

The setting is created with the value source, so upgrading to 3.1.0 changes nothing on live sites: existing cache records stay valid and no images are regenerated. The new scheme is opt-in only.

Important: this does not protect the original

The hashed and flat modes remove the source path from the cache URL, but the original itself remains reachable at its usual address as long as it lives in a public folder of the site.

If the goal is to genuinely block access to unwatermarked images, move the originals outside the web root: create a Media Source whose base path lies outside the public directory (for example {core_path}storage/images/) and point the thumb3x.source_id setting at it. Thumb3x reads files through the filesystem rather than over HTTP, so processing keeps working while only the cache folder — already watermarked — is exposed.