Add documentation on how to use PHP attributes #6830

New Issue

admin · 2026-01-22T15:39:37+01:00

admin commented

2026-01-22 15:39:37 +01:00

Originally created by @andreas-aeschlimann on GitHub (Sep 17, 2021).

Being new to Doctrine, I followed the guides and successfully integrated Doctrine into our project. As suggested in the docs, we used PHPDoc Annotation Metadata as follows:

/**
 * @ORM\Entity
 * @ORM\Table(name="user")
 */
class User { ... }

As PHP 8 is out now for a while, I decided that I would like to switch to PHP Attributes instead such that we may use:

#[ORM\Entity]
#[ORM\Table(name: "user")]
class User { ... }

After doing that, it did not work out of the box as inferred on the website – all PHP Attributes were completely ignored. I also did not find any information on how to make it properly work. Only after adding $config->setMetadataDriverImpl(new AttributeDriver([])); to the EntityManager config, PHP Attributes seemed to work.

I do not know if this is the correct way to enable attributes, but it would be nice if it were documented on the website.

Originally created by @andreas-aeschlimann on GitHub (Sep 17, 2021). Being new to Doctrine, I followed the guides and successfully integrated Doctrine into our project. As suggested in the docs, we used PHPDoc Annotation Metadata as follows: ``` /** * @ORM\Entity * @ORM\Table(name="user") */ class User { ... } ``` As PHP 8 is out now for a while, I decided that I would like to switch to PHP Attributes instead such that we may use: ``` #[ORM\Entity] #[ORM\Table(name: "user")] class User { ... } ``` After doing that, it did not work out of the box as inferred on the website – all PHP Attributes were completely ignored. I also did not find any information on how to make it properly work. Only after adding `$config->setMetadataDriverImpl(new AttributeDriver([]));` to the `EntityManager` config, PHP Attributes seemed to work. I do not know if this is the correct way to enable attributes, but it would be nice if it were documented on the website.

admin added the Documentation label 2026-01-22 15:39:37 +01:00

admin commented

2026-01-22 15:39:38 +01:00

@derrabus commented on GitHub (Sep 18, 2021):

Do you want to submit a pull request with the documentation that would've helped you?

@derrabus commented on GitHub (Sep 18, 2021): Do you want to submit a pull request with the documentation that would've helped you?

admin commented

2026-01-22 15:39:38 +01:00

@andreas-aeschlimann commented on GitHub (Sep 21, 2021):

Do you want to submit a pull request with the documentation that would've helped you?

I could do that, but I am probably not "good" enough yet to write about best practices in Doctrine. Did I even enable attributes in the appropriate way? Or are there other, maybe better ways?

@andreas-aeschlimann commented on GitHub (Sep 21, 2021): > Do you want to submit a pull request with the documentation that would've helped you? I could do that, but I am probably not "good" enough yet to write about best practices in Doctrine. Did I even enable attributes in the appropriate way? Or are there other, maybe better ways?

admin commented

2026-01-22 15:39:39 +01:00

@derrabus commented on GitHub (Sep 22, 2021):

I could do that, but I am probably not "good" enough yet to write about best practices in Doctrine.

No worries, you're not alone in this. Someone will review your PR.

Did I even enable attributes in the appropriate way?

Yes. 🙂

@derrabus commented on GitHub (Sep 22, 2021): > I could do that, but I am probably not "good" enough yet to write about best practices in Doctrine. No worries, you're not alone in this. Someone will review your PR. > Did I even enable attributes in the appropriate way? Yes. 🙂

admin commented

2026-01-22 15:39:39 +01:00

@ThomasLandauer commented on GitHub (Oct 30, 2021):

I'm currently overhauling the "Events" page, and I could add some attributes examples. But before, somebody needs to configure the RST parser to allow a new type of .. code-block::
(If you tell me in which file this is happening, I could even try myself.)

