文件

编辑此页

验证一个值是否为有效的“文件”，可以是以下类型之一

字符串（或具有 __toString() 方法的对象）指向现有文件的路径；
有效的 File 对象（包括 UploadedFile 类的对象）。

此约束通常在表单中与 FileType 表单字段一起使用。

另请参阅

如果您要验证的文件是图像，请尝试 Image 约束。

适用于	属性或方法
类	文件
验证器	FileValidator

基本用法

此约束最常用于将在表单中呈现为 FileType 字段的属性。例如，假设您正在创建一个作者表单，您可以在其中上传作者的“简历” PDF。在您的表单中，bioFile 属性将是 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 $bioFile;

    public function setBioFile(?File $file = null): void
    {
        $this->bioFile = $file;
    }

    public function getBioFile(): File
    {
        return $this->bioFile;
    }
}
    

为了保证 bioFile File 对象有效，并且文件大小低于某个限制且为有效的 PDF，请添加以下内容

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

use Symfony\Component\Validator\Constraints as Assert;

class Author
{
    #[Assert\File(
        maxSize: '1024k',
        extensions: ['pdf'],
        extensionsMessage: 'Please upload a valid PDF',
    )]
    protected File $bioFile;
}
    

        1
2
3
4
5
6
7
8
        # config/validator/validation.yaml
App\Entity\Author:
    properties:
        bioFile:
            - File:
                maxSize: 1024k
                extensions: [pdf]
                extensionsMessage: Please upload a valid PDF
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        <!-- 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="bioFile">
            <constraint name="File">
                <option name="maxSize">1024k</option>
                <option name="extensions">
                    <value>pdf</value>
                </option>
                <option name="extensionsMessage">Please upload a valid PDF</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
21
        // 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('bioFile', new Assert\File([
            'maxSize' => '1024k',
            'extensions' => [
                'pdf',
            ],
            'extensionsMessage' => 'Please upload a valid PDF',
        ]));
    }
}
    

bioFile 属性经过验证，以保证它是一个真实的文件。其大小和 mime 类型也经过验证，因为已指定了适当的选项。

注意

与大多数其他约束一样，null 和空字符串被视为有效值。这是为了允许它们成为可选值。如果该值是强制性的，一个常见的解决方案是将此约束与 NotBlank 结合使用。

选项

`binaryFormat`

类型: boolean 默认值: null

当 true 时，大小将以二进制前缀单位（KiB、MiB）显示在消息中。当 false 时，大小将以 SI 前缀单位（kB、MB）显示。当 null 时，binaryFormat 将从 maxSize 选项中定义的值进行猜测。

有关二进制和 SI 前缀之间差异的更多信息，请参阅维基百科：二进制前缀。

`extensions`

类型: array 或 string

如果设置，验证器将检查底层文件的扩展名和媒体类型（以前称为 MIME 类型）是否等于给定的扩展名和关联的媒体类型（如果是字符串），或者是否存在于集合中（如果是数组）。

默认情况下，允许所有与扩展名关联的媒体类型。支持的扩展名和关联媒体类型的列表可以在 IANA 网站上找到。

也可以显式配置扩展名的授权媒体类型。

在以下示例中，为 xml 和 txt 扩展名显式设置了允许的媒体类型，并且允许 jpg 的所有关联媒体类型

        1
2
3
4
5
        [
    'xml' => ['text/xml', 'application/xml'],
    'txt' => 'text/plain',
    'jpg',
]
    

`disallowEmptyMessage`

类型: string 默认值: 不允许空文件。

此约束检查上传的文件是否为空（即 0 字节）。如果是，则显示此消息。

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

参数	描述
`{{ file }}`	绝对文件路径
`{{ name }}`	基本文件名

`groups`

类型: array | string 默认值: null

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

`maxSize`

类型: mixed

如果设置，则底层文件的大小必须低于此文件大小才能有效。文件大小可以使用以下格式之一给出

后缀	单位名称	值	示例
（无）	字节	1 字节	`4096`
`k`	千字节	1,000 字节	`200k`
`M`	兆字节	1,000,000 字节	`2M`
`Ki`	千比特字节	1,024 字节	`32Ki`
`Mi`	兆比特字节	1,048,576 字节	`8Mi`

有关二进制和 SI 前缀之间差异的更多信息，请参阅维基百科：二进制前缀。

`maxSizeMessage`

类型: string 默认值: 文件太大 ({{ size }} {{ suffix }})。允许的最大大小为 {{ limit }} {{ suffix }}。

如果文件大于 maxSize 选项，则显示的消息。

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

参数	描述
`{{ file }}`	绝对文件路径
`{{ limit }}`	允许的最大文件大小
`{{ name }}`	基本文件名
`{{ size }}`	给定文件的文件大小
`{{ suffix }}`	使用的文件大小单位的后缀（见上文）