Thumb3x documentation

Thumb3x: modern image processing for MODX 3

This component was written to fill a gap in the MODX 3 ecosystem, which has almost no modern and reliable tools for working with images. Most existing solutions have not been updated for more than 10 years and do not use the advantages of the new version of the system.

Key features

• Modern formats: on-the-fly conversion to WebP and AVIF.

• Advanced engine: built on the high-performance Glide 3.2 library.

• MODX 3 integration: full support for Media Sources.

• Flexible processing: filters, effects, watermarks and precise positioning.

• Fenom support: convenient snippet calls with parameters passed as arrays.

• Cache management: generated files are logged in the database with a handy table in the manager.

Standard MODX call

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

Fenom call

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

Main snippet parameters

Important: any parameters (q, fm, etc.) given inside the &options string always take the highest priority.

Processing parameters reference (&options)

Official Glide documentation

Thumb3x uses the Glide library for all image operations, so you can use any parameter the library itself supports.

The most complete and up-to-date list of parameters is always on the official site: https://glide.thephpleague.com/

Size and orientation

Adjustments and effects

Background and border

Watermarks

Output format

Detailed call examples

Example 1: watermark (standard MODX call)

Task: put logo.png in the bottom right corner with padding and half 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="Watermarked portfolio image">

Example 2: Fenom call

Task: the same, using the more readable Fenom syntax with parameters passed as an array.

{* Glide parameters as an array *}
{var $params = [
    'w' => 1200,
    'h' => 800,
    'mark' => 'logo.png',
    'markpos' => 'bottom-right',
    'markpad' => 20,
    'markalpha' => 60
]}

{* Call the snippet *}
<img src="{'!Thumb3x' | snippet : [
    'input' => 'portfolio/image-01.jpg',
    'watermark' => 'assets/images/logo.png',
    'options' => $params
]}" alt="Watermarked image">

Note: the main advantage of Fenom here is that all processing parameters can be collected in a neat $params array, which makes the template much cleaner and easier to read and edit.

Cache path scheme

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

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

If you add a watermark, a visitor can easily work out the path to the original without it. Since version 3.1.0 the naming scheme can be changed with the thumb3x.cache_path_mode system setting.

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

After changing the value, clear the cache completely — the “Clear all cache” button in the manager. Previously generated images will still be served from the URLs stored in the database, but they stay in the old scheme and will eventually become garbage on disk. Also note that the URLs of all new images change: if the site uses a CDN, its cache will need to be purged.

Upgrading from previous 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 only enabled manually.

Important: this does not protect the original. The hashed and flat modes remove the original path from the cache URL, but the original itself stays available at its usual address if it is in a public folder of the site.

If you really need to block access to images without a watermark, keep the originals outside the web root: create a Media Source with a base path outside the public directory (for example {core_path}storage/images/) and set it in thumb3x.source_id. Thumb3x reads files through the file system, not over HTTP, so processing keeps working, and only the cache folder — already watermarked — is served publicly.