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
за замовчуванням: Файл було завантажено лише частково.
Відображуване повідомлення, якщо файл було завантажено лише частково.
Це повідомлення не має параметрів.