Image

Warning: You are browsing the documentation for Symfony 2.x, which is no longer maintained.

Read the updated version of this page for Symfony 7.1 (the current stable version).

The Image constraint works exactly like the File constraint, except that its mimeTypes and mimeTypesMessage options are automatically setup to work for image files specifically.

Additionally it has options so you can validate against the width and height of the image.

See the File constraint for the bulk of the documentation on this constraint.

Applies to	property or method
Options	mimeTypes minWidth maxWidth maxHeight minHeight maxRatio minRatio allowSquare allowLandscape allowPortrait mimeTypesMessage sizeNotDetectedMessage maxWidthMessage minWidthMessage maxHeightMessage minHeightMessage maxRatioMessage minRatioMessage allowSquareMessage allowLandscapeMessage allowPortraitMessage See File for inherited options
Class	Image
Validator	ImageValidator

Basic Usage

This constraint is most commonly used on a property that will be rendered in a form as a FileType field. For example, suppose you're creating an author form where you can upload a "headshot" image for the author. In your form, the headshot property would be a file type. The Author class might look as follows:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
        // src/AppBundle/Entity/Author.php
namespace AppBundle\Entity;

use Symfony\Component\HttpFoundation\File\File;

class Author
{
    protected $headshot;

    public function setHeadshot(File $file = null)
    {
        $this->headshot = $file;
    }

    public function getHeadshot()
    {
        return $this->headshot;
    }
}
    

To guarantee that the headshot File object is a valid image and that it is between a certain size, add the following:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        // src/AppBundle/Entity/Author.php
namespace AppBundle\Entity;

use Symfony\Component\Validator\Constraints as Assert;

class Author
{
    /**
     * @Assert\Image(
     *     minWidth = 200,
     *     maxWidth = 400,
     *     minHeight = 200,
     *     maxHeight = 400
     * )
     */
    protected $headshot;
}
    

        1
2
3
4
5
6
7
8
9
        # src/AppBundle/Resources/config/validation.yml
AppBundle\Entity\Author:
    properties:
        headshot:
            - Image:
                minWidth: 200
                maxWidth: 400
                minHeight: 200
                maxHeight: 400
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        <!-- src/AppBundle/Resources/config/validation.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">

    <class name="AppBundle\Entity\Author">
        <property name="headshot">
            <constraint name="Image">
                <option name="minWidth">200</option>
                <option name="maxWidth">400</option>
                <option name="minHeight">200</option>
                <option name="maxHeight">400</option>
            </constraint>
        </property>
    </class>
</constraint-mapping>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        // src/AppBundle/Entity/Author.php
namespace AppBundle\Entity;

use Symfony\Component\Validator\Mapping\ClassMetadata;
use Symfony\Component\Validator\Constraints as Assert;

class Author
{
    public static function loadValidatorMetadata(ClassMetadata $metadata)
    {
        $metadata->addPropertyConstraint('headshot', new Assert\Image(array(
            'minWidth' => 200,
            'maxWidth' => 400,
            'minHeight' => 200,
            'maxHeight' => 400,
        )));
    }
}
    

The headshot property is validated to guarantee that it is a real image and that it is between a certain width and height.

You may also want to guarantee the headshot image to be square. In this case you can disable portrait and landscape orientations as shown in the following code:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        // src/AppBundle/Entity/Author.php
namespace AppBundle\Entity;

use Symfony\Component\Validator\Constraints as Assert;

class Author
{
    /**
     * @Assert\Image(
     *     allowLandscape = false,
     *     allowPortrait = false
     * )
     */
    protected $headshot;
}
    

        1
2
3
4
5
6
7
        # src/AppBundle/Resources/config/validation.yml
AppBundle\Entity\Author:
    properties:
        headshot:
            - Image:
                allowLandscape: false
                allowPortrait: false
    

        1
2
3
4
5
6
7
8
9
        <!-- src/AppBundle/Resources/config/validation.xml -->
<class name="AppBundle\Entity\Author">
    <property name="headshot">
        <constraint name="Image">
            <option name="allowLandscape">false</option>
            <option name="allowPortrait">false</option>
        </constraint>
    </property>
</class>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        // src/AppBundle/Entity/Author.php
namespace AppBundle\Entity;

use Symfony\Component\Validator\Mapping\ClassMetadata;
use Symfony\Component\Validator\Constraints as Assert;

class Author
{
    // ...

    public static function loadValidatorMetadata(ClassMetadata $metadata)
    {
        $metadata->addPropertyConstraint('headshot', new Assert\Image(array(
            'allowLandscape'    => false,
            'allowPortrait'     => false,
        )));
    }
}
    

You can mix all the constraint options to create powerful validation rules.

Options

This constraint shares all of its options with the File constraint. It does, however, modify two of the default option values and add several other options.

mimeTypes

type: array or string default: image/*

You can find a list of existing image mime types on the IANA website.

mimeTypesMessage

type: string default: This file is not a valid image.

minWidth

type: integer

If set, the width of the image file must be greater than or equal to this value in pixels.

maxWidth

type: integer

If set, the width of the image file must be less than or equal to this value in pixels.

minHeight

type: integer

If set, the height of the image file must be greater than or equal to this value in pixels.

maxHeight

type: integer

If set, the height of the image file must be less than or equal to this value in pixels.

maxRatio

type: float

If set, the aspect ratio (width / height) of the image file must be less than or equal to this value.

minRatio

type: float

If set, the aspect ratio (width / height) of the image file must be greater than or equal to this value.

allowSquare

type: Boolean default: true

If this option is false, the image cannot be a square. If you want to force a square image, then leave this option as its default true value and set allowLandscape and allowPortrait both to false.

allowLandscape

type: Boolean default: true

If this option is false, the image cannot be landscape oriented.

allowPortrait

type: Boolean default: true

If this option is false, the image cannot be portrait oriented.

sizeNotDetectedMessage

type: string default: The size of the image could not be detected.

If the system is unable to determine the size of the image, this error will be displayed. This will only occur when at least one of the size constraint options has been set.

maxWidthMessage

type: string default: The image width is too big ({{ width }}px). Allowed maximum width is {{ max_width }}px.

The error message if the width of the image exceeds maxWidth.