websk / php-imagemanager

3.0.0 2026-10-18 05:47 UTC

Requires

• php: ^8.3
• ext-fileinfo: *
• ext-gd: *
• ext-json: *
• ext-mbstring: *
• imagine/imagine: ^1.5.4
• websk/php-config: 2.2.*
• websk/php-simple-router: 3.0.*
• websk/php-utils: 3.0.*

Requires (Dev)

• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.5

MIT

Published on Packagist.org on 2026-10-18 05:47 UTC

README

Image upload, resizing, preset generation, and cached image delivery for WebSK applications.

Requirements

• PHP 8.3 or newer, including PHP 8.5
• GD, Fileinfo, JSON, and Mbstring extensions

Installation

composer require websk/php-imagemanager

Register the built-in routes during application bootstrap:

use WebSK\Image\ImageRoutes;

ImageRoutes::routes();

The default image root is files/images below $_SERVER['DOCUMENT_ROOT']. An absolute or document-root-relative directory can be passed to ImageManager explicitly:

use WebSK\Image\ImageManager;

$manager = new ImageManager('/srv/application/files/images');

Storing an image

$storedName = $manager->storeImageFile(
    'photo.jpg',
    '/tmp/source.jpg',
    'articles/42'
);

Target directories and image paths may contain letters, numbers, dots, underscores, and hyphens. Absolute paths and .. segments are rejected.

Presets

use WebSK\Image\ImageManager;
use WebSK\Image\ImagePresets;

$url = ImageManager::getImgUrlByPreset(
    'articles/42/photo.jpg',
    ImagePresets::IMAGE_PRESET_160_auto
);

Available presets are 604_331, 510_390, 800_600, 160_200, 800_800_auto, 600_auto, 400_auto, 200_auto, 160_auto, 120_auto, 40_40, 30_30, and upload.

The first request for a preset creates a cached file below files/images/cache. Writes use a temporary file followed by an atomic rename.

Upload validation

The bundled upload controller accepts GIF, JPEG, and PNG files. It validates the upload error, maximum size, detected MIME type, extension, decoded dimensions, and pixel count. The default limits are 20 MB and 40 million pixels.

A successful upload returns JSON containing name, size, url, thumbnailUrl, deleteUrl, and deleteType.

Remote images

storeRemoteImageFile() accepts HTTP and HTTPS URLs only. Private and reserved destination addresses, redirects, responses larger than 20 MB, and invalid images are rejected.

Development

composer install
composer check
composer audit --locked

composer check runs syntax checks, PHPUnit, and PHPStan at level max.

License

MIT. See LICENSE.