Support for nesting attributes with PHP 8.1 (#9241)

* [GH-9240] Refactor Association/AttributeOverrides to use @NamedConstructorArguments with AnnotationDriver.

* [GH-9240] Add support for PHP 8.1 nested attributes.

Supported/new attributes are #[AttributeOverrides], #[AssociationOverrides], #[JoinTable] with nested joinColumns, inverseJoinColumns.

* [GH-9240] Add support for nesting Index, UniqueCosntraint into #[Table] on PHP 8.1

* Apply review comments by gregooire.

* Add documentation for new attributes.

* Add docs for new nested #[JoinTable] support of join columns

* Add docs for new nested #[Table] support of index, uniqueConstraints

* Rename "Required/Optional atttributes" to "Required/Optional parameters"

* Remove nesting for JoinTable#joinColumns and Table#indexes/uniqueConstraints again.

* Hosuekeeping: phpcs/psalm

* housekeeping

* Remove unused function imports.

Author: beberlei

docs/en/reference/attributes-reference.rst

@@ -10,6 +10,8 @@ annotation metadata supported since the first version 2.0.
 Index
 -----
 
+-  :ref:`#[AssociationOverride] <attrref_associationoverride]`
+-  :ref:`#[AttributeOverride] <attrref_attributeoverride]`
 -  :ref:`#[Column] <attrref_column>`
 -  :ref:`#[Cache] <attrref_cache>`
 -  :ref:`#[ChangeTrackingPolicy <attrref_changetrackingpolicy>`
@@ -49,6 +51,93 @@ Index
 Reference
 ---------
 
+.. _attrref_associationoverride:
+
+#[AssociationOverride]
+~~~~~~~~~~~~~~~~~~~~~~
+
+In an inheritance hierarchy this attribute allows to override the
+assocation mapping definitions of the parent mappings. It needs to be nested
+within a ``#[AssociationOverrides]`` on the class level.
+
+Required parameters:
+
+-  **name**: Name of the association mapping to overwrite.
+
+Optional parameters:
+
+-  **joinColumns**: A list of nested ``#[JoinColumn]`` declarations.
+-  **joinTable**: A nested ``#[JoinTable]`` declaration in case of a many-to-many overwrite.
+-  **inversedBy**: The name of the inversedBy field on the target entity side.
+-  **fetch**: The fetch strategy, one of: EAGER, LAZY, EXTRA_LAZY.
+
+Examples:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Mapping\AssociationOverride;
+    use Doctrine\ORM\Mapping\AssociationOverrides;
+    use Doctrine\ORM\Mapping\Column;
+    use Doctrine\ORM\Mapping\Entity;
+
+    #[AssociationOverrides([
+        new AssociationOverride(
+            name: "groups",
+            joinTable: new JoinTable(
+                name: "ddc964_users_admingroups",
+            ),
+            joinColumns: [new JoinColumn(name: "adminuser_id")],
+            inverseJoinColumns: [new JoinColumn(name: "admingroup_id")]
+        ),
+        new AssociationOverride(
+            name: "address",
+            joinColumns: [new JoinColumn(name: "adminaddress_id", referencedColumnName: "id")]
+        )
+    ])]
+    class DDC964Admin extends DDC964User
+    {
+    }
+
+.. _attrref_attributeoverride:
+
+#[AttributeOverride]
+~~~~~~~~~~~~~~~~~~~~
+
+In an inheritance hierarchy this attribute allows to override the
+field mapping definitions of the parent mappings. It needs to be nested
+within a ``#[AttributeOverrides]`` on the class level.
+
+Required parameters:
+
+-  **name**: Name of the association mapping to overwrite.
+-  **column**: A nested ``#[Column]`` attribute with the overwritten field settings.
+
+Examples:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Mapping\AttributeOverride;
+    use Doctrine\ORM\Mapping\AttributeOverrides;
+    use Doctrine\ORM\Mapping\Column;
+    use Doctrine\ORM\Mapping\Entity;
+
+    #[Entity]
+    #[AttributeOverrides([
+        new AttributeOverride(
+            name: "id",
+            column: new Column(name: "guest_id", type: "integer", length: 140)
+        ),
+        new AttributeOverride(
+            name: "name",
+            column: new Column(name: "guest_name", nullable: false, unique: true, length: 240)
+        )]
+    )]
+    class DDC964Guest extends DDC964User
+    {
+    }
+
 .. _attrref_column:
 
 #[Column]
