Поле FileType

Дата обновления перевода 2025-02-05

Поле FileType

FileType представляет ввод файла в вашей форме.

???????????? ??? ???? input file
????????? ???????????? ?? ????????? ??????????, ???????? ???????? ????.
???????????? ??? FormType
????? FileType

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

Tip

Полный список опций, определенных и унаследованных этим типом формы, доступен путем
выполнения этой команды в вашем приложении:

1
2
# замените 'FooType' именем класса вашего типа формы
$ php bin/console debug:form FooType

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

Допустим, у вас есть такое определение формы:

1
2
3
4
use Symfony\Component\Form\Extension\Core\Type\FileType;
// ...

$builder->add('attachment', FileType::class);

Когда отправляется форма, поле attachment будет экземпляром UploadedFile. Он может быть использован для перемещения файла attachment в постоянную локацию:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
use Symfony\Component\HttpFoundation\File\UploadedFile;

public function upload(): Response
{
    // ...

    if ($form->isSubmitted() && $form->isValid()) {
        $someNewFilename = ...

        $file = $form['attachment']->getData();
        $file->move($dir, $someNewFilename);
        
        // ...
    }

    // ...
}

Метод move() берёт каталог и имя файла в качестве своих аргументов. Вы можете вычислить имя файла одним из следующих способов:

1
2
3
4
5
6
7
8
9
10
// использовать оригинальное имя файла
$file->move($dir, $file->getClientOriginalName());

// создать случайное имя и попробовать угадать расширение (более безопасно)
$extension = $file->guessExtension();
if (!$extension) {
    // расширение не может быть угадано
    $extension = 'bin';
}
$file->move($dir, rand(1, 99999).'.'.$extension);

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

Прочтите Как загружать файлы, чтобы увидеть пример того, как управлять загрузкой файла, связанного с сущностью Doctrine.

Опции поля

multiple

тип: Boolean по умолчанию: false

Когда установлена, как "true", пользователь сможет загрузать несколько файлов одновременно.

Переопределённые опции

Дата обновления перевода 2025-02-22

compound

тип: boolean по умолчанию: false

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

data_class

тип: string default: File

Эта опция устанавливает правильный преобразователь данных, связанный с данными, для использования типом.

empty_data

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

Эта опция определяет, какое значение будет возвращать поле, когда отправленное значение пусто.

Переопределённые опции

Дата обновления перевода 2025-02-24

invalid_message

тип: string по умолчанию: Это значение не валидно

Это сообщение ошибки валидации, которое используется, если данные, введенные в это поле, не имеют смысла (т.е. валидация проходит неудачно).

Это может случиться, к примеру, если пользователь вводит в поле TimeType асбурдную строку, которая не может быть конвертирована в настоящее время, или если пользователь вводит строку (например, apple) в числовое поле.

Нормальная (программный код) валидация (например, установка минимальной длины для поля), должна быть установлена с использованием сообщений валидации с вашими правилами валидации (справочник ).

Наследуемые опции

Эти опции наследуются из FormType:

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

attr

тип: array по умолчанию: []

Если вы хотите добавить дополнительные атрибуты к HTML представлению поля, то вы можете использовать опцию attr. Это ассоциативный массив с HTML-атрибутами в качестве ключей. Этоможет быть полезно, когда вам нужно установить для некоторого виджета пользовательский класс:

1
2
3
$builder->add('body', TextareaType::class, [
    'attr' => ['class' => 'tinymce'],
]);

See also

Используйте опцию row_attr, если вы хотите добавить эти атрибуты к к элементу строки типа формы

Дата обновления перевода 2025-02-24

disabled

тип: boolean по умолчанию: false

Если вы не хотите, чтобы пользователь изменял значение поля, то вы можете установить опцию отключения, как "true". Любые отправленные данные будут проигнорированы.

Дата обновления перевода 2025-02-24

error_bubbling

тип: boolean по умолчанию: false, кроме случаев, когда форма compound

Если true, то любые ошибки в этом поле будут переданы родительскому полю или форме. Например, если установлена, как true в нормальном поле, то любые ошибки для этого поля будут присоединены к главной форме, а не к конкретному полю.

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

error_mapping

тип: array по умолчанию: []

Эта опция позволяет вам изменять цель ошибки валидации.

Представьте, что у вас есть пользовательский метод под именем matchingCityAndZipCode(), который валидирует, совпадает ли город и почтовый индекс. К сожалению, поля "matchingCityAndZipCode" в вашей форме нет, поэтому всё, что Symfony может сделать - это отобразить ошибку наверху формы.

С настроенным отображением ошибок вы можете сделать лучше: привяжите ошибку к полю города, чтобы она отображалась над ним:

1
2
3
4
5
6
7
8
public function configureOptions(OptionsResolver $resolver): void
{
    $resolver->setDefaults([
        'error_mapping' => [
            'matchingCityAndZipCode' => 'city',
        ],
    ]);
}

Вот правила для лево- и правостороннего отображения:

  • Левая сторона содержит пути свойств;
  • Если нарушение генерируется в свойстве или методе класса, то его путь - это просто propertyName;
  • Если нарушение сгенерировано в записи объекта array или ArrayAccess,
    то путь свойства будет [indexName]; * Вы можете создать вложенные пути свойств, соединив их, разделяя свойства точками. Например: addresses[work].matchingCityAndZipCode;
  • Правая сторона содержит просто имена полей в форме.

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

