File

Дата оновлення перекладу 2024-05-29

File

Валідує, що значення є валідним "файлом", який може бути:

  • Рядком шляху (або обʼєктом з методом __toString()) до існуючого файлу;
  • Валідним обʼєктом File (включно з обʼєктами класу UploadedFile).

Це обмеження часто використовується у формах з полем форми FileType.

See also

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

????????????? ?? ??????????? ??? ??????
???? File
????????? 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;
}

Властивість bioFile валідується, щоб гарантувати, що це справжній файл. Його розмір та mime-тип також ваідуються, так як були вказані відповідні опції.

Дата оновлення перекладу 2022-12-20

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

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-05-29

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 за замовчуванням: Файл було завантажено лише частково.

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

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