Skip to content
Subset

For developers

Developer reference

Where the plugin will let you intervene — filters, actions and WP-CLI — and what is deliberately not extensible.

The extension points we intend to have

Image Resizer touches uploads, which is somewhere plugins collide. The extension surface is therefore small and deliberately positioned at the two moments where another plugin might reasonably need to disagree with us.

Decide whether to touch an upload at all

A filter that runs before anything is written, receiving the attachment context and returning a boolean. This is the one everybody needs: a site with a stock-photo importer, or a print-on-demand product that needs its 6000-pixel original, has to be able to say no.

<?php
/**
 * PLACEHOLDER — the filter name and signature are not final.
 * Skip resizing for anything uploaded into the product-artwork folder.
 */
add_filter(
	'subset_image_resizer_should_resize',
	function ( bool $should_resize, array $context ): bool {
		if ( str_contains( $context['relative_path'], '/product-artwork/' ) ) {
			return false;
		}

		return $should_resize;
	},
	10,
	2
);

Planned for 1.0.0Changelog

A per-upload opt-out filter ships with the free version. It is the one hook we consider non-negotiable, because without it the plugin is unusable on any site with a legitimate need for large originals.

Override the maximum dimensions per upload

The same shape, returning dimensions rather than a boolean, for the case where an upload should be capped differently rather than not at all.

<?php
// PLACEHOLDER — name and array shape are not final.
add_filter(
	'subset_image_resizer_max_dimensions',
	function ( array $max, array $context ): array {
		if ( 'banner' === ( $context['purpose'] ?? '' ) ) {
			return array( 'width' => 3840, 'height' => 2160 );
		}

		return $max;
	},
	10,
	2
);

WP-CLI

Bulk operations belong on the command line as well as in wp-admin: a run over fifty thousand attachments should not depend on a browser tab staying open.

# PLACEHOLDER — command names and flags are not final.
wp subset image-resizer regenerate --dry-run
wp subset image-resizer regenerate --since=2019-01-01 --format=webp
wp subset image-resizer prune-originals --older-than=90d

Every command that changes files will support --dry-run, and --dry-run will print what would change rather than a count. A migration tool that can only tell you “1,482 files affected” is a tool you cannot check before running.

What will deliberately not be extensible

Two things, and it is worth saying why in advance.

The encoder is not pluggable. Which library encodes a JPEG — Imagick, GD, or a binary on the host — is chosen by capability detection and not by a filter. Making it configurable turns every bug report into a question about the reporter’s environment, and the plugin cannot support an encoder nobody has tested.

The queue’s storage is not a public API. Progress is written somewhere, and where that is will change. Reading it from another plugin means a schema we have not promised, and the moment somebody depends on it we cannot fix the queue without breaking them. If you need progress, ask for an action to hook — that is a request we can honour.

Reporting an API you need

Issues are the roadmap. If you need a hook that is not here, the useful form of that request is a code sample of what you would write if it existed — that is the fastest way to establish whether the hook or the plugin is wrong.

github.com/function-form/subset/issues (opens in a new tab)