Merge branch '6.0' into 6.1

* 6.0:
  Replace remaining annotations with attributes, remove remaining annotations configuration block
  Fixing "HTML5 color format" link
  Fixing path
  Removing heading
  fixes #16310 unclear alternate DSN format

Author: javiereguiluz

best_practices.rst

@@ -236,11 +236,11 @@ configuration. You don't need to browse several files created with different
 formats (YAML, XML, PHP): all the configuration is just where you need it and
 it only uses one format.
 
-Don't Use Annotations to Configure the Controller Template
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Don't Use Attributes to Configure the Controller Template
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``@Template`` annotation is useful, but also involves some *magic*.
-Moreover, most of the time ``@Template`` is used without any parameters, which
+The ``#[Template]`` attribute is useful, but also involves some *magic*.
+Moreover, most of the time ``#[Template]`` is used without any parameters, which
 makes it more difficult to know which template is being rendered. It also hides
 the fact that a controller should always return a ``Response`` object.
 
@@ -380,8 +380,7 @@ Use Voters to Implement Fine-grained Security Restrictions
 
 If your security logic is complex, you should create custom
 :doc:`security voters </security/voters>` instead of defining long expressions
-inside the ``#[Security]`` attribute (or in the ``@Security`` annotation if your
-PHP version doesn't support attributes yet).
+inside the ``#[Security]`` attribute.
 
 Web Assets
 ----------

components/cache/adapters/redis_adapter.rst

@@ -67,12 +67,18 @@ replaced by ``rediss`` (the second ``s`` means "secure").
 
 .. note::
 
-    A `Data Source Name (DSN)`_ for this adapter must use the following format.
+    A `Data Source Name (DSN)`_ for this adapter must use either one of the following formats.
 
     .. code-block:: text
 
         redis[s]://[pass@][ip|host|socket[:port]][/db-index]
 
+    .. code-block:: text
+
+        redis[s]:[[user]:pass@]?[ip|host|socket[:port]][&params]
+
+    Values for placeholders ``[user]``, ``[:port]``, ``[/db-index]`` and ``[&params]`` are optional.
+
 Below are common examples of valid DSNs showing a combination of available values::
 
     use Symfony\Component\Cache\Adapter\RedisAdapter;
@@ -89,8 +95,13 @@ Below are common examples of valid DSNs showing a combination of available value
     // socket "/var/run/redis.sock" and auth "bad-pass"
     RedisAdapter::createConnection('redis://bad-pass@/var/run/redis.sock');
 
-    // a single DSN can define multiple servers using the following syntax:
-    // host[hostname-or-IP:port] (where port is optional). Sockets must include a trailing ':'
+    // host "redis1" (docker container) with alternate DSN syntax and selecting database index "3"
+    RedisAdapter::createConnection('redis:?host[redis1:6379]&dbindex=3');
+
+    // providing credentials with alternate DSN syntax
+    RedisAdapter::createConnection('redis:default:verysecurepassword@?host[redis1:6379]&dbindex=3');
+
+    // a single DSN can also define multiple servers
     RedisAdapter::createConnection(
         'redis:?host[localhost]&host[localhost:6379]&host[/var/run/redis.sock:]&auth=my-password&redis_cluster=1'
     );
@@ -103,6 +114,16 @@ parameter to set the name of your service group::
         'redis:?host[redis1:26379]&host[redis2:26379]&host[redis3:26379]&redis_sentinel=mymaster'
     );
 
+    // providing credentials
+    RedisAdapter::createConnection(
+        'redis:default:verysecurepassword@?host[redis1:26379]&host[redis2:26379]&host[redis3:26379]&redis_sentinel=mymaster'
+    );
+
+    // providing credentials and selecting database index "3"
+    RedisAdapter::createConnection(
+        'redis:default:verysecurepassword@?host[redis1:26379]&host[redis2:26379]&host[redis3:26379]&redis_sentinel=mymaster&dbindex=3'
+    );
+
 .. note::
 
     See the :class:`Symfony\\Component\\Cache\\Traits\\RedisTrait` for more options
