[Documentation] Deprecate annotations

alexandre-daubois · alexandre-daubois · commit 14d8b137388c · 2023-07-20T16:52:57.000+02:00
diff --git a/best_practices.rst b/best_practices.rst
@@ -207,9 +207,6 @@ Doctrine supports several metadata formats, but it's recommended to use PHP
 attributes because they are by far the most convenient and agile way of setting
 up and looking for mapping information.
 
-If your PHP version doesn't support attributes yet, use annotations, which is
-similar but requires installing some extra dependencies in your project.
-
 Controllers
 -----------
 
@@ -226,12 +223,12 @@ controllers shouldn't contain any business logic. Controllers should contain
 nothing more than a few lines of *glue-code*, so you are not coupling the
 important parts of your application.
 
-.. _best-practice-controller-annotations:
+.. _best-practice-controller-attributes:
 
-Use Attributes or Annotations to Configure Routing, Caching, and Security
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Use Attributes to Configure Routing, Caching, and Security
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Using attributes or annotations for routing, caching, and security simplifies
+Using attributes for routing, caching, and security simplifies
 configuration. You don't need to browse several files created with different
 formats (YAML, XML, PHP): all the configuration is just where you  require it,
 and it only uses one format.
diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst
@@ -123,8 +123,8 @@ Event Listeners                                      ``src/EventListener/``
 Configuration (routes, services, etc.)               ``config/``
 Web Assets (CSS, JS, images)                         ``public/``
 Translation files                                    ``translations/``
-Validation (when not using annotations)              ``config/validation/``
-Serialization (when not using annotations)           ``config/serialization/``
+Validation (when not using attributes)               ``config/validation/``
+Serialization (when not using attributes)            ``config/serialization/``
 Templates                                            ``templates/``
 Unit and Functional Tests                            ``tests/``
 ===================================================  ========================================
@@ -163,7 +163,7 @@ If the bundle includes Doctrine ORM entities and/or ODM documents, it's
 recommended to define their mapping using XML files stored in
 ``config/doctrine/``. This allows to override that mapping using the
 :doc:`standard Symfony mechanism to override bundle parts </bundles/override>`.
-This is not possible when using annotations/attributes to define the mapping.
+This is not possible when using attributes to define the mapping.
 
 Tests
 -----
diff --git a/components/config/resources.rst b/components/config/resources.rst
@@ -30,7 +30,7 @@ an array containing all matches.
 Resource Loaders
 ----------------
 
-For each type of resource (YAML, XML, annotation, etc.) a loader must be
+For each type of resource (YAML, XML, attributes, etc.) a loader must be
 defined. Each loader should implement
 :class:`Symfony\\Component\\Config\\Loader\\LoaderInterface` or extend the
 abstract :class:`Symfony\\Component\\Config\\Loader\\FileLoader` class,
diff --git a/components/serializer.rst b/components/serializer.rst
@@ -288,7 +288,7 @@ for each format:
 
     $classMetadataFactory = new ClassMetadataFactory(new XmlFileLoader('/path/to/your/definition.xml'));
 
-.. _component-serializer-attributes-groups-annotations:
+.. _component-serializer-attributes-groups-attributes:
 
 Then, create your groups definition:
 
@@ -436,8 +436,8 @@ Ignoring Attributes
 All attributes are included by default when serializing objects. There are two
 options to ignore some of those attributes.
 
-Option 1: Using ``@Ignore`` Annotation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Option 1: Using ``#[Ignore]`` Attribute
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. configuration-block::
 
diff --git a/components/validator/resources.rst b/components/validator/resources.rst
@@ -114,6 +114,10 @@ If you use annotations instead of attributes, it's also required to call
         ->addDefaultDoctrineAnnotationReader() // add this only when using annotations
         ->getValidator();
 
+.. deprecated:: 6.4
+
+    Annotations are deprecated since Symfony 6.4, use attributes instead.
+
 To disable the annotation loader after it was enabled, call
 :method:`Symfony\\Component\\Validator\\ValidatorBuilder::disableAnnotationMapping`.
 
diff --git a/configuration/micro_kernel_trait.rst b/configuration/micro_kernel_trait.rst
@@ -298,6 +298,10 @@ Now it looks like this::
         }
     }
 
+.. deprecated:: 6.4
+
+    Annotations are deprecated since Symfony 6.4, use attributes instead.
+
 Before continuing, run this command to add support for the new dependencies:
 
 .. code-block:: terminal
@@ -377,7 +381,7 @@ because the configuration started to get bigger:
             ;
         };
 
-This also loads annotation routes from an ``src/Controller/`` directory, which
+This also loads attribute routes from an ``src/Controller/`` directory, which
 has one file in it::
 
     // src/Controller/MicroController.php
