图像

编辑此页

Image 约束的工作方式与 File 约束完全相同，除了它的 mimeTypes 和 mimeTypesMessage 选项被自动设置为专门用于图像文件。

此外，它还具有一些选项，以便您可以根据图像的宽度和高度进行验证。

有关此约束的大部分文档，请参阅 File 约束。

适用于	属性或方法
类	图像
验证器	ImageValidator

基本用法

此约束最常用于将在表单中呈现为 FileType 字段的属性。例如，假设您正在创建一个作者表单，您可以在其中上传作者的“头像”图像。在您的表单中，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.ac.cn/schema/dic/constraint-mapping"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/constraint-mapping http://symfony.ac.cn/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，则图像不能为横向。

注意

此选项不适用于 SVG 文件。如果您将其与 SVG 文件一起使用，您将看到在 sizeNotDetectedMessage 选项中定义的错误消息。

`allowLandscapeMessage`

类型：string 默认值：图像为横向 ({{ width }}x{{ height }}px)。不允许使用横向图像

如果图像为横向且您将 allowLandscape 设置为 false 时的错误消息。

您可以在此消息中使用以下参数

参数	描述
`{{ height }}`	当前高度
`{{ width }}`	当前宽度

`allowPortrait`

类型：Boolean 默认值：true

如果此选项为 false，则图像不能为纵向。

注意

此选项不适用于 SVG 文件。如果您将其与 SVG 文件一起使用，您将看到在 sizeNotDetectedMessage 选项中定义的错误消息。

`allowPortraitMessage`

类型：string 默认值：图像为纵向 ({{ width }}x{{ height }}px)。不允许使用纵向图像

如果图像为纵向且您将 allowPortrait 设置为 false 时的错误消息。

您可以在此消息中使用以下参数

参数	描述
`{{ height }}`	当前高度
`{{ width }}`	当前宽度

`allowSquare`

类型：Boolean 默认值：true

如果此选项为 false，则图像不能为正方形。如果您想强制图像为正方形，则将此选项保留为其默认的 true 值，并将 allowLandscape 和 allowPortrait 都设置为 false。

注意

此选项不适用于 SVG 文件。如果您将其与 SVG 文件一起使用，您将看到在 sizeNotDetectedMessage 选项中定义的错误消息。

`allowSquareMessage`

类型：string 默认值：图像为正方形 ({{ width }}x{{ height }}px)。不允许使用正方形图像

如果图像为正方形且您将 allowSquare 设置为 false 时的错误消息。

您可以在此消息中使用以下参数

参数	描述
`{{ height }}`	当前高度
`{{ width }}`	当前宽度

`corruptedMessage`

类型：string 默认值：图像文件已损坏。

启用 detectCorrupted 选项且图像已损坏时的错误消息。

此消息没有参数。

`detectCorrupted`

类型：boolean 默认值：false

如果此选项为 true，则会验证图像内容以确保图像未损坏。此验证通过 PHP 的 imagecreatefromstring 函数完成，该函数需要启用 PHP GD 扩展。

`groups`

类型：array | string 默认值：null

它定义了此约束的验证组或组。阅读更多关于验证组的信息。

`maxHeight`

类型：integer

如果设置，图像文件的高度必须小于或等于此值（以像素为单位）。

`maxHeightMessage`

类型：string 默认值：图像高度过大 ({{ height }}px)。允许的最大高度为 {{ max_height }}px。

如果图像的高度超过 maxHeight 时的错误消息。

您可以在此消息中使用以下参数

参数	描述
`{{ height }}`	当前（无效）高度
`{{ max_height }}`	允许的最大高度

`maxPixels`

类型：integer

如果设置，图像文件的像素数必须小于或等于此值。

`maxPixelsMessage`

类型：string 默认值：图像像素过多 ({{ pixels }} 像素)。预期的最大像素数为 {{ max_pixels }} 像素。

如果图像的像素数超过 maxPixels 时的错误消息。

您可以在此消息中使用以下参数

参数	描述
`{{ height }}`	当前图像高度
`{{ max_pixels }}`	允许的最大像素数
`{{ pixels }}`	当前像素数
`{{ width }}`	当前图像宽度

`maxRatio`

类型：float

如果设置，图像文件的宽高比（width / height）必须小于或等于此值。

注意

