feature #26075 [Validator] Deprecate use of Locale validation constraint without setting "canonicalize" option to true (phansys)

This PR was merged into the 4.1-dev branch.

Discussion
----------

[Validator] Deprecate use of `Locale` validation constraint without setting "canonicalize" option to `true`

|Q            |A        |
|---          |---      |
|Branch       |master   |
|Bug fix?     |no       |
|New feature? |no       |
|BC breaks?   |no       |
|Deprecations?|yes      |
|Tests pass?  |yes      |
|Fixed tickets|#22353   |
|License      |MIT      |
|Doc PR       |symfony/symfony-docs#9248|

See https://github.com/symfony/symfony/pull/22353#issuecomment-363671089.

Commits
-------

1572540a3a Deprecate use of `Locale` validation constraint without setting "canonicalize" option to `true`

src/Symfony/Component/Validator/CHANGELOG.md

@@ -6,6 +6,7 @@ CHANGELOG
 
  * Deprecated the `checkDNS` and `dnsMessage` options of the `Url` constraint.
  * added a `values` option to the `Expression` constraint
+ * Deprecated use of `Locale` constraint without setting `true` at "canonicalize" option, which will be the default value in 5.0
 
 4.0.0
 -----

src/Symfony/Component/Validator/Constraints/Locale.php

@@ -29,4 +29,13 @@ class Locale extends Constraint
 
     public $message = 'This value is not a valid locale.';
     public $canonicalize = false;
+
+    public function __construct($options = null)
+    {
+        if (!($options['canonicalize'] ?? false)) {
+            @trigger_error('The "canonicalize" option with value "false" is deprecated since Symfony 4.1, set it to "true" instead.', E_USER_DEPRECATED);
+        }
+
+        parent::__construct($options);
+    }
 }

src/Symfony/Component/Validator/Constraints/LocaleValidator.php

@@ -40,7 +40,8 @@ class LocaleValidator extends ConstraintValidator
             throw new UnexpectedTypeException($value, 'string');
         }
 
-        $value = (string) $value;
+        $inputValue = (string) $value;
+        $value = $inputValue;
         if ($constraint->canonicalize) {
             $value = \Locale::canonicalize($value);
         }
@@ -49,7 +50,7 @@ class LocaleValidator extends ConstraintValidator
 
         if (!isset($locales[$value]) && !in_array($value, $localeBundle->getAliases(), true)) {
             $this->context->buildViolation($constraint->message)
-                ->setParameter('{{ value }}', $this->formatValue($value))
+                ->setParameter('{{ value }}', $this->formatValue($inputValue))
                 ->setCode(Locale::NO_SUCH_LOCALE_ERROR)
                 ->addViolation();
         }

src/Symfony/Component/Validator/Tests/Constraints/LocaleValidatorTest.php

@@ -22,34 +22,83 @@ class LocaleValidatorTest extends ConstraintValidatorTestCase
         return new LocaleValidator();
     }
 
-    public function testNullIsValid()
+    /**
+     * @group legacy
+     * @expectedDeprecation The "canonicalize" option with value "false" is deprecated since Symfony 4.1, set it to "true" instead.
+     *
+     * @dataProvider getValidLocales
+     */
+    public function testLegacyNullIsValid()
     {
         $this->validator->validate(null, new Locale());
 
         $this->assertNoViolation();
     }
 
-    public function testEmptyStringIsValid()
+    public function testNullIsValid()
+    {
+        $this->validator->validate(null, new Locale(array('canonicalize' => true)));
+
+        $this->assertNoViolation();
+    }
+
+    /**
+     * @group legacy
+     * @expectedDeprecation The "canonicalize" option with value "false" is deprecated since Symfony 4.1, set it to "true" instead.
+     *
+     * @dataProvider getValidLocales
+     */
+    public function testLegacyEmptyStringIsValid()
     {
         $this->validator->validate('', new Locale());
 
         $this->assertNoViolation();
     }
 