diff --git a/configuration/multiple_kernels.rst b/configuration/multiple_kernels.rst
@@ -205,7 +205,7 @@ resources::
             }
 
             if (false !== ($fileName = (new \ReflectionObject($this))->getFileName())) {
-                $routes->import($fileName, 'annotation');
+                $routes->import($fileName, 'attribute');
             }
         }
     }
diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst
@@ -118,7 +118,6 @@ Markup Format        Use It to Display
 ``html+twig``        Twig markup blended with HTML
 ``html+php``         PHP code blended with HTML
 ``ini``              INI
-``php-annotations``  PHP Annotations
 ``php-attributes``   PHP Attributes
 ``php-symfony``      PHP code example when using the Symfony framework
 ``php-standalone``   PHP code to be used in any PHP application using standalone Symfony components
diff --git a/controller.rst b/controller.rst
@@ -63,7 +63,7 @@ Mapping a URL to a Controller
 
 In order to *view* the result of this controller, you need to map a URL to it via
 a route. This was done above with the ``#[Route('/lucky/number/{max}')]``
-:ref:`route attribute <annotation-routes>`.
+:ref:`route attribute <attribute-routes>`.
 
 To see your page, go to this URL in your browser: http://localhost:8000/lucky/number/100
 
diff --git a/controller/upload_file.rst b/controller/upload_file.rst
@@ -72,7 +72,7 @@ so Symfony doesn't try to get/set its value from the related entity::
                     // every time you edit the Product details
                     'required' => false,
 
-                    // unmapped fields can't define their validation using annotations
+                    // unmapped fields can't define their validation using attributes
                     // in the associated entity, so you can use the PHP constraint classes
                     'constraints' => [
                         new File([
diff --git a/doctrine.rst b/doctrine.rst
@@ -193,7 +193,7 @@ add/remove fields, add/remove methods or update configuration.
 
 Doctrine supports a wide variety of field types, each with their own options.
 To see a full list, check out `Doctrine's Mapping Types documentation`_.
-If you want to use XML instead of annotations, add ``type: xml`` and
+If you want to use XML instead of attributes, add ``type: xml`` and
 ``dir: '%kernel.project_dir%/config/doctrine'`` to the entity mappings in your
 ``config/packages/doctrine.yaml`` file.
 
@@ -746,7 +746,7 @@ the default convention.
 MapEntity Options
 ~~~~~~~~~~~~~~~~~
 
-A number of options are available on the ``MapEntity`` annotation to
+A number of options are available on the ``MapEntity`` attribute to
 control behavior:
 
 ``id``
diff --git a/doctrine/associations.rst b/doctrine/associations.rst
@@ -91,7 +91,7 @@ From the perspective of the ``Product`` entity, this is a many-to-one relationsh
 From the perspective of the ``Category`` entity, this is a one-to-many relationship.
 
 To map this, first create a ``category`` property on the ``Product`` class with
-the ``ManyToOne`` annotation. You can do this by hand, or by using the ``make:entity``
+the ``ManyToOne`` attribute. You can do this by hand, or by using the ``make:entity``
 command, which will ask you several questions about your relationship. If you're
 not sure of the answer, don't worry! You can always change the settings later:
 
diff --git a/form/unit_testing.rst b/form/unit_testing.rst
@@ -228,6 +228,10 @@ allows you to return a list of extensions to register::
         // ... your tests
     }
 
+.. deprecated:: 6.4
+
+    Annotations are deprecated since Symfony 6.4, use attributes instead.
+
 .. note::
 
     By default only the
diff --git a/page_creation.rst b/page_creation.rst
@@ -55,7 +55,7 @@ random) number and prints it. To do that, create a "Controller" class and a
         }
     }
 
-.. _annotation-routes:
+.. _attribute-routes:
 
 Now you need to associate this controller function with a public URL (e.g. ``/lucky/number``)
 so that the ``number()`` method is called when a user browses to it. This association
diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst
@@ -135,13 +135,8 @@ Try the page out by going to ``http://localhost:8000/hello/Symfony``. You should
 see: Hello Symfony! The value of the ``{name}`` in the URL is available as a ``$name``
 argument in your controller.
 
-But this can be even simpler! So let's install annotations support:
-
-.. code-block:: terminal
-
-    $ composer require annotations
-
-Now, comment-out the YAML route by adding the ``#`` character:
+But this can be even simpler! Comment-out the YAML route by adding the
+``#`` character:
 
 .. code-block:: yaml
 
diff --git a/reference/attributes.rst b/reference/attributes.rst
@@ -5,6 +5,11 @@ Attributes are the successor of annotations since PHP 8. Attributes are native
 to the language and Symfony takes full advantage of them across the framework
 and its different components.
 
+.. deprecated:: 6.4
+
+    Annotations across the framework are deprecated since Symfony 6.4, you must
+    only use attributes instead.
+
 Doctrine Bridge
 ~~~~~~~~~~~~~~~
 
