8000 [Documentation] Deprecate annotations · symfony/symfony-docs@9918c6f · GitHub
[go: up one dir, main page]
Skip to content

Commit 9918c6f

Browse files
alexandre-dauboisalexandre-daubois
committed
[Documentation] Deprecate annotations
1 parent db49e10 commit 9918c6f

22 files changed

+89
-119
lines changed

‎best_practices.rst

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -207,9 +207,6 @@ Doctrine supports several metadata formats, but it's recommended to use PHP
207207
attributes because they are by far the most convenient and agile way of setting
208208
up and looking for mapping information.
209209

210-
If your PHP version doesn't support attributes yet, use annotations, which is
211-
similar but requires installing some extra dependencies in your project.
212-
213210
Controllers
214211
-----------
215212

@@ -226,12 +223,12 @@ controllers shouldn't contain any business logic. Controllers should contain
226223
nothing more than a few lines of *glue-code*, so you are not coupling the
227224
important parts of your application.
228225

229-
.. _best-practice-controller-annotations:
226+
.. _best-practice-controller-attributes:
230227

231-
Use Attributes or Annotations to Configure Routing, Caching, and Security
232-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
228+
Use Attributes to Configure Routing, Caching, and Security
229+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
233230

234-
Using attributes or annotations for routing, caching, and security simplifies
231+
Using attributes for routing, caching, and security simplifies
235232
configuration. You don't need to browse several files created with different
236233
formats (YAML, XML, PHP): all the configuration is just where you require it,
237234
and it only uses one format.

‎bundles/best_practices.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -123,8 +123,8 @@ Event Listeners ``src/EventListener/``
123123
Configuration (routes, services, etc.) ``config/``
124124
Web Assets (CSS, JS, images) ``public/``
125125
Translation files ``translations/``
126-
Validation (when not using annotations) ``config/validation/``
127-
Serialization (when not using annotations) ``config/serialization/``
126+
Validation (when not using attributes) ``config/validation/``
127+
Serialization (when not using attributes) ``config/serialization/``
128128
Templates ``templates/``
129129
Unit and Functional Tests ``tests/``
130130
=================================================== ========================================
@@ -163,7 +163,7 @@ If the bundle includes Doctrine ORM entities and/or ODM documents, it's
163163
recommended to define their mapping using XML files stored in
164164
``config/doctrine/``. This allows to override that mapping using the
165165
:doc:`standard Symfony mechanism to override bundle parts </bundles/override>`.
166-
This is not possible when using annotations/attributes to define the mapping.
166+
This is not possible when using attributes to define the mapping.
167167

168168
Tests
169169
-----

‎components/config/resources.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ an array containing all matches.
3030
Resource Loaders
3131
----------------
3232

33-
For each type of resource (YAML, XML, annotation, etc.) a loader must be
33+
For each type of resource (YAML, XML, attributes, etc.) a loader must be
3434
defined. Each loader should implement
3535
:class:`Symfony\\Component\\Config\\Loader\\LoaderInterface` or extend the
3636
abstract :class:`Symfony\\Component\\Config\\Loader\\FileLoader` class,

‎components/serializer.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -288,7 +288,7 @@ for each format:
288288

289289
$classMetadataFactory = new ClassMetadataFactory(new XmlFileLoader('/path/to/your/definition.xml'));
290290

291-
.. _component-serializer-attributes-groups-annotations:
291+
.. _component-serializer-attributes-groups-attributes:
292292

293293
Then, create your groups definition:
294294

@@ -436,8 +436,8 @@ Ignoring Attributes
436436
All attributes are included by default when serializing objects. There are two
437437
options to ignore some of those attributes.
438438

439-
Option 1: Using ``@Ignore`` Annotation
440-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
439+
Option 1: Using ``#[Ignore]`` Attribute
440+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
441441

442442
.. configuration-block::
443443

‎components/validator/resources.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,10 @@ If you use annotations instead of attributes, it's also required to call
< 10000 /code>
114114
->addDefaultDoctrineAnnotationReader() // add this only when using annotations
115115
->getValidator();
116116

117+
.. deprecated:: 6.4
118+
119+
Annotations are deprecated since Symfony 6.4, use attributes instead.
120+
117121
To disable the annotation loader after it was enabled, call
118122
:method:`Symfony\\Component\\Validator\\ValidatorBuilder::disableAnnotationMapping`.
119123

‎configuration/micro_kernel_trait.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -302,7 +302,7 @@ Before continuing, run this command to add support for the new dependencies:
302302

