=== Subset Sizes ===
Contributors: functionform
Tags: image sizes, thumbnails, regenerate thumbnails, webp, performance
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 0.9.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Generate image sizes on demand. Skip sizes at upload or delete them safely: any missing size is created the first time it's requested.

== Description ==

Every theme and plugin can register image sizes, and WordPress creates every one of them for every upload, whether a page ever uses it or not. Subset Sizes turns that around: sizes are created when they're first needed.

* **On-demand sizes.** When a browser requests a size file that doesn't exist (`photo-600x400.jpg`), the plugin creates it, saves it where the web server will serve it directly next time, and records it in the attachment's metadata.
* **Lazy sizes mode.** Uploads create only the sizes you keep (thumbnail and medium by default). Everything else is made on first request. Uploads are faster and the uploads folder stays smaller.
* **Delete sizes safely.** Because a missing size is regenerated when requested, removing size files never leaves broken images.
* **Size changes reach old posts.** Change a size in Settings → Media and images already in posts use the new dimensions, without re-saving posts or bulk regenerating.
* **Complete srcset.** Responsive image srcset includes every matching size, generated or not.
* **Correct output.** Same dimensions and crops as WordPress itself for named sizes, `[825, 825]` arrays cropped to that proportion, EXIF rotation applied, never upscaled, PNG transparency kept, animated GIFs left intact.
* **WebP and AVIF.** Respects the `image_editor_output_format` filter.
* **Safe under load.** A per-image lock stops concurrent requests from generating twice or losing metadata.
* **Abuse guards.** Only registered sizes, and sizes the site itself asked for, are generated. There is a maximum dimension and a per-visitor rate limit.
* **Works with your stack.** Hands new sizes to ShortPixel, Imagify, and EWWW for compression, and supports media offload plugins such as WP Offload Media.
* **Optional background mode.** Serve a larger existing size with the same aspect ratio while the new size is made in the background.
* **WP-CLI.** `wp subset image-resizer generate`, `clean-orphans`, `stats`, `self-test`, and `settings`.
* **Site Health.** Server setup problems and failed offload downloads are reported in Tools → Site Health, never as admin notices.

Settings live under **Subset → Image Sizes**, which also lists every registered size and which theme or plugin registered it.

The plugin makes no requests to outside services. With a media offload plugin active, it may download an attachment's original from the site's own offloaded storage to create a size.

== Installation ==

1. Install and activate the plugin from **Plugins → Add New**, or upload the zip.
2. Visit **Subset → Image Sizes** to choose which sizes to create at upload.

Missing size files are caught by a WordPress rewrite rule, so pretty permalinks must be enabled. On most Apache hosts nothing else is needed.

**nginx:** nginx usually serves `/wp-content/uploads/` directly and returns its own 404 for missing files, so requests never reach WordPress. Pass missing upload files to WordPress:

`location ~* ^/wp-content/uploads/.+-[0-9]+x[0-9]+\.(jpe?g|png|gif|webp|avif)$ { try_files $uri /index.php?$args; }`

Server examples for Apache, nginx, and legacy multisite networks are in the developer documentation linked below.

== Frequently Asked Questions ==

= Does it work on nginx? =

Yes, with one `try_files` rule so missing upload files reach WordPress. See Installation.

= How do I know my server is set up correctly? =

Open **Tools → Site Health**. The plugin requests a test image from your site and reports whether requests for missing sizes reach WordPress. If they don't, it links to the server rule to add; until then, sizes are created while pages render, so images still work but first views are slower. WordPress repeats the check weekly, and `wp subset image-resizer self-test` runs it from the command line. If a media offload plugin's originals couldn't be downloaded to create a size, Site Health reports that too.

= What happens to sizes that already exist? =

Nothing. Existing files and metadata are used as they are. Only missing sizes are generated.

= Does it work with image optimization plugins? =

ShortPixel, Imagify, and EWWW are told about each new size so they can compress it. Other optimizers can hook `subir_size_generated`, which fires after the size is saved to the attachment metadata.

= Does it work with media offload plugins? =

Yes. With WP Offload Media, the original is copied back from the bucket to create the size, and the new size is handed to WP Offload Media to upload. With other offload plugins the original is downloaded from its URL. If a size can't be created, visitors get the full image instead of a broken one.

= Should I turn on background (async) mode? =

Usually not. Background jobs run on WP-Cron, which only runs when the site gets visits, so on low-traffic sites jobs can wait a long time. By default a missing size is created during the request for the image file, which takes a fraction of a second once.

= Which WP-CLI commands are there? =

`wp subset image-resizer generate [--size=<names>] [--ids=<ids>]` creates missing sizes. `wp subset image-resizer clean-orphans [--dry-run]` removes size files no registered size uses. `wp subset image-resizer stats` shows sizes, files, and disk usage. `wp subset image-resizer self-test` checks that requests for missing sizes reach WordPress.

`wp subset image-resizer settings list|get|set|reset` reads and changes the settings on Subset → Image Sizes, for example `wp subset image-resizer settings set lazy_mode true`. Values are checked the same way the settings screen checks them, and settings locked by the network can't be changed.

