File

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

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 $bioFile;

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

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

Щоб гарантувати, що обʼєкт bioFile File валідний, і що він менше визначеного розміру файлу і є валідним PDF-файлом, додайте наступне:

Attributes
YAML
XML
PHP

        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',
        mimeTypes: ['application/pdf', 'application/x-pdf'],
        mimeTypesMessage: 'Please upload a valid PDF',
    )]
    protected $bioFile;
}
    

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

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

Властивість 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

6.2

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

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

За замовчуванням, всі типи медіа, асоційовані з розширенням, дозволені. Список підтримуваних розширень та асоційованих типів медіа можна знайти на сайті IANA.

Також можливо чітко сконфігурувати авторизовані типи медіа для розширення.

У наступному прикладі, дозволені типи медіа чітко встановлені для розширень xml та txt, а всі асоційовані типи дозволені для jpg:

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

`disallowEmptyMessage`

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

Обмеження перевірає, чи не є завантажений файл порожнім (тобто, 0 байтів). Якщо він порожній, то вібражується це повідомлення.

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

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

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

`groups`

тип: array | string

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

`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.

`extensionsMessage`

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

6.2

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

Повідомлення, відображене, якщо розширення файлу не є валідним розширенням згідно з опцією 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 }}`	?????????? ???? ?????

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

`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