Documented the email_validation_mode config option

javiereguiluz · javiereguiluz · commit 799c57b7bf7b · 2018-01-31T16:28:43.000+01:00
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
@@ -99,6 +99,7 @@ Configuration
     * :ref:`enable_annotations <reference-validation-enable_annotations>`
     * `translation_domain`_
     * `strict_email`_
+    * `email_validation_mode`_
     * :ref:`mapping <reference-validation-mapping>`
         * :ref:`paths <reference-validation-mapping-paths>`
 * `annotations`_
@@ -1577,10 +1578,34 @@ strict_email
 
 **type**: ``Boolean`` **default**: ``false``
 
+.. versionadded:: 4.1
+    The ``strict_email`` option was deprecated in Symfony 4.1. Use the new
+    ``email_validation_mode`` option instead.
+
 If this option is enabled, the `egulias/email-validator`_ library will be
 used by the :doc:`/reference/constraints/Email` constraint validator. Otherwise,
 the validator uses a simple regular expression to validate email addresses.
 
+email_validation_mode
+.....................
+
+**type**: ``string`` **default**: ``loose``
+
+.. versionadded:: 4.1
+    The ``email_validation_mode`` option was introduced in Symfony 4.1.
+
+It controls the way email addresses are validated by the
+:doc:`/reference/constraints/Email` validator. The possible values are:
+
+* ``loose``, it uses a simple regular expression to validate the address (it
+  checks that at least one ``@`` character is present, etc.). This validation is
+  too simple and it's recommended to use the ``html5`` validation instead;
+* ``html5``, it validates email addresses using the same regular expression
+  defined in the HTML5 standard, making the backend validation consistent with
+  the one provided by browsers;
+* ``strict``, it uses the `egulias/email-validator`_ library (which you must
+  install separately) to validate the addresses according to the `RFC 5322`_.
+
 .. _reference-validation-mapping:
 
 mapping
@@ -2056,6 +2081,7 @@ Full Default Configuration
 .. _`Security Advisory Blog post`: https://symfony.com/blog/security-releases-symfony-2-0-24-2-1-12-2-2-5-and-2-3-3-released#cve-2013-4752-request-gethost-poisoning
 .. _`Doctrine Cache`: http://docs.doctrine-project.org/projects/doctrine-common/en/latest/reference/caching.html
 .. _`egulias/email-validator`: https://github.com/egulias/EmailValidator
+.. _`RFC 5322`: https://tools.ietf.org/html/rfc5322
 .. _`PhpStormProtocol`: https://github.com/aik099/PhpStormProtocol
 .. _`phpstorm-url-handler`: https://github.com/sanduhrs/phpstorm-url-handler
 .. _`blue/green deployment`: http://martinfowler.com/bliki/BlueGreenDeployment.html
