minor #18590 [Documentation] Deprecate annotations (alexandre-daubois)

javiereguiluz · javiereguiluz · commit b4683aeeabaf · 2023-07-21T12:38:16.000+02:00
This PR was merged into the 6.4 branch. Discussion ---------- [Documentation] Deprecate annotations My take on #18589, feedbacks always welcome! 🙂 Commits ------- 0380429 [Documentation] Deprecate annotations
diff --git a/best_practices.rst b/best_practices.rst
@@ -223,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`	`}`