KDA Thumbnails

Description

KDA Thumbnails creates resized, cached image thumbnails from the WordPress Media Library (or any local file) without touching your original uploads. Thumbnails are generated once, stored in a configurable cache folder, and served directly on subsequent requests.

How it works

The plugin works in two modes: zero-code (everything from the settings page) and developer mode (shortcodes, PHP functions, filters).

Zero-code mode (no programming required):

1. Go to Settings в†’ KDA Thumbnails.
2. Set the cache folder path (defaults to wp-content/uploads/kda-thumbnails/).
3. Choose the image library (Auto, Imagick, or GD).
4. Configure the default output format (JPEG, PNG, or WebP) and quality (1-100).
5. Optionally enable a watermark: choose between text and image, set color, opacity, position, font size, and font family (Google Fonts or a custom local .ttf/.otf file).
6. Optionally enable responsive srcset: specify a list of widths (e.g. 300, 768, 1200) and an optional sizes attribute.
7. Optionally enable automatic content image caching: add CSS classes to the list, and the plugin will replace matching <img> tags in post content with optimized thumbnails.
8. Optionally enable remote image caching: allow http(s) URLs as sources, with SSRF protection, TTL refresh, and max file size limit.

That is it. The plugin takes care of the rest: generating thumbnails on first request, caching them, invalidating when the source changes, and enforcing a cache size quota if configured.

Developer mode (shortcodes and PHP):

• Use the [kdath_thumbnail] shortcode in posts, pages, or widgets.
• Call PHP functions in theme templates or custom plugins.
• Hook into the_content to process all content images automatically.
• Use the custom field (kdath_thumbs_url) to store and retrieve thumbnail URLs.

Features

• On-the-fly thumbnail generation with GD or Imagick (auto-detected, or force a specific engine on the settings page).
• Output as JPG, PNG or WebP. Global default format setting applies to all thumbnails, including srcset variants.
• Smart caching with optional organization by post type (each post type gets its own subfolder). The cache folder can be any absolute server path or a subfolder inside wp-content/uploads/.
• Optional watermark — text or image:
  • Text watermark: custom text, color, opacity, position, and font size (in pixels or as a percentage of the smaller image side so it scales with the thumbnail).
  • Google Fonts: pick a font family from a curated list. The TrueType file is downloaded once and cached locally, then reused for every render. A custom local .ttf/.otf path can be used instead.
  • Outline (stroke) mode: render the text with a colored outline (configurable width in pixels) for readability on any background.
  • Image watermark: overlay a selected Media Library image with configurable opacity.
• Shortcode [kdath_thumbnail] and PHP helper functions for theme and plugin developers.
• kdath_get_thumbnail_srcset( $args, $widths ) + kdath_the_thumbnail_srcset() for responsive srcset.
• Automatic caching of content images by CSS class (configurable list, applied via the the_content filter).
• Optional responsive srcset/sizes generation: configure a list of widths, and the rendered <img> tag can include srcset with wp-style width descriptors and an optional sizes attribute. Works for plugin shortcodes/PHP functions, content images, and native WordPress featured images.
• Optional remote image caching (opt-in, SSRF-protected, with TTL refresh and a max file size limit).
• Automatic cache size limit: the oldest thumbnails are purged automatically when the quota is exceeded.
• Lightweight admin page: engine status, cache size, font diagnostics and one-click cache clearing.
• Global output format setting (JPEG / PNG / WebP) applied to all generated thumbnails, including srcset variants.

Watermark font resolution

When a watermark is rendered the font is resolved in this order:

1. The selected Google Font (downloaded once to wp-content/uploads/kda-thumbnails-fonts/<family>.ttf and reused).
2. A custom local font file path you provide in the settings.
3. If neither is available, the text falls back to the engine’s built-in/best-effort font.

The selected Google Font is downloaded on first use and cached, so the watermark always has a real font to render with (important for Imagick, which otherwise renders nothing when no font is configured). The “Status” panel on the settings page shows the resolved font and whether the Google Font has already been downloaded.

Shortcode

[kdath_thumbnail id="123" width="400" height="300" quality="90" crop="center" format="webp" alt="Photo"]

Shortcode parameters:

