[Form] Document the hidden placeholder of required ChoiceType fields

Since 8.1, placeholder_attr defaults to ["hidden" => true] on required
collapsed ChoiceType fields, but the change shipped without CHANGELOG or
UPGRADE entries and no layout test asserts the attribute. Add both notes
and pin the rendering at HTML level: hidden on the placeholder option of
required fields, absent for non-required fields and for placeholders
injected via view variables (the default only applies to the placeholder
option). The required-field assertions detect the installed symfony/form
behavior so the bridge test suite keeps passing against 7.4/8.0 in the
lowest-dependencies jobs.

Author: lacatoire

Tests/Extension/AbstractBootstrap3LayoutTestCase.php

@@ -775,13 +775,14 @@ public function testSingleChoiceRequiredWithPlaceholder()
             'placeholder' => 'Test&Me',
         ]);
 
+        $placeholderHidden = $this->isRequiredPlaceholderHiddenByDefault() ? '[@hidden="hidden"]' : '[not(@hidden)]';
         $this->assertWidgetMatchesXpath($form->createView(), ['attr' => ['class' => 'my&class']],
             '/select
     [@name="name"]
     [@class="my&class form-control"]
     [@required="required"]
     [
-        ./option[@value=""][not(@selected)][not(@disabled)][.="[trans]Test&Me[/trans]"]
+        ./option[@value=""][not(@selected)][not(@disabled)]'.$placeholderHidden.'[.="[trans]Test&Me[/trans]"]
         /following-sibling::option[@value="&a"][@selected="selected"][.="[trans]Choice&A[/trans]"]
         /following-sibling::option[@value="&b"][not(@selected)][.="[trans]Choice&B[/trans]"]
     ]
@@ -799,13 +800,15 @@ public function testSingleChoiceRequiredWithPlaceholderViaView()
             'expanded' => false,
         ]);
 
+        // The hidden attribute is only defaulted for the "placeholder" option:
+        // placeholders injected via view variables render without it.
         $this->assertWidgetMatchesXpath($form->createView(), ['placeholder' => '', 'attr' => ['class' => 'my&class']],
             '/select
     [@name="name"]
     [@class="my&class form-control"]
     [@required="required"]
     [
-        ./option[@value=""][not(@selected)][not(@disabled)][.=""]
+        ./option[@value=""][not(@selected)][not(@disabled)][not(@hidden)][.=""]
         /following-sibling::option[@value="&a"][@selected="selected"][.="[trans]Choice&A[/trans]"]
         /following-sibling::option[@value="&b"][not(@selected)][.="[trans]Choice&B[/trans]"]
     ]

Tests/Extension/AbstractBootstrap5LayoutTestCase.php

@@ -783,13 +783,14 @@ public function testSingleChoiceRequiredWithPlaceholder()
             'placeholder' => 'Test&Me',
         ]);
 
+        $placeholderHidden = $this->isRequiredPlaceholderHiddenByDefault() ? '[@hidden="hidden"]' : '[not(@hidden)]';
         $this->assertWidgetMatchesXpath($form->createView(), ['attr' => ['class' => 'my&class']],
             '/select
     [@name="name"]
     [@class="my&class form-select"]
     [@required="required"]
     [
-        ./option[@value=""][not(@selected)][not(@disabled)][.="[trans]Test&Me[/trans]"]
+        ./option[@value=""][not(@selected)][not(@disabled)]'.$placeholderHidden.'[.="[trans]Test&Me[/trans]"]
         /following-sibling::option[@value="&a"][@selected="selected"][.="[trans]Choice&A[/trans]"]
         /following-sibling::option[@value="&b"][not(@selected)][.="[trans]Choice&B[/trans]"]
     ]
@@ -807,13 +808,15 @@ public function testSingleChoiceRequiredWithPlaceholderViaView()
             'expanded' => false,
         ]);
 