@@ -59,12 +148,12 @@ inside the instance variables PHP DocBlock comment. Any value hold
 inside this variable will be saved to and loaded from the database
 as part of the lifecycle of the instance variables entity-class.
 
-Required attributes:
+Required parameters:
 
 -  **type**: Name of the DBAL Type which does the conversion between PHP
    and Database representation.
 
-Optional attributes:
+Optional parameters:
 
 -  **name**: By default the property name is used for the database
    column name also, however the ``name`` attribute allows you to
@@ -165,7 +254,7 @@ Examples:
 ~~~~~~~~
 Add caching strategy to a root entity or a collection.
 
-Optional attributes:
+Optional parameters:
 
 -  **usage**: One of ``READ_ONLY``, ``READ_WRITE`` or ``NONSTRICT_READ_WRITE``, By default this is ``READ_ONLY``.
 -  **region**: An specific region name
@@ -210,7 +299,7 @@ Example:
 
 This attribute allows you to specify a user-provided class to generate identifiers. This attribute only works when both :ref:`#[Id] <attrref_id>` and :ref:`#[GeneratedValue(strategy: "CUSTOM")] <attrref_generatedvalue>` are specified.
 
-Required attributes:
+Required parameters:
 
 -  **class**: name of the class which should extend Doctrine\ORM\Id\AbstractIdGenerator
 
@@ -244,13 +333,13 @@ actually instantiated as.
 If this attribute is not specified, the discriminator column defaults
 to a string column of length 255 called ``dtype``.
 
-Required attributes:
+Required parameters:
 
 
 -  **name**: The column name of the discriminator. This name is also
    used during Array hydration as key to specify the class-name.
 
-Optional attributes:
+Optional parameters:
 
 
 -  **type**: By default this is string.
@@ -319,7 +408,7 @@ attribute to establish the relationship between the two classes.
 The embedded attribute is required on an entity's member variable,
 in order to specify that it is an embedded class.
 
-Required attributes:
+Required parameters:
 
 -  **class**: The embeddable class
 
@@ -331,7 +420,7 @@ Required attributes:
 Required attribute to mark a PHP class as an entity. Doctrine manages
 the persistence of all classes marked as entities.
 
-Optional attributes:
+Optional parameters:
 
 -  **repositoryClass**: Specifies the FQCN of a subclass of the
    ``EntityRepository``. Use of repositories for entities is encouraged to keep
@@ -368,7 +457,7 @@ conjunction with #[Id].
 If this attribute is not specified with ``#[Id]`` the ``NONE`` strategy is
 used as default.
 
-Optional attributes:
+Optional parameters:
 
 -  **strategy**: Set the name of the identifier generation strategy.
    Valid values are ``AUTO``, ``SEQUENCE``, ``IDENTITY``, ``UUID``
@@ -424,14 +513,14 @@ Attribute is used on the entity-class level. It provides a hint to the SchemaToo
 generate a database index on the specified table columns. It only
 has meaning in the ``SchemaTool`` schema generation context.
 
-Required attributes:
+Required parameters:
 
 -  **name**: Name of the Index
 -  **fields**: Array of fields. Exactly one of **fields, columns** is required.
 -  **columns**: Array of columns. Exactly one of **fields, columns** is required.
 
 
-Optional attributes:
+Optional parameters:
 
 -  **options**: Array of platform specific options:
 
@@ -546,9 +635,10 @@ are missing they will be computed considering the field's name and the current
 
 The ``#[InverseJoinColumn]`` is the same as ``#[JoinColumn]`` and is used in the context
 of a ``#[ManyToMany]`` attribute declaration to specifiy the details of the join table's
-column information used for the join to the inverse entity.
+column information used for the join to the inverse entity. This is only required
+on PHP 8.0, where nested attributes are not yet supported.
 
-Optional attributes:
+Optional parameters:
 
 -  **name**: Column name that holds the foreign key identifier for
    this relation. In the context of ``#[JoinTable]`` it specifies the column
