Documentation

ImageFlow

Adaptive image delivery

ImageFlow turns high-quality source images into fast first paint, responsive upgrades, theme-aware image pairs and cache-controlled delivery. Built for shared hosting, stronger on servers.

PHP + JS v1.0.0 Shared hosting Cached WebP/AVIF

Get ImageFlow - €19 one-time

Installation

Copy the runtime files, create one user-owned config, and keep generated variants out of your asset folders.

FILES

imageflow.php
imageflow.js
imageflow.css
imageflow.config.example.php

SHELL

cp imageflow.config.example.php imageflow.config.php
mkdir -p storage/imageflow-cache
chmod 755 storage/imageflow-cache

Quick Start

HTML

<link rel="stylesheet" href="/imageflow.css">
<script src="/imageflow.js" defer></script>

<img
  data-imageflow
  src="/imageflow.php?src=%2Fassets%2Fphoto.jpg&profile=low&format=auto"
  data-iflow-src="/assets/photo.jpg"
  data-iflow-high-profile="high"
  data-iflow-sizes="100vw"
  width="1600"
  height="1000"
  alt="">

<script>
  window.imageFlow = ImageFlow.auto();
</script>

Core Concepts

One config: PHP reads imageflow.config.php; JS loads the public section through /imageflow.php?config=1.

Profiles keep generated variants predictable: low, medium, high, card and hero.

Capability-aware delivery uses GD by default, Imagick when available, and falls back safely.

Dark/light image pairs can preload the opposite theme after the current theme is ready.

Configuration

PHP

return [
  'enabled' => true,
  'allowed_paths' => ['/assets/'],
  'cache_dir' => __DIR__ . '/storage/imageflow-cache',
  'format' => 'auto',
  'processor' => 'auto',
  'public' => [
    'mode' => 'marked',
    'endpoint' => '/imageflow.php',
  ],
];

Profiles & Cache

ImageFlow only creates variants that are requested. Width and quality values are snapped to allowed steps, which prevents random URLs from creating thousands of near-duplicates.

Profile	Width	Quality
low	384	35
card	960	68
high	1600	82
hero	1920	82

Theme Pairs

Use data-iflow-src-dark and data-iflow-src-light when an image should follow your theme. ImageFlow manages the image itself, so Nightwave and other theme systems can skip data-imageflow images.

HTML

<img
  data-imageflow
  src="/imageflow.php?src=%2Fassets%2Fpreview-dark.png&profile=low&format=auto"
  data-iflow-src-dark="/assets/preview-dark.png"
  data-iflow-src-light="/assets/preview-light.png"
  data-iflow-high-profile="card"
  data-iflow-sizes="(max-width: 760px) 100vw, 33vw"
  alt="">

API & Endpoints

The PHP endpoint exposes JSON helpers for setup checks and custom dashboards.

URL

/imageflow.php?health=1
/imageflow.php?config=1
/imageflow.php?stats=1

CLI

The CLI is optional. It is useful on servers for health checks, stats, cleanup and warming the cache before visitors arrive.

SHELL

php tools/imageflow-cli.php health --url=https://example.com/imageflow.php
php tools/imageflow-cli.php stats --url=https://example.com/imageflow.php
php tools/imageflow-cli.php cleanup
php tools/imageflow-cli.php warmup --url=https://example.com/imageflow.php --profiles=low,high --formats=auto --limit=200

Video-ready Docs

The docs system supports embedded videos. ImageFlow itself remains image-only; future VideoFlow/AudioFlow modules can use the same documentation components.

PHP<?php docs_video('/assets/docs/demo.mp4', 'ImageFlow walkthrough'); ?>

Common Issues

Cache folder is not writable

Set cache_dir to a folder PHP can write to, for example storage/imageflow-cache, then create it with the right permissions.

AVIF is not being served

AVIF requires server support. /imageflow.php?health=1 shows whether GD or Imagick can write AVIF. If not, ImageFlow falls back to WebP or JPEG.

The first request feels slower

The first uncached request generates the variant. Use the CLI warmup command on servers, or let the on-demand cache fill naturally on shared hosting.

Changelog

v1.0.0

2026-04-29

Adaptive low-to-high image delivery
Profiles, srcset, theme-pair preload and cache limits
GD/Imagick, WebP/AVIF capability detection
Health, stats JSON, CLI warmup and cleanup