303303
.. code-block:: terminal
304304
305-
$ composer require symfony/yaml symfony/twig-bundle symfony/web-profiler-bundle doctrine/annotations
305+
$ composer require symfony/yaml symfony/twig-bundle symfony/web-profiler-bundle
306306
307307
Next, create a new extension class that defines your app configuration and
308308
add a service conditionally based on the ``foo`` value::
@@ -377,7 +377,7 @@ because the configuration started to get bigger:
377377
;
378378
};
379379
380-
This also loads annotation routes from an ``src/Controller/`` directory, which
380+
This also loads attribute routes from an ``src/Controller/`` directory, which
381381
has one file in it::
382382

383383
// src/Controller/MicroController.php

‎configuration/multiple_kernels.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -205,7 +205,7 @@ resources::
205205
}
206206

207207
if (false !== ($fileName = (new \ReflectionObject($this))->getFileName())) {
208-
$routes->import($fileName, 'annotation');
208+
$routes->import($fileName, 'attribute');
209209
}
210210
}
211211
}

‎controller.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ Mapping a URL to a Controller
6363

6464
In order to *view* the result of this controller, you need to map a URL to it via
6565
a route. This was done above with the ``#[Route('/lucky/number/{max}')]``
66-
:ref:`route attribute <annotation-routes>`.
66+
:ref:`route attribute <attribute-routes>`.
6767

6868
To see your page, go to this URL in your browser: http://localhost:8000/lucky/number/100
6969

‎controller/upload_file.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ so Symfony doesn't try to get/set its value from the related entity::
7272
// every time you edit the Product details
7373
'required' => false,
7474

