Automated Adapive Image solution
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


What is it?

This is the standalone PHP implementation of "3-layer technique" for Adaptive Images generation. See for technical explanations and justifications (french version available : <>)


PHP>=5.1 with GD library (if PHP<5.3.0 extending AdaptiveImages also needs to override method getInstance())


Simple use-case

Call adaptHTMLPage method on your HTML page with optional maximum display width of images in your HTML page.

require_once "AdaptiveImages.php"
$AdaptiveImages = AdaptiveImages::getInstance();
$html = $AdaptiveImages->adaptHTMLPage($html,780);

First view of page with adaptive Images can timeout due to all the images to generate. Reload the page to complete image generation.


If your CMS/application allow caching of HTML part of pages, apply adaptHTMLPart method on this part in order to cache Adaptive Images

require_once "AdaptiveImages.php"
$AdaptiveImages = AdaptiveImages::getInstance();
return $AdaptiveImages->adaptHTMLPart($texte, 780);

then recall adaptHTMLPage method on full HTML page to finish the job

$AdaptiveImages = AdaptiveImages::getInstance();
$html = $AdaptiveImages->adaptHTMLPage($html,780);

URL vs filepath

By default AdaptiveImages considers that relative URLs are also relative file system path. If this is not the case in your URL scheme, you can override the 2 methods URL2filepath and filepath2URL that are used to make transpositions.

In the following example we transpose absolutes URLs to relative file system path and, if defined we add special domain _ADAPTIVE_IMAGES_DOMAIN to file path in the final URL (domain sharding)

class MyAdaptiveImages extends AdaptiveImages {
	protected function URL2filepath($url){
		$url = parent::URL2filepath($url);
		// absolute URL to relative file path
		if (preg_match(",^https?://,",$url)){
			$base = url_de_base();
			if (strncmp($url,$base,strlen($base))==0)
				$url = _DIR_RACINE . substr($url,strlen($base));
			elseif (defined('_ADAPTIVE_IMAGES_DOMAIN')
				$url = _DIR_RACINE . substr($url,strlen(_ADAPTIVE_IMAGES_DOMAIN));
		return $url;

	protected function filepath2URL($filepath){
		$filepath = parent::filepath2URL($filepath);
		if (defined('_ADAPTIVE_IMAGES_DOMAIN')){
			$filepath = rtrim(_ADAPTIVE_IMAGES_DOMAIN,"/")."/".$filepath;
		return $filepath;
$AdaptiveImages = MyAdaptiveImages::getInstance();

Markup Hook

If source <img/> has some inline styles, it can be needed to add some wrapper and put the style on it on order to keep initial visual result. This can be done in overriding the method imgMarkupHook(&$markup,$originalClass,$originalStyle). It is call with following arguments

  • partial adaptive markup (only the <span> wrapper with the fallback <img/> inside)
  • the original class attribute of <img/>
  • the original style attribute of <img/>

The method must return the partial markup, with your modifications.

OnDemand images generation

To avoid timeout on first view of HTML page you can activate OnDemand images generation. In this case, only URL of adapted images will be computed, and you need to use a Rewrite Rules and a router to call AdaptiveImages::deliverBkptImage.

For instance with SPIP CMS :

Rewrite Rule

# If file or directory exists deliver it and ignore others rewrite rules
RewriteCond %{REQUEST_FILENAME} -f
RewriteRule "." - [skip=100]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule "." - [skip=100]

# Adaptive Images : call action_adapt_img_dist() function if image not available

RewriteRule \badapt-img/(\d+/\d\dx/.*)$ spip.php?action=adapt_img&arg=$1 [QSA,L]

# Fin des Adaptive Images


function action_adapt_img_dist(){

	$AdaptiveImages = AdaptiveImages::getInstance();
	try {
	catch (Exception $e){
		die('Error : '.$e->getMessage());

Advanced Configuration

  • Directory for storing adaptive images
    $AdaptiveImages->destDirectory = "local/adapt-img/";
  • Default Maximum display width for images
    $AdaptiveImages->maxWidth1x = 640;
  • Minimum display width for adaptive images (smaller will be unchanged)
    $AdaptiveImages->minWidth1x = 320;
  • Maximum width for delivering mobile version in data-src-mobile=""
    $AdaptiveImages->maxWidthMobileVersion = 320;
  • Activade On-Demand images generation
    $AdaptiveImages->onDemandImages = true;
  • Background color for JPG lowsrc generation (if source has transparency layer)
    $AdaptiveImages->lowsrcJpgBgColor = '#eeeeee';
  • Breakpoints width for image generation
    $AdaptiveImages->defaultBkpts = array(160,320,480,640,960,1440);
  • Allow progressive rendering og PNG and GIF even without JS :
    $AdaptiveImages->nojsPngGifProgressiveRendering = true;
  • JPG compression quality for JPG lowsrc
    $AdaptiveImages->lowsrcJpgQuality = 10;
  • JPG compression quality for 1x JPG images
    $AdaptiveImages->x10JpgQuality = 75;
  • JPG compression quality for 1.5x JPG images
    $AdaptiveImages->x15JpgQuality = 65;
  • JPG compression quality for 2x JPG images
    $AdaptiveImages->x15JpgQuality = 45;
  • GD maximum px size (width x height) of image that can be manipulated without Fatal Memory Error (0=no limit)
    $AdaptiveImages->maxImagePxGDMemoryLimit = 2000*2000;

Real-life use case

This library is already available through plugins in: