File

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

File

Валидирует, что значение является валидным "файлом", который может быть:

Строкой пути (или объектом с методом __toString()) к существующему файлу;
Валидным объектом File (включая объекты класса UploadedFile).

Это ограничение часто используется в формах с полем формы FileType.

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

Это ограничение чаще всего используется в свойстве, которое будет отображено в форме в качестве поля 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.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="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-тип также валидируются, так как были указаны соответствующие опции.

Note

As with most of the other constraints, null and empty strings are considered valid values. This is to allow them to be optional values. If the value is mandatory, a common solution is to combine this constraint with 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`

type: array | string default: null

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

`maxSize`

тип: mixed

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

???????	???????? ???????	????????	??????
(none)	????	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.

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

`mimeTypes`

тип: array или string

Caution

Вы должны всегда использовать опцию extensions вместо mimeTypes, кроме случаев, если вы ясно не хотите проверять, что расширение файла соответствует его содержанию (это может быть проблемой безопасности).

По умолчанию, опция extensions также проверяет тип медиа файла.

Если опция установлена, то валидатор проверит, чтобы mime-тип основоположного файла равнялся заданному mime-типу (если это строка), или существовал в коллекции заданных mime-типов (если это массив).

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

Note

При использовании этого ограничения в поле FileType, значение опции mimeTypes также используется в атрибуте accept связанного HTML элемента <input type="file">.

Это поведение применяется только при использовании угадывания типа формы (т.е. тип формы не определён ясно в методе ->add() конструктора формы) и когда поле не определяет собственное значение accept.

`filenameMaxLength`

тип: integer по умолчанию: null

Если установлена, валидатор проверит, чтобы имя исходного файла не превышало определённую длину.

`filenameTooLongMessage`

тип: string по умолчанию: Имя файла слишком длинное. Оно должно иметь {{ filename_max_length }} символов или меньше.

Сообщение, отображаемое, если имя файла превышает ограничение, установленное опцией filenameMaxLength.

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

????????	????????
`{{ filename_max_length }}`	???????????? ??????????? ?????????? ????????

`extensionsMessage`

тип: string по умолчанию: Расширение файла не является валидным ({{ extension }}). Разрешённые расширения: {{ extensions }}.

Сообщение, отображённое, если расширение файла не является валидным расширением в соответствии с опцией extensions.

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

`mimeTypesMessage`

тип: string по умолчанию: Mime-тип файла не является валидным ({{ type }}). Позволенный mime-тип - {{ types }}.

Отображаемое сообщение, если mime-тип файла не является валидным в опции mimeTypes.

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

`notFoundMessage`

тип: string по умолчанию: Файл не был найден.

Отображаемое сообщение, если файл не мог быть найден по заданному пути. Эта ошибка возможна только если основоположное значение является строкой пути, так как объект File не может быть сконструирован с невалидным путём файла.

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

????????	????????
`{{ file }}`	?????????? ???? ?????

`notReadableMessage`

тип: string по умолчанию: Файл нечитаем.

Сообщение отображаемое, если файл существует, но PHP-функция is_readable() терпит неудачу при передачи пути файлу.

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

????????	????????
`{{ file }}`	?????????? ???? ?????

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

payload

тип: mixed по умолчанию: null

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

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

`uploadCantWriteErrorMessage`

тип: string по умолчанию: Файл слишком большой. Позволенный максимальный размер - {{ limit }} {{ suffix }}.

Отображаемое сообщение, если загруженный файл больше, чем настройка upload_max_filesize php.ini.

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

`uploadErrorMessage`

тип: string по умолчанию: Файл не мог быть загружен.

Сообщение, отображаемое, если загруженный файл не мог быть загружен по неизвестной причине.

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

`uploadExtensionErrorMessage`

тип: string по умолчанию: PHP-расширение привело к ошибке загрузки файла.

Сообщение, отображаемое, если PHP-расширение привело к ошибке загрузки файла.

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

`uploadFormSizeErrorMessage`

тип: string по умолчанию: Файл слишком большой.

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

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

`uploadIniSizeErrorMessage`

тип: string по умолчанию: Файл слишком большой. Разрешённый максимальный размер - {{ limit }} {{ suffix }}.

Сообщение, отображаемое, если загруженный файл больше, чем настройка upload_max_filesize php.ini.

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

????????	????????
`{{ limit }}`	???????????? ??????????? ?????? ?????
`{{ suffix }}`	??????? ??? ?????????????? ??????? ????? (??. ????)

`uploadNoFileErrorMessage`

тип: string по умолчанию: Ни один файл не был загружен.

Сообщение, отображаемое, если ни один файл не был загружен.

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

`uploadNoTmpDirErrorMessage`

тип: string по умолчанию: В php.ini не было создано временной папки.

Сообщение, отображаемое, если отсутствует настройка php.ini upload_tmp_dir.

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

`uploadPartialErrorMessage`

тип: string по умолчанию: Файл был загружен только частично.

Сообщение, отображаемое, если загруженный файл был загружен только частично.

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

??????????? ?	???????? ??? ??????
?????	File
?????????	FileValidator