Validators: File size
The image FieldType allows you to store an image file.
A variation service handles conversion of the original image into different formats and sizes through a set of pre-configured named variations: large, small, medium, black & white thumbnail...
value property of an Image Field will return an
\eZ\Publish\Core\FieldType\Image\Value object with the following properties:
The image's unique identifier. Usually the path, or a part of the path. To get the full path, use
|string||The alternative text, as entered in the field's properties|
|string||The original image's filename, without the path|
|int||The original image's size, in bytes|
|string||The original image's URI|
|string||A special image ID, used by REST|
Using the variation Service, variations of the original image can be obtained. Those are
\eZ\Publish\SPI\Variation\Values\ImageVariation objects with the following properties:
|int||The variation's width in pixels|
|int||The variation's height in pixels|
|string||The variation's identifier|
|mixed||Extra info, such as EXIF data|
|string||The variation's uri|
|DateTime||When the variation was last modified|
The Image FieldType supports one FieldDefinition option: the maximum size for the file.
Using an Image Field
When displayed using
ez_render_field, an Image Field will output this type of HTML:
ez_render_field accepts several parameters:
- which variation must be used can be set using the
heightcan be forced for the image, for instance to handle custom screen densities. If not specified, the variation's attributes will be used if available.
The raw Field can also be used if needed. Image variations for the Field's content can be obtained using the
ez_image_alias Twig helper:
The variation's properties can be used to generate the required output:
With the REST API
Image Fields within REST are exposed by the
application/vnd.ez.api.Content media-type. An Image Field will look like this:
From 5.2 version, new images must be inputed using the
inputUri property from
path still work, but a deprecation warning will be thrown.
Children of the fieldValue node will list the general properties of the Field's original image (fileSize, fileName, inputUri...), as well as variations. For each variation, an uri is provided. Requested through REST, this resource will generate the variation if it doesn't exist yet, and list the variation details:
From PHP code
Getting an image variation
The variation service,
ezpublish.fieldType.ezimage.variation_service, can be used to generate/get variations for a Field. It expects a VersionInfo, the Image Field and the variation name, as a string (
Manipulating image content
As for any Fieldtype, there are several ways to input content to a Field. For an Image, the quickest is to call
setField() on the ContentStruct:
In order to customize the Image's alternative texts, you must first get an Image\Value object, and set this property. For that, you can use the Image\Value::fromString() method, that accepts the path to a local file:
You can also provide an hash of
Image\Value properties, either to
setField(), or to the constructor:
The REST API expects Field values to be provided in a hash-like structure. Those keys are identical to those expected by the
alternativeText. In addition, image data can be provided using the
data property, with the image's content encoded as base64.
Creating an image Field
Updating an image Field
Updating an Image Field requires that you re-send existing data. This can be done by re-using the Field obtained via REST, removing the variations key, and updating
data. If you do not want to change the image itself, do not provide the
Each storage engine determines how image files are named.
Legacy Storage Engine naming
Images are stored within the following directory structure:
With the following values:
VarDir= var (default)
Images will be stored to
Using the field ID digits in reverse order as the folder structure maximizes sharding of files through multiple folders on the filesystem.
Within this folder, images will be named like the uploaded file, suffixed with an underscore and the variation name:
|5.2||adding inputURI for input by API|
|id property contains only the path of the image, not the full path|