Configure image formats¶
Sulu supports to configure image formats for images that are uploaded via the administration interface. This allows to optimize the performance of your website by outputting images in the exact dimensions that are needed. Furthermore, the content manager can select the cutout that should be used when outputting a specific image format for an uploaded image.
To save space on your server, image formats for uploaded images are generated when they are requested the first time.
Image formats can be defined in:
config/image-formats.xml
Or when you use the SuluThemeBundle you can define the formats in your theme folder:
path/to/<theme>/config/image-formats.xml
The following example shows you different ways to define image formats:
<?xml version="1.0" encoding="UTF-8"?>
<formats xmlns="http://schemas.sulu.io/media/formats"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.sulu.io/media/formats http://schemas.sulu.io/media/formats-1.1.xsd">
<!-- Fixed width and dynamic height -->
<format key="300x">
<scale x="300"/>
</format>
<!-- Dynamic width and fixed height -->
<format key="x200">
<scale y="200"/>
</format>
<!-- Fixed width and fixed height -->
<format key="300x200">
<scale x="300" y="200"/>
</format>
<!-- Max width and max height -->
<format key="300x200-inset">
<scale x="300" y="200" mode="inset"/>
</format>
</formats>
Defining meta title¶
You should define a meta title for every image format, since these titles are shown to the content manager in the administration interface when cropping the images.
<?xml version="1.0" encoding="UTF-8"?>
<formats xmlns="http://schemas.sulu.io/media/formats"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.sulu.io/media/formats http://schemas.sulu.io/media/formats-1.1.xsd">
<format key="300x">
<meta>
<title lang="en">Author Avatar</title>
<title lang="de">Autor Avatar</title>
</meta>
<scale x="300"/>
</format>
<format key="920x">
<meta>
<title lang="en">Header</title>
<title lang="de">Header</title>
</meta>
<scale x="920"/>
</format>
</formats>
Using image formats in your Twig template¶
The URLs for accessing specific image formats are passed to you twig template inside of the thumbnails
property:
<div>
<img src="{{ image.thumbnails['200x100'] }}" alt="{{ image.title }}"/>
</div>
Per default, image formats will be outputted in the file format of the original file.
You can also use a specific file format (eg. png
or webp
) by adding the extension to the format key:
<div>
<img src="{{ image.thumbnails['200x100.webp'] }}" alt="{{ image.title }}"/>
</div>
Image Compression¶
Global image compression¶
Images will not get compressed by default when you upload them. You can set the compression for images globally e.g. in the config/packages/sulu_media.yml. This file does not exist by default and must be created on your own.
sulu_media:
format_manager:
default_imagine_options:
jpeg_quality: 80
webp_quality: 80
png_compression_level: 6
Its recommended to have jpeg_quality between 70-90 as this is the best compromise between quality and image size.
Specific image compression¶
A image compression can also be set on a specific image format the following way:
<?xml version="1.0" encoding="UTF-8"?>
<formats xmlns="http://schemas.sulu.io/media/formats"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.sulu.io/media/formats http://schemas.sulu.io/media/formats-1.1.xsd">
<format key="300x">
<scale x="300"/>
<options>
<option name="jpeg_quality">80</option>
<option name="webp_quality">80</option>
<option name="png_compression_level">6</option>
</options>
</format>
</formats>
Transformations¶
There are several transformations available in sulu to add some effects to your images:
Blur¶
Will blur the image by a given sigma parameter:
<?xml version="1.0" encoding="UTF-8"?>
<formats xmlns="http://schemas.sulu.io/media/formats"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.sulu.io/media/formats http://schemas.sulu.io/media/formats-1.1.xsd">
<format key="300x-blur">
<scale x="300"/>
<transformations>
<transformation>
<effect>blur</effect>
<parameters>
<parameter name="sigma">6</parameter>
</parameters>
</transformation>
</transformations>
</format>
</formats>
Grayscale¶
Will convert the image into a black/white image:
<?xml version="1.0" encoding="UTF-8"?>
<formats xmlns="http://schemas.sulu.io/media/formats"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.sulu.io/media/formats http://schemas.sulu.io/media/formats-1.1.xsd">
<format key="300x-black">
<scale x="300"/>
<transformations>
<!-- Black/white effect -->
<transformation>
<effect>grayscale</effect>
</transformation>
</transformations>
</format>
</formats>
Gamma¶
Will add a gamma effect by a given correction parameter:
<?xml version="1.0" encoding="UTF-8"?>
<formats xmlns="http://schemas.sulu.io/media/formats"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.sulu.io/media/formats http://schemas.sulu.io/media/formats-1.1.xsd">
<format key="300x-gamma">
<scale x="300"/>
<transformations>
<!-- Gamma effect -->
<transformation>
<effect>gamma</effect>
<parameters>
<parameter name="correction">0.7</parameter>
</parameters>
</transformation>
</transformations>
</format>
</formats>
Paste¶
The paste transformation effect will add another image on top on the rendered image. This can be used to add a border or a copyright to the image.
<?xml version="1.0" encoding="UTF-8"?>
<formats xmlns="http://schemas.sulu.io/media/formats"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.sulu.io/media/formats http://schemas.sulu.io/media/formats-1.1.xsd">
<format key="300x300-border">
<scale x="300" y="300"/>
<transformations>
<!-- Paste effect -->
<transformation>
<effect>paste</effect>
<parameters>
<parameter name="image">@AppBundle/Resources/public/border.png</parameter>
</parameters>
</transformation>
</transformations>
</format>
</formats>
The given image can be positioned by adding x, y, w h parameter:
<?xml version="1.0" encoding="UTF-8"?>
<formats xmlns="http://schemas.sulu.io/media/formats"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.sulu.io/media/formats http://schemas.sulu.io/media/formats-1.1.xsd">
<format key="300x300-border">
<scale x="300" y="300"/>
<transformations>
<!-- Paste effect -->
<transformation>
<effect>paste</effect>
<parameters>
<parameter name="image">@AppBundle/Resources/public/border.png</parameter>
<parameter name="x">0</parameter>
<parameter name="y">0</parameter>
<parameter name="w">300</parameter>
<parameter name="h">300</parameter>
</parameters>
</transformation>
</transformations>
</format>
</formats>
Combining Transformations¶
Transformation effect can also be combined the following way:
<?xml version="1.0" encoding="UTF-8"?>
<formats xmlns="http://schemas.sulu.io/media/formats"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.sulu.io/media/formats http://schemas.sulu.io/media/formats-1.1.xsd">
<format key="300x-blur-black">
<scale x="300"/>
<transformations>
<transformation>
<effect>blur</effect>
<parameters>
<parameter name="sigma">6</parameter>
</parameters>
</transformation>
<transformation>
<effect>grayscale</effect>
</transformation>
</transformations>
</format>
</formats>
Editing existing image formats¶
If you edit exist image formats you need to run the following command to regenerate exist images:
If you modify an existing image format configuration, you need to regenerate already generated images by executing the following command:
php bin/websiteconsole sulu:media:regenerate-formats
Alternatively, you can also remove all generated image formats by executing:
php bin/websiteconsole sulu:media:format:cache:clear
In this case, image formats will be regenerated using the new configuration on the first request of the image format.
Remove obsolete images¶
In a multi server setup, when an image is removed via the administration interface, existing image formats are only removed on the current server. Generated image formats of media that do not exist in the database can be removed by running the following command:
php bin/websiteconsole sulu:media:format:cache:cleanup