Download the PHP package pboivin/flou without Composer
On this page you can find all versions of the php package pboivin/flou. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package flou
flou
Flou is a PHP package integrating Glide (PHP) and vanilla-lazyload (JS). It's optimized to quickly implement lazy loading and responsive images from a local folder of source images.
Features:
- Transform local images on initial page load (does not expose Glide URLs)
- Can leverage custom Glide configurations (e.g. source images on S3)
- Generate responsive HTML for
img
andpicture
elements - Useable with static site generators and in CLI scripts
- Framework agnostic (a set of plain PHP classes)
Requirements:
- PHP >= 8.0
Table of contents:
- Installing
- Getting Started
- Image Transformations
- Image Rendering
- Image Sets (Responsive Images)
- Remote Images
- Examples
- Development
- License
Demo project:
See the flou-jigsaw-demo repository for an example project integrating Flou with the Jigsaw PHP static site generator.
Installing
The package can be installed via Composer:
This also installs Glide as a Composer dependency.
You can pull in the vanilla-lazyload library via a CDN:
or via NPM:
Consult the vanilla-lazyload documentation for more installation options.
Getting Started
First, initialize the LazyLoad
JS object. Add the following script to your page template:
Then, initialize the ImageFactory
PHP object with your project-specific configuration:
Configuration
The required options are:
Name | Type | Description |
---|---|---|
sourcePath |
string | The full path to the source images. |
cachePath |
string | The full path where Glide will store the image transformations. |
sourceUrlBase |
string | The base URL for the source images. |
cacheUrlBase |
string | The base URL for the transformed images. |
Other options:
Name | Type | Description |
---|---|---|
glideParams |
array | Default Glide parameters for LQIP elements. |
renderOptions |
array | Default render options for all images. |
Framework Integration
If you're using a framework with a Service Container, you can register the $flou
instance as a singleton for your entire application. This will be your entry point to transform and render images.
Extra JS and CSS
Some examples below require additional JS and CSS. You'll find a more complete sample in the assets directory.
Image Transformations
Transforming source images
Use the image()
method to transform a single image into a low-quality image placeholder (LQIP):
You can also provide custom Glide parameters for the image transformation:
You'll find all available parameters in the Glide documentation.
As you can see, the default parameters are used to generate LQIP from source images, but you are not restricted to that. You may generate as many transformations as you need from the source image:
If you're working with responsive images and the srcset
attribute, have a look at the next section (Image Sets).
Default Glide parameters
You can customize the default Glide parameters in the ImageFactory
configuration:
Image objects
The image()
method returns an Image
object, from which you can conveniently access the source image file and the transformed (cached) image file:
Use the toArray()
method to export the image to a plain array:
Image resampling
Image resampling is a simple way to reuse a transformed image as the source of another transformation. Use the resample()
method to begin:
This is the same as calling image()
, but returns an instance of ResampledImage
instead. The resampled image can then be used again as a source for image()
:
Image Rendering
Rendering single images
The render()
method on the image returns an ImageRender
object, which prepares HTML suitable for the vanilla-lazyload library. Then, img()
is used to render an img
element:
See HTML Output
Options passed into img()
are included as HTML attributes on the element. Attribute values are not escaped by default.
Some attributes are automatically generated (e.g. src
, width
, height
, etc.). You can override them with a !
prefix:
See HTML Output
Render options
The ImageRender
object can be configured to optimize the HTML output:
-
useAspectRatio()
: Prevents content shifting when the LQIP is replaced with the source image:See HTML Output
-
usePaddingTop()
: A workaround for older browsers not supporting theaspect-ratio
CSS property:See HTML Output
-
useWrapper()
: Wraps the image with an extradiv
and separates the LQIP element from the mainimg
element. This is used to add a fade-in effect when the image is loaded.(Requires additional JS and CSS. See fade-in example.)
See HTML Output
-
useBase64Lqip()
: Inlines a Base64 version of the LQIP in thesrc
attribute of theimg
element. This reduces the number of HTTP requests needed to display a page, at the cost of making the HTML a bit heavier.See HTML Output
Default render options
You can set the default render options for all images in the ImageFactory
configuration:
See Available Options
| Name | Type | Description | |---|---|---| | `baseClass` | string | CSS class for `img` element. Default: `'lazyload'` | | `wrapperClass` | string | CSS class for wrapper element. Default: `'lazyload-wrapper'` | | `lqipClass` | string | CSS class for LQIP element. Default: `'lazyload-lqip'` | | `paddingClass` | string | CSS class for padding-specific wrapper element. Default: `'lazyload-padding'` | | `aspectRatio` | boolean or number | Use aspect ratio. Default: `false` | | `paddingTop` | boolean or number | Use padding-top workaround. Default: `false` | | `wrapper` | boolean | Use wrapper element. Default: `false` | | `base64Lqip` | boolean | Use Base64 LQIP value. Default: `false` |Noscript variation
Use the noScript()
method to render an img
element without any lazy loading behavior:
See HTML Output
This is used to add a noscript
image fallback. (See Noscript image fallback example)
It can also be used creatively to work on the source image with CSS classes and HTML attributes. (See Browser native lazy loading example)
Image Sets (Responsive Images)
Single source (img
element)
Use the imageSet()
method to transform a source image into a set of responsive images:
This returns an ImageSet
object, which prepares all variations of the source image. The render()
method on the image set returns an ImageSetRender
instance, as seen before with single images:
See HTML Output
Like ImageRender
, you can optimize ImageSetRender
with the same methods:
useAspectRatio()
usePaddingTop()
useWrapper()
useBase64Lqip()
noScript()
Multiple sources (picture
element)
With a similar configuration, imageSet()
also handles multiple source images:
Then, the picture()
method is used to render a picture
element:
See HTML Output
See also: Art-directed picture
element example
Multiple formats (picture
element)
The configuration allows multiple image formats for each source:
See HTML Output
Custom Glide parameters
You can provide an array of base Glide parameters as a second argument to imageSet()
:
You'll find all available parameters in the Glide documentation.
Note: You may use all parameters except w
and fm
, which are automatically generated from the widths
and formats
configuration above.
Remote Images
The base ImageFactory
class is optimized for cases where both source and cached images exist on the local filesystem. The RemoteImageFactory
class was introduced to enable new use-cases:
- Working with remote Glide endpoints
- Integrating with existing Glide Server configurations
This adds support for images stored on remote filesystems, such as Amazon S3.
Configuration
The options for RemoteImageFactory
are:
Name | Type | Description |
---|---|---|
glideServer |
League\Glide\Server | A Server instance. |
glideUrlBase |
string | Alternatively, the base URL for a remotely accessible Glide server. |
glideUrlSignKey |
string | Private key used for Glide HTTP signatures. (optional) |
Glide Endpoint
If you already have a Glide instance setup and publicly accessible, you can hook into it with the following configuration:
Glide Server
Alternatively, you can pass in a fully configured Glide Server
object:
If you're using Laravel, you can access the filesystem driver from the Storage
facade:
Caveats
When using RemoteImageFactory
, it is too costly to fetch remote images to analyze their dimensions. Therefore, rendered images will not include width
and height
attributes. I recommend leveraging useAspectRatio()
with a fixed aspect ratio value if possible.
Similarly, useBase64Lqip()
will return a blank placeholder instead of a Base64 encoded LQIP.
Image resampling is not available for remote images.
Examples
Fade-in image on load
Extra JS and CSS:
Usage:
Art-directed picture
element
CSS:
Usage:
Noscript fallback
CSS:
Usage:
Native lazy loading (no JS, with LQIP)
Usage:
Lazy loaded background image
Usage:
CLI script
Preprocess all images in a source directory and prepare a JSON inventory file:
Development
Test suite (phpunit)
Static analysis (phpstan)
Code formatting (pint)
License
Flou is open-sourced software licensed under the MIT license.