• id — Media Library attachment ID (integer).
• src — alternative to id: local file path or URL inside wp-content/uploads/. Remote URLs are only supported when remote caching is enabled; otherwise use a Media Library ID or local path.
• width — target width in pixels (integer).
• height — target height in pixels (integer).
• quality — JPEG/WebP quality, 1-100 (default: 90 from settings).
• crop — crop mode: top, bottom, left, right, center (default: center).
• format — output format: jpg, png, webp (default: global “Output format” setting).
• alt — image alt text (string).
• class — extra CSS class(es) for the <img> tag (string).

Shortcode return value: an <img> HTML tag with src, width, height, alt, class, and optional srcset/sizes. On error returns empty string for non-admins, or an HTML comment with the error message for admins.

PHP functions

All functions are available after the plugin is activated.

kdath_get_thumbnail( $args )

Returns the cached thumbnail URL (string) or WP_Error on failure.

Example:

$url = kdath_get_thumbnail( array( 'id' => 123, 'width' => 400, 'height' => 300 ) );

kdath_the_thumbnail( $args ) / kdath_the_thumbnail_src( $args )

Echoes the thumbnail URL directly. Same args as kdath_get_thumbnail().

Example:

kdath_the_thumbnail_src( array( 'id' => 123, 'width' => 400 ) );

kdath_get_thumbnail_img( $args, $attributes )

Returns a complete <img> tag. $attributes is an array of extra HTML attributes (class, loading, decoding, fetchpriority, style, etc.). When “Responsive srcset” is enabled in settings, srcset and sizes are added automatically unless explicitly passed in $attributes.

Example:

echo kdath_get_thumbnail_img(
    array( 'id' => 123, 'width' => 400, 'height' => 300 ),
    array( 'class' => 'my-custom-class', 'loading' => 'lazy' )
);

kdath_the_thumbnail_img( $args, $attributes )

Echoes the <img> tag. Useful inside theme templates.

Example:

kdath_the_thumbnail_img( array( 'src' => '/path/to/image.jpg', 'width' => 800, 'height' => 600, 'crop' => 'center' ), array( 'alt' => 'My photo' ) );

kdath_get_thumbnail_srcset( $args, $widths )

Returns a srcset string (e.g. "url1 300w, url2 768w, url3 1200w") or WP_Error. Generates one cached thumbnail per width.

Example:

$srcset = kdath_get_thumbnail_srcset( array( 'id' => 123 ), array( 300, 768, 1200 ) );

kdath_the_thumbnail_srcset( $args, $widths )

Echoes the srcset string.

Example:

kdath_the_thumbnail_srcset( array( 'id' => 123 ), array( 300, 768, 1200 ) );

kdath_get_thumbnail_url_from_meta( $post_id, $meta_key = '' )

Returns the thumbnail URL saved in the custom field configured in settings. Requires a Media Library attachment ID. If $meta_key is omitted, the globally configured field name is used.

Example:

echo kdath_get_thumbnail_url_from_meta( 123 );

kdath_the_thumbnail_url_from_meta( $post_id, $meta_key = '' )

Echoes the URL from the custom field.

Example:

echo kdath_the_thumbnail_url_from_meta( 123 );

KDATH_Thumbnail_Cache::clear_all()

Programmatically clear the entire cache. Useful after bulk imports or when you need to regenerate all thumbnails immediately.

Example:

KDATH_Thumbnail_Cache::clear_all();

Automatic content processing (no code required):

When the plugin is active, it automatically hooks into the_content and post_thumbnail_html. Images in post content that have one of the configured CSS classes (Settings в†’ “Classes for automatic caching”) are replaced with cached thumbnails. Featured images rendered by WordPress (including block themes like Twenty Twenty-Five) are also processed and can include srcset/sizes automatically.

If you prefer to apply this manually, use:

add_filter( 'the_content', function( $content ) {
    return KDATH_Thumbnail_Content_Processor::process( $content );
} );

This replaces standard <img> tags in post content with optimized thumbnails. Useful when you cannot edit theme templates directly.

Custom field for thumbnail URL

When “Custom field for thumbnail URL” (kdath_thumbs_url) is configured in Settings в†’ KDA Thumbnails, the plugin automatically saves the generated thumbnail URL into that post meta key for every Media Library attachment. This is useful if you want to access the URL via get_post_meta() without calling the plugin functions again.