@@ -596,7 +686,7 @@ details of the database join table. If you do not specify
 using the affected table and the column names.
 
 A notable difference to the annotation metadata support, ``#[JoinColumn]``
-and ``#[InverseJoinColumn]`` are specified at the property level and are not
+and ``#[InverseJoinColumn]`` can be specified at the property level and are not
 nested within the ``#[JoinTable]`` attribute.
 
 Required attribute:
@@ -623,14 +713,14 @@ Example:
 Defines that the annotated instance variable holds a reference that
 describes a many-to-one relationship between two entities.
 
-Required attributes:
+Required parameters:
 
 
 -  **targetEntity**: FQCN of the referenced target entity. Can be the
    unqualified class name if both classes are in the same namespace.
    *IMPORTANT:* No leading backslash!
 
-Optional attributes:
+Optional parameters:
 
 
 -  **cascade**: Cascade Option
@@ -659,14 +749,14 @@ additional, optional attribute that has reasonable default
 configuration values using the table and names of the two related
 entities.
 
-Required attributes:
+Required parameters:
 
 
 -  **targetEntity**: FQCN of the referenced target entity. Can be the
    unqualified class name if both classes are in the same namespace.
    *IMPORTANT:* No leading backslash!
 
-Optional attributes:
+Optional parameters:
 
 
 -  **mappedBy**: This option specifies the property name on the
@@ -720,7 +810,7 @@ The ``#[MappedSuperclass]`` attribute cannot be used in conjunction with
 ``#[Entity]``. See the Inheritance Mapping section for
 :doc:`more details on the restrictions of mapped superclasses <inheritance-mapping>`.
 
-Optional attributes:
+Optional parameters:
 
 -  **repositoryClass**: Specifies the FQCN of a subclass of the EntityRepository.
    That will be inherited for all subclasses of that Mapped Superclass.
@@ -756,13 +846,13 @@ be specified. When no
 :ref:`#[JoinColumn] <attrref_joincolumn>` is specified it defaults to using the target entity table and
 primary key column names and the current naming strategy to determine a name for the join column.
 
-Required attributes:
+Required parameters:
 
 -  **targetEntity**: FQCN of the referenced target entity. Can be the
    unqualified class name if both classes are in the same namespace.
    *IMPORTANT:* No leading backslash!
 
-Optional attributes:
+Optional parameters:
 
 -  **cascade**: Cascade Option
 -  **fetch**: One of LAZY or EAGER
@@ -786,13 +876,13 @@ Example:
 #[OneToMany]
 ~~~~~~~~~~~~
 
-Required attributes:
+Required parameters:
 
 -  **targetEntity**: FQCN of the referenced target entity. Can be the
    unqualified class name if both classes are in the same namespace.
    *IMPORTANT:* No leading backslash!
 
-Optional attributes:
+Optional parameters:
 
 -  **cascade**: Cascade Option
 -  **orphanRemoval**: Boolean that specifies if orphans, inverse
@@ -916,11 +1006,11 @@ For use with ``#[GeneratedValue(strategy: "SEQUENCE")]`` this
 attribute allows to specify details about the sequence, such as
 the increment size and initial values of the sequence.
 
-Required attributes:
+Required parameters:
 
 -  **sequenceName**: Name of the sequence
 
-Optional attributes:
+Optional parameters:
 
 -  **allocationSize**: Increment the sequence by the allocation size
    when its fetched. A value larger than 1 allows optimization for
@@ -954,11 +1044,11 @@ placed on the entity-class level and is optional. If it is
 not specified the table name will default to the entity's
 unqualified classname.
 
-Required attributes:
+Required parameters:
 
 -  **name**: Name of the table
 
-Optional attributes:
+Optional parameters:
 
 -  **schema**: Name of the schema the table lies in.
 
@@ -985,12 +1075,12 @@ generate a database unique constraint on the specified table
 columns. It only has meaning in the SchemaTool schema generation
 context.
 
-Required attributes:
+Required parameters:
 
 -  **name**: Name of the Index
 -  **columns**: Array of columns.
 
-Optional attributes:
+Optional parameters:
 
 -  **options**: Array of platform specific options: