kaiseki/wp-image-sizes

Register, configure and remove WordPress image sizes, including aspect-ratio-based size sets

1.0.0 2026-06-01 09:51 UTC

Requires

• php: ^8.2
• kaiseki/config: ^2.0
• kaiseki/wp-hook: ^2.0
• psr/container: ^1.1 || ^2.0

Requires (Dev)

• bnf/phpstan-psr-container: ^1.1
• kaiseki/php-coding-standard: ^1.0
• maglnet/composer-require-checker: ^4.0
• php-stubs/wordpress-stubs: ^6.2
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^11.0
• roave/security-advisories: dev-latest
• roots/wordpress-core-installer: *
• roots/wordpress-no-content: @stable
• szepeviktor/phpstan-wordpress: ^2.0
• thecodingmachine/phpstan-safe-rule: ^1.4

MIT

• Kaiseki
• David Mondok
• Wolfgang Schaefer

README

Register, configure and remove WordPress image sizes, including aspect-ratio-based size sets.

Driven by the image_sizes config key and wired through ConfigProvider: set the built-in size dimensions, register custom sizes, generate whole families of sizes from an aspect ratio and a list of widths, tune the big-image threshold, and remove unwanted core sizes.

Installation

composer require kaiseki/wp-image-sizes

Requires PHP 8.2 or newer.

Usage

Register ConfigProvider with your laminas-style config aggregator and configure the image_sizes key:

use Kaiseki\WordPress\ImageSizes\AspectRatio;
use Kaiseki\WordPress\ImageSizes\ImageSize;

return [
    'image_sizes' => [
        // Built-in sizes: [width, height, crop] or null to leave untouched.
        'thumbnail'    => [150, 150, true],
        'medium'       => [300, 300, false],
        'medium_large' => null,
        'large'        => [1024, 1024, false],

        // Additional custom sizes.
        'image_sizes' => [
            new ImageSize('hero', 1600, 900, true),
        ],

        // Generate one ImageSize per width from a name + aspect ratio.
        'aspect_ratios' => [
            (new AspectRatio('card-', 4, 3, []))->withWidths(320, 640, 960),
        ],

        // Override the 2560px "big image" threshold (or false to disable scaling).
        'big_image_threshold' => 2560,

        // Core/registered sizes to remove.
        'remove_sizes' => ['1536x1536', '2048x2048'],
    ],
];

ConfigProvider registers factories for WpImageSizes (applies the size configuration), ImageSizesRegistry, BigImageSizeThreshold (the big_image_size_threshold filter) and RemoveImageSizes (removes sizes and filters them out of intermediate_image_sizes). An AspectRatio expands a ratio and a set of widths into individual ImageSizes via createImageSizes().

Development

composer install
composer check   # check-deps, cs-check, phpstan

License

MIT — see LICENSE.