@@ -78,14 +83,14 @@ Security
 ~~~~~~~~
 
 * :ref:`CurrentUser <security-json-login>`
-* :ref:`IsGranted <security-securing-controller-annotations>`
+* :ref:`IsGranted <security-securing-controller-attributes>`
 
 Serializer
 ~~~~~~~~~~
 
 * :ref:`Context <serializer_serializer-context>`
 * :ref:`DiscriminatorMap <serializer_interfaces-and-abstract-classes>`
-* :ref:`Groups <component-serializer-attributes-groups-annotations>`
+* :ref:`Groups <component-serializer-attributes-groups-attributes>`
 * :ref:`Ignore <serializer_ignoring-attributes>`
 * :ref:`MaxDepth <serializer_handling-serialization-depth>`
 * :ref:`SerializedName <serializer_name-conversion>`
diff --git a/reference/configuration/doctrine.rst b/reference/configuration/doctrine.rst
@@ -274,6 +274,10 @@ One of ``annotation`` (for PHP annotations; it's the default value),
 ``attribute`` (for PHP attributes), ``xml``, ``yml``, ``php`` or
 ``staticphp``. This specifies which type of metadata type your mapping uses.
 
+.. deprecated:: 6.4
+
+    Annotations are deprecated since Symfony 6.4, use attributes instead.
+
 See `Doctrine Metadata Drivers`_ for more information about this option.
 
 ``dir``
@@ -385,7 +389,7 @@ namespace in the ``src/Entity`` directory and gives them an ``App`` alias
                     mappings:
                         # ...
                         SomeEntityNamespace:
-                            type: annotation
+                            type: attribute
                             dir: '%kernel.project_dir%/src/Entity'
                             is_bundle: false
                             prefix: App\Entity
@@ -403,7 +407,7 @@ namespace in the ``src/Entity`` directory and gives them an ``App`` alias
             <doctrine:config>
                 <doctrine:orm>
                     <mapping name="SomeEntityNamespace"
-                        type="annotation"
+                        type="attribute"
                         dir="%kernel.project_dir%/src/Entity"
                         is-bundle="false"
                         prefix="App\Entity"
@@ -422,7 +426,7 @@ namespace in the ``src/Entity`` directory and gives them an ``App`` alias
 
             $emDefault->autoMapping(true);
             $emDefault->mapping('SomeEntityNamespace')
-                ->type('annotation')
+                ->type('attribute')
                 ->dir('%kernel.project_dir%/src/Entity')
                 ->isBundle(false)
                 ->prefix('App\Entity')
@@ -446,14 +450,14 @@ configuration format. The bundle will stop as soon as it locates one.
 
 If it wasn't possible to determine a configuration format for a bundle,
 the DoctrineBundle will check if there is an ``Entity`` folder in the bundle's
-root directory. If the folder exist, Doctrine will fall back to using an
-annotation driver.
+root directory. If the folder exist, Doctrine will fall back to using
+attributes.
 
 Default Value of Dir
 ....................
 
 If ``dir`` is not specified, then its default value depends on which configuration
-driver is being used. For drivers that rely on the PHP files (annotation,
+driver is being used. For drivers that rely on the PHP files (attribute,
 ``staticphp``) it will be ``[Bundle]/Entity``. For drivers that are using
 configuration files (XML, YAML, ...) it will be
 ``[Bundle]/Resources/config/doctrine``.
diff --git a/reference/constraints/DisableAutoMapping.rst b/reference/constraints/DisableAutoMapping.rst
@@ -3,7 +3,7 @@ DisableAutoMapping
 
 This constraint allows to disable :ref:`Doctrine's auto mapping <doctrine_auto-mapping>`
 on a class or a property. Automapping allows to determine validation rules based
-on Doctrine's annotations and attributes. You may use this constraint when
+on Doctrine's attributes. You may use this constraint when
 automapping is globally enabled, but you still want to disable this feature for
 a class or a property specifically.
 
diff --git a/reference/constraints/EnableAutoMapping.rst b/reference/constraints/EnableAutoMapping.rst
@@ -3,7 +3,7 @@ EnableAutoMapping
 
 This constraint allows to enable :ref:`Doctrine's auto mapping <doctrine_auto-mapping>`
 on a class or a property. Automapping allows to determine validation rules based
-on Doctrine's annotations and attributes. You may use this constraint when
+on Doctrine's attributes. You may use this constraint when
 automapping is globally disabled, but you still want to enable this feature for
 a class or a property specifically.
 
diff --git a/routing.rst b/routing.rst
@@ -15,7 +15,7 @@ Creating Routes
 Routes can be configured in YAML, XML, PHP or using attributes.
 All formats provide the same features and performance, so choose
 your favorite.
-:ref:`Symfony recommends attributes <best-practice-controller-annotations>`
+:ref:`Symfony recommends attributes <best-practice-controller-attributes>`
 because it's convenient to put the route and controller in the same place.
 
 Creating Routes as Attributes
@@ -744,7 +744,7 @@ visit ``/blog/1``, it will match. But if they visit ``/blog``, it will **not**
 match. As soon as you add a parameter to a route, it must have a value.
 
 You can make ``blog_list`` once again match when the user visits ``/blog`` by
-adding a default value for the ``{page}`` parameter. When using annotations or attributes,
+adding a default value for the ``{page}`` parameter. When using attributes,
 default values are defined in the arguments of the controller action. In the
 other configuration formats they are defined with the ``defaults`` option:
 
@@ -901,7 +901,7 @@ Symfony evaluates routes in the order they are defined. If the path of a route
 matches many different patterns, it might prevent other routes from being
 matched. In YAML and XML you can move the route definitions up or down in the
 configuration file to control their priority. In routes defined as PHP
-annotations or attributes this is much harder to do, so you can set the
+attributes this is much harder to do, so you can set the
 optional ``priority`` parameter in those routes to control their priority:
 
 .. configuration-block::
@@ -1505,11 +1505,15 @@ when importing the routes.
             ;
         };
 
+.. deprecated:: 6.4
+
+    Annotations are deprecated since Symfony 6.4, use attributes instead.
+
 In this example, the route of the ``index()`` action will be called ``blog_index``
 and its URL will be ``/blog/{_locale}``. The route of the ``show()`` action will be called
 ``blog_show`` and its URL will be ``/blog/{_locale}/posts/{slug}``. Both routes
 will also validate that the ``_locale`` parameter matches the regular expression
-defined in the class annotation.
+defined in the class attribute.
 
 .. note::
 
@@ -1564,6 +1568,10 @@ defined in the class annotation.
                 ;
             };
 