@@ -124,29 +145,31 @@ array of ``key => value`` pairs representing option names and their respective v
 
         // associative array of configuration options
         [
-            'lazy' => false,
+            'class' => null,
             'persistent' => 0,
             'persistent_id' => null,
-            'tcp_keepalive' => 0,
             'timeout' => 30,
             'read_timeout' => 0,
             'retry_interval' => 0,
+            'tcp_keepalive' => 0,
+            'lazy' => null,
+            'redis_cluster' => false,
+            'redis_sentinel' => null,
+            'dbindex' => 0,
+            'failover' => 'none',
+            'ssl' => null,
         ]
 
     );
 
 Available Options
 ~~~~~~~~~~~~~~~~~
 
-``class`` (type: ``string``)
+``class`` (type: ``string``, default: ``null``)
     Specifies the connection library to return, either ``\Redis`` or ``\Predis\Client``.
     If none is specified, it will return ``\Redis`` if the ``redis`` extension is
-    available, and ``\Predis\Client`` otherwise.
-
-``lazy`` (type: ``bool``, default: ``false``)
-    Enables or disables lazy connections to the backend. It's ``false`` by
-    default when using this as a stand-alone component and ``true`` by default
-    when using it inside a Symfony application.
+    available, and ``\Predis\Client`` otherwise. Explicitly set this to ``\Predis\Client`` for Sentinel if you are
+    running into issues when retrieving master information.
 
 ``persistent`` (type: ``int``, default: ``0``)
     Enables or disables use of persistent connections. A value of ``0`` disables persistent
@@ -155,6 +178,10 @@ Available Options
 ``persistent_id`` (type: ``string|null``, default: ``null``)
     Specifies the persistent id string to use for a persistent connection.
 
+``timeout`` (type: ``int``, default: ``30``)
+    Specifies the time (in seconds) used to connect to a Redis server before the
+    connection attempt times out.
+
 ``read_timeout`` (type: ``int``, default: ``0``)
     Specifies the time (in seconds) used when performing read operations on the underlying
     network resource before the operation times out.
@@ -167,9 +194,28 @@ Available Options
     Specifies the `TCP-keepalive`_ timeout (in seconds) of the connection. This
     requires phpredis v4 or higher and a TCP-keepalive enabled server.
 
-``timeout`` (type: ``int``, default: ``30``)
-    Specifies the time (in seconds) used to connect to a Redis server before the
-    connection attempt times out.
+``lazy`` (type: ``bool``, default: ``null``)
+    Enables or disables lazy connections to the backend. It's ``false`` by
+    default when using this as a stand-alone component and ``true`` by default
+    when using it inside a Symfony application.
+
+``redis_cluster`` (type: ``bool``, default: ``false``)
+    Enables or disables redis cluster. The actual value passed is irrelevant as long as it passes loose comparison
+    checks: `redis_cluster=1` will suffice.
+
+``redis_sentinel`` (type: ``string``, default: ``null``)
+    Specifies the master name connected to the sentinels.
+
+``dbindex`` (type: ``int``, default: ``0``)
+    Specifies the database index to select.
+
+``failover`` (type: ``string``, default: ``none``)
+    Specifies failover for cluster implementations. For ``\RedisCluster`` valid options are ``none`` (default),
+    ``error``, ``distribute`` or ``slaves``.  For ``\Predis\ClientInterface`` valid options are ``slaves``
+    or ``distribute``.
+
+``ssl`` (type: ``bool``, default: ``null``)
+    SSL context options. See `php.net/context.ssl`_ for more information.
 
 .. note::
 
