Add a psalm type for field mapping

Field mapping have different definitions
in property definition and method return.
As suggested in issue and to avoid further desynchronization,
a psalm type has been created.
Fixes doctrine#9193

lib/Doctrine/ORM/Mapping/ClassMetadataInfo.php

@@ -70,6 +70,34 @@
  *
  * @template-covariant T of object
  * @template-implements ClassMetadata<T>
+ * @psalm-type FieldMapping = array{
+ *      type?: string,
+ *      fieldName?: string,
+ *      columnName?: string,
+ *      length?: int,
+ *      id?: bool,
+ *      nullable?: bool,
+ *      columnDefinition?: string,
+ *      precision?: int,
+ *      scale?: int,
+ *      unique?: bool,
+ *      inherited?: class-string,
+ *      originalClass?: class-string,
+ *      originalField?: string,
+ *      quoted?: bool,
+ *      requireSQLConversion?: bool,
+ *      declared?: class-string,
+ *      declaredField?: string,
+ *      options?: array{
+ *         unsigned?: bool,
+ *         fixed?: bool,
+ *         comment?: string,
+ *         default?: string,
+ *         collation?: string,
+ *         check?: string,
+ *      },
+ *      version?: bool|string,
+ * }
  */
 class ClassMetadataInfo implements ClassMetadata
 {
@@ -427,26 +455,7 @@ class ClassMetadataInfo implements ClassMetadata
      * Whether a unique constraint should be generated for the column.
      *
      * @var mixed[]
-     * @psalm-var array<string, array{
-     *      type: string,
-     *      fieldName: string,
-     *      columnName?: string,
-     *      length?: int,
-     *      id?: bool,
-     *      nullable?: bool,
-     *      columnDefinition?: string,
-     *      precision?: int,
-     *      scale?: int,
-     *      unique?: string,
-     *      inherited?: class-string,
-     *      originalClass?: class-string,
-     *      originalField?: string,
-     *      quoted?: bool,
-     *      requireSQLConversion?: bool,
-     *      declared?: class-string,
-     *      declaredField?: string,
-     *      options: array<mixed>
-     * }>
+     * @psalm-var array<string, FieldMapping>
      */
     public $fieldMappings = [];
 
@@ -1285,18 +1294,7 @@ public function getColumnName($fieldName)
      * @param string $fieldName The field name.
      *
      * @return mixed[] The field mapping.
-     * @psalm-return array{
-     *      type: string,
-     *      fieldName: string,
-     *      columnName?: string,
-     *      inherited?: class-string,
-     *      nullable?: bool,
-     *      originalClass?: class-string,
-     *      originalField?: string,
-     *      scale?: int,
-     *      precision?: int,
-     *      length?: int
-     * }
+     * @psalm-return FieldMapping
      *
      * @throws MappingException
      */
@@ -1534,7 +1532,7 @@ private function validateAndCompleteTypedAssociationMapping(array $mapping): arr
     /**
      * Validates & completes the given field mapping.
      *
-     * @psalm-param array<string, mixed> $mapping The field mapping to validate & complete.
+     * @psalm-param FieldMapping $mapping The field mapping to validate & complete.
      *
      * @return mixed[] The updated mapping.
      *
@@ -2639,7 +2637,7 @@ private function isInheritanceType(int $type): bool
     /**
      * Adds a mapped field to the class.
      *
-     * @psalm-param array<string, mixed> $mapping The field mapping.
+     * @psalm-param FieldMapping $mapping The field mapping.
      *
      * @return void
      *
@@ -2678,7 +2676,7 @@ public function addInheritedAssociationMapping(array $mapping/*, $owningClassNam
      * Adds a field mapping without completing/validating it.
      * This is mainly used to add inherited field mappings to derived classes.
      *
-     * @psalm-param array<string, mixed> $fieldMapping
+     * @psalm-param FieldMapping $fieldMapping
      *
      * @return void
      */

lib/Doctrine/ORM/Mapping/Driver/AnnotationDriver.php

@@ -13,6 +13,7 @@
 use Doctrine\ORM\Id\TableGenerator;
 use Doctrine\ORM\Mapping;
 use Doctrine\ORM\Mapping\Builder\EntityListenerBuilder;
+use Doctrine\ORM\Mapping\ClassMetadataInfo;
 use Doctrine\ORM\Mapping\MappingException;
 use Doctrine\Persistence\Mapping\ClassMetadata;
 use Doctrine\Persistence\Mapping\Driver\AnnotationDriver as AbstractAnnotationDriver;
@@ -31,6 +32,8 @@
 
 /**
  * The AnnotationDriver reads the mapping metadata from docblock annotations.
+ *
+ * @psalm-import-type FieldMapping from ClassMetadataInfo
  */
 class AnnotationDriver extends AbstractAnnotationDriver
 {
@@ -712,18 +715,7 @@ private function joinColumnToArray(Mapping\JoinColumn $joinColumn): array
      * Parse the given Column as array
      *
      * @return mixed[]
-     * @psalm-return array{
-     *                   fieldName: string,
-     *                   type: mixed,
-     *                   scale: int,
-     *                   length: int,
-     *                   unique: bool,
-     *                   nullable: bool,
-     *                   precision: int,
-     *                   options?: mixed[],
-     *                   columnName?: string,
-     *                   columnDefinition?: string
-     *               }
+     * @psalm-return FieldMapping
      */
     private function columnToArray(string $fieldName, Mapping\Column $column): array
     {

lib/Doctrine/ORM/Mapping/Driver/AttributeDriver.php

@@ -21,6 +21,9 @@
 use function defined;
 use function get_class;
 
+/**
+ * @psalm-import-type FieldMapping from ClassMetadataInfo
+ */
 class AttributeDriver extends AnnotationDriver
 {
     /** @var array<string,int> */
@@ -439,6 +442,7 @@ public function loadMetadataForClass($className, ClassMetadata $metadata): void
         }
 
         // Evaluate @HasLifecycleCallbacks annotation
+
         if (isset($classAttributes[Mapping\HasLifecycleCallbacks::class])) {
             foreach ($reflectionClass->getMethods(ReflectionMethod::IS_PUBLIC) as $method) {
                 assert($method instanceof ReflectionMethod);
@@ -546,18 +550,7 @@ private function joinColumnToArray($joinColumn): array
      * Parse the given Column as array
      *
      * @return mixed[]
-     * @psalm-return array{
-     *                   fieldName: string,
-     *                   type: mixed,
-     *                   scale: int,
-     *                   length: int,
-     *                   unique: bool,
-     *                   nullable: bool,
-     *                   precision: int,
-     *                   options?: mixed[],
-     *                   columnName?: string,
-     *                   columnDefinition?: string
-     *               }
+     * @psalm-return FieldMapping
      */
     private function columnToArray(string $fieldName, Mapping\Column $column): array
     {

lib/Doctrine/ORM/Mapping/Driver/DatabaseDriver.php

@@ -32,6 +32,8 @@
  * The DatabaseDriver reverse engineers the mapping metadata from a database.
  *
  * @link    www.doctrine-project.org
+ *
+ * @psalm-import-type FieldMapping from ClassMetadataInfo
  */
 class DatabaseDriver implements MappingDriver
 {
@@ -374,21 +376,7 @@ private function buildFieldMappings(ClassMetadataInfo $metadata): void
      * Build field mapping from a schema column definition
      *
      * @return mixed[]
-     * @psalm-return array{
-     *     fieldName: string,
-     *     columnName: string,
-     *     type: string,
-     *     nullable: bool,
-     *     options?: array{
-     *         unsigned?: bool,
-     *         fixed?: bool,
-     *         comment?: string,
-     *         default?: string
-     *     },
-     *     precision?: int,
-     *     scale?: int,
-     *     length?: int|null
-     * }
+     * @psalm-return FieldMapping
      */
     private function buildFieldMapping(string $tableName, Column $column): array
     {

lib/Doctrine/ORM/Mapping/Driver/XmlDriver.php

@@ -7,6 +7,7 @@
 use Doctrine\Common\Collections\Criteria;
 use Doctrine\ORM\Mapping\Builder\EntityListenerBuilder;
 use Doctrine\ORM\Mapping\ClassMetadata as Metadata;
+use Doctrine\ORM\Mapping\ClassMetadataInfo;
 use Doctrine\ORM\Mapping\MappingException;
 use Doctrine\Persistence\Mapping\ClassMetadata;
 use Doctrine\Persistence\Mapping\Driver\FileDriver;
@@ -29,6 +30,8 @@
  * XmlDriver is a metadata driver that enables mapping through XML files.
  *
  * @link        www.doctrine-project.org
+ *
+ * @psalm-import-type FieldMapping from ClassMetadataInfo
  */
 class XmlDriver extends FileDriver
 {
@@ -791,19 +794,7 @@ private function joinColumnToArray(SimpleXMLElement $joinColumnElement): array
       * Parses the given field as array.
       *
       * @return mixed[]
-      * @psalm-return array{
-      *                   fieldName: string,
-      *                   type?: string,
-      *                   columnName?: string,
-      *                   length?: int,
-      *                   precision?: int,
-      *                   scale?: int,
-      *                   unique?: bool,
-      *                   nullable?: bool,
-      *                   version?: bool,
-      *                   columnDefinition?: string,
-      *                   options?: array
-      *               }
+      * @psalm-return FieldMapping
       */
     private function columnToArray(SimpleXMLElement $fieldMapping): array
     {

lib/Doctrine/ORM/Mapping/Driver/YamlDriver.php

@@ -7,6 +7,7 @@
 use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\Mapping\Builder\EntityListenerBuilder;
 use Doctrine\ORM\Mapping\ClassMetadata as Metadata;
+use Doctrine\ORM\Mapping\ClassMetadataInfo;
 use Doctrine\ORM\Mapping\MappingException;
 use Doctrine\Persistence\Mapping\ClassMetadata;
 use Doctrine\Persistence\Mapping\Driver\FileDriver;
@@ -29,6 +30,8 @@
  * The YamlDriver reads the mapping metadata from yaml schema files.
  *
  * @deprecated 2.7 This class is being removed from the ORM and won't have any replacement
+ *
+ * @psalm-import-type FieldMapping from ClassMetadataInfo
  */
 class YamlDriver extends FileDriver
 {
@@ -791,19 +794,7 @@ private function joinColumnToArray(array $joinColumnElement): array
      *              }|null $column
      *
      * @return mixed[]
-     * @psalm-return array{
-     *                   fieldName: string,
-     *                   type?: string,
-     *                   columnName?: string,
-     *                   length?: int,
-     *                   precision?: mixed,
-     *                   scale?: mixed,
-     *                   unique?: bool,
-     *                   options?: mixed,
-     *                   nullable?: mixed,
-     *                   version?: mixed,
-     *                   columnDefinition?: mixed
-     *               }
+     * @psalm-return FieldMapping
      */
     private function columnToArray(string $fieldName, ?array $column): array
     {

lib/Doctrine/ORM/Tools/Console/Command/MappingDescribeCommand.php

@@ -6,6 +6,7 @@
 
 use Doctrine\ORM\EntityManagerInterface;
 use Doctrine\ORM\Mapping\ClassMetadata;
+use Doctrine\ORM\Mapping\ClassMetadataInfo;
 use Doctrine\Persistence\Mapping\MappingException;
 use InvalidArgumentException;
 use Symfony\Component\Console\Input\InputArgument;
@@ -39,6 +40,8 @@
  * Show information about mapped entities.
  *
  * @link    www.doctrine-project.org
+ *
+ * @psalm-import-type FieldMapping from ClassMetadataInfo
  */
 final class MappingDescribeCommand extends AbstractEntityManagerCommand
 {
@@ -245,7 +248,7 @@ private function formatField(string $label, $value): array
     /**
      * Format the association mappings
      *
-     * @psalm-param array<string, array<string, mixed>> $propertyMappings
+     * @psalm-param FieldMapping|array<string, array<string, mixed>> $propertyMappings
      *
      * @return string[][]
      * @psalm-return list<array{0: string, 1: string}>

lib/Doctrine/ORM/Tools/EntityGenerator.php

@@ -88,6 +88,8 @@
  * @deprecated 2.7 This class is being removed from the ORM and won't have any replacement
  *
  * @link    www.doctrine-project.org
+ *
+ * @psalm-import-type FieldMapping from ClassMetadataInfo
  */
 class EntityGenerator
 {
@@ -1683,6 +1685,7 @@ protected function generateAssociationMappingPropertyDocBlock(array $association
 
     /**
      * @param mixed[] $fieldMapping
+     * @psalm-param FieldMapping $fieldMapping
      *
      * @return string
      */

phpstan-baseline.neon

@@ -575,21 +575,11 @@ parameters:
 			count: 1
 			path: lib/Doctrine/ORM/Mapping/ClassMetadataInfo.php
 
-		-
-			message: "#^Offset 'unique' on array\\{type\\: string, fieldName\\: string, columnName\\?\\: string, inherited\\?\\: class\\-string, nullable\\?\\: bool, originalClass\\?\\: class\\-string, originalField\\?\\: string, scale\\?\\: int, \\.\\.\\.\\} in isset\\(\\) does not exist\\.$#"
-			count: 1
-			path: lib/Doctrine/ORM/Mapping/ClassMetadataInfo.php
-
 		-
 			message: "#^Parameter \\#2 \\$type of static method Doctrine\\\\ORM\\\\Mapping\\\\MappingException\\:\\:invalidInheritanceType\\(\\) expects string, int given\\.$#"
 			count: 1
 			path: lib/Doctrine/ORM/Mapping/ClassMetadataInfo.php
 
-		-
-			message: "#^Result of && is always false\\.$#"
-			count: 2
-			path: lib/Doctrine/ORM/Mapping/ClassMetadataInfo.php
-
 		-
 			message: "#^Array \\(array\\<class\\-string, object\\>\\) does not accept key string\\.$#"
 			count: 1
@@ -2211,11 +2201,6 @@ parameters:
 			count: 1
 			path: lib/Doctrine/ORM/Tools/Export/Driver/XmlExporter.php
 
-		-
-			message: "#^Offset 'options' on array\\{type\\: string, fieldName\\: string, columnName\\?\\: string, length\\?\\: int, id\\?\\: bool, nullable\\?\\: bool, columnDefinition\\?\\: string, precision\\?\\: int, \\.\\.\\.\\} in isset\\(\\) always exists and is not nullable\\.$#"
-			count: 1
-			path: lib/Doctrine/ORM/Tools/Export/Driver/XmlExporter.php
-
 		-
 			message: "#^Offset 'schema' on array\\{name\\: string, schema\\: string, indexes\\: array, uniqueConstraints\\: array, options\\: array\\<string, mixed\\>, quoted\\?\\: bool\\} in isset\\(\\) always exists and is not nullable\\.$#"
 			count: 1
@@ -2226,11 +2211,6 @@ parameters:
 			count: 1
 			path: lib/Doctrine/ORM/Tools/Export/Driver/XmlExporter.php
 
-		-
-			message: "#^Offset 'version' on array\\{type\\: string, fieldName\\: string, options\\: array, columnName\\?\\: string, length\\?\\: int, id\\?\\: bool, nullable\\?\\: bool, columnDefinition\\?\\: string, \\.\\.\\.\\} in isset\\(\\) does not exist\\.$#"
-			count: 1
-			path: lib/Doctrine/ORM/Tools/Export/Driver/XmlExporter.php
-
 		-
 			message: "#^Parameter \\#1 \\$policy of method Doctrine\\\\ORM\\\\Tools\\\\Export\\\\Driver\\\\AbstractExporter\\:\\:_getChangeTrackingPolicyString\\(\\) expects 1\\|2\\|3, int given\\.$#"
 			count: 1
@@ -2316,11 +2296,6 @@ parameters:
 			count: 1
 			path: lib/Doctrine/ORM/Tools/SchemaTool.php
 
-		-
-			message: "#^Offset 'columnDefinition' on array\\{type\\: string, fieldName\\: string, columnName\\?\\: string, inherited\\?\\: class\\-string, nullable\\?\\: bool, originalClass\\?\\: class\\-string, originalField\\?\\: string, scale\\?\\: int, \\.\\.\\.\\} in isset\\(\\) does not exist\\.$#"
-			count: 1
-			path: lib/Doctrine/ORM/Tools/SchemaTool.php
-
 		-
 			message: "#^Offset 'indexes' on array\\{name\\: string, schema\\: string, indexes\\: array, uniqueConstraints\\: array, options\\: array\\<string, mixed\\>, quoted\\?\\: bool\\} in isset\\(\\) always exists and is not nullable\\.$#"
 			count: 1