[00] Subset Sizes, For developers
Developer reference
Subset Sizes' WP-CLI commands, the filters and actions you can hook, and the server rules on-demand sizes need.
This page lists Subset Sizes’ main hooks and the server configuration on-demand sizes need, and links to its WP-CLI commands. Every hook uses the subir_ prefix, and Pro’s own hooks use subir_pro_.
WP-CLI
Every command lives under wp subset image-resizer. WP-CLI commands lists each one with its options, defaults and examples, free and Pro.
Suite hooks
These are stable. Their names and arguments only change in a major version, with a deprecation notice first.
| Hook | Type | When it runs |
|---|---|---|
subir_image_uploaded | action | Once per new image upload, after WordPress generates its metadata. Gets $attachment_id, $metadata. |
subir_size_generated | action | After the plugin creates a size file and merges it into the metadata. Gets $attachment_id, $size, $size_data. |
subir_media_panel_slots | filter | The read-only rows shown in the image details panel. |
subir_audit_data | filter | Shared audit data. The plugin adds an image_sizes section with generated and missing counts per size. |
subir_size_generated can fire during a front-end request while a visitor waits for the image. Queue slow work instead of doing it inline:
<?php
add_action(
'subir_size_generated',
function ( int $attachment_id, string $size, array $size_data ): void {
as_enqueue_async_action( 'my_compress_size', array( $attachment_id, $size ) );
},
10,
3
);
For registered sizes, $size is the size name. Sizes your code asks for by dimensions use keys such as subir-500x500-c.
Extension points
| Hook | Type | Use it to |
|---|---|---|
subir_registered_sizes | filter | Add or remove sizes the plugin will plan and generate. A removed size is never served. |
subir_kept_sizes | filter | Change which sizes are still made at upload in lazy sizes mode. Defaults to the Create at upload setting. |
subir_can_generate | filter | Decide whether the current request may generate sizes inline while rendering. |
subir_max_dimension | filter | Change the largest width or height the handler creates. Defaults to the Maximum dimension setting (4096). |
subir_resize_animated_gif | filter | Allow animated GIFs to be resized. Off by default, because resizing keeps only the first frame. |
subir_before_save_size | action | Set quality or process pixels on the resized image before it’s saved. |
subir_crop_focus | filter | Move the centre of a hard crop. Return x and y as fractions from the top left. |
subir_size_file_companions | filter | Add files that clean-orphans should delete along with a size file. |
subir_optimizer_adapters | filter | Register an adapter so your optimiser plugin is told about new sizes. |
subir_loaded | action | Register an add-on’s components once the plugin has loaded. |
subir_admin_tabs | filter | Add a tab to Subset → Image Sizes. Print its content with subir_admin_panel_{slug}. |
Add a size the plugin generates on demand even though WordPress doesn’t know about it:
<?php
use Subset\ImageResizer\Engine\SizeSpec;
add_filter(
'subir_registered_sizes',
function ( array $sizes ): array {
$sizes['og-image'] = new SizeSpec( 'og-image', 1200, 630, true );
return $sizes;
}
);
Keep a WooCommerce size ready at upload when lazy sizes is on:
<?php
add_filter(
'subir_kept_sizes',
function ( array $kept ): array {
$kept[] = 'woocommerce_thumbnail';
return $kept;
}
);
Tuning
| Hook | Default | What it controls |
|---|---|---|
subir_client_ip | REMOTE_ADDR | The IP the rate limit is keyed on. Return the real client IP behind a trusted proxy or CDN. |
subir_cache_control | public, max-age=31536000 | The Cache-Control header on a newly generated image. |
subir_lock_ttl | 60 seconds | How long a per-image lock lives before it’s treated as abandoned. |
subir_lock_wait | 10 seconds | How long a request waits for another request’s lock. A timeout returns 503. |
subir_lock_use_object_cache | wp_using_ext_object_cache() | Whether locks use the object cache. Turn it off if your cache isn’t shared between web servers. |
Behind Cloudflare, rate-limit by the visitor’s address:
<?php
add_filter(
'subir_client_ip',
function ( string $ip ): string {
return $_SERVER['HTTP_CF_CONNECTING_IP'] ?? $ip;
}
);
Only trust a header your proxy sets.
Pro hooks
| Hook | Type | Default | What it controls |
|---|---|---|---|
subir_pro_variant_quality | filter | 0 (editor default) | Quality of AVIF and WebP copies. Gets $quality, $mime, $base. |
subir_pro_picture_enabled | filter | true | Whether images on this request are wrapped in <picture>. |
subir_pro_prewarm_urls | filter | Home page and core sitemaps | The pages a pre-warm run visits. Add URLs here if an SEO plugin replaces the core sitemaps. |
subir_pro_prewarm_max_pages | filter | 500 | Most pages one pre-warm run visits. |
subir_pro_prewarm_auto | filter | true | Whether a theme switch or size change starts a pre-warm run by itself. |
subir_pro_transform_prefix | filter | img | The first path segment of signed transform URLs. |
subir_pro_usage_sample_rate | filter | 0.25 | Share of front-end page views whose size usage the audit records. |
subir_pro_usage_window | filter | 30 days | How long a size must go unseen before the audit counts it as unused. |
subir_pro_builder_active | filter | Builder constant defined | Whether Elementor or Bricks content counts as rendered for the audit. |
Lower the AVIF quality and leave WebP alone:
<?php
add_filter(
'subir_pro_variant_quality',
fn ( int $quality, string $mime ): int => 'image/avif' === $mime ? 55 : $quality,
10,
2
);
Signed transform URLs
Pro can serve any size of any image from a URL your site signed, such as /img/w_400,h_300,fit_crop/2026/09/photo.jpg?subir_sig=…. Build one in PHP:
<?php
use Subset\ImageResizerPro\Transforms\Transforms;
$url = Transforms::url( $attachment_id, array( 'w' => 400, 'h' => 300, 'fit' => 'crop' ) );
Parameters are w_<n>, h_<n>, and fit_crop or fit_scale (the default). fit_crop needs both dimensions and centres on the focal point when one is set. A missing or wrong signature returns 403, and dimensions above Maximum dimension return 400. Signatures use a key derived from your site’s salts, so changing the salts breaks every signed URL.
Server configuration
Missing size files must reach WordPress. Once a file exists, the web server serves it directly.
Apache, single site, pretty permalinks. The standard WordPress .htaccess already does this. Nothing else is needed.
Apache, plain permalinks. Switch to any other permalink structure, or add this to the root .htaccess:
# BEGIN Subset Image Resizer
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(wp-content/uploads/.+-[0-9]+x[0-9]+\.(jpe?g|png|gif|webp|avif))$ /index.php [NC,L]
</IfModule>
# END Subset Image Resizer
Apache, multisite. The network .htaccess sends every wp-content/… request straight to the file. Add this directly above that wp-(content|admin|includes) rule:
# BEGIN Subset Image Resizer
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(wp-content/uploads/.+-[0-9]+x[0-9]+\.(jpe?g|png|gif|webp|avif))$ index.php [NC,L]
# END Subset Image Resizer
nginx. Add this above your other image locations. It covers multisite uploads/sites/{id}/ paths too:
location ~* ^/wp-content/uploads/.+-[0-9]+x[0-9]+\.(jpe?g|png|gif|webp|avif)$ {
try_files $uri /index.php?$args;
expires max;
}
Pro AVIF and WebP copies. Requests for a copy that doesn’t exist yet must also reach WordPress. On nginx, add:
location ~* ^/wp-content/uploads/.+\.(jpe?g|png|gif|webp)\.(avif|webp)$ {
try_files $uri /index.php?$args;
expires max;
}
Your server must also send .avif files as image/avif. Older Apache and nginx builds may not know the type: add AddType image/avif .avif on Apache, or image/avif avif; to mime.types on nginx.
Pro “Same URLs” delivery on nginx. In the http {} block:
map $http_accept $subir_avif { default ""; "~*image/avif" ".avif"; }
map $http_accept $subir_webp { default ""; "~*image/webp" ".webp"; }
Then in the server {} block, above other image locations:
location ~* ^/wp-content/uploads/.+\.(jpe?g|png|gif)$ {
add_header Vary Accept;
try_files $uri$subir_avif $uri$subir_webp $uri /index.php?$args;
expires max;
}
Pro “Same URLs” delivery on Apache. Add this above the # BEGIN WordPress block. It needs mod_rewrite and mod_headers:
# BEGIN Subset Image Resizer Pro: formats
<IfModule mod_mime.c>
AddType image/avif .avif
AddType image/webp .webp
</IfModule>
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteCond %{HTTP_ACCEPT} image/avif
RewriteCond %{REQUEST_FILENAME}.avif -f
RewriteRule ^wp-content/uploads/.+\.(?:jpe?g|png|gif)$ %{REQUEST_URI}.avif [L]
RewriteCond %{HTTP_ACCEPT} image/webp
RewriteCond %{REQUEST_FILENAME}.webp -f
RewriteRule ^wp-content/uploads/.+\.(?:jpe?g|png|gif)$ %{REQUEST_URI}.webp [L]
</IfModule>
<IfModule mod_headers.c>
<If "%{REQUEST_URI} =~ m#^/wp-content/uploads/.+\.(?:jpe?g|png|gif)(?:\.(?:avif|webp))?$#">
Header merge Vary Accept
</If>
</IfModule>
# END Subset Image Resizer Pro: formats
Also check for an .htaccess inside wp-content/uploads/ that turns off rewriting (some security plugins add one), and for hosts that serve uploads from a static origin that never falls back to PHP.
Asking for a hook
If you need a hook that isn’t here, open an issue on the Subset feedback tracker (opens in a new tab) with the code you’d write if the hook existed. For other questions, email hello@subsetwp.com.