@@ -217,3 +263,4 @@ Read more about this topic in the official `Redis LRU Cache Documentation`_.
 .. _`TCP-keepalive`: https://redis.io/topics/clients#tcp-keepalive
 .. _`Redis Sentinel`: https://redis.io/topics/sentinel
 .. _`Redis LRU Cache Documentation`: https://redis.io/topics/lru-cache
+.. _`php.net/context.ssl`: https://php.net/context.ssl

components/http_kernel.rst

@@ -302,7 +302,7 @@ on the event object that's passed to listeners on this event.
     the profiler is enabled.
 
     One interesting listener comes from the `SensioFrameworkExtraBundle`_. This
-    listener's `@ParamConverter`_ functionality allows you to pass a full object
+    listener's `#[ParamConverter]`_ functionality allows you to pass a full object
     (e.g. a ``Post`` object) to your controller instead of a scalar value (e.g.
     an ``id`` parameter that was on your route). The listener -
     ``ParamConverterListener`` - uses reflection to look at each of the
@@ -411,8 +411,8 @@ return a ``Response``.
 
     There is no default listener inside the Symfony Framework for the ``kernel.view``
     event. However, `SensioFrameworkExtraBundle`_ *does* add a listener to this
-    event. If your controller returns an array, and you place the `@Template`_
-    annotation above the controller, then this listener renders a template,
+    event. If your controller returns an array, and you place the `#[Template]`_
+    attribute above the controller, then this listener renders a template,
     passes the array you returned from your controller to that template, and
     creates a ``Response`` containing the returned content from that template.
 
@@ -750,6 +750,6 @@ Learn more
 .. _FOSRestBundle: https://github.com/friendsofsymfony/FOSRestBundle
 .. _`PHP FPM`: https://www.php.net/manual/en/install.fpm.php
 .. _`SensioFrameworkExtraBundle`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/index.html
-.. _`@ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
-.. _`@Template`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/view.html
+.. _`#[ParamConverter]`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
+.. _`#[Template]`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/view.html
 .. _variadic: https://www.php.net/manual/en/functions.arguments.php#functions.variable-arg-list

components/serializer.rst

@@ -293,35 +293,6 @@ Then, create your groups definition:
 
 .. configuration-block::
 
-    .. code-block:: php-annotations
-
-        namespace Acme;
-
-        use Symfony\Component\Serializer\Annotation\Groups;
-
-        class MyObj
-        {
-            /**
-             * @Groups({"group1", "group2"})
-             */
-            public $foo;
-
-            /**
-             * @Groups({"group4"})
-             */
-            public $anotherProperty;
-
-            /**
-             * @Groups("group3")
-             */
-            public function getBar() // is* methods are also supported
-            {
-                return $this->bar;
-            }
-
-            // ...
-        }
-
     .. code-block:: php-attributes
 
         namespace Acme;
@@ -467,22 +438,6 @@ Option 1: Using ``@Ignore`` Annotation
 
 .. configuration-block::
 
-    .. code-block:: php-annotations
-
-        namespace App\Model;
-
-        use Symfony\Component\Serializer\Annotation\Ignore;
-
-        class MyClass
-        {
-            public $foo;
-
-            /**
-             * @Ignore()
-             */
-            public $bar;
-        }
-
     .. code-block:: php-attributes
 
         namespace App\Model;
@@ -697,27 +652,6 @@ defines a ``Person`` entity with a ``firstName`` property:
 
 .. configuration-block::
 
-    .. code-block:: php-annotations
-
-        namespace App\Entity;
-
-        use Symfony\Component\Serializer\Annotation\SerializedName;
-
-        class Person
-        {
-            /**
-             * @SerializedName("customer_name")
-             */
-            private $firstName;
-
-            public function __construct($firstName)
-            {
-                $this->firstName = $firstName;
-            }
-
-            // ...
-        }
-
     .. code-block:: php-attributes
 
         namespace App\Entity;
@@ -1450,22 +1384,6 @@ Here, we set it to 2 for the ``$child`` property:
 
 .. configuration-block::
 