此选项不适用于 SVG 文件。如果您将其与 SVG 文件一起使用，您将看到在 sizeNotDetectedMessage 选项中定义的错误消息。

`maxRatioMessage`

类型：string 默认值：图像宽高比过大 ({{ ratio }})。允许的最大宽高比为 {{ max_ratio }}

如果图像的宽高比超过 maxRatio 时的错误消息。

您可以在此消息中使用以下参数

参数	描述
`{{ max_ratio }}`	要求的最大宽高比
`{{ ratio }}`	当前（无效）宽高比

`maxWidth`

类型：integer

如果设置，图像文件的宽度必须小于或等于此值（以像素为单位）。

`maxWidthMessage`

类型：string 默认值：图像宽度过大 ({{ width }}px)。允许的最大宽度为 {{ max_width }}px。

如果图像的宽度超过 maxWidth 时的错误消息。

您可以在此消息中使用以下参数

参数	描述
`{{ max_width }}`	允许的最大宽度
`{{ width }}`	当前（无效）宽度

`mimeTypes`

类型：array 或 string 默认值：image/*

您可以在 IANA 网站上找到现有图像 MIME 类型的列表。

`mimeTypesMessage`

类型：string 默认值：此文件不是有效的图像。

如果 mimeTypes 选项的所有值都是 image/* 的子集，则错误消息将变为：文件的 MIME 类型无效 ({{ type }})。允许的 MIME 类型为 {{ types }}。

您可以在此消息中使用以下参数

参数	描述
`{{ file }}`	绝对文件路径
`{{ name }}`	基本文件名
`{{ type }}`	给定文件的 MIME 类型
`{{ types }}`	允许的 MIME 类型列表

`minHeight`

类型：integer

如果设置，图像文件的高度必须大于或等于此值（以像素为单位）。

`minHeightMessage`

类型：string 默认值：图像高度过小 ({{ height }}px)。预期的最小高度为 {{ min_height }}px。

如果图像的高度小于 minHeight 时的错误消息。

您可以在此消息中使用以下参数

参数	描述
`{{ height }}`	当前（无效）高度
`{{ min_height }}`	要求的最小高度

`minPixels`

类型：integer

如果设置，图像文件的像素数必须大于或等于此值。

`minPixelsMessage`

类型：string 默认值：图像像素过少 ({{ pixels }} 像素)。预期的最小像素数为 {{ min_pixels }} 像素。

如果图像的像素数小于 minPixels 时的错误消息。

您可以在此消息中使用以下参数

参数	描述
`{{ height }}`	当前图像高度
`{{ min_pixels }}`	要求的最小像素数
`{{ pixels }}`	当前像素数
`{{ width }}`	当前图像宽度

`minRatio`

类型：float

如果设置，图像文件的宽高比（width / height）必须大于或等于此值。

注意

此选项不适用于 SVG 文件。如果您将其与 SVG 文件一起使用，您将看到在 sizeNotDetectedMessage 选项中定义的错误消息。

`minRatioMessage`

类型：string 默认值：图像宽高比过小 ({{ ratio }})。预期的最小宽高比为 {{ min_ratio }}

如果图像的宽高比小于 minRatio 时的错误消息。

您可以在此消息中使用以下参数

参数	描述
`{{ min_ratio }}`	要求的最小宽高比
`{{ ratio }}`	当前（无效）宽高比

`minWidth`

类型：integer

如果设置，图像文件的宽度必须大于或等于此值（以像素为单位）。

`minWidthMessage`

类型：string 默认值：图像宽度过小 ({{ width }}px)。预期的最小宽度为 {{ min_width }}px。

如果图像的宽度小于 minWidth 时的错误消息。

您可以在此消息中使用以下参数

参数	描述
`{{ min_width }}`	要求的最小宽度
`{{ width }}`	当前（无效）宽度

`sizeNotDetectedMessage`

类型：string 默认值：无法检测到图像尺寸。

如果系统无法确定图像的尺寸，将显示此错误。这仅在至少设置了一个尺寸约束选项时才会发生。

此消息没有参数。

注意

不支持检测 SVG 图像的尺寸。如果您使用以下任何选项，将显示此错误消息：allowLandscape、allowPortrait、allowSquare、maxRatio 和 minRatio。

本作品，包括代码示例，根据 Creative Commons BY-SA 3.0 许可协议获得许可。

版本