+    .. deprecated:: 6.4
+
+        Annotations are deprecated since Symfony 6.4, use attributes instead.
+
 .. seealso::
 
     Symfony can :doc:`import routes from different sources </routing/custom_route_loader>`
@@ -2640,6 +2648,10 @@ defined as annotations:
             ;
         };
 
+.. deprecated:: 6.4
+
+    Annotations are deprecated since Symfony 6.4, use attributes instead.
+
 .. note::
 
     The Security component provides
diff --git a/routing/custom_route_loader.rst b/routing/custom_route_loader.rst
@@ -131,7 +131,7 @@ What is a Custom Route Loader
 A custom route loader enables you to generate routes based on some
 conventions, patterns or integrations. An example for this use-case is the
 `OpenAPI-Symfony-Routing`_ library where routes are generated based on
-OpenAPI/Swagger annotations. Another example is the `SonataAdminBundle`_ that
+OpenAPI/Swagger attributes. Another example is the `SonataAdminBundle`_ that
 creates routes based on CRUD conventions.
 
 Loading Routes
diff --git a/security.rst b/security.rst
@@ -2316,7 +2316,7 @@ will happen:
    be shown the 403 access denied page (which you can
    :ref:`customize <controller-error-pages-by-status-code>`).
 
-.. _security-securing-controller-annotations:
+.. _security-securing-controller-attributes:
 
 Another way to secure one or more controller actions is to use the ``#[IsGranted()]`` attribute.
 In the following example, all controller actions will require the
diff --git a/serializer.rst b/serializer.rst

Original file line number	Diff line number	Diff line change
`@@ -298,6 +298,10 @@ Now it looks like this::`
`298`	`298`	`}`
`299`	`299`	`}`
`300`	`300`
	`301`	`+.. deprecated:: 6.4`
	`302`	`+`
	`303`	`+ Annotations are deprecated since Symfony 6.4, use attributes instead.`
	`304`	`+`
`301`	`305`	`Before continuing, run this command to add support for the new dependencies:`
`302`	`306`
`303`	`307`	`.. code-block:: terminal`
`@@ -377,7 +381,7 @@ because the configuration started to get bigger:`
`377`	`381`	`;`
`378`	`382`	`};`
`379`	`383`
`380`		-This also loads annotation routes from an ``src/Controller/`` directory, which
	`384`	+This also loads attribute routes from an ``src/Controller/`` directory, which
`381`	`385`	`has one file in it::`
`382`	`386`
`383`	`387`	`// src/Controller/MicroController.php`
Original file line number	Diff line number	Diff line change
`@@ -205,7 +205,7 @@ resources::`
`205`	`205`	`}`
`206`	`206`
`207`	`207`	`if (false !== ($fileName = (new \ReflectionObject($this))->getFileName())) {`
`208`		`- $routes->import($fileName, 'annotation');`
	`208`	`+ $routes->import($fileName, 'attribute');`
`209`	`209`	`}`
`210`	`210`	`}`
`211`	`211`	`}`