PHPackages                             jkphl/responsive-images-css - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. jkphl/responsive-images-css

ActiveLibrary

jkphl/responsive-images-css
===========================

HTML5-like responsive background images in CSS (sort of …)

v0.1.0(8y ago)211MITPHPPHP >=7.1

Since Apr 15Pushed 8y ago1 watchersCompare

[ Source](https://github.com/jkphl/responsive-images-css)[ Packagist](https://packagist.org/packages/jkphl/responsive-images-css)[ Docs](https://github.com/jkphl/responsive-images-css)[ RSS](/packages/jkphl-responsive-images-css/feed)WikiDiscussions master Synced today

READMEChangelog (1)Dependencies (7)Versions (2)Used By (0)

jkphl/responsive-images-css
===========================

[](#jkphlresponsive-images-css)

[![Build Status](https://camo.githubusercontent.com/1be966b1211368235b14d05e3e2fd327ce688fad9e185e994c24cbb247d54333/68747470733a2f2f7365637572652e7472617669732d63692e6f72672f6a6b70686c2f726573706f6e736976652d696d616765732d6373732e737667)](https://travis-ci.org/jkphl/responsive-images-css) [![Coverage Status](https://camo.githubusercontent.com/dcd9e3ce07887d8a34d0869af39218abf918c3af6ef479dd115536ecab95bc7d/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6a6b70686c2f726573706f6e736976652d696d616765732d6373732f62616467652e7376673f6272616e63683d6d617374657226736572766963653d676974687562)](https://coveralls.io/github/jkphl/responsive-images-css?branch=master) [![Scrutinizer Code Quality](https://camo.githubusercontent.com/a36e02f19827e54c770dfb04492b3418efc13e6c269b0b3cf6f6a58d472bbf47/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6a6b70686c2f726573706f6e736976652d696d616765732d6373732f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/jkphl/responsive-images-css/?branch=master) [![Code Climate](https://camo.githubusercontent.com/cf048dd89063dd28f0002838ae3611eddf61c8983562f403e9d68288937c02f9/68747470733a2f2f6c696d612e636f6465636c696d6174652e636f6d2f6769746875622f6a6b70686c2f726573706f6e736976652d696d616765732d6373732f6261646765732f6770612e737667)](https://lima.codeclimate.com/github/jkphl/responsive-images-css) [![Clear architecture](https://camo.githubusercontent.com/46cba3a6536205bb0009f2aabb66c4ae732b162bb6321610f94c6dd6cf6fe74c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f436c6561722532304172636869746563747572652d2545322539432539342d627269676874677265656e2e737667)](https://github.com/jkphl/clear-architecture)

> HTML5-like responsive background images in CSS (sort of …)

About
-----

[](#about)

The purpose of *responsive-images-css* is to ease the creation process of responsive background images in CSS. It provides similar semantics as responsive images via `` in HTML5.

The rendering sequence of a standard HTML5 responsive (foreground) image is a highly complex process. It's impossible to fully predict which exact image candidate a browser will pick as some decisions may depend on environment settings that are only available at runtime (such as the network performance).

In contrast, *responsive-images-css* generates CSS code on the server-side — that is, long before the browser gets to interpret the generated output. To make this work, some asumptions have to be made:

- The generator needs a fixed **em to pixel ratio** in order to predictably deal with `em` / `rem` values.
- The generator utilizes the **specified breakpoints** only, even if the image candidates suggest additional steps.
- The **device densities** (resolutions) for which the CSS should be rendered must be explictly provided.

Usage
-----

[](#usage)

### The generator

[](#the-generator)

Creating a responsive background image always starts with a fresh `Generator` instance:

```
use Jkphl\Respimgcss\Ports\Generator;

$breakpoints = ['24em', '36em', '48em']; // CSS Breakpoints
$emToPixel = 16; // EM to PX ratio

$generator = new Generator($breakpoints, $emToPixel);
```

As you see in the example, the `Generator` accepts a list of **CSS breakpoints** and an **`em` to `px` ratio** as constructor arguments. The latter defaults to `16` if omitted. The breakpoints only get used in combination with a width based image candidates set and [a `sizes` specification](#using-sizes) (you can pass in an empty array in all other cases).

### Image candidates

[](#image-candidates)

Next, you have to register a couple of **image candidates** for the various states of the responsive image. The file names don't get validated in any way — they will be used as-is for the generated CSS.

```
// Use a `srcset`-like combined file name + width descriptor string ...
$generator->registerImageCandidate('small-400.jpg 400w');

// ... or an explicit width / resolution descriptor as second argument
$generator->registerImageCandidate('medium-800.jpg', '800w');
$generator->registerImageCandidate('large-1200.jpg', '1200w');
```

As with HTML5 responsive images, you can use **resolution** or **width based descriptors** for the image candidates, but be aware that you're not allowed to mix them within a single image candidate set.

```
$generator->registerImageCandidate('small-400.jpg', '1x');
$generator->registerImageCandidate('medium-800.jpg', '2x');
```

### Compiling the CSS ruleset

[](#compiling-the-css-ruleset)

Finally, to create the responsive image CSS, call the generator's `make()` method and apply a **CSS selector** of your choice to the resulting CSS ruleset:

```
$cssRuleset = $generator->make([1.0, 2.0]);
echo $cssRuleset->toCss('.respimg-container');
```

The list of floating point numbers passed to the `make()` method are the **device pixel densities / resolutions** you want the CSS to be rendered for. If you omit this argument, only the default density `1.0` will be considered. The output will look something like this (not pretty-printed):

```
.respimg-container {
    background-image: url("small-400.jpg");
}
@media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi),(min-resolution: 2ddpx) {
    .respimg-container {
        background-image: url("medium-800.jpg");
    }
}
```

As you see in the example, **only the `background-image` property is specified** for the image candidates. For a fully functional responsive image you will need some more lines of CSS — in order to give you full control, however, it's up to you to add this to your overall CSS.

### Example

[](#example)

A minimal, all-things-inlined HTML / PHP example document with responsive background image could look like this:

```
DOCTYPE html>

        Example document with responsive background image

            .respimg {
                padding-bottom: 75%; /* 4:3 aspect ratio */
                background-repeat: no-repeat;
                background-position: top left;
                background-size: cover;
            }