tomkirsch / superimage
SuperImage Library for CodeIgniter4
Requires
- php: ^8.0
- codeigniter4/framework: ^4
Requires (Dev)
- phpunit/phpunit: ^9.6 || ^10 || ^11
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-15 22:12:43 UTC
README
A modern responsive image library for CodeIgniter 4 with on-the-fly resizing, versioned cache filenames, and modern HTML output (<picture> / <img srcset>). By default (cacheBustingMethod = 'mtime'), stale requests are redirected (302) to the current versioned URL.
Requirements and formats
Requires PHP ^8.0, CodeIgniter ^4, and GD with the encoder for the selected output format.
The suite is tested on PHP 8.3.6 / CI4 4.7.0; the CI4 convert() API was also checked in 4.4.6–4.7.6.
Older CI4 versions and PHP 8.0 are not runtime-tested here; the dependency floors are unchanged.
Output formats are WebP, JPEG (jpg or jpeg), and PNG. Other output extensions,
including AVIF, return 404; AVIF output was never supported by CI4's GD handler.
Upgrading to 0.5
- Use
^0.5in consuming projects (this is not a 0.4.x patch). - Clear existing generated files once with
Services::resizer()->cleanAll(): older.webpcache files can contain JPEG bytes. Only run this against a dedicated cache directory;cleanAll()removes every file there, including.htaccessor unrelated files. - Separately remove any legacy
*.php,*.phtml, and*.htmlfiles from that cache directory if they remain (for example, in a different old cache root). - Replace the Apache rule below so only
(webp|jpe?g|png)variants use its fast path. - Off-ladder widths and stale versions now redirect with 302, not 301. Widths snap up to the
configured
widthLadder, capped by source width andmaxSize(ormaxSizewhen upscaling). The cap is also an allowed width: at mostcount(widthLadder) + 1widths per image per format. - The only new config options are
widthLadderandmaxSourcePixels(default 40 million). Outputs above 25 million pixels or 16383 pixels on either axis are rejected with 404. - Builder and fixed-list markup changes intentionally: builders use fluid
vwsizes andwdescriptors; fixed lists (including[150]) use an<img>with a fixedsizesslot equal to the smallest supplied width. Presets retain<picture>and gain a high-DPR phone fallback. resolutionStepmust be finite and positive;maxResolutionfinite and at least 1. Configurations requiring more than 1000 resolution increments are rejected instead of looping indefinitely.
Keep cachePath dedicated to generated images, outside source assets, and not writable by
untrusted users. No symlink/TOCTOU protection is provided for locally writable cache trees.
The cleanup helpers are unchanged: create the cache directory before calling cleanAll() or
cleanExpired(), and do not point them at a directory containing anything you need to keep.
Use numeric appVersion / cacheVersion values: the public URL grammar accepts digits only.
A per-render cacheVersion override still redirects to the server's configured version. Prefer
mtime (the default); time changes every second and is unsuitable for stable caching.
EXIF auto-orientation is not added; pre-orient phone JPEGs before using them as sources.
Install
composer require tomkirsch/superimage
Create app\config\SuperImage.php
These are some basic values. See vendor/tomkirsch/superimage/src/SuperImageConfig.php for all settings.
<?php namespace Config; class SuperImage extends \Tomkirsch\SuperImage\SuperImageConfig { public string $sourcePath = WRITEPATH . 'img/'; // where your hires assets live public string $cachePath = FCPATH . '_superimage_cache/'; // dedicated generated-image directory; public only for direct Apache caching public string $servingStrategy = 'htaccess'; // most efficient. falls back to php's readfile() public string $publicUrlPrefix = 'img/'; public string $defaultOutputExt = 'webp'; public bool $enableCacheBusting = true; public string $cacheBustingMethod = 'mtime'; // use mtime so updated images get automatically stale }
.htaccess serving (default)
True htaccess serving requires cached files to be in public. Add to .gitignore:
public/_superimage_cache/
Paste this after RewriteEngine ON:
# ============================================================================
# SUPERIMAGE SERVING
# ============================================================================
# These rules MUST come BEFORE CodeIgniter's main rewrite rules
# Match pattern: img/{anything}-w{number}-v{version}.{ext}
# Examples:
# /img/image_1.jpg-w1200-v1737063600.webp
# /img/products/photo.jpg-w800-v1737063600.jpg
# /img/blog/hero.jpg-w1920-v1737063600.png
# Check if the cached version of the requested image exists
# We use a look-ahead to capture the groups from the rule below
# NOTE: this will NOT work when serving via spark!
RewriteCond %{DOCUMENT_ROOT}/_superimage_cache/$1-w$2-v$3.$4 -f
# If it exists, serve it and stop (L)!
# (comment out the CI redirect to test true apache cache serving)
RewriteRule ^img/(.+)-w(\d+)-v(\d+)\.(webp|jpe?g|png)$ _superimage_cache/$1-w$2-v$3.$4 [L]
# ============================================================================
# CACHE HEADERS FOR IMAGES (Optional but Recommended)
# ============================================================================
# Sets proper caching headers for image files
# This works for both cached resizes AND original images
# ============================================================================
<IfModule mod_headers.c>
# Match image files
<FilesMatch "\.(webp|jpe?g|png)$">
# Cache for 1 year (versions are in filenames)
Header set Cache-Control "public, max-age=31536000, immutable"
# Security: Prevent hotlinking (optional - uncomment if needed)
# RewriteCond %{HTTP_REFERER} !^$
# RewriteCond %{HTTP_REFERER} !^https?://(www\.)?yourdomain\.com [NC]
# RewriteRule \.(webp|jpg|jpeg|png|gif)$ - [F,L]
</FilesMatch>
</IfModule>
NOTE!
You might need to change the path to the DOCUMENT_ROOT above to match your setup.
config/Services.php
public static function superImage(?array $options = null, ?SuperImageConfig $config = null): \Tomkirsch\SuperImage\SuperImage { $config = $config ?? new \Config\SuperImage(); $instance = new \Tomkirsch\SuperImage\SuperImage($config); if (!empty($options)) { $instance->load($options); } return $instance; } public static function resizer(?SuperImageConfig $config = null): \Tomkirsch\SuperImage\Resizer { $config = $config ?? new \Config\SuperImage(); return new \Tomkirsch\SuperImage\Resizer($config); }
config/Routes.php
<?php use CodeIgniter\Router\RouteCollection; /** * @var RouteCollection $routes */ $routes->get('/', 'Home::index'); $routes->get('img/(.+)', 'Home::serveImage/$1'); // optional - cache management
controllers/Home.php
/** * Serve image request */ public function serveImage(...$path) { $path = implode("/", $path); \Config\Services::resizer()->serve($path); }
View
The src parameter must be a relative base filename with extension:
'src' => 'hero.jpg' // relative base name with extension 'src' => 'product_1.jpg' // relative base name with extension 'src' => 'products/photo_1.png' // relative base name with subdirectory and extension
The source path is resolved from your config's $sourcePath setting.
Supported render() options (current SuperImage class)
src is an alias for file.
src/fileoutputExt(webp,jpg,jpeg,png)widths('full','half','third','quarter','two-thirds', builder, array, or decimal fraction)gutter,static,maxResolution,resolutionStepmaxWidth,maxHeight(supports'source')loading('lazy' | 'eager' | 'auto')fetchPriority('high' | 'low' | 'auto')alt,cacheVersion,pictureAttr,imgAttr,prettyPrint
Set loading behavior carefully to avoid writing too many variants during a single page load. Above-fold:
<?= \Config\Services::superImage()->render([ 'src' => 'hero.jpg', 'widths' => 'full', 'loading' => 'eager', 'fetchPriority' => 'high' ]) ?>
Below-fold:
<?= \Config\Services::superImage()->render([ 'src' => 'product_1.jpg', 'widths' => 'full', 'loading' => 'lazy', 'fetchPriority' => 'low', ]) ?>
Resizer utility methods
From \Config\Services::resizer():
serve(string $requestPath): voidcleanExpired(): intcleanImage(string $basePath): intcleanAll(): int
Testing .htaccess serving
Bring up an image in the browser, so it writes the cache file. Verify file is written. Comment out the CI rewrite, clear cache, and refresh the browser. You should NOT see X-Superimage-Cache in development a env - this means the file is being served by .htaccess!
If you still see X-Superimage-Cache header...
Mess with the DOCUMENT_ROOT paths until it goes away.
View Examples
Hero — above the fold, full width
<?= \Config\Services::superImage()->render([ 'src' => 'hero.jpg', 'alt' => 'Hero image', 'widths' => 'full', 'loading' => 'eager', 'fetchPriority' => 'high', ]) ?>
Product grid — three columns with gutter
<?php for ($i = 1; $i <= 3; $i++): ?> <?= \Config\Services::superImage()->render([ 'src' => "product_$i.jpg", 'alt' => "Product $i", 'widths' => 'third', 'gutter' => 30, 'loading' => $i === 1 ? 'eager' : 'lazy', ]) ?> <?php endfor; ?>
Responsive layout — full → half → third across breakpoints
Use SuperImageWidths when the image occupies different fractions of the viewport at different screen sizes. Each at() call is a min-width, matching CSS media query logic.
<?= \Config\Services::superImage()->render([ 'src' => 'featured.jpg', 'alt' => 'Featured article', 'loading' => 'lazy', 'widths' => \Tomkirsch\SuperImage\SuperImageWidths::make() ->full() // 0px+: 100% (mobile) ->at(800, 'half') // 800px+: 50% (tablet) ->at(1024, 'third') // 1024px+: 33% (desktop) ]) ?>
Builder output is an <img> with width-descriptor candidates from the bounded ladder and
sizes="(min-width: 1024px) 33.3333vw, (min-width: 800px) 50vw, 100vw".
Fractions remain fluid at wider viewports; px(1200, 360) can specify a fixed slot.
If every slot is pixel-based (including an explicit mobile px(0, N)), candidates honor
maxResolution and resolutionStep, rounded up to canonical ladder widths.
Fluid or mixed builders use the full safe ladder to cover arbitrary viewport widths; a single
width-descriptor srcset cannot enforce a per-slot DPR ceiling there, so maxResolution does
not limit those builders. A single fixed pixel slot has a bounded candidate ceiling; when
multiple different pixel slots share a srcset, candidates are bounded relative to each supplied
slot, but the browser may select a larger slot's candidate. Presets use per-breakpoint density
srcsets when a per-slot ceiling is needed.
Subclasses overriding resolve(int $gutter = 0): array retain pixel-map sizes and bounded density candidates.
gutter subtracts pixels using calc() (clamped to at least 1px).
Raw decimals and gutter also work:
'widths' => \Tomkirsch\SuperImage\SuperImageWidths::make() ->at(0, 1.0) ->at(768, 0.6) ->at(1200, 0.4), 'gutter' => 24,
Reuse config across multiple images with load()
<?php $si = \Config\Services::superImage()->load([ 'widths' => 'quarter', 'loading' => 'lazy', 'gutter' => 16, ]); ?> <?= $si->render(['src' => 'gallery/photo-1.jpg', 'alt' => 'Photo 1']) ?> <?= $si->render(['src' => 'gallery/photo-2.jpg', 'alt' => 'Photo 2']) ?> <?= $si->render(['src' => 'gallery/photo-3.jpg', 'alt' => 'Photo 3']) ?>
Static <img srcset> for fixed-size images (avatars, icons)
<?= \Config\Services::superImage()->render([ 'src' => 'avatar.jpg', 'alt' => 'User avatar', 'static' => true, 'widths' => [100, 200, 300], 'imgAttr' => ['class' => 'rounded-circle'], ]) ?>
Plain URL for CSS backgrounds
$url = \Config\Services::superImage()->imgUrl(800, ['src' => 'banner.jpg']);
<div style="background-image: url('<?= $url ?>')"></div>