+    public function testEmptyStringIsValid()
+    {
+        $this->validator->validate('', new Locale(array('canonicalize' => true)));
+
+        $this->assertNoViolation();
+    }
+
+    /**
+     * @group legacy
+     * @expectedDeprecation The "canonicalize" option with value "false" is deprecated since Symfony 4.1, set it to "true" instead.
+     * @expectedException \Symfony\Component\Validator\Exception\UnexpectedTypeException
+     */
+    public function testLegacyExpectsStringCompatibleType()
+    {
+        $this->validator->validate(new \stdClass(), new Locale());
+    }
+
     /**
      * @expectedException \Symfony\Component\Validator\Exception\UnexpectedTypeException
      */
     public function testExpectsStringCompatibleType()
     {
-        $this->validator->validate(new \stdClass(), new Locale());
+        $this->validator->validate(new \stdClass(), new Locale(array('canonicalize' => true)));
+    }
+
+    /**
+     * @group legacy
+     * @expectedDeprecation The "canonicalize" option with value "false" is deprecated since Symfony 4.1, set it to "true" instead.
+     *
+     * @dataProvider getValidLocales
+     */
+    public function testLegacyValidLocales(string $locale)
+    {
+        $this->validator->validate($locale, new Locale());
+
+        $this->assertNoViolation();
     }
 
     /**
      * @dataProvider getValidLocales
      */
-    public function testValidLocales($locale)
+    public function testValidLocales($locale, array $options)
     {
-        $this->validator->validate($locale, new Locale());
+        $this->validator->validate($locale, new Locale($options));
 
         $this->assertNoViolation();
     }
@@ -57,19 +106,21 @@ class LocaleValidatorTest extends ConstraintValidatorTestCase
     public function getValidLocales()
     {
         return array(
-            array('en'),
-            array('en_US'),
-            array('pt'),
-            array('pt_PT'),
-            array('zh_Hans'),
-            array('fil_PH'),
+            array('en', array('canonicalize' => true)),
+            array('en_US', array('canonicalize' => true)),
+            array('pt', array('canonicalize' => true)),
+            array('pt_PT', array('canonicalize' => true)),
+            array('zh_Hans', array('canonicalize' => true)),
+            array('fil_PH', array('canonicalize' => true)),
         );
     }
 
     /**
-     * @dataProvider getInvalidLocales
+     * @group legacy
+     * @expectedDeprecation The "canonicalize" option with value "false" is deprecated since Symfony 4.1, set it to "true" instead.
+     * @dataProvider getLegacyInvalidLocales
      */
-    public function testInvalidLocales($locale)
+    public function testLegacyInvalidLocales(string $locale)
     {
         $constraint = new Locale(array(
             'message' => 'myMessage',
@@ -83,7 +134,7 @@ class LocaleValidatorTest extends ConstraintValidatorTestCase
             ->assertRaised();
     }
 
-    public function getInvalidLocales()
+    public function getLegacyInvalidLocales()
     {
         return array(
             array('EN'),
@@ -92,6 +143,34 @@ class LocaleValidatorTest extends ConstraintValidatorTestCase
     }
 
     /**
+     * @dataProvider getInvalidLocales
+     */
+    public function testInvalidLocales($locale)
+    {
+        $constraint = new Locale(array(
+            'message' => 'myMessage',
+            'canonicalize' => true,
+        ));
+
+        $this->validator->validate($locale, $constraint);
+
+        $this->buildViolation('myMessage')
+            ->setParameter('{{ value }}', '"'.$locale.'"')
+            ->setCode(Locale::NO_SUCH_LOCALE_ERROR)
+            ->assertRaised();
+    }
+
+    public function getInvalidLocales()
+    {
+        return array(
+            array('baz'),
+            array('foobar'),
+        );
+    }
+
+    /**
+     * @group legacy
+     * @expectedDeprecation The "canonicalize" option with value "false" is deprecated since Symfony 4.1, set it to "true" instead.
      * @dataProvider getUncanonicalizedLocales
      */
     public function testInvalidLocalesWithoutCanonicalization(string $locale)