[ker0x]

Q	A
Bug fix?	no
New feature?	yes
Deprecations?	yes
Documentation?	yes
Issues	#4142
License	MIT

Fifth step of the RFC in #4142.

The placeholder of the drop zone comes from attr.placeholder. This has two problems:

• attr is also rendered on the <input type="file">, so the input gets a placeholder attribute, which is not valid on a file input.
• The default text is the default value of the whole attr option, so the text and the input's attributes cannot be set apart.

This adds a placeholder option (string, TranslatableInterface or false), translated with the form's translation domain like before (a TranslatableInterface is always translated, also with translation_domain: false). false shows no text. The text stays in attr.placeholder of the form view, where the theme reads it and leaves it out of the input's attributes: the placeholder is no longer rendered on the input, while a placeholder passed to form_widget() and themes copied from an older version keep working. Its default keeps today's behavior: 'Drag and drop or browse' when the field has no attr, and attr.placeholder (or no text) when the field passes its own attr, which used to replace the default text.

attr.placeholder keeps working as the text when the placeholder option is not passed, and is deprecated in favor of the new option. The deprecation is triggered once per field, when the options are resolved. src/Dropzone/UPGRADE.md explains the migration.

Field options	Before	After
none	default text, placeholder attribute on input	default text
'attr' => ['data-controller' => 'x']	no text	no text
'attr' => ['placeholder' => 'Drop it']	Drop it, placeholder attribute on input	Drop it, deprecation
'placeholder' => 'Drop it'	not possible	Drop it
'placeholder' => false	not possible	no text

symfony/deprecation-contracts is added to require, for trigger_deprecation(). It was already installed through symfony/form.

Tests: PHPUnit tests for the default text, with and without attr, a string, a TranslatableInterface (also without translation domain), false, true and a non-string attr.placeholder (rejected), the text in the view's attr, attr variables passed to form_widget() with and without a placeholder, and the deprecated attr.placeholder, alone, next to the new option, and with the view created twice. They fail on the base branch, except the one checking that attr variables without a placeholder keep the default text, as before. The deprecation tests catch it with their own error handler, which keeps only the Dropzone deprecations: the test bootstrap registers Symfony's ErrorHandler, and PHPUnit ignores a deprecation triggered from an options normalizer because the OptionsResolver calls it (ignoreIndirectDeprecations).

[Kocal]

Thank you @ker0x.