[Documentation] Deprecate annotations

alexandre-daubois · alexandre-daubois · commit 03804299faa1 · 2023-07-21T09:25:42.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
@@ -302,7 +302,7 @@ Before continuing, run this command to add support for the new dependencies:
 
 .. code-block:: terminal
 
-    $ composer require symfony/yaml symfony/twig-bundle symfony/web-profiler-bundle doctrine/annotations
+    $ composer require symfony/yaml symfony/twig-bundle symfony/web-profiler-bundle
 
 Next, create a new extension class that defines your app configuration and
 add a service conditionally based on the ``foo`` value::
@@ -377,7 +377,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/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
@@ -217,7 +217,6 @@ allows you to return a list of extensions to register::
             // or if you also need to read constraints from annotations
             $validator = Validation::createValidatorBuilder()
                 ->enableAnnotationMapping(true)
-                ->addDefaultDoctrineAnnotationReader()
                 ->getValidator();
 
             return [
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
diff --git a/routing/custom_route_loader.rst b/routing/custom_route_loader.rst
diff --git a/security.rst b/security.rst
diff --git a/serializer.rst b/serializer.rst

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`	`}`