It's probably best to follow what Symfony did, see e.g. https://symfony.com/doc/current/doctrine/associations.html#mapping-the-manytoone-relationship
Four tabs above the code block:
Annotations | Attributes | YAML | XML
(I personally would even list Attributes (=future) first, and YAML (=past) last, but that's not so important right now)

Symfony's RST syntax:

.. code-block:: php-annotations
.. code-block:: php-attributes
.. code-block:: yaml
.. code-block:: xml

Doctrine's:

.. code-block:: php
.. code-block:: yaml
.. code-block:: xml

Is there a way to setup .. code-block:: php as alias for the (new) .. code-block:: php-annotations? Or do some automatic search and replace throughout the entire docs?

@ThomasLandauer commented on GitHub (Oct 30, 2021): I'm currently overhauling the "Events" page, and I could add some attributes examples. But before, somebody needs to configure the RST parser to allow a new type of `.. code-block::` (If you tell me in which file this is happening, I could even try myself.) It's probably best to follow what Symfony did, see e.g. https://symfony.com/doc/current/doctrine/associations.html#mapping-the-manytoone-relationship Four tabs above the code block: Annotations | Attributes | YAML | XML (I personally would even list Attributes (=future) first, and YAML (=past) last, but that's not so important right now) Symfony's RST syntax: ``` .. code-block:: php-annotations .. code-block:: php-attributes .. code-block:: yaml .. code-block:: xml ``` Doctrine's: ``` .. code-block:: php .. code-block:: yaml .. code-block:: xml ``` Is there a way to setup `.. code-block:: php` as alias for the (new) `.. code-block:: php-annotations`? Or do some automatic search and replace throughout the entire docs?

admin commented

2026-01-22 15:39:39 +01:00

@SenseException commented on GitHub (Oct 30, 2021):

There's an attribute highlighter that's a copy of the PHP one. .. code-block:: attribute should work.
https://github.com/doctrine/doctrine-website/pull/409

@SenseException commented on GitHub (Oct 30, 2021): There's an `attribute` highlighter that's a copy of the PHP one. `.. code-block:: attribute` should work. https://github.com/doctrine/doctrine-website/pull/409

admin commented

2026-01-22 15:39:39 +01:00

@ThomasLandauer commented on GitHub (Oct 30, 2021):

Oddly enough, I have a faint memory that I've already used this - but can't find any PR ;-) Never mind.

Is there a chance to rename attribute to php-attributes, for consistency with Symfony? Since there are not many usages of this in Doctrine's documentation yet (couldn't find a single one), it's either now or never ;-)
What the OP @andreas-aeschlimann really asked for is this page: https://www.doctrine-project.org/projects/doctrine-orm/en/2.10/reference/attributes-reference.html However, it's not listed in the table-of-contents column on the left. https://www.doctrine-project.org/projects/doctrine-orm/en/2.10/reference/annotations-reference.html is missing too. How/where is this table-of-contents list generated?

@ThomasLandauer commented on GitHub (Oct 30, 2021): Oddly enough, I have a faint memory that I've already used this - but can't find any PR ;-) Never mind. 1. Is there a chance to rename `attribute` to `php-attributes`, for consistency with Symfony? Since there are not many usages of this in Doctrine's documentation yet (couldn't find a single one), it's either *now or never* ;-) 2. What the OP @andreas-aeschlimann really asked for is this page: https://www.doctrine-project.org/projects/doctrine-orm/en/2.10/reference/attributes-reference.html However, it's not listed in the table-of-contents column on the left. https://www.doctrine-project.org/projects/doctrine-orm/en/2.10/reference/annotations-reference.html is missing too. How/where is this table-of-contents list generated?

admin referenced this issue

2026-01-22 16:06:38 +01:00

[PR #6830] fix applying column options on foreign key columns #10160

admin referenced this issue

2026-01-22 16:06:38 +01:00

[PR #6833] Fix applying target column options on foreign key columns #10161

Sign in to join this conversation.