= Can someone fill my disk by requesting random sizes? =

No. Only registered sizes, and sizes the site itself has asked for, are generated. Other dimensions return 404 and write nothing. A maximum dimension and a per-visitor rate limit also apply.

= What does uninstalling remove? =

All settings and internal data. Generated size files stay, because they are ordinary WordPress image sizes.

= Where is the developer documentation? =

Hooks, server configuration and optimizer integration are documented in the plugin's `docs` folder: `hooks.md`, `server-config.md` and `optimizers.md`.

= I uploaded the new version by hand and now see Subset Sizes twice =

Before 0.6.0 the plugin lived in a folder called `subset-image-resizer`, so uploading 0.6.0 adds it next to the old copy instead of replacing it. Both copies use the same settings. Deactivate the old copy, then delete it: the Plugins screen marks which one is the old copy. If you update through the Subset Installer you won't see this, because the update replaces the old folder.

== Screenshots ==

1. Subset → Image Sizes: every registered size with its dimensions, crop, and who registered it.
2. Settings: lazy sizes, sizes kept at upload, generation mode, and limits.

== Changelog ==

= 0.9.1 =
* Security: The Subset menu and its Overview page now need the same capability as a Subset page you can open, so a subscriber no longer reaches the Overview.
* Changed: Built on subset-core 1.13.3.

= 0.9.0 =
* Changed: An image requested with both dimensions, such as `[825, 825]`, is now cropped to that proportion. To scale it instead, set one dimension to 0, such as `[825, 0]`. Images requested this way change shape after updating, so clear any page cache.

= 0.8.1 =
* Changed: Built on subset-core 1.13.2.

= 0.8.0 =
* Fixed: With `WP_DEBUG_DISPLAY` on, a database error printed while a size was being made no longer lands in front of the image, which showed up as a broken or cut-off image.
* Changed: The sizes table on the settings screen scrolls with the style the other Subset plugins share. It looks the same.
* Changed: Built on subset-core 1.13.0.

= 0.7.0 =
* Changed: Add-ons now hook `subir_admin_tab_{slug}`; the old `_admin_panel_` hook still works but is deprecated.
* Changed for developers: `subir_admin_enqueue` and `current_tab()` now pass `settings` for the Settings tab, where they used to pass an empty string.
* Under the hood: shares more code with the other Subset plugins.

= 0.6.1 =
* Fixed: A copy of 0.6.0 running from the old folder, as on some development sites, no longer stops with an error on load.

= 0.6.0 =
* Changed: The plugin now lives in a `subset-sizes` folder, with the text domain `subset-sizes`. If you update through the Subset Installer, nothing changes for you: the update moves it and keeps it active. Settings, size files, server rules and integrations keep working.
* New: If you upload this version by hand, it lands next to the old `subset-image-resizer` copy. It waits until you deactivate the old copy, then takes over with the same settings, and the Plugins screen and Site Health tell you to delete the old copy.
* Changed: Built on subset-core 1.10.0.

= 0.5.6 =
* Fixed: `wp help` for the `settings` command is written for users, and its examples use this plugin's own command.
* Changed: Built on subset-core 1.9.1.

= 0.5.5 =
* Fixed: WordPress no longer logs a "translation loading was triggered too early" notice for this plugin on admin pages.
* Changed: Built on subset-core 1.9.0.

= 0.5.4 =
* Changed: The image count for the suite's shared audit now runs in the background on WP-Cron, so the page that asks for it no longer waits while every image is scanned. Until the first count finishes, the audit shows no images.
* Fixed: The sizes table on the Image Sizes screen shows a focus outline when you tab to it.
* Changed: Subset Sizes Pro can reuse more of this plugin's code instead of keeping its own copies.
* Changed: Built on subset-core 1.8.1.

= 0.5.3 =
* Changed: The plugin is now called Subset Sizes. Settings and data are unchanged.

= 0.5.2 =
* Changed: The About tab uses plain WordPress admin styling.

= 0.5.1 =
* Fixed: on the Image Sizes settings screen, each network-locked setting now has a clear name for screen readers, locked notes link to the setting they explain, and the sizes table scrolls on narrow screens.

= 0.5.0 =
* Changed: Image Sizes moved from Settings to the new shared Subset menu. The old Settings URL redirects.

= 0.4.0 =
* New: add-ons can add tabs and sections to Settings > Image Sizes through new admin hooks.

= 0.3.0 =
* New: the `subir_loaded` action, which add-ons use to register their own components.
* Changed: Pro features now ship as a separate add-on, Subset Image Resizer Pro, which loads on top of this plugin. Settings and licence keys carry over.

= 0.2.0 =
* New: an About tab with a short introduction to Subset and a link to subsetwp.com.

= 0.1.0 =
* First release: on-demand sizes, lazy sizes mode, srcset fill-in, block image support, WebP/AVIF, per-image locking, abuse guards, optimizer and offload compatibility, background mode, WP-CLI commands, and the Image Sizes screen.

== Upgrade Notice ==

= 0.1.0 =
First release.
