Image

Дата обновления перевода 2023-09-25

Image

Ограничение Image работает так же, как и ограничение File, только его опции mimeTypes и mimeTypesMessage автоматически устанавливаются так, чтобы работать конкретно с файлами изображений.

Кроме того, оно имеет опции, чтобы вы могли валидировать ширину и высоту изображения.

См. ограничение File, чтобы увидеть часть документации этого ограничения.

??????????? ?	???????? ??? ??????
?????	Image
?????????	ImageValidator

Базовое применение

Это ограничение наиболее часто используется в свойстве, которое будет отображено в форме как поле FileType. Например, представьте, что вы создаёте форму автора, где вы можете загружать изображение "портрет" (headshot) автора. В вашей форие, свойство headshot будет типом file. Класс Author может выглядеть так:

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

use Symfony\Component\HttpFoundation\File\File;

class Author
{
    protected File $headshot;

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

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

Чтобы гарантировать, что объект headshot File является валидным изображением и что он имеет определённый размер, добавьте следующее:

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

use Symfony\Component\HttpFoundation\File\File;
use Symfony\Component\Validator\Constraints as Assert;

class Author
{
    #[Assert\Image(
        minWidth: 200,
        maxWidth: 400,
        minHeight: 200,
        maxHeight: 400,
    )]
    protected File $headshot;
}
    

        1
2
3
4
5
6
7
8
9
        # config/validator/validation.yaml
App\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
        <!-- config/validator/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 https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">

    <class name="App\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
19
20
        // src/Entity/Author.php
namespace App\Entity;

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

class Author
{
    // ...

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

Свойство headshot валидируется, чтобы гарантировать, что это настоящее изображение, и что оно находится в рамках определённой ширины и высоты.

Вы также можете захотеть гарантировать, что изображение headshot является квадратом. В этом случае, вы можете отключить вертикальную и горизонтальную ориентацию, как показано в следующем коде:

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

use Symfony\Component\HttpFoundation\File\File;
use Symfony\Component\Validator\Constraints as Assert;

class Author
{
    #[Assert\Image(
        allowLandscape: false,
        allowPortrait: false,
    )]
    protected File $headshot;
}
    

        1
2
3
4
5
6
7
        # config/validator/validation.yaml
App\Entity\Author:
    properties:
        headshot:
            - Image:
                allowLandscape: false
                allowPortrait: false
    

        1
2
3
4
5
6
7
8
9
        <!-- config/validator/validation.xml -->
<class name="App\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/Entity/Author.php
namespace App\Entity;

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

