From 6c1567051e451071f3ee8660e1b01cfc1f67687f Mon Sep 17 00:00:00 2001 From: Romain Monteil Date: Wed, 24 Aug 2022 15:46:10 +0200 Subject: [PATCH] Replace remaining annotations with attributes, remove remaining annotations configuration block --- best_practices.rst | 11 ++- components/http_kernel.rst | 10 +-- components/serializer.rst | 103 +---------------------- contributing/documentation/standards.rst | 6 +- controller/argument_value_resolver.rst | 8 +- reference/configuration/doctrine.rst | 2 +- routing/routing_from_database.rst | 4 +- security.rst | 25 ------ service_container/autowiring.rst | 40 --------- service_container/calls.rst | 8 +- validation/custom_constraint.rst | 31 ------- 11 files changed, 25 insertions(+), 223 deletions(-) diff --git a/best_practices.rst b/best_practices.rst index 859b203a24a..6be952c0a22 100644 --- a/best_practices.rst +++ b/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 ` 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 ---------- diff --git a/components/http_kernel.rst b/components/http_kernel.rst index 52a0cee8332..d4c785ea6dc 100644 --- a/components/http_kernel.rst +++ b/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 diff --git a/components/serializer.rst b/components/serializer.rst index 3b5370cb5cb..53e1f1d7299 100644 --- a/components/serializer.rst +++ b/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; @@ -1412,22 +1346,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; @@ -1501,9 +1419,7 @@ having unique identifiers:: { public $id; - /** - * @MaxDepth(1) - */ + #[MaxDepth(1)] public $child; } @@ -1735,23 +1651,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; diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index 8e266f68cab..7372d7058b1 100644 --- a/contributing/documentation/standards.rst +++ b/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 diff --git a/controller/argument_value_resolver.rst b/controller/argument_value_resolver.rst index 2cea87964ab..95be321f7f2 100644 --- a/controller/argument_value_resolver.rst +++ b/controller/argument_value_resolver.rst @@ -81,8 +81,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: @@ -253,7 +253,7 @@ To ensure your resolvers are added in the right position you can run the followi command to see which argument resolvers are present and in which order they run. .. code-block:: terminal - + $ php bin/console debug:container debug.argument_resolver.inner --show-arguments .. tip:: @@ -267,5 +267,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 diff --git a/reference/configuration/doctrine.rst b/reference/configuration/doctrine.rst index 53f98858d90..6c9d758bb18 100644 --- a/reference/configuration/doctrine.rst +++ b/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. diff --git a/routing/routing_from_database.rst b/routing/routing_from_database.rst index 28d539a77f1..eca06dccdef 100644 --- a/routing/routing_from_database.rst +++ b/routing/routing_from_database.rst @@ -23,8 +23,8 @@ For these cases, the ``DynamicRouter`` offers an alternative approach: When all routes are known during deploy time and the number is not too high, using a :doc:`custom route loader ` is the preferred way to add more routes. When working with only one type of -objects, a slug parameter on the object and the ``@ParamConverter`` -annotation works fine (see `FrameworkExtraBundle`_) . +objects, a slug parameter on the object and the ``#[ParamConverter]`` +attribute works fine (see `FrameworkExtraBundle`_) . The ``DynamicRouter`` is useful when you need ``Route`` objects with the full feature set of Symfony. Each route can define a specific diff --git a/security.rst b/security.rst index 005b0781b32..10466a8c067 100644 --- a/security.rst +++ b/security.rst @@ -2131,31 +2131,6 @@ using annotations: .. configuration-block:: - .. code-block:: php-annotations - - // src/Controller/AdminController.php - // ... - - use Sensio\Bundle\FrameworkExtraBundle\Configuration\IsGranted; - - /** - * Require ROLE_ADMIN for all the actions of this controller - * - * @IsGranted("ROLE_ADMIN") - */ - class AdminController extends AbstractController - { - /** - * Require ROLE_SUPER_ADMIN only for this action - * - * @IsGranted("ROLE_SUPER_ADMIN") - */ - public function adminDashboard(): Response - { - // ... - } - } - .. code-block:: php-attributes // src/Controller/AdminController.php diff --git a/service_container/autowiring.rst b/service_container/autowiring.rst index a0517d8e937..b6a99ecef85 100644 --- a/service_container/autowiring.rst +++ b/service_container/autowiring.rst @@ -551,30 +551,6 @@ to inject the ``logger`` service, and decide to use setter-injection: .. configuration-block:: - .. code-block:: php-annotations - - // src/Util/Rot13Transformer.php - namespace App\Util; - - class Rot13Transformer - { - private $logger; - - /** - * @required - */ - public function setLogger(LoggerInterface $logger): void - { - $this->logger = $logger; - } - - public function transform($value): string - { - $this->logger->info('Transforming '.$value); - // ... - } - } - .. code-block:: php-attributes // src/Util/Rot13Transformer.php @@ -612,22 +588,6 @@ typed properties: .. configuration-block:: - .. code-block:: php-annotations - - namespace App\Util; - - class Rot13Transformer - { - /** @required */ - public LoggerInterface $logger; - - public function transform($value) - { - $this->logger->info('Transforming '.$value); - // ... - } - } - .. code-block:: php-attributes namespace App\Util; diff --git a/service_container/calls.rst b/service_container/calls.rst index 0fb2f0d2462..48b8640d516 100644 --- a/service_container/calls.rst +++ b/service_container/calls.rst @@ -6,7 +6,7 @@ Service Method Calls and Setter Injection .. tip:: - If you're using autowiring, you can use ``#[Required]`` or ``@required`` to + If you're using autowiring, you can use ``#[Required]`` to :ref:`automatically configure method calls `. Usually, you'll want to inject your dependencies via the constructor. But sometimes, @@ -145,13 +145,13 @@ The configuration to tell the container it should do so would be like: .. tip:: - If autowire is enabled, you can also use annotations; with the previous + If autowire is enabled, you can also use attributes; with the previous example it would be:: /** - * @required * @return static */ + #[Required] public function withLogger(LoggerInterface $logger) { $new = clone $this; @@ -162,6 +162,6 @@ The configuration to tell the container it should do so would be like: You can also leverage the PHP 8 ``static`` return type instead of the ``@return static`` annotation. If you don't want a method with a - PHP 8 ``static`` return type and a ``@required`` annotation to behave as + PHP 8 ``static`` return type and a ``#[Required]`` attribute to behave as a wither, you can add a ``@return $this`` annotation to disable the *returns clone* feature. diff --git a/validation/custom_constraint.rst b/validation/custom_constraint.rst index 3e2ca6dd2b9..aa3d08aa948 100644 --- a/validation/custom_constraint.rst +++ b/validation/custom_constraint.rst @@ -16,22 +16,6 @@ First you need to create a Constraint class and extend :class:`Symfony\\Componen .. configuration-block:: - .. code-block:: php-annotations - - // src/Validator/ContainsAlphanumeric.php - namespace App\Validator; - - use Symfony\Component\Validator\Constraint; - - /** - * @Annotation - */ - class ContainsAlphanumeric extends Constraint - { - public $message = 'The string "{{ string }}" contains an illegal character: it can only contain letters or numbers.'; - public $mode = 'strict'; // If the constraint has configuration options, define them as public properties - } - .. code-block:: php-attributes // src/Validator/ContainsAlphanumeric.php @@ -248,21 +232,6 @@ not to the property: .. configuration-block:: - .. code-block:: php-annotations - - // src/Entity/AcmeEntity.php - namespace App\Entity; - - use App\Validator as AcmeAssert; - - /** - * @AcmeAssert\ProtocolClass - */ - class AcmeEntity - { - // ... - } - .. code-block:: php-attributes // src/Entity/AcmeEntity.php