jmultimidia / thumb

v1.0.0 2026-09-29 22:20 UTC

Requires

• php: >=8.1
• ext-gd: *

MIT

• Johannes Nogueira

• image
• cache
• thumbnail
• resize
• crop
• Webp
• avif

Published on Packagist.org on 2026-09-29 22:49 UTC

README

A lightweight, high-performance on-the-fly thumbnail generator for PHP with automatic AVIF and WebP caching, smart cropping, and HTTP 304 conditional cache support.

Features

• Next-Gen Formats: Automatically outputs AVIF (with WebP fallback) for minimum payload sizes.
• Smart Aspect-Ratio Cropping: Crops and resizes images to exact dimensions without distortion.
• High-Performance Caching: Saves generated images to disk and serves cached copies directly.
• HTTP Cache Headers: Built-in Cache-Control, ETag, Last-Modified, and 304 Not Modified browser validation.
• Download-Friendly: Sends RFC 6266 Content-Disposition so users saving the image keep the original filename.
• Security Built-In: Validates real paths to prevent Directory Traversal (LFI) attacks.
• Zero Framework Lock-in: Works with vanilla PHP, Bramus Router, Laravel, Slim, Symfony, etc.

Requirements

• PHP >= 8.1
• GD Extension with AVIF / WebP support (php-gd)

Installation

composer require jmultimidia/thumb

Quick Start

1. Configuration (Optional)

Configure global paths once during application bootstrap (e.g., index.php or a service provider):

use JMultimidia\Thumb\Thumb;

Thumb::config([
    'cache_dir'     => __DIR__ . '/storage/images/cache',
    'document_root' => __DIR__ . '/public',
    'default_image' => 'https://example.com/assets/placeholder.png',
    'quality'       => 85, // 1 to 100
]);

2. Basic Usage (Vanilla PHP / Procedural)

use JMultimidia\Thumb\Thumb;

// Serves the image directly to the browser and terminates execution
Thumb::serve(
    imagePath: '/storage/images/sample.jpg',
    width: 600,
    height: 300,
    quality: 80
);

3. Routing Examples

Bramus Router

$router->get('/image/thumb/w/(\d+)/h/(\d+)/(.+)', function ($w, $h, $image) {
    \JMultimidia\Thumb\Thumb::serve('/' . ltrim($image, '/'), (int)$w, (int)$h);
});

Laravel

Route::get('/image/thumb/w/{w}/h/{h}/{image}', function ($w, $h, $image) {
    \JMultimidia\Thumb\Thumb::serve('/' . ltrim($image, '/'), (int)$w, (int)$h);
})->where('image', '.*');

License

This package is open-sourced software licensed under the MIT license.