-    .. code-block:: php-annotations
-
-        namespace Acme;
-
-        use Symfony\Component\Serializer\Annotation\MaxDepth;
-
-        class MyObj
-        {
-            /**
-             * @MaxDepth(2)
-             */
-            public $child;
-
-            // ...
-        }
-
     .. code-block:: php-attributes
 
         namespace Acme;
@@ -1539,9 +1457,7 @@ having unique identifiers::
     {
         public $id;
 
-        /**
-         * @MaxDepth(1)
-         */
+        #[MaxDepth(1)]
         public $child;
     }
 
@@ -1773,23 +1689,6 @@ and ``BitBucketCodeRepository`` classes:
 
 .. configuration-block::
 
-    .. code-block:: php-annotations
-
-        namespace App;
-
-        use Symfony\Component\Serializer\Annotation\DiscriminatorMap;
-
-        /**
-         * @DiscriminatorMap(typeProperty="type", mapping={
-         *    "github"="App\GitHubCodeRepository",
-         *    "bitbucket"="App\BitBucketCodeRepository"
-         * })
-         */
-        abstract class CodeRepository
-        {
-            // ...
-        }
-
     .. code-block:: php-attributes
 
         namespace App;

contributing/documentation/standards.rst

@@ -88,9 +88,9 @@ Configuration examples should show all supported formats using
 (and their orders) are:
 
 * **Configuration** (including services): YAML, XML, PHP
-* **Routing**: Annotations, YAML, XML, PHP
-* **Validation**: Annotations, YAML, XML, PHP
-* **Doctrine Mapping**: Annotations, YAML, XML, PHP
+* **Routing**: Attributes, YAML, XML, PHP
+* **Validation**: Attributes, YAML, XML, PHP
+* **Doctrine Mapping**: Attributes, YAML, XML, PHP
 * **Translation**: XML, YAML, PHP
 
 Example

controller/argument_value_resolver.rst

@@ -186,8 +186,8 @@ with the ``User`` class::
         }
     }
 
-Beware that this feature is already provided by the `@ParamConverter`_
-annotation from the SensioFrameworkExtraBundle. If you have that bundle
+Beware that this feature is already provided by the `#[ParamConverter]`_
+attribute from the SensioFrameworkExtraBundle. If you have that bundle
 installed in your project, add this config to disable the auto-conversion of
 type-hinted method arguments:
 
@@ -372,5 +372,5 @@ command to see which argument resolvers are present and in which order they run.
     $user = null``). The ``DefaultValueResolver`` is executed as the last
     resolver and will use the default value if no value was already resolved.
 
-.. _`@ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
+.. _`#[ParamConverter]`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
 .. _`yield`: https://www.php.net/manual/en/language.generators.syntax.php

form/form_collections.rst

@@ -522,8 +522,6 @@ Now, you need to put some code into the ``removeTag()`` method of ``Task``::
         }
     }
 
-Template Modifications
-~~~~~~~~~~~~~~~~~~~~~~
 
 The ``allow_delete`` option means that if an item of a collection
 isn't sent on submission, the related data is removed from the collection

form/form_themes.rst

@@ -141,7 +141,7 @@ order is important, because each theme overrides all the previous ones):
     {# apply multiple form themes but only to the form of this template #}
     {% form_theme form with [
         'foundation_5_layout.html.twig',
-        'forms/my_custom_theme.html.twig'
+        'form/my_custom_theme.html.twig'
     ] %}
 
     {# ... #}

reference/configuration/doctrine.rst

@@ -310,7 +310,7 @@ to organize the application code.
 Custom Mapping Entities in a Bundle
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Doctrine's ``auto_mapping`` feature loads annotation configuration from
+Doctrine's ``auto_mapping`` feature loads attribute configuration from
 the ``Entity/`` directory of each bundle *and* looks for other formats (e.g.
 YAML, XML) in the ``Resources/config/doctrine`` directory.