class Author
{
    // ...

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

Вы можете смешать все опции ограничений, чтобы создать мощные правила валидации.

Опции

Это ограничеие использует все опции вместе с ограничением File. Однако, оно изменяется два значения опций по умолчанию и несколько других опций.

`allowLandscape`

тип: Boolean по умолчанию: true

Если эта опция - false, то изображение не может иметь горизонтальную ориентацию.

`allowLandscapeMessage`

тип: string по умолчанию: Изображение имеет горизонтальную ориентацию ({{ width }}x{{ height }} пикселей). Изображения с горизонтальной ориентацией не допускаются

Сообщение ошибки, если изображение имеет горизонтальную ориентацию, а вы установили allowLandscape, как false.

Вы можете использовать следующие параметры в этом сообщении:

????????	????????
`{{ height }}`	??????? ??????
`{{ width }}`	??????? ??????

`allowPortrait`

тип: Boolean по умолчанию: true

Если эта опция - false, изображение не может быть вертикально ориентированным.

`allowPortraitMessage`

тип: string по умолчанию: Изображение имеет вертикальную ориентацию ({{ width }}x{{ height }} пикселей). Изображения с вертикальной ориентацией не допускаются

Сообщение ошибки, если изображение имеет вертикальную ориентацию, а вы установили allowPortrait, как false.

Вы можете использовать следующие параметры в этом сообщении:

????????	????????
`{{ height }}`	??????? ??????
`{{ width }}`	??????? ??????

`allowSquare`

тип: Boolean по умолчанию: true

Если эта опция - "false", то изображение не может быть квадратом. Если вы хотите принудить к квадратному изображению, то оставьте этой опции значение по умолчанию true, и установите и allowLandscape, и allowPortrait как false.

`allowSquareMessage`

тип: string по умолчанию: Изображение является квадратом ({{ width }}x{{ height }}px). Квадратные изображения не допускаются

Сообщение ошибки, если изображение является квадратом, а вы установили allowSquare, как false.

Вы можете использовать следующие параметры в этом сообщении:

????????	????????
`{{ height }}`	??????? ??????
`{{ width }}`	??????? ??????

`corruptedMessage`

тип: string по умолчанию: Файл изображения повреждён.

Сообщение ошибки, когда опция detectCorrupted подключена и изображение повреждено.

Это сообщение не имеет параметров.

`detectCorrupted`

тип: boolean по умолчанию: false

Если эта опция - "true", то содержимое изображения валидируется, чтобы гарантировать, что изображение не повреждено. Эта валидация проводится с PHP-функцией imagecreatefromstring, которая требует, чтобы расширение PHP GD было подключено.

`groups`

type: array | string default: null

It defines the validation group or groups of this constraint. Read more about validation groups.

`maxHeight`

тип: integer

Если установлена, то высота файла изображения должна быть меньше, или равна этому значению в пикселях.

maxHeightMessage

тип: string по умолчанию: Высота изображения слишком большая ({{ height }}px). Максимальная позволенная высота - {{ max_height }} пикселей.

Сообщение ошибки, если высота изображения превышает maxHeight.

Вы можете использовать следующие параметры в этом сообщении:

????????	????????
`{{ height }}`	??????? (??????????) ??????
`{{ max_height }}`	???????????? ??????????? ??????

`maxPixels`

тип: integer

Если установлена, то количество пикселей файла изображения должно быть меньше или равно этому значению.

`maxPixelsMessage`

тип: string по умолчанию: Изображение имеет слишком много пикселей ({{ pixels }} пикселей). Максимальное ожидаемое количество - {{ max_pixels }} пикселей.

Сообщение ошибки, если количество пикселей изображения превышает maxPixels.

Вы можете использовать следующие параметры в этом сообщении:

????????	????????
`{{ height }}`	??????? ?????? ???????????
`{{ max_pixels }}`	???????????? ??????????? ?????????? ????????
`{{ pixels }}`	??????? ?????????? ????????
`{{ width }}`	??????? ?????? ???????????

`maxRatio`

тип: float

Если установлена, то соотношение аспектов (width / height) файла изображения должно быть меньше, или равно этому значению.

`maxRatioMessage`

тип: string по умолчанию: Соотношене изображения слишком большое ({{ ratio }}). Максимальное позволенное соотношение - {{ max_ratio }}

Сообщение ошибки, если соотношение изображения превышает maxRatio.

Вы можете использовать следующие параметры в этом сообщении:

????????	????????
`{{ max_ratio }}`	???????????? ??????????? ???????????
`{{ ratio }}`	??????? (??????????) ???????????

`maxWidth`

тип: integer

Если установлена, то ширина файла изображения должна быть меньше, или равна этому значению в пикселях.

`maxWidthMessage`

тип: string по умолчанию: Ширина изображения слишком большая ({{ width }}px). Максимальная позволенная ширина - {{ max_width }} пикселей.

Сообщение ошибки, если ширина изображения превышает maxWidth.

Вы можете использовать следующие параметры в этом сообщении:

????????	????????
`{{ max_width }}`	???????????? ??????????? ??????
`{{ width }}`	??????? (??????????) ??????

`mimeTypes`

тип: array или string default: image/*

Вы можете найти список существующих mime-типов изображений на сайте IANA.

`mimeTypesMessage`

тип: string default: Этот файл не является валидным изображением.

If all the values of the mimeTypes option are a subset of image/*, the error message will be instead: The mime type of the file is invalid ({{ type }}). Allowed mime types are {{ types }}.

You can use the following parameters in this message:

Parameter	Description
`{{ file }}`	Absolute file path
`{{ name }}`	Base file name
`{{ type }}`	The MIME type of the given file
`{{ types }}`	The list of allowed MIME types

`minHeight`

тип: integer

Если установлена, то высота файла изображения должна быть больше, или равна этому значению в пикселях.

`minHeightMessage`

тип: string по умолчанию: Высота изображения слишком маленькая ({{ height }}px). Минимальная позволенная высота - {{ min_height }} пикселей.

Сообщение ошибки, если высота изображения меньше, чем minHeight.

Вы можете использовать следующие параметры в этом сообщении:

????????	????????
`{{ height }}`	??????? (??????????) ??????
`{{ min_height }}`	??????????? ??????????? ??????

`minPixels`

тип: integer

Если установлена, то количество пикселей файла изображения должно быть больше или равно этому значению.

`minPixelsMessage`

тип: string по умолчанию: Изображение имеет слишком мало пикселей ({{ pixels }} пикселей). Минимальное ожидаемое количество - {{ min_pixels }} пикселей.

Сообщение ошибки, если количество пикселей изображения меньше, чем minPixels.

Вы можете использовать следующие параметры в этом сообщении:

????????	????????
`{{ height }}`	??????? ?????? ???????????
`{{ min_pixels }}`	??????????? ??????????? ?????????? ????????
`{{ pixels }}`	??????? ?????????? ????????
`{{ width }}`	??????? ?????? ???????????

`minRatio`

тип: float

Если установлена, то соотношение аспектов (width / height) файла изображения должно быть больше, или равно этому значению.

`minRatioMessage`

тип: string по умолчанию: Соотношене изображения слишком маленькое ({{ ratio }}). Минимальное позволенное соотношение - {{ min_ratio }}

Сообщение ошибки, если соотношение изображения меньше, чем minRatio.

Вы можете использовать следующие параметры в этом сообщении:

????????	????????
`{{ min_ratio }}`	??????????? ??????????? ???????????
`{{ ratio }}`	??????? (??????????) ???????????

`minWidth`

тип: integer

Если установлена, то ширина файла изображения должна быть больше, или равна этому значению в пикселях.

`minWidthMessage`

тип: string по умолчанию: Ширина изображения слишком маленькая ({{ width }}px). Минимальная позволенная ширина - {{ min_width }} пикселей.

Сообщение ошибки, если ширина изображения меньше, чем minWidth.

Вы можете использовать следующие параметры в этом сообщении:

????????	????????
`{{ min_width }}`	??????????? ??????????? ??????
`{{ width }}`	??????? (??????????) ??????

`sizeNotDetectedMessage`

тип: string по умолчанию: Размер изображения не мог быть определён.

Если система не может определить размер изображения, то будет отображена эта ошибка. Это случится только если было установлено хотя бы одно ограничение опций размера.

Это сообщение не имеет параметров.