1
2
3
4
5
$resolver->setDefaults([
    'error_mapping' => [
        '.' => 'city',
    ],
]);

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

help

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

Позволяет вам определять сообщение помощи для поля формы, которое по умолчанию отображается под полем:

1
2
3
4
5
6
7
8
9
10
11
12
13
use Symfony\Component\Translation\TranslatableMessage;

$builder
    ->add('zipCode', null, [
        'help' => 'The ZIP/Postal code for your credit card\'s billing address.',
    ])

    // ...

    ->add('status', null, [
        'help' => new TranslatableMessage('order.status', ['%order_id%' => $order->getId()], 'store'),
    ])
;

Дата обновления перевода 2025-02-24

help_attr

тип: array по умолчанию: []

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

1
2
3
{{ form_help(form.name, 'Your name', {
    'help_attr': {'class': 'CUSTOM_LABEL_CLASS'}
}) }}

Дата обновления перевода 2025-02-24

help_html

тип: boolean по умолчанию: false

По умолчанию содержание опции help экранируется перед отображением в шаблоне.
Установите для этой опции значение true, чтобы не экранировать их, что полезно,
когда справка содержит элементы HTML.

Дата обновления перевода 2023-01-12

label

тип: string или TranslatableMessage по умолчанию: Ярлык "угадывается" из имени поля

Устанавливает ярлык, который будет использован при отображении поля. Установка, как "false" подавит ярлык:

1
2
3
4
5
6
7
8
use Symfony\Component\Translation\TranslatableMessage;

$builder
    ->add('zipCode', null, [
        'label' => 'The ZIP/Postal code',
        // по желанию, вы можете использовать объекты TranslatableMessage как содержание ярлыка
        'label' => new TranslatableMessage('address.zipCode', ['%country%' => $country], 'address'),
    ])

Ярлык также может быть установлен внутри шаблона:

1
{{ form_label(form.name, 'Your name') }}

Дата обновления перевода 2025-02-24

label_attr

тип: array по умолчанию: []

Устанавливает HTML-атрибуты для элемента <label>, который будет использован при отображении ярлыка для поля. Это ассоциативный массив с HTML-атрибутом в качестве ключа. Этот атрибут может также быть установлен прямо внутри шаблона:

1
2
3
{{ form_label(form.name, 'Your name', {
    'label_attr': {'class': 'CUSTOM_LABEL_CLASS'}
}) }}

Дата обновления перевода 2025-02-24

label_html

тип: boolean по умолчанию: false

По умолчанию, содержание опции label экранируется перед отображением в шаблоне. Установите для этой опции значение true, чтобы не экранировать ее, что может быть полезно, когда ярлык содержит HTML-элементы.

Дата обновления перевода 2025-02-24

label_format

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

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

Если вы используете сообщения переводов ключевых слов в качестве ярлыков, то у вас часто будет несколько сообщений с ключевым словом для одного и того же ярлыка (например, profile_address_street, invoice_address_street). Это потому, что ярлык строится для каждого "пути" к полю. Чтобы избежать повтора сообщений ключевых слов, вы можете сконфигурировать формат ярлыка в качестве статичного значения, например:

1
2
3
4
5
6
7
8
// ...
$profileFormBuilder->add('address', AddressType::class, [
    'label_format' => 'form.address.%name%',
]);

$invoiceFormBuilder->add('invoice', AddressType::class, [
    'label_format' => 'form.address.%name%',
]);

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

В формате ярлыка доступны две переменные:

%id%
Уникальный идентификатор для поля, состоящий из полного пути к полю и имени поля (например, profile_address_street);
%name%
Имя поля (например, street).

Значение по умолчанию (null) приводит к "человеческой" версии имени поля.

Note

Опция label_format оценивается в теме формы. Убедитесь в том, что вы обновили ваши щаблоны, в случае, если вы настраивали темизацию форм.

Дата обновления перевода 2025-02-24

mapped

тип: boolean по умолчанию: true

Если вы хотите, чтобы поле было проигнорировано про чтении или записи в него объекта, вы можете установить опцию mapped, как false.

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

required

тип: boolean по умолчанию: true

Если "true", то будет отображён обязательный атрибут HTML5. Соответствующий label также отобразится с классом required.

Эта опция внешняя и не зависит от валидации. В лучшем случае, если вы позволите Symfony отгадать ваш тип поля, тогда значение этой опции будет угадано из вашей информации о валидации.

Note

Обязательная опция также влияет на то, как будут обработаны пустые данные для каждого поля. Чтобы узнать больше, см. опцию empty_data.

Дата обновления перевода 2025-02-24

row_attr

тип: array по умолчанию: []

Ассоциативный массив атрибутов HTML, добавляемых к элементу, который используется для отображения строки типа формы :

1
2
3
$builder->add('body', TextareaType::class, [
    'row_attr' => ['class' => 'text-editor', 'id' => '...'],
]);

See also

Используйте опцию attr, если вы хотите добавить эти атрибуты к к элементу виджета типа формы .

Переменные формы

?????????? ??? ???????????
type string ??? ?????????? ??????????, ??? file, ????? ?????????? ? ???? ???? ????? ?????.