File

Дата оновлення перекладу 2025-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-тип також ваідуються, так як були вказані відповідні опції.

Дата оновлення перекладу 2025-02-21

Note

Як і в більшості інших обмежень, 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 }}`	???? ???????? ?????

Дата оновлення перекладу 2023-09-24

`groups`

тип: array | string за замовчуванням: null

Визначає групу або групи валідації обмеження. Прочитайте більше про групи валідації.

`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

Warning

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

За замовчуванням, опція extensions також перевіряє тип медіа файлу.

Якщо опція встановлена, то валідатор перевірить, щоб mime-тип файлу, що лежить в основні, дорівнюва заданому mime-типу (якщо це рядок), або існував у колекції заданих mime-типів (якщо це масив).

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

Note

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

Ця поведінка застосовується лише при використанні вгадування типу форми (наприклад, тип форми не визначено чітко у методі ->add() побудовника форми) і коли поле не визначає власне значення accept.

`filenameMaxLength`

тип: integer за замовчуванням: null

Якщо встановлено, валідатор перевірить, щоб імʼя вихідного файлу не перевищувало певне значення.

`filenameCountUnit`

тип: string за замовчуванням: File::FILENAME_COUNT_BYTES

Одиниця виміру кількості символів, яка використовується для перевірки максимальної довжини імені файлу. За замовчуванням використовується strlen, яка підраховує довжину рядка в байтах.

Може бути однією з наступних констант класу File:

FILENAME_COUNT_BYTES: Використовує strlen, рахуючи довжину рядка в байтах.
FILENAME_COUNT_CODEPOINTS: Використовує mb_strlen, рахуючи довжину рядка в кодових точках Unicode. Прості (мультибайтові) символи Unicode рахуються як 1 символ, в той час як, наприклад послідовності ZWJ складених емодзі рахуються як декілька символів.
FILENAME_COUNT_GRAPHEMES: Використовує grapheme_strlen, рахуючи довжину рядка в
графемах, тобто навіть емодзі та послідовності ZWJ складених емодзі рахуються як один символ.

7.3

Опція filenameCountUnit була представлена в Symfony 7.3.

`filenameTooLongMessage`

тип: string за замовчуванням: Імʼя файлу занадто довге. Воно має складатися з {{ filename_max_length }} символів або менше.

Повідомлення, яке відображується, якщо імʼя файлу перевищує обмеження, встановлене опцією filenameMaxLength.

Ви можете використати наступні параметри у цьому повідомленні:

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

`filenameCharset`

тип: string за замовчуванням: null

Набір символів, який використовується при обчисленні максимальної довжини імені файлу за допомогою
функцій PHP mb_check_encoding та mb_strlen.

`filenameCharsetMessage`

тип: string за замовчуванням: Це імʼя файлу не співпадає з очікуваним набором символів.

Повідомлення, яке буде відображено, якщо значення не використовує задане filenameCharsetMessage.

Ви можете використовувати наступні параметри у цьому повідомленні:

????????	?????
`{{ charset }}`	?????????? ????? ????????
`{{ name }}`	??????? (?????????) ????????

7.3

Опції filenameCharset та filenameCharsetMessage були представлені в Symfony 7.3.

`extensionsMessage`

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

Повідомлення, відображене, якщо розширення файлу не є валідним розширенням згідно з опцією extensions.

????????	????
`{{ extension }}`	?????????? ???????? ?????
`{{ extensions }}`	?????? ?????????? ????????? ??????

`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 }}`	?????????? ???? ?????

Дата оновлення перекладу 2025-07-27

`payload`

тип: mixed за замовчуванням: null

Ця опція може бути використана, щоб додати довільні дані, специфічні для домену, до обмеження. Сконфігуроване корисне навантаження не використовується компонентом Validator, але його обробка повністю залежить від вас.

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

`uploadCantWriteErrorMessage`

тип: string за замовчуванням: Файл занадто великий. Дозволений максимальний розмір - {{ limit }} {{ suffix }}.

Відображуване повідомлення, якщо завантажений файл не можна зберегти у тимчасовій папці.

Це повідомлення не має параметрів.

`uploadErrorMessage`

тип: string за замовчуванням: Файл не зміг бути завантаженим.

Відображуване повідомлення, якщо завантажений файл не було завантажено за якоїсь невідомої причини.

Це повідомлення не має параметрів.

`uploadExtensionErrorMessage`

тип: string за замовчуванням: PHP-розширення призвело до невдачі файлу.

Відображуване повідомлення, якщо PHP-розширення призвело до невдачі завантаження файлу.

Це повідомлення не має параметрів.

`uploadFormSizeErrorMessage`

тип: string за замовчуванням: Файл занадто великий.

Відображуване повідомлення, якщо завантажений файл більше, ніж дозволяє HTML поле введення файлу.

Це повідомлення не має параметрів.

`uploadIniSizeErrorMessage`

тип: string за замовчуванням: Файл занадто великий. Дозволений максимальний розмір - {{ limit }} {{ suffix }}.

Відображуване повідомлення, якщо завантажуваний файл більше, ніж налаштування upload_max_filesize php.ini.

Ви можете використати наступні параметри у цьому повідомленні:

`uploadNoFileErrorMessage`

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

Відображуване повідомлення, якщо не було завантажено жодного файлу.

Це повідомлення не має параметрів.

`uploadNoTmpDirErrorMessage`

тип: string за замовчуванням: У php.ini. не було сконфігуровано тимчасової папки

Відображуване повідомлення, якщо налаштування php.ini upload_tmp_dir відсутнє.

Це повідомлення не має параметрів.

`uploadPartialErrorMessage`

тип: string за замовчуванням: Файл було завантажено лише частково.

Відображуване повідомлення, якщо файл було завантажено лише частково.

Це повідомлення не має параметрів.

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