75-
// unmapped fields can't define their validation using annotations
75+
// unmapped fields can't define their validation using attributes
7676
// in the associated entity, so you can use the PHP constraint classes
7777
'constraints' => [
7878
new File([

‎doctrine.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -193,7 +193,7 @@ add/remove fields, add/remove methods or update configuration.
193193

194194
Doctrine supports a wide variety of field types, each with their own options.
195195
To see a full list, check out `Doctrine's Mapping Types documentation`_.
196-
If you want to use XML instead of annotations, add ``type: xml`` and
196+
If you want to use XML instead of attributes, add ``type: xml`` and
197197
``dir: '%kernel.project_dir%/config/doctrine'`` to the entity mappings in your
198198
``config/packages/doctrine.yaml`` file.
199199

@@ -746,7 +746,7 @@ the default convention.
746746
MapEntity Options
747747
~~~~~~~~~~~~~~~~~
748748

749-
A number of options are available on the ``MapEntity`` annotation to
749+
A number of options are available on the ``MapEntity`` attribute to
750750
control behavior:
751751

752752
``id``

‎doctrine/associations.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ From the perspective of the ``Product`` entity, this is a many-to-one relationsh
9191
From the perspective of the ``Category`` entity, this is a one-to-many relationship.
9292

9393
To map this, first create a ``category`` property on the ``Product`` class with
94-
the ``ManyToOne`` annotation. You can do this by hand, or by using the ``make:entity``
94+
the ``ManyToOne`` attribute. You can do this by hand, or by using the ``make:entity``
9595
command, which will ask you several questions about your relationship. If you're
9696
not sure of the answer, don't worry! You can always change the settings later:
9797

‎form/unit_testing.rst

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -217,7 +217,6 @@ allows you to return a list of extensions to register::
217217
// or if you also need to read constraints from annotations
218218
$validator = Validation::createValidatorBuilder()
219219
->enableAnnotationMapping(true)
220-
->addDefaultDoctrineAnnotationReader()
221220
->getValidator();
222221

223222
return [

‎page_creation.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ random) number and prints it. To do that, create a "Controller" class and a
5555
}
5656
}
5757

58-
.. _annotation-routes:
58+
.. _attribute-routes:
5959

6060
Now you need to associate this controller function with a public URL (e.g. ``/lucky/number``)
6161
so that the ``number()`` method is called when a user browses to it. This association

‎quick_tour/the_big_picture.rst

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -135,13 +135,8 @@ Try the page out by going to ``http://localhost:8000/hello/Symfony``. You should
135135
see: Hello Symfony! The value of the ``{name}`` in the URL is available as a ``$name``
136136
argument in your controller.
137137

138-
But this can be even simpler! So let's install annotations support:
139-
140-
.. code-block:: terminal
141 10000 -
142-
$ composer require annotations
143-
144-
Now, comment-out the YAML route by adding the ``#`` character:
138+
But this can be even simpler! Comment-out the YAML route by adding the
139+
``#`` character:
145140

146141
.. code-block:: yaml
147142

‎reference/attributes.rst

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,11 @@ Attributes are the successor of annotations since PHP 8. Attributes are native
55
to the language and Symfony takes full advantage of them across the framework
66
and its different components.
77

8+
.. deprecated:: 6.4
9+
10+
Annotations across the framework are deprecated since Symfony 6.4, you must
11+
only use attributes instead.
12+
813
Doctrine Bridge
914
~~~~~~~~~~~~~~~
1015

@@ -78,14 +83,14 @@ Security
7883
~~~~~~~~
7984

8085
* :ref:`CurrentUser <security-json-login>`
81-
* :ref:`IsGranted <security-securing-controller-annotations>`
86+
* :ref:`IsGranted <security-securing-controller-attributes>`
8287

8388
Serializer
8489
~~~~~~~~~~
8590

8691
* :ref:`Context <serializer_serializer-context>`
8792
* :ref:`DiscriminatorMap <serializer_interfaces-and-abstract-classes>`
88-
* :ref:`Groups <component-serializer-attributes-groups-annotations>`
93+
* :ref:`Groups <component-serializer-attributes-groups-attributes>`
8994
* :ref:`Ignore <serializer_ignoring-attributes>`
9095
* :ref:`MaxDepth <serializer_handling-serialization-depth>`
9196
* :ref:`SerializedName <serializer_name-conversion>`

‎reference/configuration/doctrine.rst

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -274,6 +274,10 @@ One of ``annotation`` (for PHP annotations; it's the default value),
274274
``attribute`` (for PHP attributes), ``xml``, ``yml``, ``php`` or
275275
``staticphp``. This specifies which type of metadata type your mapping uses.
276276

277+
.. deprecated:: 6.4
278+
279+
Annotations are deprecated since Symfony 6.4, use attributes instead.
280+
277281
See `Doctrine Metadata Drivers`_ for more information about this option.
278282

279283
``dir``
@@ -385,7 +389,7 @@ namespace in the ``src/Entity`` directory and gives them an ``App`` alias
385389
mappings:
386390
# ...
387391
SomeEntityNamespace:
388-
type: annotation
392+
type: attribute
389393
dir: '%kernel.project_dir%/src/Entity'
390394
is_bundle: false
391395
prefix: App\Entity
@@ -403,7 +407,7 @@ namespace in the ``src/Entity`` directory and gives them an ``App`` alias
403407
<doctrine:config>
404408
<doctrine:orm>
405409
<mapping name="SomeEntityNamespace"
406-
type="annotation"
410+
type="attribute"
407411
dir="%kernel.project_dir%/src/Entity"
408412
is-bundle="false"
409413
prefix="App\Entity"
@@ -422,7 +426,7 @@ namespace in the ``src/Entity`` directory and gives them an ``App`` alias
422426
423427
$emDefault->autoMapping(true);
424428
$emDefault->mapping('SomeEntityNamespace')
425-
->type('annotation')
429+
->type('attribute')
426430
->dir('%kernel.project_dir%/src/Entity')
427431
->isBundle(false)
428432
->prefix('App\Entity')
@@ -446,14 +450,14 @@ configuration format. The bundle will stop as soon as it locates one.
446450

447451
If it wasn't possible to determine a configuration format for a bundle,
448452
the DoctrineBundle will check if there is an ``Entity`` folder in the bundle's
449-
root directory. If the folder exist, Doctrine will fall back to using an
450-
annotation driver.
453+
root directory. If the folder exist, Doctrine will fall back to using
454+
attributes.
451455

452456
Default Value of Dir
453457
....................
454458

455459
If ``dir`` is not specified, then its default value depends on which configuration
456-
driver is being used. For drivers that rely on the PHP files (annotation,
460+
driver is being used. For drivers that rely on the PHP files (attribute,
457461
``staticphp``) it will be ``[Bundle]/Entity``. For drivers that are using
458462
configuration files (XML, YAML, ...) it will be
459463
``[Bundle]/Resources/config/doctrine``.

‎reference/constraints/DisableAutoMapping.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ DisableAutoMapping
33

44
This constraint allows to disable :ref:`Doctrine's auto mapping <doctrine_auto-mapping>`
55
on a class or a property. Automapping allows to determine validation rules based
6-
on Doctrine's annotations and attributes. You may use this constraint when
6+
on Doctrine's attributes. You may use this constraint when
77
automapping is globally enabled, but you still want to disable this feature for
88
a class or a property specifically.
99

‎reference/constraints/EnableAutoMapping.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ EnableAutoMapping
33

44
This constraint allows to enable :ref:`Doctrine's auto mapping <doctrine_auto-mapping>`
55
on a class or a property. Automapping allows to determine validation rules based
6-
on Doctrine's annotations and attributes. You may use this constraint when
6+
on Doctrine's attributes. You may use this constraint when
77
automapping is globally disabled, but you still want to enable this feature for
88
a class or a property specifically.
99

0 commit comments

Comments
 (0)
0