How to Upgrade Annotations to Attributes

March 2025 update

Since Rector 2.0 a new withAttributesSets() configuration method is available.

We used @annotations in PHP 7.4 and below. Now we can use native #[attributes] in PHP 8. They have better support in PHPStan and Rector, thanks to their native language nature.

The Internet is full of questions "How can I use PHP 8 attributes instead of annotations in Doctrine?" or "Converting Annotations to Attributes".

Do you want to know the answer? Rector has a simple solution for you.

One package that added support for attributes is Doctrine:

 use Doctrine\ORM\Mapping as ORM;

-/**
- * @ORM\Column(type="string")
- */
+#[ORM\Column(type: "string")]

Now, let's go to upgrade itself. It's effortless.

Upgrade from Annotations to Attributes in 3 Steps

1. Configure rector.php to include all available attributes:

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withAttributesSets();

Or limit to specific group - this option is better when you're addin Rector to a new project:

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withAttributesSets(symfony: true);

2. Run Rector to upgrade your code

vendor/bin/rector process

3. Handle Manual Steps

  • Do you use doctrine/orm? Be sure to use at least version 2.9, where attributes were released.

  • Do you use Doctrine with Symfony? Update the Symfony bundle mapping parser in your config to read attributes:

 # config/packages/doctrine.yaml
 doctrine:
     orm:
         mappings:
             App:
-                type: annotation
+                type: attribute

This enables new Symfony auto-detection feature.

That's it! Now your codebase uses nice and shiny PHP 8 native attributes.


Happy coding!