Skip to content

[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.

HookTypeWhen it runs
subir_image_uploadedactionOnce per new image upload, after WordPress generates its metadata. Gets $attachment_id, $metadata.
subir_size_generatedactionAfter the plugin creates a size file and merges it into the metadata. Gets $attachment_id, $size, $size_data.
subir_media_panel_slotsfilterThe read-only rows shown in the image details panel.
subir_audit_datafilterShared 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

HookTypeUse it to
subir_registered_sizesfilterAdd or remove sizes the plugin will plan and generate. A removed size is never served.
subir_kept_sizesfilterChange which sizes are still made at upload in lazy sizes mode. Defaults to the Create at upload setting.
subir_can_generatefilterDecide whether the current request may generate sizes inline while rendering.
subir_max_dimensionfilterChange the largest width or height the handler creates. Defaults to the Maximum dimension setting (4096).
subir_resize_animated_giffilterAllow animated GIFs to be resized. Off by default, because resizing keeps only the first frame.
subir_before_save_sizeactionSet quality or process pixels on the resized image before it’s saved.
subir_crop_focusfilterMove the centre of a hard crop. Return x and y as fractions from the top left.
subir_size_file_companionsfilterAdd files that clean-orphans should delete along with a size file.
subir_optimizer_adaptersfilterRegister an adapter so your optimiser plugin is told about new sizes.
subir_loadedactionRegister an add-on’s components once the plugin has loaded.
subir_admin_tabsfilterAdd 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

HookDefaultWhat it controls
subir_client_ipREMOTE_ADDRThe IP the rate limit is keyed on. Return the real client IP behind a trusted proxy or CDN.
subir_cache_controlpublic, max-age=31536000The Cache-Control header on a newly generated image.
subir_lock_ttl60 secondsHow long a per-image lock lives before it’s treated as abandoned.
subir_lock_wait10 secondsHow long a request waits for another request’s lock. A timeout returns 503.
subir_lock_use_object_cachewp_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

HookTypeDefaultWhat it controls
subir_pro_variant_qualityfilter0 (editor default)Quality of AVIF and WebP copies. Gets $quality, $mime, $base.
subir_pro_picture_enabledfiltertrueWhether images on this request are wrapped in <picture>.
subir_pro_prewarm_urlsfilterHome page and core sitemapsThe pages a pre-warm run visits. Add URLs here if an SEO plugin replaces the core sitemaps.
subir_pro_prewarm_max_pagesfilter500Most pages one pre-warm run visits.
subir_pro_prewarm_autofiltertrueWhether a theme switch or size change starts a pre-warm run by itself.
subir_pro_transform_prefixfilterimgThe first path segment of signed transform URLs.
subir_pro_usage_sample_ratefilter0.25Share of front-end page views whose size usage the audit records.
subir_pro_usage_windowfilter30 daysHow long a size must go unseen before the audit counts it as unused.
subir_pro_builder_activefilterBuilder constant definedWhether 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.