+        // The hidden attribute is only defaulted for the "placeholder" option:
+        // placeholders injected via view variables render without it.
         $this->assertWidgetMatchesXpath($form->createView(), ['placeholder' => '', 'attr' => ['class' => 'my&class']],
             '/select
     [@name="name"]
     [@class="my&class form-select"]
     [@required="required"]
     [
-        ./option[@value=""][not(@selected)][not(@disabled)][.=""]
+        ./option[@value=""][not(@selected)][not(@disabled)][not(@hidden)][.=""]
         /following-sibling::option[@value="&a"][@selected="selected"][.="[trans]Choice&A[/trans]"]
         /following-sibling::option[@value="&b"][not(@selected)][.="[trans]Choice&B[/trans]"]
     ]

Tests/Extension/AbstractLayoutTestCase.php

@@ -63,6 +63,21 @@ protected function tearDown(): void
         }
     }
 
+    /**
+     * The "hidden" placeholder_attr default of required ChoiceType fields depends
+     * on the installed symfony/form version (the default was introduced in 8.1).
+     */
+    protected function isRequiredPlaceholderHiddenByDefault(): bool
+    {
+        $view = $this->factory->createNamed('name', 'Symfony\Component\Form\Extension\Core\Type\ChoiceType', null, [
+            'choices' => [],
+            'required' => true,
+            'placeholder' => 'placeholder',
+        ])->createView();
+
+        return (bool) ($view->vars['placeholder_attr']['hidden'] ?? false);
+    }
+
     protected function assertWidgetMatchesXpath(FormView $view, array $vars, $xpath)
     {
         // include ampersands everywhere to validate escaping
@@ -820,7 +835,7 @@ public function testSingleChoiceNonRequiredWithPlaceholder()
     [@name="name"]
     [not(@required)]
     [
-        ./option[@value=""][not(@selected)][not(@disabled)][.="[trans]Select&Anything&Not&Me[/trans]"]
+        ./option[@value=""][not(@selected)][not(@disabled)][not(@hidden)][.="[trans]Select&Anything&Not&Me[/trans]"]
         /following-sibling::option[@value="&a"][@selected="selected"][.="[trans]Choice&A[/trans]"]
         /following-sibling::option[@value="&b"][not(@selected)][.="[trans]Choice&B[/trans]"]
     ]
@@ -842,12 +857,13 @@ public function testSingleChoiceRequiredWithPlaceholder()
         // The "disabled" attribute was removed again due to a bug in the
         // BlackBerry 10 browser.
         // See https://github.com/symfony/symfony/pull/7678
+        $placeholderHidden = $this->isRequiredPlaceholderHiddenByDefault() ? '[@hidden="hidden"]' : '[not(@hidden)]';
         $this->assertWidgetMatchesXpath($form->createView(), [],
             '/select
     [@name="name"]
     [@required="required"]
     [
-        ./option[@value=""][not(@selected)][not(@disabled)][.="[trans]Test&Me[/trans]"]
+        ./option[@value=""][not(@selected)][not(@disabled)]'.$placeholderHidden.'[.="[trans]Test&Me[/trans]"]
         /following-sibling::option[@value="&a"][@selected="selected"][.="[trans]Choice&A[/trans]"]
         /following-sibling::option[@value="&b"][not(@selected)][.="[trans]Choice&B[/trans]"]
     ]
@@ -868,12 +884,14 @@ public function testSingleChoiceRequiredWithPlaceholderViaView()
         // The "disabled" attribute was removed again due to a bug in the
         // BlackBerry 10 browser.
         // See https://github.com/symfony/symfony/pull/7678
+        // The hidden attribute is only defaulted for the "placeholder" option:
+        // placeholders injected via view variables render without it.
         $this->assertWidgetMatchesXpath($form->createView(), ['placeholder' => ''],
             '/select
     [@name="name"]
     [@required="required"]
     [
-        ./option[@value=""][not(@selected)][not(@disabled)][.=""]
+        ./option[@value=""][not(@selected)][not(@disabled)][not(@hidden)][.=""]
         /following-sibling::option[@value="&a"][@selected="selected"][.="[trans]Choice&A[/trans]"]
         /following-sibling::option[@value="&b"][not(@selected)][.="[trans]Choice&B[/trans]"]
     ]