Example:

update_post_meta( 123, 'kdath_thumbs_url', 'https://example.com/wp-content/uploads/kda-thumbnails/kdath_abc123_400x300.jpg' );

// Retrieve later:
$url = get_post_meta( 123, 'kdath_thumbs_url', true );

// Or via helper:
echo kdath_the_thumbnail_url_from_meta( 123 );

Settings reference

All settings are available under Settings в†’ KDA Thumbnails. No code is required.

General tab:

• Cache folder path — absolute server path or relative to wp-content/uploads/. Default: kda-thumbnails.
• Cache folder URL — public URL for the cache folder. Required when the path is outside the web root.
• Custom field for thumbnail URL — optional meta key name. When set, the plugin saves each generated thumbnail URL into this field for Media Library attachments.
• Organize cache by post type — saves thumbnails in subfolders per post type.
• Classes for automatic caching — comma-separated CSS classes. Images with these classes in post content are automatically replaced with cached thumbnails.
• Image library — choose GD, Imagick, or Auto.
• Output format — default format for generated thumbnails: JPEG, PNG, or WebP. Applies to all thumbnails, including srcset variants. Can be overridden per-request with the format parameter.
• Default quality — JPEG/WebP quality from 1 to 100. Higher values produce larger files. Can be overridden per-request with the quality parameter.
• Allow remote image sources — enable caching of external http(s) image URLs.
• Remote cache TTL (hours) — how long a downloaded remote image stays fresh.
• Max remote file size (MB) — limit for remote downloads.

Watermark tab:

• Enable copyright watermark — master switch.
• Copyright type — text or image.
• Copyright text — text for the watermark.
• Copyright image — URL or server path to an image file. Use the “Select Image” button to pick from the Media Library, or enter the full path manually.
• Copyright color — text color (hex).
• Outline width — stroke width in pixels around the text watermark. 0 = disabled.
• Copyright opacity (0-100) — transparency of the watermark.
• Copyright position — top-left, top-right, bottom-left, bottom-right, center.
• Copyright font size — size in pixels or percentage of the smaller image side.
• Auto-fit watermark text — automatically reduces font size so the text always fits inside the thumbnail width.
• Custom font path — absolute path to a .ttf or .otf font file.
• Copyright Google Font — pick from a curated list. Overrides the custom font path when set.

Responsive images tab:

• Responsive srcset — generate srcset and sizes attributes automatically.
• Srcset widths — comma-separated widths in pixels. A thumbnail is generated for each width.
• Sizes attribute — optional HTML sizes attribute value. Leave empty to omit.

Cache management tab:

• Cache size limit (MB) — 0 = unlimited. Oldest cached thumbnails are removed automatically when the limit is exceeded.
• Cache size — current total size of the cache folder.
• Clear all cache — delete all cached thumbnails.
• Clear cache by post type — when “Organize cache by post type” is enabled, clear individual post-type folders.

Debug & docs tab:

• Status — engine availability, cache directory, cached files count, watermark resource status.
• Usage — detailed reference for shortcodes, PHP functions, and cache management.

Notes

• Generated thumbnails live under wp-content/uploads/kda-thumbnails/ by default (configurable via Settings в†’ KDA Thumbnails).
• Downloaded Google Fonts live under wp-content/uploads/kda-thumbnails-fonts/.
• A thumbnail is regenerated automatically when the source file’s modification time changes, or when any watermark/copyright setting changes (the cache key includes the full watermark configuration).
• The plugin does not modify original images in the Media Library. Only cached copies are created.

External services

This plugin connects to the GitHub API (https://api.github.com) to list the contents of the google/fonts repository and locate the appropriate TrueType font files for the selected Google Font family. The font files are downloaded from GitHub’s raw content delivery network and cached locally under wp-content/uploads/kda-thumbnails-fonts/.

Data sent: The name of the selected Google Font family is included in the API URL path. No user-specific data is transmitted. Requests include a User-Agent header identifying the plugin.

Service provider: GitHub, Inc.

Terms of Service: https://docs.github.com/site-policy/github-terms/github-terms-of-service
Privacy Policy: https://docs.github.com/site-policy/privacy-policies/github-privacy-statement