vendor/doctrine/orm/src/Mapping/ClassMetadataInfo.php line 1215

Open in your IDE?
  1. <?php
  3. declare(strict_types=1);
  5. namespace Doctrine\ORM\Mapping;
  7. use BackedEnum;
  8. use BadMethodCallException;
  9. use Doctrine\DBAL\Platforms\AbstractPlatform;
  10. use Doctrine\DBAL\Types\Type;
  11. use Doctrine\Deprecations\Deprecation;
  12. use Doctrine\Instantiator\Instantiator;
  13. use Doctrine\Instantiator\InstantiatorInterface;
  14. use Doctrine\ORM\Cache\Exception\NonCacheableEntityAssociation;
  15. use Doctrine\ORM\EntityRepository;
  16. use Doctrine\ORM\Id\AbstractIdGenerator;
  17. use Doctrine\Persistence\Mapping\ClassMetadata;
  18. use Doctrine\Persistence\Mapping\ReflectionService;
  19. use InvalidArgumentException;
  20. use LogicException;
  21. use ReflectionClass;
  22. use ReflectionNamedType;
  23. use ReflectionProperty;
  24. use RuntimeException;
  26. use function array_diff;
  27. use function array_flip;
  28. use function array_intersect;
  29. use function array_keys;
  30. use function array_map;
  31. use function array_merge;
  32. use function array_pop;
  33. use function array_values;
  34. use function assert;
  35. use function class_exists;
  36. use function count;
  37. use function enum_exists;
  38. use function explode;
  39. use function gettype;
  40. use function in_array;
  41. use function interface_exists;
  42. use function is_array;
  43. use function is_subclass_of;
  44. use function ltrim;
  45. use function method_exists;
  46. use function spl_object_id;
  47. use function str_contains;
  48. use function str_replace;
  49. use function strtolower;
  50. use function trait_exists;
  51. use function trim;
  53. use const PHP_VERSION_ID;
  55. /**
  56.  * A <tt>ClassMetadata</tt> instance holds all the object-relational mapping metadata
  57.  * of an entity and its associations.
  58.  *
  59.  * Once populated, ClassMetadata instances are usually cached in a serialized form.
  60.  *
  61.  * <b>IMPORTANT NOTE:</b>
  62.  *
  63.  * The fields of this class are only public for 2 reasons:
  64.  * 1) To allow fast READ access.
  65.  * 2) To drastically reduce the size of a serialized instance (private/protected members
  66.  *    get the whole class name, namespace inclusive, prepended to every property in
  67.  *    the serialized representation).
  68.  *
  69.  * @template-covariant T of object
  70.  * @template-implements ClassMetadata<T>
  71.  * @psalm-import-type AssociationMapping from \Doctrine\ORM\Mapping\ClassMetadata
  72.  * @psalm-import-type FieldMapping from \Doctrine\ORM\Mapping\ClassMetadata
  73.  * @psalm-import-type EmbeddedClassMapping from \Doctrine\ORM\Mapping\ClassMetadata
  74.  * @psalm-import-type JoinColumnData from \Doctrine\ORM\Mapping\ClassMetadata
  75.  * @psalm-import-type DiscriminatorColumnMapping from \Doctrine\ORM\Mapping\ClassMetadata
  76.  */
  77. class ClassMetadataInfo implements ClassMetadata
  78. {
  79.     /* The inheritance mapping types */
  80.     /**
  81.      * NONE means the class does not participate in an inheritance hierarchy
  82.      * and therefore does not need an inheritance mapping type.
  83.      */
  84.     public const INHERITANCE_TYPE_NONE = 1;
  86.     /**
  87.      * JOINED means the class will be persisted according to the rules of
  88.      * <tt>Class Table Inheritance</tt>.
  89.      */
  90.     public const INHERITANCE_TYPE_JOINED = 2;
  92.     /**
  93.      * SINGLE_TABLE means the class will be persisted according to the rules of
  94.      * <tt>Single Table Inheritance</tt>.
  95.      */
  96.     public const INHERITANCE_TYPE_SINGLE_TABLE = 3;
  98.     /**
  99.      * TABLE_PER_CLASS means the class will be persisted according to the rules
  100.      * of <tt>Concrete Table Inheritance</tt>.
  101.      *
  102.      * @deprecated
  103.      */
  104.     public const INHERITANCE_TYPE_TABLE_PER_CLASS = 4;
  106.     /* The Id generator types. */
  107.     /**
  108.      * AUTO means the generator type will depend on what the used platform prefers.
  109.      * Offers full portability.
  110.      */
  111.     public const GENERATOR_TYPE_AUTO = 1;
  113.     /**
  114.      * SEQUENCE means a separate sequence object will be used. Platforms that do
  115.      * not have native sequence support may emulate it. Full portability is currently
  116.      * not guaranteed.
  117.      */
  118.     public const GENERATOR_TYPE_SEQUENCE = 2;
  120.     /**
  121.      * TABLE means a separate table is used for id generation.
  122.      * Offers full portability (in that it results in an exception being thrown
  123.      * no matter the platform).
  124.      *
  125.      * @deprecated no replacement planned
  126.      */
  127.     public const GENERATOR_TYPE_TABLE = 3;
  129.     /**
  130.      * IDENTITY means an identity column is used for id generation. The database
  131.      * will fill in the id column on insertion. Platforms that do not support
  132.      * native identity columns may emulate them. Full portability is currently
  133.      * not guaranteed.
  134.      */
  135.     public const GENERATOR_TYPE_IDENTITY = 4;
  137.     /**
  138.      * NONE means the class does not have a generated id. That means the class
  139.      * must have a natural, manually assigned id.
  140.      */
  141.     public const GENERATOR_TYPE_NONE = 5;
  143.     /**
  144.      * UUID means that a UUID/GUID expression is used for id generation. Full
  145.      * portability is currently not guaranteed.
  146.      *
  147.      * @deprecated use an application-side generator instead
  148.      */
  149.     public const GENERATOR_TYPE_UUID = 6;
  151.     /**
  152.      * CUSTOM means that customer will use own ID generator that supposedly work
  153.      */
  154.     public const GENERATOR_TYPE_CUSTOM = 7;
  156.     /**
  157.      * DEFERRED_IMPLICIT means that changes of entities are calculated at commit-time
  158.      * by doing a property-by-property comparison with the original data. This will
  159.      * be done for all entities that are in MANAGED state at commit-time.
  160.      *
  161.      * This is the default change tracking policy.
  162.      */
  163.     public const CHANGETRACKING_DEFERRED_IMPLICIT = 1;
  165.     /**
  166.      * DEFERRED_EXPLICIT means that changes of entities are calculated at commit-time
  167.      * by doing a property-by-property comparison with the original data. This will
  168.      * be done only for entities that were explicitly saved (through persist() or a cascade).
  169.      */
  170.     public const CHANGETRACKING_DEFERRED_EXPLICIT = 2;
  172.     /**
  173.      * NOTIFY means that Doctrine relies on the entities sending out notifications
  174.      * when their properties change. Such entity classes must implement
  175.      * the <tt>NotifyPropertyChanged</tt> interface.
  176.      */
  177.     public const CHANGETRACKING_NOTIFY = 3;
  179.     /**
  180.      * Specifies that an association is to be fetched when it is first accessed.
  181.      */
  182.     public const FETCH_LAZY = 2;
  184.     /**
  185.      * Specifies that an association is to be fetched when the owner of the
  186.      * association is fetched.
  187.      */
  188.     public const FETCH_EAGER = 3;
  190.     /**
  191.      * Specifies that an association is to be fetched lazy (on first access) and that
  192.      * commands such as Collection#count, Collection#slice are issued directly against
  193.      * the database if the collection is not yet initialized.
  194.      */
  195.     public const FETCH_EXTRA_LAZY = 4;
  197.     /**
  198.      * Identifies a one-to-one association.
  199.      */
  200.     public const ONE_TO_ONE = 1;
  202.     /**
  203.      * Identifies a many-to-one association.
  204.      */
  205.     public const MANY_TO_ONE = 2;
  207.     /**
  208.      * Identifies a one-to-many association.
  209.      */
  210.     public const ONE_TO_MANY = 4;
  212.     /**
  213.      * Identifies a many-to-many association.
  214.      */
  215.     public const MANY_TO_MANY = 8;
  217.     /**
  218.      * Combined bitmask for to-one (single-valued) associations.
  219.      */
  220.     public const TO_ONE = 3;
  222.     /**
  223.      * Combined bitmask for to-many (collection-valued) associations.
  224.      */
  225.     public const TO_MANY = 12;
  227.     /**
  228.      * ReadOnly cache can do reads, inserts and deletes, cannot perform updates or employ any locks,
  229.      */
  230.     public const CACHE_USAGE_READ_ONLY = 1;
  232.     /**
  233.      * Nonstrict Read Write Cache doesn’t employ any locks but can do inserts, update and deletes.
  234.      */
  235.     public const CACHE_USAGE_NONSTRICT_READ_WRITE = 2;
  237.     /**
  238.      * Read Write Attempts to lock the entity before update/delete.
  239.      */
  240.     public const CACHE_USAGE_READ_WRITE = 3;
  242.     /**
  243.      * The value of this column is never generated by the database.
  244.      */
  245.     public const GENERATED_NEVER = 0;
  247.     /**
  248.      * The value of this column is generated by the database on INSERT, but not on UPDATE.
  249.      */
  250.     public const GENERATED_INSERT = 1;
  252.     /**
  253.      * The value of this column is generated by the database on both INSERT and UDPATE statements.
  254.      */
  255.     public const GENERATED_ALWAYS = 2;
  257.     /**
  258.      * READ-ONLY: The name of the entity class.
  259.      *
  260.      * @var class-string<T>
  261.      */
  262.     public $name;
  264.     /**
  265.      * READ-ONLY: The namespace the entity class is contained in.
  266.      *
  267.      * @var string
  268.      * @todo Not really needed. Usage could be localized.
  269.      */
  270.     public $namespace;
  272.     /**
  273.      * READ-ONLY: The name of the entity class that is at the root of the mapped entity inheritance
  274.      * hierarchy. If the entity is not part of a mapped inheritance hierarchy this is the same
  275.      * as {@link $name}.
  276.      *
  277.      * @var class-string
  278.      */
  279.     public $rootEntityName;
  281.     /**
  282.      * READ-ONLY: The definition of custom generator. Only used for CUSTOM
  283.      * generator type
  284.      *
  285.      * The definition has the following structure:
  286.      * <code>
  287.      * array(
  288.      *     'class' => 'ClassName',
  289.      * )
  290.      * </code>
  291.      *
  292.      * @todo Merge with tableGeneratorDefinition into generic generatorDefinition
  293.      * @var array<string, string>|null
  294.      */
  295.     public $customGeneratorDefinition;
  297.     /**
  298.      * The name of the custom repository class used for the entity class.
  299.      * (Optional).
  300.      *
  301.      * @var class-string<EntityRepository>|null
  302.      */
  303.     public $customRepositoryClassName;
  305.     /**
  306.      * READ-ONLY: Whether this class describes the mapping of a mapped superclass.
  307.      *
  308.      * @var bool
  309.      */
  310.     public $isMappedSuperclass = false;
  312.     /**
  313.      * READ-ONLY: Whether this class describes the mapping of an embeddable class.
  314.      *
  315.      * @var bool
  316.      */
  317.     public $isEmbeddedClass = false;
  319.     /**
  320.      * READ-ONLY: The names of the parent <em>entity</em> classes (ancestors), starting with the
  321.      * nearest one and ending with the root entity class.
  322.      *
  323.      * @var list<class-string>
  324.      */
  325.     public $parentClasses = [];
  327.     /**
  328.      * READ-ONLY: For classes in inheritance mapping hierarchies, this field contains the names of all
  329.      * <em>entity</em> subclasses of this class. These may also be abstract classes.
  330.      *
  331.      * This list is used, for example, to enumerate all necessary tables in JTI when querying for root
  332.      * or subclass entities, or to gather all fields comprised in an entity inheritance tree.
  333.      *
  334.      * For classes that do not use STI/JTI, this list is empty.
  335.      *
  336.      * Implementation note:
  337.      *
  338.      * In PHP, there is no general way to discover all subclasses of a given class at runtime. For that
  339.      * reason, the list of classes given in the discriminator map at the root entity is considered
  340.      * authoritative. The discriminator map must contain all <em>concrete</em> classes that can
  341.      * appear in the particular inheritance hierarchy tree. Since there can be no instances of abstract
  342.      * entity classes, users are not required to list such classes with a discriminator value.
  343.      *
  344.      * The possibly remaining "gaps" for abstract entity classes are filled after the class metadata for the
  345.      * root entity has been loaded.
  346.      *
  347.      * For subclasses of such root entities, the list can be reused/passed downwards, it only needs to
  348.      * be filtered accordingly (only keep remaining subclasses)
  349.      *
  350.      * @var list<class-string>
  351.      */
  352.     public $subClasses = [];
  354.     /**
  355.      * READ-ONLY: The names of all embedded classes based on properties.
  356.      *
  357.      * The value (definition) array may contain, among others, the following values:
  358.      *
  359.      * - <b>'inherited'</b> (string, optional)
  360.      * This is set when this embedded-class field is inherited by this class from another (inheritance) parent
  361.      * <em>entity</em> class. The value is the FQCN of the topmost entity class that contains
  362.      * mapping information for this field. (If there are transient classes in the
  363.      * class hierarchy, these are ignored, so the class property may in fact come
  364.      * from a class further up in the PHP class hierarchy.)
  365.      * Fields initially declared in mapped superclasses are
  366.      * <em>not</em> considered 'inherited' in the nearest entity subclasses.
  367.      *
  368.      * - <b>'declared'</b> (string, optional)
  369.      * This is set when the embedded-class field does not appear for the first time in this class, but is originally
  370.      * declared in another parent <em>entity or mapped superclass</em>. The value is the FQCN
  371.      * of the topmost non-transient class that contains mapping information for this field.
  372.      *
  373.      * @psalm-var array<string, EmbeddedClassMapping>
  374.      */
  375.     public $embeddedClasses = [];
  377.     /**
  378.      * READ-ONLY: The named queries allowed to be called directly from Repository.
  379.      *
  380.      * @psalm-var array<string, array<string, mixed>>
  381.      */
  382.     public $namedQueries = [];
  384.     /**
  385.      * READ-ONLY: The named native queries allowed to be called directly from Repository.
  386.      *
  387.      * A native SQL named query definition has the following structure:
  388.      * <pre>
  389.      * array(
  390.      *     'name'               => <query name>,
  391.      *     'query'              => <sql query>,
  392.      *     'resultClass'        => <class of the result>,
  393.      *     'resultSetMapping'   => <name of a SqlResultSetMapping>
  394.      * )
  395.      * </pre>
  396.      *
  397.      * @psalm-var array<string, array<string, mixed>>
  398.      */
  399.     public $namedNativeQueries = [];
  401.     /**
  402.      * READ-ONLY: The mappings of the results of native SQL queries.
  403.      *
  404.      * A native result mapping definition has the following structure:
  405.      * <pre>
  406.      * array(
  407.      *     'name'               => <result name>,
  408.      *     'entities'           => array(<entity result mapping>),
  409.      *     'columns'            => array(<column result mapping>)
  410.      * )
  411.      * </pre>
  412.      *
  413.      * @psalm-var array<string, array{
  414.      *                name: string,
  415.      *                entities: mixed[],
  416.      *                columns: mixed[]
  417.      *            }>
  418.      */
  419.     public $sqlResultSetMappings = [];
  421.     /**
  422.      * READ-ONLY: The field names of all fields that are part of the identifier/primary key
  423.      * of the mapped entity class.
  424.      *
  425.      * @psalm-var list<string>
  426.      */
  427.     public $identifier = [];
  429.     /**
  430.      * READ-ONLY: The inheritance mapping type used by the class.
  431.      *
  432.      * @var int
  433.      * @psalm-var self::INHERITANCE_TYPE_*
  434.      */
  435.     public $inheritanceType = self::INHERITANCE_TYPE_NONE;
  437.     /**
  438.      * READ-ONLY: The Id generator type used by the class.
  439.      *
  440.      * @var int
  441.      * @psalm-var self::GENERATOR_TYPE_*
  442.      */
  443.     public $generatorType = self::GENERATOR_TYPE_NONE;
  445.     /**
  446.      * READ-ONLY: The field mappings of the class.
  447.      * Keys are field names and values are mapping definitions.
  448.      *
  449.      * The mapping definition array has the following values:
  450.      *
  451.      * - <b>fieldName</b> (string)
  452.      * The name of the field in the Entity.
  453.      *
  454.      * - <b>type</b> (string)
  455.      * The type name of the mapped field. Can be one of Doctrine's mapping types
  456.      * or a custom mapping type.
  457.      *
  458.      * - <b>columnName</b> (string, optional)
  459.      * The column name. Optional. Defaults to the field name.
  460.      *
  461.      * - <b>length</b> (integer, optional)
  462.      * The database length of the column. Optional. Default value taken from
  463.      * the type.
  464.      *
  465.      * - <b>id</b> (boolean, optional)
  466.      * Marks the field as the primary key of the entity. Multiple fields of an
  467.      * entity can have the id attribute, forming a composite key.
  468.      *
  469.      * - <b>nullable</b> (boolean, optional)
  470.      * Whether the column is nullable. Defaults to FALSE.
  471.      *
  472.      * - <b>'notInsertable'</b> (boolean, optional)
  473.      * Whether the column is not insertable. Optional. Is only set if value is TRUE.
  474.      *
  475.      * - <b>'notUpdatable'</b> (boolean, optional)
  476.      * Whether the column is updatable. Optional. Is only set if value is TRUE.
  477.      *
  478.      * - <b>columnDefinition</b> (string, optional, schema-only)
  479.      * The SQL fragment that is used when generating the DDL for the column.
  480.      *
  481.      * - <b>precision</b> (integer, optional, schema-only)
  482.      * The precision of a decimal column. Only valid if the column type is decimal.
  483.      *
  484.      * - <b>scale</b> (integer, optional, schema-only)
  485.      * The scale of a decimal column. Only valid if the column type is decimal.
  486.      *
  487.      * - <b>'unique'</b> (boolean, optional, schema-only)
  488.      * Whether a unique constraint should be generated for the column.
  489.      *
  490.      * - <b>'inherited'</b> (string, optional)
  491.      * This is set when the field is inherited by this class from another (inheritance) parent
  492.      * <em>entity</em> class. The value is the FQCN of the topmost entity class that contains
  493.      * mapping information for this field. (If there are transient classes in the
  494.      * class hierarchy, these are ignored, so the class property may in fact come
  495.      * from a class further up in the PHP class hierarchy.)
  496.      * Fields initially declared in mapped superclasses are
  497.      * <em>not</em> considered 'inherited' in the nearest entity subclasses.
  498.      *
  499.      * - <b>'declared'</b> (string, optional)
  500.      * This is set when the field does not appear for the first time in this class, but is originally
  501.      * declared in another parent <em>entity or mapped superclass</em>. The value is the FQCN
  502.      * of the topmost non-transient class that contains mapping information for this field.
  503.      *
  504.      * @var mixed[]
  505.      * @psalm-var array<string, FieldMapping>
  506.      */
  507.     public $fieldMappings = [];
  509.     /**
  510.      * READ-ONLY: An array of field names. Used to look up field names from column names.
  511.      * Keys are column names and values are field names.
  512.      *
  513.      * @psalm-var array<string, string>
  514.      */
  515.     public $fieldNames = [];
  517.     /**
  518.      * READ-ONLY: A map of field names to column names. Keys are field names and values column names.
  519.      * Used to look up column names from field names.
  520.      * This is the reverse lookup map of $_fieldNames.
  521.      *
  522.      * @deprecated 3.0 Remove this.
  523.      *
  524.      * @var mixed[]
  525.      */
  526.     public $columnNames = [];
  528.     /**
  529.      * READ-ONLY: The discriminator value of this class.
  530.      *
  531.      * <b>This does only apply to the JOINED and SINGLE_TABLE inheritance mapping strategies
  532.      * where a discriminator column is used.</b>
  533.      *
  534.      * @see discriminatorColumn
  535.      *
  536.      * @var mixed
  537.      */
  538.     public $discriminatorValue;
  540.     /**
  541.      * READ-ONLY: The discriminator map of all mapped classes in the hierarchy.
  542.      *
  543.      * <b>This does only apply to the JOINED and SINGLE_TABLE inheritance mapping strategies
  544.      * where a discriminator column is used.</b>
  545.      *
  546.      * @see discriminatorColumn
  547.      *
  548.      * @var array<int|string, class-string>
  549.      */
  550.     public $discriminatorMap = [];
  552.     /**
  553.      * READ-ONLY: The definition of the discriminator column used in JOINED and SINGLE_TABLE
  554.      * inheritance mappings.
  555.      *
  556.      * @var array<string, mixed>
  557.      * @psalm-var DiscriminatorColumnMapping|null
  558.      */
  559.     public $discriminatorColumn;
  561.     /**
  562.      * READ-ONLY: The primary table definition. The definition is an array with the
  563.      * following entries:
  564.      *
  565.      * name => <tableName>
  566.      * schema => <schemaName>
  567.      * indexes => array
  568.      * uniqueConstraints => array
  569.      *
  570.      * @var mixed[]
  571.      * @psalm-var array{
  572.      *               name: string,
  573.      *               schema?: string,
  574.      *               indexes?: array,
  575.      *               uniqueConstraints?: array,
  576.      *               options?: array<string, mixed>,
  577.      *               quoted?: bool
  578.      *           }
  579.      */
  580.     public $table;
  582.     /**
  583.      * READ-ONLY: The registered lifecycle callbacks for entities of this class.
  584.      *
  585.      * @psalm-var array<string, list<string>>
  586.      */
  587.     public $lifecycleCallbacks = [];
  589.     /**
  590.      * READ-ONLY: The registered entity listeners.
  591.      *
  592.      * @psalm-var array<string, list<array{class: class-string, method: string}>>
  593.      */
  594.     public $entityListeners = [];
  596.     /**
  597.      * READ-ONLY: The association mappings of this class.
  598.      *
  599.      * The mapping definition array supports the following keys:
  600.      *
  601.      * - <b>fieldName</b> (string)
  602.      * The name of the field in the entity the association is mapped to.
  603.      *
  604.      * - <b>sourceEntity</b> (string)
  605.      * The class name of the source entity. In the case of to-many associations initially
  606.      * present in mapped superclasses, the nearest <em>entity</em> subclasses will be
  607.      * considered the respective source entities.
  608.      *
  609.      * - <b>targetEntity</b> (string)
  610.      * The class name of the target entity. If it is fully-qualified it is used as is.
  611.      * If it is a simple, unqualified class name the namespace is assumed to be the same
  612.      * as the namespace of the source entity.
  613.      *
  614.      * - <b>mappedBy</b> (string, required for bidirectional associations)
  615.      * The name of the field that completes the bidirectional association on the owning side.
  616.      * This key must be specified on the inverse side of a bidirectional association.
  617.      *
  618.      * - <b>inversedBy</b> (string, required for bidirectional associations)
  619.      * The name of the field that completes the bidirectional association on the inverse side.
  620.      * This key must be specified on the owning side of a bidirectional association.
  621.      *
  622.      * - <b>cascade</b> (array, optional)
  623.      * The names of persistence operations to cascade on the association. The set of possible
  624.      * values are: "persist", "remove", "detach", "merge", "refresh", "all" (implies all others).
  625.      *
  626.      * - <b>orderBy</b> (array, one-to-many/many-to-many only)
  627.      * A map of field names (of the target entity) to sorting directions (ASC/DESC).
  628.      * Example: array('priority' => 'desc')
  629.      *
  630.      * - <b>fetch</b> (integer, optional)
  631.      * The fetching strategy to use for the association, usually defaults to FETCH_LAZY.
  632.      * Possible values are: ClassMetadata::FETCH_EAGER, ClassMetadata::FETCH_LAZY.
  633.      *
  634.      * - <b>joinTable</b> (array, optional, many-to-many only)
  635.      * Specification of the join table and its join columns (foreign keys).
  636.      * Only valid for many-to-many mappings. Note that one-to-many associations can be mapped
  637.      * through a join table by simply mapping the association as many-to-many with a unique
  638.      * constraint on the join table.
  639.      *
  640.      * - <b>indexBy</b> (string, optional, to-many only)
  641.      * Specification of a field on target-entity that is used to index the collection by.
  642.      * This field HAS to be either the primary key or a unique column. Otherwise the collection
  643.      * does not contain all the entities that are actually related.
  644.      *
  645.      * - <b>'inherited'</b> (string, optional)
  646.      * This is set when the association is inherited by this class from another (inheritance) parent
  647.      * <em>entity</em> class. The value is the FQCN of the topmost entity class that contains
  648.      * this association. (If there are transient classes in the
  649.      * class hierarchy, these are ignored, so the class property may in fact come
  650.      * from a class further up in the PHP class hierarchy.)
  651.      * To-many associations initially declared in mapped superclasses are
  652.      * <em>not</em> considered 'inherited' in the nearest entity subclasses.
  653.      *
  654.      * - <b>'declared'</b> (string, optional)
  655.      * This is set when the association does not appear in the current class for the first time, but
  656.      * is initially declared in another parent <em>entity or mapped superclass</em>. The value is the FQCN
  657.      * of the topmost non-transient class that contains association information for this relationship.
  658.      *
  659.      * A join table definition has the following structure:
  660.      * <pre>
  661.      * array(
  662.      *     'name' => <join table name>,
  663.      *      'joinColumns' => array(<join column mapping from join table to source table>),
  664.      *      'inverseJoinColumns' => array(<join column mapping from join table to target table>)
  665.      * )
  666.      * </pre>
  667.      *
  668.      * @psalm-var array<string, AssociationMapping>
  669.      */
  670.     public $associationMappings = [];
  672.     /**
  673.      * READ-ONLY: Flag indicating whether the identifier/primary key of the class is composite.
  674.      *
  675.      * @var bool
  676.      */
  677.     public $isIdentifierComposite = false;
  679.     /**
  680.      * READ-ONLY: Flag indicating whether the identifier/primary key contains at least one foreign key association.
  681.      *
  682.      * This flag is necessary because some code blocks require special treatment of this cases.
  683.      *
  684.      * @var bool
  685.      */
  686.     public $containsForeignIdentifier = false;
  688.     /**
  689.      * READ-ONLY: Flag indicating whether the identifier/primary key contains at least one ENUM type.
  690.      *
  691.      * This flag is necessary because some code blocks require special treatment of this cases.
  692.      *
  693.      * @var bool
  694.      */
  695.     public $containsEnumIdentifier = false;
  697.     /**
  698.      * READ-ONLY: The ID generator used for generating IDs for this class.
  699.      *
  700.      * @var AbstractIdGenerator
  701.      * @todo Remove!
  702.      */
  703.     public $idGenerator;
  705.     /**
  706.      * READ-ONLY: The definition of the sequence generator of this class. Only used for the
  707.      * SEQUENCE generation strategy.
  708.      *
  709.      * The definition has the following structure:
  710.      * <code>
  711.      * array(
  712.      *     'sequenceName' => 'name',
  713.      *     'allocationSize' => '20',
  714.      *     'initialValue' => '1'
  715.      * )
  716.      * </code>
  717.      *
  718.      * @var array<string, mixed>|null
  719.      * @psalm-var array{sequenceName: string, allocationSize: string, initialValue: string, quoted?: mixed}|null
  720.      * @todo Merge with tableGeneratorDefinition into generic generatorDefinition
  721.      */
  722.     public $sequenceGeneratorDefinition;
  724.     /**
  725.      * READ-ONLY: The definition of the table generator of this class. Only used for the
  726.      * TABLE generation strategy.
  727.      *
  728.      * @deprecated
  729.      *
  730.      * @var array<string, mixed>
  731.      */
  732.     public $tableGeneratorDefinition;
  734.     /**
  735.      * READ-ONLY: The policy used for change-tracking on entities of this class.
  736.      *
  737.      * @var int
  738.      */
  739.     public $changeTrackingPolicy = self::CHANGETRACKING_DEFERRED_IMPLICIT;
  741.     /**
  742.      * READ-ONLY: A Flag indicating whether one or more columns of this class
  743.      * have to be reloaded after insert / update operations.
  744.      *
  745.      * @var bool
  746.      */
  747.     public $requiresFetchAfterChange = false;
  749.     /**
  750.      * READ-ONLY: A flag for whether or not instances of this class are to be versioned
  751.      * with optimistic locking.
  752.      *
  753.      * @var bool
  754.      */
  755.     public $isVersioned = false;
  757.     /**
  758.      * READ-ONLY: The name of the field which is used for versioning in optimistic locking (if any).
  759.      *
  760.      * @var string|null
  761.      */
  762.     public $versionField;
  764.     /** @var mixed[]|null */
  765.     public $cache;
  767.     /**
  768.      * The ReflectionClass instance of the mapped class.
  769.      *
  770.      * @var ReflectionClass|null
  771.      */
  772.     public $reflClass;
  774.     /**
  775.      * Is this entity marked as "read-only"?
  776.      *
  777.      * That means it is never considered for change-tracking in the UnitOfWork. It is a very helpful performance
  778.      * optimization for entities that are immutable, either in your domain or through the relation database
  779.      * (coming from a view, or a history table for example).
  780.      *
  781.      * @var bool
  782.      */
  783.     public $isReadOnly = false;
  785.     /**
  786.      * NamingStrategy determining the default column and table names.
  787.      *
  788.      * @var NamingStrategy
  789.      */
  790.     protected $namingStrategy;
  792.     /**
  793.      * The ReflectionProperty instances of the mapped class.
  794.      *
  795.      * @var array<string, ReflectionProperty|null>
  796.      */
  797.     public $reflFields = [];
  799.     /** @var InstantiatorInterface|null */
  800.     private $instantiator;
  802.     /** @var TypedFieldMapper $typedFieldMapper */
  803.     private $typedFieldMapper;
  805.     /**
  806.      * Initializes a new ClassMetadata instance that will hold the object-relational mapping
  807.      * metadata of the class with the given name.
  808.      *
  809.      * @param class-string<T> $entityName The name of the entity class the new instance is used for.
  810.      */
  811.     public function __construct($entityName, ?NamingStrategy $namingStrategy = null, ?TypedFieldMapper $typedFieldMapper = null)
  812.     {
  813.         $this->name             = $entityName;
  814.         $this->rootEntityName   = $entityName;
  815.         $this->namingStrategy   = $namingStrategy ?? new DefaultNamingStrategy();
  816.         $this->instantiator     = new Instantiator();
  817.         $this->typedFieldMapper = $typedFieldMapper ?? new DefaultTypedFieldMapper();
  818.     }
  820.     /**
  821.      * Gets the ReflectionProperties of the mapped class.
  822.      *
  823.      * @return ReflectionProperty[]|null[] An array of ReflectionProperty instances.
  824.      * @psalm-return array<ReflectionProperty|null>
  825.      */
  826.     public function getReflectionProperties()
  827.     {
  828.         return $this->reflFields;
  829.     }
  831.     /**
  832.      * Gets a ReflectionProperty for a specific field of the mapped class.
  833.      *
  834.      * @param string $name
  835.      *
  836.      * @return ReflectionProperty
  837.      */
  838.     public function getReflectionProperty($name)
  839.     {
  840.         return $this->reflFields[$name];
  841.     }
  843.     /**
  844.      * Gets the ReflectionProperty for the single identifier field.
  845.      *
  846.      * @return ReflectionProperty
  847.      *
  848.      * @throws BadMethodCallException If the class has a composite identifier.
  849.      */
  850.     public function getSingleIdReflectionProperty()
  851.     {
  852.         if ($this->isIdentifierComposite) {
  853.             throw new BadMethodCallException('Class ' . $this->name . ' has a composite identifier.');
  854.         }
  856.         return $this->reflFields[$this->identifier[0]];
  857.     }
  859.     /**
  860.      * Extracts the identifier values of an entity of this class.
  861.      *
  862.      * For composite identifiers, the identifier values are returned as an array
  863.      * with the same order as the field order in {@link identifier}.
  864.      *
  865.      * @param object $entity
  866.      *
  867.      * @return array<string, mixed>
  868.      */
  869.     public function getIdentifierValues($entity)
  870.     {
  871.         if ($this->isIdentifierComposite) {
  872.             $id = [];
  874.             foreach ($this->identifier as $idField) {
  875.                 $value = $this->reflFields[$idField]->getValue($entity);
  877.                 if ($value !== null) {
  878.                     $id[$idField] = $value;
  879.                 }
  880.             }
  882.             return $id;
  883.         }
  885.         $id    = $this->identifier[0];
  886.         $value = $this->reflFields[$id]->getValue($entity);
  888.         if ($value === null) {
  889.             return [];
  890.         }
  892.         return [$id => $value];
  893.     }
  895.     /**
  896.      * Populates the entity identifier of an entity.
  897.      *
  898.      * @param object $entity
  899.      * @psalm-param array<string, mixed> $id
  900.      *
  901.      * @return void
  902.      *
  903.      * @todo Rename to assignIdentifier()
  904.      */
  905.     public function setIdentifierValues($entity, array $id)
  906.     {
  907.         foreach ($id as $idField => $idValue) {
  908.             $this->reflFields[$idField]->setValue($entity, $idValue);
  909.         }
  910.     }
  912.     /**
  913.      * Sets the specified field to the specified value on the given entity.
  914.      *
  915.      * @param object $entity
  916.      * @param string $field
  917.      * @param mixed  $value
  918.      *
  919.      * @return void
  920.      */
  921.     public function setFieldValue($entity, $field, $value)
  922.     {
  923.         $this->reflFields[$field]->setValue($entity, $value);
  924.     }
  926.     /**
  927.      * Gets the specified field's value off the given entity.
  928.      *
  929.      * @param object $entity
  930.      * @param string $field
  931.      *
  932.      * @return mixed
  933.      */
  934.     public function getFieldValue($entity, $field)
  935.     {
  936.         return $this->reflFields[$field]->getValue($entity);
  937.     }
  939.     /**
  940.      * Creates a string representation of this instance.
  941.      *
  942.      * @return string The string representation of this instance.
  943.      *
  944.      * @todo Construct meaningful string representation.
  945.      */
  946.     public function __toString()
  947.     {
  948.         return self::class . '@' . spl_object_id($this);
  949.     }
  951.     /**
  952.      * Determines which fields get serialized.
  953.      *
  954.      * It is only serialized what is necessary for best unserialization performance.
  955.      * That means any metadata properties that are not set or empty or simply have
  956.      * their default value are NOT serialized.
  957.      *
  958.      * Parts that are also NOT serialized because they can not be properly unserialized:
  959.      *      - reflClass (ReflectionClass)
  960.      *      - reflFields (ReflectionProperty array)
  961.      *
  962.      * @return string[] The names of all the fields that should be serialized.
  963.      */
  964.     public function __sleep()
  965.     {
  966.         // This metadata is always serialized/cached.
  967.         $serialized = [
  968.             'associationMappings',
  969.             'columnNames', //TODO: 3.0 Remove this. Can use fieldMappings[$fieldName]['columnName']
  970.             'fieldMappings',
  971.             'fieldNames',
  972.             'embeddedClasses',
  973.             'identifier',
  974.             'isIdentifierComposite', // TODO: REMOVE
  975.             'name',
  976.             'namespace', // TODO: REMOVE
  977.             'table',
  978.             'rootEntityName',
  979.             'idGenerator', //TODO: Does not really need to be serialized. Could be moved to runtime.
  980.         ];
  982.         // The rest of the metadata is only serialized if necessary.
  983.         if ($this->changeTrackingPolicy !== self::CHANGETRACKING_DEFERRED_IMPLICIT) {
  984.             $serialized[] = 'changeTrackingPolicy';
  985.         }
  987.         if ($this->customRepositoryClassName) {
  988.             $serialized[] = 'customRepositoryClassName';
  989.         }
  991.         if ($this->inheritanceType !== self::INHERITANCE_TYPE_NONE) {
  992.             $serialized[] = 'inheritanceType';
  993.             $serialized[] = 'discriminatorColumn';
  994.             $serialized[] = 'discriminatorValue';
  995.             $serialized[] = 'discriminatorMap';
  996.             $serialized[] = 'parentClasses';
  997.             $serialized[] = 'subClasses';
  998.         }
  1000.         if ($this->generatorType !== self::GENERATOR_TYPE_NONE) {
  1001.             $serialized[] = 'generatorType';
  1002.             if ($this->generatorType === self::GENERATOR_TYPE_SEQUENCE) {
  1003.                 $serialized[] = 'sequenceGeneratorDefinition';
  1004.             }
  1005.         }
  1007.         if ($this->isMappedSuperclass) {
  1008.             $serialized[] = 'isMappedSuperclass';
  1009.         }
  1011.         if ($this->isEmbeddedClass) {
  1012.             $serialized[] = 'isEmbeddedClass';
  1013.         }
  1015.         if ($this->containsForeignIdentifier) {
  1016.             $serialized[] = 'containsForeignIdentifier';
  1017.         }
  1019.         if ($this->containsEnumIdentifier) {
  1020.             $serialized[] = 'containsEnumIdentifier';
  1021.         }
  1023.         if ($this->isVersioned) {
  1024.             $serialized[] = 'isVersioned';
  1025.             $serialized[] = 'versionField';
  1026.         }
  1028.         if ($this->lifecycleCallbacks) {
  1029.             $serialized[] = 'lifecycleCallbacks';
  1030.         }
  1032.         if ($this->entityListeners) {
  1033.             $serialized[] = 'entityListeners';
  1034.         }
  1036.         if ($this->namedQueries) {
  1037.             $serialized[] = 'namedQueries';
  1038.         }
  1040.         if ($this->namedNativeQueries) {
  1041.             $serialized[] = 'namedNativeQueries';
  1042.         }
  1044.         if ($this->sqlResultSetMappings) {
  1045.             $serialized[] = 'sqlResultSetMappings';
  1046.         }
  1048.         if ($this->isReadOnly) {
  1049.             $serialized[] = 'isReadOnly';
  1050.         }
  1052.         if ($this->customGeneratorDefinition) {
  1053.             $serialized[] = 'customGeneratorDefinition';
  1054.         }
  1056.         if ($this->cache) {
  1057.             $serialized[] = 'cache';
  1058.         }
  1060.         if ($this->requiresFetchAfterChange) {
  1061.             $serialized[] = 'requiresFetchAfterChange';
  1062.         }
  1064.         return $serialized;
  1065.     }
  1067.     /**
  1068.      * Creates a new instance of the mapped class, without invoking the constructor.
  1069.      *
  1070.      * @return object
  1071.      */
  1072.     public function newInstance()
  1073.     {
  1074.         return $this->instantiator->instantiate($this->name);
  1075.     }
  1077.     /**
  1078.      * Restores some state that can not be serialized/unserialized.
  1079.      *
  1080.      * @param ReflectionService $reflService
  1081.      *
  1082.      * @return void
  1083.      */
  1084.     public function wakeupReflection($reflService)
  1085.     {
  1086.         // Restore ReflectionClass and properties
  1087.         $this->reflClass    = $reflService->getClass($this->name);
  1088.         $this->instantiator = $this->instantiator ?: new Instantiator();
  1090.         $parentReflFields = [];
  1092.         foreach ($this->embeddedClasses as $property => $embeddedClass) {
  1093.             if (isset($embeddedClass['declaredField'])) {
  1094.                 assert($embeddedClass['originalField'] !== null);
  1095.                 $childProperty = $this->getAccessibleProperty(
  1096.                     $reflService,
  1097.                     $this->embeddedClasses[$embeddedClass['declaredField']]['class'],
  1098.                     $embeddedClass['originalField']
  1099.                 );
  1100.                 assert($childProperty !== null);
  1101.                 $parentReflFields[$property] = new ReflectionEmbeddedProperty(
  1102.                     $parentReflFields[$embeddedClass['declaredField']],
  1103.                     $childProperty,
  1104.                     $this->embeddedClasses[$embeddedClass['declaredField']]['class']
  1105.                 );
  1107.                 continue;
  1108.             }
  1110.             $fieldRefl = $this->getAccessibleProperty(
  1111.                 $reflService,
  1112.                 $embeddedClass['declared'] ?? $this->name,
  1113.                 $property
  1114.             );
  1116.             $parentReflFields[$property] = $fieldRefl;
  1117.             $this->reflFields[$property] = $fieldRefl;
  1118.         }
  1120.         foreach ($this->fieldMappings as $field => $mapping) {
  1121.             if (isset($mapping['declaredField']) && isset($parentReflFields[$mapping['declaredField']])) {
  1122.                 $childProperty = $this->getAccessibleProperty($reflService, $mapping['originalClass'], $mapping['originalField']);
  1123.                 assert($childProperty !== null);
  1125.                 if (isset($mapping['enumType'])) {
  1126.                     $childProperty = new ReflectionEnumProperty(
  1127.                         $childProperty,
  1128.                         $mapping['enumType']
  1129.                     );
  1130.                 }
  1132.                 $this->reflFields[$field] = new ReflectionEmbeddedProperty(
  1133.                     $parentReflFields[$mapping['declaredField']],
  1134.                     $childProperty,
  1135.                     $mapping['originalClass']
  1136.                 );
  1137.                 continue;
  1138.             }
  1140.             $this->reflFields[$field] = isset($mapping['declared'])
  1141.                 ? $this->getAccessibleProperty($reflService, $mapping['declared'], $field)
  1142.                 : $this->getAccessibleProperty($reflService, $this->name, $field);
  1144.             if (isset($mapping['enumType']) && $this->reflFields[$field] !== null) {
  1145.                 $this->reflFields[$field] = new ReflectionEnumProperty(
  1146.                     $this->reflFields[$field],
  1147.                     $mapping['enumType']
  1148.                 );
  1149.             }
  1150.         }
  1152.         foreach ($this->associationMappings as $field => $mapping) {
  1153.             $this->reflFields[$field] = isset($mapping['declared'])
  1154.                 ? $this->getAccessibleProperty($reflService, $mapping['declared'], $field)
  1155.                 : $this->getAccessibleProperty($reflService, $this->name, $field);
  1156.         }
  1157.     }
  1159.     /**
  1160.      * Initializes a new ClassMetadata instance that will hold the object-relational mapping
  1161.      * metadata of the class with the given name.
  1162.      *
  1163.      * @param ReflectionService $reflService The reflection service.
  1164.      *
  1165.      * @return void
  1166.      */
  1167.     public function initializeReflection($reflService)
  1168.     {
  1169.         $this->reflClass = $reflService->getClass($this->name);
  1170.         $this->namespace = $reflService->getClassNamespace($this->name);
  1172.         if ($this->reflClass) {
  1173.             $this->name = $this->rootEntityName = $this->reflClass->name;
  1174.         }
  1176.         $this->table['name'] = $this->namingStrategy->classToTableName($this->name);
  1177.     }
  1179.     /**
  1180.      * Validates Identifier.
  1181.      *
  1182.      * @return void
  1183.      *
  1184.      * @throws MappingException
  1185.      */
  1186.     public function validateIdentifier()
  1187.     {
  1188.         if ($this->isMappedSuperclass || $this->isEmbeddedClass) {
  1189.             return;
  1190.         }
  1192.         // Verify & complete identifier mapping
  1193.         if (! $this->identifier) {
  1194.             throw MappingException::identifierRequired($this->name);
  1195.         }
  1197.         if ($this->usesIdGenerator() && $this->isIdentifierComposite) {
  1198.             throw MappingException::compositeKeyAssignedIdGeneratorRequired($this->name);
  1199.         }
  1200.     }
  1202.     /**
  1203.      * Validates association targets actually exist.
  1204.      *
  1205.      * @return void
  1206.      *
  1207.      * @throws MappingException
  1208.      */
  1209.     public function validateAssociations()
  1210.     {
  1211.         foreach ($this->associationMappings as $mapping) {
  1212.             if (
  1213.                 ! class_exists($mapping['targetEntity'])
  1214.                 && ! interface_exists($mapping['targetEntity'])
  1215.                 && ! trait_exists($mapping['targetEntity'])
  1216.             ) {
  1217.                 throw MappingException::invalidTargetEntityClass($mapping['targetEntity'], $this->name, $mapping['fieldName']);
  1218.             }
  1219.         }
  1220.     }
  1222.     /**
  1223.      * Validates lifecycle callbacks.
  1224.      *
  1225.      * @param ReflectionService $reflService
  1226.      *
  1227.      * @return void
  1228.      *
  1229.      * @throws MappingException
  1230.      */
  1231.     public function validateLifecycleCallbacks($reflService)
  1232.     {
  1233.         foreach ($this->lifecycleCallbacks as $callbacks) {
  1234.             foreach ($callbacks as $callbackFuncName) {
  1235.                 if (! $reflService->hasPublicMethod($this->name, $callbackFuncName)) {
  1236.                     throw MappingException::lifecycleCallbackMethodNotFound($this->name, $callbackFuncName);
  1237.                 }
  1238.             }
  1239.         }
  1240.     }
  1242.     /**
  1243.      * {@inheritDoc}
  1244.      */
  1245.     public function getReflectionClass()
  1246.     {
  1247.         return $this->reflClass;
  1248.     }
  1250.     /**
  1251.      * @psalm-param array{usage?: mixed, region?: mixed} $cache
  1252.      *
  1253.      * @return void
  1254.      */
  1255.     public function enableCache(array $cache)
  1256.     {
  1257.         if (! isset($cache['usage'])) {
  1258.             $cache['usage'] = self::CACHE_USAGE_READ_ONLY;
  1259.         }
  1261.         if (! isset($cache['region'])) {
  1262.             $cache['region'] = strtolower(str_replace('\\', '_', $this->rootEntityName));
  1263.         }
  1265.         $this->cache = $cache;
  1266.     }
  1268.     /**
  1269.      * @param string $fieldName
  1270.      * @psalm-param array{usage?: int, region?: string} $cache
  1271.      *
  1272.      * @return void
  1273.      */
  1274.     public function enableAssociationCache($fieldName, array $cache)
  1275.     {
  1276.         $this->associationMappings[$fieldName]['cache'] = $this->getAssociationCacheDefaults($fieldName, $cache);
  1277.     }
  1279.     /**
  1280.      * @param string $fieldName
  1281.      * @param array  $cache
  1282.      * @psalm-param array{usage?: int|null, region?: string|null} $cache
  1283.      *
  1284.      * @return int[]|string[]
  1285.      * @psalm-return array{usage: int, region: string|null}
  1286.      */
  1287.     public function getAssociationCacheDefaults($fieldName, array $cache)
  1288.     {
  1289.         if (! isset($cache['usage'])) {
  1290.             $cache['usage'] = $this->cache['usage'] ?? self::CACHE_USAGE_READ_ONLY;
  1291.         }
  1293.         if (! isset($cache['region'])) {
  1294.             $cache['region'] = strtolower(str_replace('\\', '_', $this->rootEntityName)) . '__' . $fieldName;
  1295.         }
  1297.         return $cache;
  1298.     }
  1300.     /**
  1301.      * Sets the change tracking policy used by this class.
  1302.      *
  1303.      * @param int $policy
  1304.      *
  1305.      * @return void
  1306.      */
  1307.     public function setChangeTrackingPolicy($policy)
  1308.     {
  1309.         $this->changeTrackingPolicy = $policy;
  1310.     }
  1312.     /**
  1313.      * Whether the change tracking policy of this class is "deferred explicit".
  1314.      *
  1315.      * @return bool
  1316.      */
  1317.     public function isChangeTrackingDeferredExplicit()
  1318.     {
  1319.         return $this->changeTrackingPolicy === self::CHANGETRACKING_DEFERRED_EXPLICIT;
  1320.     }
  1322.     /**
  1323.      * Whether the change tracking policy of this class is "deferred implicit".
  1324.      *
  1325.      * @return bool
  1326.      */
  1327.     public function isChangeTrackingDeferredImplicit()
  1328.     {
  1329.         return $this->changeTrackingPolicy === self::CHANGETRACKING_DEFERRED_IMPLICIT;
  1330.     }
  1332.     /**
  1333.      * Whether the change tracking policy of this class is "notify".
  1334.      *
  1335.      * @return bool
  1336.      */
  1337.     public function isChangeTrackingNotify()
  1338.     {
  1339.         return $this->changeTrackingPolicy === self::CHANGETRACKING_NOTIFY;
  1340.     }
  1342.     /**
  1343.      * Checks whether a field is part of the identifier/primary key field(s).
  1344.      *
  1345.      * @param string $fieldName The field name.
  1346.      *
  1347.      * @return bool TRUE if the field is part of the table identifier/primary key field(s),
  1348.      * FALSE otherwise.
  1349.      */
  1350.     public function isIdentifier($fieldName)
  1351.     {
  1352.         if (! $this->identifier) {
  1353.             return false;
  1354.         }
  1356.         if (! $this->isIdentifierComposite) {
  1357.             return $fieldName === $this->identifier[0];
  1358.         }
  1360.         return in_array($fieldName, $this->identifier, true);
  1361.     }
  1363.     /**
  1364.      * Checks if the field is unique.
  1365.      *
  1366.      * @param string $fieldName The field name.
  1367.      *
  1368.      * @return bool TRUE if the field is unique, FALSE otherwise.
  1369.      */
  1370.     public function isUniqueField($fieldName)
  1371.     {
  1372.         $mapping = $this->getFieldMapping($fieldName);
  1374.         return $mapping !== false && isset($mapping['unique']) && $mapping['unique'];
  1375.     }
  1377.     /**
  1378.      * Checks if the field is not null.
  1379.      *
  1380.      * @param string $fieldName The field name.
  1381.      *
  1382.      * @return bool TRUE if the field is not null, FALSE otherwise.
  1383.      */
  1384.     public function isNullable($fieldName)
  1385.     {
  1386.         $mapping = $this->getFieldMapping($fieldName);
  1388.         return $mapping !== false && isset($mapping['nullable']) && $mapping['nullable'];
  1389.     }
  1391.     /**
  1392.      * Gets a column name for a field name.
  1393.      * If the column name for the field cannot be found, the given field name
  1394.      * is returned.
  1395.      *
  1396.      * @param string $fieldName The field name.
  1397.      *
  1398.      * @return string The column name.
  1399.      */
  1400.     public function getColumnName($fieldName)
  1401.     {
  1402.         // @phpstan-ignore property.deprecated
  1403.         return $this->columnNames[$fieldName] ?? $fieldName;
  1404.     }
  1406.     /**
  1407.      * Gets the mapping of a (regular) field that holds some data but not a
  1408.      * reference to another object.
  1409.      *
  1410.      * @param string $fieldName The field name.
  1411.      *
  1412.      * @return mixed[] The field mapping.
  1413.      * @psalm-return FieldMapping
  1414.      *
  1415.      * @throws MappingException
  1416.      */
  1417.     public function getFieldMapping($fieldName)
  1418.     {
  1419.         if (! isset($this->fieldMappings[$fieldName])) {
  1420.             throw MappingException::mappingNotFound($this->name, $fieldName);
  1421.         }
  1423.         return $this->fieldMappings[$fieldName];
  1424.     }
  1426.     /**
  1427.      * Gets the mapping of an association.
  1428.      *
  1429.      * @see ClassMetadataInfo::$associationMappings
  1430.      *
  1431.      * @param string $fieldName The field name that represents the association in
  1432.      *                          the object model.
  1433.      *
  1434.      * @return mixed[] The mapping.
  1435.      * @psalm-return AssociationMapping
  1436.      *
  1437.      * @throws MappingException
  1438.      */
  1439.     public function getAssociationMapping($fieldName)
  1440.     {
  1441.         if (! isset($this->associationMappings[$fieldName])) {
  1442.             throw MappingException::mappingNotFound($this->name, $fieldName);
  1443.         }
  1445.         return $this->associationMappings[$fieldName];
  1446.     }
  1448.     /**
  1449.      * Gets all association mappings of the class.
  1450.      *
  1451.      * @psalm-return array<string, AssociationMapping>
  1452.      */
  1453.     public function getAssociationMappings()
  1454.     {
  1455.         return $this->associationMappings;
  1456.     }
  1458.     /**
  1459.      * Gets the field name for a column name.
  1460.      * If no field name can be found the column name is returned.
  1461.      *
  1462.      * @param string $columnName The column name.
  1463.      *
  1464.      * @return string The column alias.
  1465.      */
  1466.     public function getFieldName($columnName)
  1467.     {
  1468.         return $this->fieldNames[$columnName] ?? $columnName;
  1469.     }
  1471.     /**
  1472.      * Gets the named query.
  1473.      *
  1474.      * @see ClassMetadataInfo::$namedQueries
  1475.      *
  1476.      * @param string $queryName The query name.
  1477.      *
  1478.      * @return string
  1479.      *
  1480.      * @throws MappingException
  1481.      */
  1482.     public function getNamedQuery($queryName)
  1483.     {
  1484.         if (! isset($this->namedQueries[$queryName])) {
  1485.             throw MappingException::queryNotFound($this->name, $queryName);
  1486.         }
  1488.         return $this->namedQueries[$queryName]['dql'];
  1489.     }
  1491.     /**
  1492.      * Gets all named queries of the class.
  1493.      *
  1494.      * @return mixed[][]
  1495.      * @psalm-return array<string, array<string, mixed>>
  1496.      */
  1497.     public function getNamedQueries()
  1498.     {
  1499.         return $this->namedQueries;
  1500.     }
  1502.     /**
  1503.      * Gets the named native query.
  1504.      *
  1505.      * @see ClassMetadataInfo::$namedNativeQueries
  1506.      *
  1507.      * @param string $queryName The query name.
  1508.      *
  1509.      * @return mixed[]
  1510.      * @psalm-return array<string, mixed>
  1511.      *
  1512.      * @throws MappingException
  1513.      */
  1514.     public function getNamedNativeQuery($queryName)
  1515.     {
  1516.         if (! isset($this->namedNativeQueries[$queryName])) {
  1517.             throw MappingException::queryNotFound($this->name, $queryName);
  1518.         }
  1520.         return $this->namedNativeQueries[$queryName];
  1521.     }
  1523.     /**
  1524.      * Gets all named native queries of the class.
  1525.      *
  1526.      * @psalm-return array<string, array<string, mixed>>
  1527.      */
  1528.     public function getNamedNativeQueries()
  1529.     {
  1530.         return $this->namedNativeQueries;
  1531.     }
  1533.     /**
  1534.      * Gets the result set mapping.
  1535.      *
  1536.      * @see ClassMetadataInfo::$sqlResultSetMappings
  1537.      *
  1538.      * @param string $name The result set mapping name.
  1539.      *
  1540.      * @return mixed[]
  1541.      * @psalm-return array{name: string, entities: array, columns: array}
  1542.      *
  1543.      * @throws MappingException
  1544.      */
  1545.     public function getSqlResultSetMapping($name)
  1546.     {
  1547.         if (! isset($this->sqlResultSetMappings[$name])) {
  1548.             throw MappingException::resultMappingNotFound($this->name, $name);
  1549.         }
  1551.         return $this->sqlResultSetMappings[$name];
  1552.     }
  1554.     /**
  1555.      * Gets all sql result set mappings of the class.
  1556.      *
  1557.      * @return mixed[]
  1558.      * @psalm-return array<string, array{name: string, entities: array, columns: array}>
  1559.      */
  1560.     public function getSqlResultSetMappings()
  1561.     {
  1562.         return $this->sqlResultSetMappings;
  1563.     }
  1565.     /**
  1566.      * Checks whether given property has type
  1567.      *
  1568.      * @param string $name Property name
  1569.      */
  1570.     private function isTypedProperty(string $name): bool
  1571.     {
  1572.         return PHP_VERSION_ID >= 70400
  1573.                && isset($this->reflClass)
  1574.                && $this->reflClass->hasProperty($name)
  1575.                && $this->reflClass->getProperty($name)->hasType();
  1576.     }
  1578.     /**
  1579.      * Validates & completes the given field mapping based on typed property.
  1580.      *
  1581.      * @param  array{fieldName: string, type?: string} $mapping The field mapping to validate & complete.
  1582.      *
  1583.      * @return array{fieldName: string, enumType?: class-string<BackedEnum>, type?: string} The updated mapping.
  1584.      */
  1585.     private function validateAndCompleteTypedFieldMapping(array $mapping): array
  1586.     {
  1587.         $field = $this->reflClass->getProperty($mapping['fieldName']);
  1589.         $mapping = $this->typedFieldMapper->validateAndComplete($mapping, $field);
  1591.         return $mapping;
  1592.     }
  1594.     /**
  1595.      * Validates & completes the basic mapping information based on typed property.
  1596.      *
  1597.      * @param array{type: self::ONE_TO_ONE|self::MANY_TO_ONE|self::ONE_TO_MANY|self::MANY_TO_MANY, fieldName: string, targetEntity?: class-string} $mapping The mapping.
  1598.      *
  1599.      * @return mixed[] The updated mapping.
  1600.      */
  1601.     private function validateAndCompleteTypedAssociationMapping(array $mapping): array
  1602.     {
  1603.         $type = $this->reflClass->getProperty($mapping['fieldName'])->getType();
  1605.         if ($type === null || ($mapping['type'] & self::TO_ONE) === 0) {
  1606.             return $mapping;
  1607.         }
  1609.         if (! isset($mapping['targetEntity']) && $type instanceof ReflectionNamedType) {
  1610.             $mapping['targetEntity'] = $type->getName();
  1611.         }
  1613.         return $mapping;
  1614.     }
  1616.     /**
  1617.      * Validates & completes the given field mapping.
  1618.      *
  1619.      * @psalm-param array{
  1620.      *     fieldName?: string,
  1621.      *     columnName?: string,
  1622.      *     id?: bool,
  1623.      *     generated?: int,
  1624.      *     enumType?: class-string,
  1625.      * } $mapping The field mapping to validate & complete.
  1626.      *
  1627.      * @return FieldMapping The updated mapping.
  1628.      *
  1629.      * @throws MappingException
  1630.      */
  1631.     protected function validateAndCompleteFieldMapping(array $mapping): array
  1632.     {
  1633.         // Check mandatory fields
  1634.         if (! isset($mapping['fieldName']) || ! $mapping['fieldName']) {
  1635.             throw MappingException::missingFieldName($this->name);
  1636.         }
  1638.         if ($this->isTypedProperty($mapping['fieldName'])) {
  1639.             $mapping = $this->validateAndCompleteTypedFieldMapping($mapping);
  1640.         }
  1642.         if (! isset($mapping['type'])) {
  1643.             // Default to string
  1644.             $mapping['type'] = 'string';
  1645.         }
  1647.         // Complete fieldName and columnName mapping
  1648.         if (! isset($mapping['columnName'])) {
  1649.             $mapping['columnName'] = $this->namingStrategy->propertyToColumnName($mapping['fieldName'], $this->name);
  1650.         }
  1652.         if ($mapping['columnName'][0] === '`') {
  1653.             $mapping['columnName'] = trim($mapping['columnName'], '`');
  1654.             $mapping['quoted']     = true;
  1655.         }
  1657.         // @phpstan-ignore property.deprecated
  1658.         $this->columnNames[$mapping['fieldName']] = $mapping['columnName'];
  1660.         if (isset($this->fieldNames[$mapping['columnName']]) || ($this->discriminatorColumn && $this->discriminatorColumn['name'] === $mapping['columnName'])) {
  1661.             throw MappingException::duplicateColumnName($this->name, $mapping['columnName']);
  1662.         }
  1664.         $this->fieldNames[$mapping['columnName']] = $mapping['fieldName'];
  1666.         // Complete id mapping
  1667.         if (isset($mapping['id']) && $mapping['id'] === true) {
  1668.             if ($this->versionField === $mapping['fieldName']) {
  1669.                 throw MappingException::cannotVersionIdField($this->name, $mapping['fieldName']);
  1670.             }
  1672.             if (! in_array($mapping['fieldName'], $this->identifier, true)) {
  1673.                 $this->identifier[] = $mapping['fieldName'];
  1674.             }
  1676.             // Check for composite key
  1677.             if (! $this->isIdentifierComposite && count($this->identifier) > 1) {
  1678.                 $this->isIdentifierComposite = true;
  1679.             }
  1680.         }
  1682.         // @phpstan-ignore method.deprecated
  1683.         if (Type::hasType($mapping['type']) && Type::getType($mapping['type'])->canRequireSQLConversion()) {
  1684.             if (isset($mapping['id']) && $mapping['id'] === true) {
  1685.                  throw MappingException::sqlConversionNotAllowedForIdentifiers($this->name, $mapping['fieldName'], $mapping['type']);
  1686.             }
  1688.             $mapping['requireSQLConversion'] = true;
  1689.         }
  1691.         if (isset($mapping['generated'])) {
  1692.             if (! in_array($mapping['generated'], [self::GENERATED_NEVER, self::GENERATED_INSERT, self::GENERATED_ALWAYS])) {
  1693.                 throw MappingException::invalidGeneratedMode($mapping['generated']);
  1694.             }
  1696.             if ($mapping['generated'] === self::GENERATED_NEVER) {
  1697.                 unset($mapping['generated']);
  1698.             }
  1699.         }
  1701.         if (isset($mapping['enumType'])) {
  1702.             if (PHP_VERSION_ID < 80100) {
  1703.                 throw MappingException::enumsRequirePhp81($this->name, $mapping['fieldName']);
  1704.             }
  1706.             if (! enum_exists($mapping['enumType'])) {
  1707.                 throw MappingException::nonEnumTypeMapped($this->name, $mapping['fieldName'], $mapping['enumType']);
  1708.             }
  1710.             if (! empty($mapping['id'])) {
  1711.                 $this->containsEnumIdentifier = true;
  1712.             }
  1713.         }
  1715.         return $mapping;
  1716.     }
  1718.     /**
  1719.      * Validates & completes the basic mapping information that is common to all
  1720.      * association mappings (one-to-one, many-ot-one, one-to-many, many-to-many).
  1721.      *
  1722.      * @psalm-param array<string, mixed> $mapping The mapping.
  1723.      *
  1724.      * @return mixed[] The updated mapping.
  1725.      * @psalm-return AssociationMapping
  1726.      *
  1727.      * @throws MappingException If something is wrong with the mapping.
  1728.      */
  1729.     protected function _validateAndCompleteAssociationMapping(array $mapping)
  1730.     {
  1731.         if (! isset($mapping['mappedBy'])) {
  1732.             $mapping['mappedBy'] = null;
  1733.         }
  1735.         if (! isset($mapping['inversedBy'])) {
  1736.             $mapping['inversedBy'] = null;
  1737.         }
  1739.         $mapping['isOwningSide'] = true; // assume owning side until we hit mappedBy
  1741.         if (empty($mapping['indexBy'])) {
  1742.             unset($mapping['indexBy']);
  1743.         }
  1745.         // If targetEntity is unqualified, assume it is in the same namespace as
  1746.         // the sourceEntity.
  1747.         $mapping['sourceEntity'] = $this->name;
  1749.         if ($this->isTypedProperty($mapping['fieldName'])) {
  1750.             $mapping = $this->validateAndCompleteTypedAssociationMapping($mapping);
  1751.         }
  1753.         if (isset($mapping['targetEntity'])) {
  1754.             $mapping['targetEntity'] = $this->fullyQualifiedClassName($mapping['targetEntity']);
  1755.             $mapping['targetEntity'] = ltrim($mapping['targetEntity'], '\\');
  1756.         }
  1758.         if (($mapping['type'] & self::MANY_TO_ONE) > 0 && isset($mapping['orphanRemoval']) && $mapping['orphanRemoval']) {
  1759.             throw MappingException::illegalOrphanRemoval($this->name, $mapping['fieldName']);
  1760.         }
  1762.         // Complete id mapping
  1763.         if (isset($mapping['id']) && $mapping['id'] === true) {
  1764.             if (isset($mapping['orphanRemoval']) && $mapping['orphanRemoval']) {
  1765.                 throw MappingException::illegalOrphanRemovalOnIdentifierAssociation($this->name, $mapping['fieldName']);
  1766.             }
  1768.             if (! in_array($mapping['fieldName'], $this->identifier, true)) {
  1769.                 if (isset($mapping['joinColumns']) && count($mapping['joinColumns']) >= 2) {
  1770.                     throw MappingException::cannotMapCompositePrimaryKeyEntitiesAsForeignId(
  1771.                         $mapping['targetEntity'],
  1772.                         $this->name,
  1773.                         $mapping['fieldName']
  1774.                     );
  1775.                 }
  1777.                 $this->identifier[]              = $mapping['fieldName'];
  1778.                 $this->containsForeignIdentifier = true;
  1779.             }
  1781.             // Check for composite key
  1782.             if (! $this->isIdentifierComposite && count($this->identifier) > 1) {
  1783.                 $this->isIdentifierComposite = true;
  1784.             }
  1786.             if ($this->cache && ! isset($mapping['cache'])) {
  1787.                 throw NonCacheableEntityAssociation::fromEntityAndField(
  1788.                     $this->name,
  1789.                     $mapping['fieldName']
  1790.                 );
  1791.             }
  1792.         }
  1794.         // Mandatory attributes for both sides
  1795.         // Mandatory: fieldName, targetEntity
  1796.         if (! isset($mapping['fieldName']) || ! $mapping['fieldName']) {
  1797.             throw MappingException::missingFieldName($this->name);
  1798.         }
  1800.         if (! isset($mapping['targetEntity'])) {
  1801.             throw MappingException::missingTargetEntity($mapping['fieldName']);
  1802.         }
  1804.         // Mandatory and optional attributes for either side
  1805.         if (! $mapping['mappedBy']) {
  1806.             if (isset($mapping['joinTable']) && $mapping['joinTable']) {
  1807.                 if (isset($mapping['joinTable']['name']) && $mapping['joinTable']['name'][0] === '`') {
  1808.                     $mapping['joinTable']['name']   = trim($mapping['joinTable']['name'], '`');
  1809.                     $mapping['joinTable']['quoted'] = true;
  1810.                 }
  1811.             }
  1812.         } else {
  1813.             $mapping['isOwningSide'] = false;
  1814.         }
  1816.         if (isset($mapping['id']) && $mapping['id'] === true && $mapping['type'] & self::TO_MANY) {
  1817.             throw MappingException::illegalToManyIdentifierAssociation($this->name, $mapping['fieldName']);
  1818.         }
  1820.         // Fetch mode. Default fetch mode to LAZY, if not set.
  1821.         if (! isset($mapping['fetch'])) {
  1822.             $mapping['fetch'] = self::FETCH_LAZY;
  1823.         }
  1825.         // Cascades
  1826.         $cascades = isset($mapping['cascade']) ? array_map('strtolower', $mapping['cascade']) : [];
  1828.         $allCascades = ['remove', 'persist', 'refresh', 'merge', 'detach'];
  1829.         if (in_array('all', $cascades, true)) {
  1830.             $cascades = $allCascades;
  1831.         } elseif (count($cascades) !== count(array_intersect($cascades, $allCascades))) {
  1832.             throw MappingException::invalidCascadeOption(
  1833.                 array_diff($cascades, $allCascades),
  1834.                 $this->name,
  1835.                 $mapping['fieldName']
  1836.             );
  1837.         }
  1839.         $mapping['cascade']          = $cascades;
  1840.         $mapping['isCascadeRemove']  = in_array('remove', $cascades, true);
  1841.         $mapping['isCascadePersist'] = in_array('persist', $cascades, true);
  1842.         $mapping['isCascadeRefresh'] = in_array('refresh', $cascades, true);
  1843.         $mapping['isCascadeMerge']   = in_array('merge', $cascades, true);
  1844.         $mapping['isCascadeDetach']  = in_array('detach', $cascades, true);
  1846.         return $mapping;
  1847.     }
  1849.     /**
  1850.      * Validates & completes a one-to-one association mapping.
  1851.      *
  1852.      * @psalm-param array<string, mixed> $mapping The mapping to validate & complete.
  1853.      *
  1854.      * @return mixed[] The validated & completed mapping.
  1855.      * @psalm-return AssociationMapping
  1856.      *
  1857.      * @throws RuntimeException
  1858.      * @throws MappingException
  1859.      */
  1860.     protected function _validateAndCompleteOneToOneMapping(array $mapping)
  1861.     {
  1862.         $mapping = $this->_validateAndCompleteAssociationMapping($mapping);
  1864.         if (isset($mapping['joinColumns']) && $mapping['joinColumns'] && ! $mapping['isOwningSide']) {
  1865.             Deprecation::trigger(
  1866.                 'doctrine/orm',
  1867.                 'https://github.com/doctrine/orm/pull/10654',
  1868.                 'JoinColumn configuration is not allowed on the inverse side of one-to-one associations, and will throw a MappingException in Doctrine ORM 3.0'
  1869.             );
  1870.         }
  1872.         if (isset($mapping['joinColumns']) && $mapping['joinColumns']) {
  1873.             $mapping['isOwningSide'] = true;
  1874.         }
  1876.         if ($mapping['isOwningSide']) {
  1877.             if (empty($mapping['joinColumns'])) {
  1878.                 // Apply default join column
  1879.                 $mapping['joinColumns'] = [
  1880.                     [
  1881.                         'name' => $this->namingStrategy->joinColumnName($mapping['fieldName'], $this->name),
  1882.                         'referencedColumnName' => $this->namingStrategy->referenceColumnName(),
  1883.                     ],
  1884.                 ];
  1885.             }
  1887.             $uniqueConstraintColumns = [];
  1889.             foreach ($mapping['joinColumns'] as &$joinColumn) {
  1890.                 if ($mapping['type'] === self::ONE_TO_ONE && ! $this->isInheritanceTypeSingleTable()) {
  1891.                     if (count($mapping['joinColumns']) === 1) {
  1892.                         if (empty($mapping['id'])) {
  1893.                             $joinColumn['unique'] = true;
  1894.                         }
  1895.                     } else {
  1896.                         $uniqueConstraintColumns[] = $joinColumn['name'];
  1897.                     }
  1898.                 }
  1900.                 if (empty($joinColumn['name'])) {
  1901.                     $joinColumn['name'] = $this->namingStrategy->joinColumnName($mapping['fieldName'], $this->name);
  1902.                 }
  1904.                 if (empty($joinColumn['referencedColumnName'])) {
  1905.                     $joinColumn['referencedColumnName'] = $this->namingStrategy->referenceColumnName();
  1906.                 }
  1908.                 if ($joinColumn['name'][0] === '`') {
  1909.                     $joinColumn['name']   = trim($joinColumn['name'], '`');
  1910.                     $joinColumn['quoted'] = true;
  1911.                 }
  1913.                 if ($joinColumn['referencedColumnName'][0] === '`') {
  1914.                     $joinColumn['referencedColumnName'] = trim($joinColumn['referencedColumnName'], '`');
  1915.                     $joinColumn['quoted']               = true;
  1916.                 }
  1918.                 $mapping['sourceToTargetKeyColumns'][$joinColumn['name']] = $joinColumn['referencedColumnName'];
  1919.                 $mapping['joinColumnFieldNames'][$joinColumn['name']]     = $joinColumn['fieldName'] ?? $joinColumn['name'];
  1920.             }
  1922.             if ($uniqueConstraintColumns) {
  1923.                 if (! $this->table) {
  1924.                     throw new RuntimeException('ClassMetadataInfo::setTable() has to be called before defining a one to one relationship.');
  1925.                 }
  1927.                 $this->table['uniqueConstraints'][$mapping['fieldName'] . '_uniq'] = ['columns' => $uniqueConstraintColumns];
  1928.             }
  1930.             $mapping['targetToSourceKeyColumns'] = array_flip($mapping['sourceToTargetKeyColumns']);
  1931.         }
  1933.         $mapping['orphanRemoval']   = isset($mapping['orphanRemoval']) && $mapping['orphanRemoval'];
  1934.         $mapping['isCascadeRemove'] = $mapping['orphanRemoval'] || $mapping['isCascadeRemove'];
  1936.         if ($mapping['orphanRemoval']) {
  1937.             unset($mapping['unique']);
  1938.         }
  1940.         if (isset($mapping['id']) && $mapping['id'] === true && ! $mapping['isOwningSide']) {
  1941.             throw MappingException::illegalInverseIdentifierAssociation($this->name, $mapping['fieldName']);
  1942.         }
  1944.         return $mapping;
  1945.     }
  1947.     /**
  1948.      * Validates & completes a one-to-many association mapping.
  1949.      *
  1950.      * @psalm-param array<string, mixed> $mapping The mapping to validate and complete.
  1951.      *
  1952.      * @return mixed[] The validated and completed mapping.
  1953.      * @psalm-return AssociationMapping
  1954.      *
  1955.      * @throws MappingException
  1956.      * @throws InvalidArgumentException
  1957.      */
  1958.     protected function _validateAndCompleteOneToManyMapping(array $mapping)
  1959.     {
  1960.         $mapping = $this->_validateAndCompleteAssociationMapping($mapping);
  1962.         // OneToMany-side MUST be inverse (must have mappedBy)
  1963.         if (! isset($mapping['mappedBy'])) {
  1964.             throw MappingException::oneToManyRequiresMappedBy($this->name, $mapping['fieldName']);
  1965.         }
  1967.         $mapping['orphanRemoval']   = isset($mapping['orphanRemoval']) && $mapping['orphanRemoval'];
  1968.         $mapping['isCascadeRemove'] = $mapping['orphanRemoval'] || $mapping['isCascadeRemove'];
  1970.         $this->assertMappingOrderBy($mapping);
  1972.         return $mapping;
  1973.     }
  1975.     /**
  1976.      * Validates & completes a many-to-many association mapping.
  1977.      *
  1978.      * @psalm-param array<string, mixed> $mapping The mapping to validate & complete.
  1979.      *
  1980.      * @return mixed[] The validated & completed mapping.
  1981.      * @psalm-return AssociationMapping
  1982.      *
  1983.      * @throws InvalidArgumentException
  1984.      */
  1985.     protected function _validateAndCompleteManyToManyMapping(array $mapping)
  1986.     {
  1987.         $mapping = $this->_validateAndCompleteAssociationMapping($mapping);
  1989.         if ($mapping['isOwningSide']) {
  1990.             // owning side MUST have a join table
  1991.             if (! isset($mapping['joinTable']['name'])) {
  1992.                 $mapping['joinTable']['name'] = $this->namingStrategy->joinTableName($mapping['sourceEntity'], $mapping['targetEntity'], $mapping['fieldName']);
  1993.             }
  1995.             $selfReferencingEntityWithoutJoinColumns = $mapping['sourceEntity'] === $mapping['targetEntity']
  1996.                 && (! (isset($mapping['joinTable']['joinColumns']) || isset($mapping['joinTable']['inverseJoinColumns'])));
  1998.             if (! isset($mapping['joinTable']['joinColumns'])) {
  1999.                 $mapping['joinTable']['joinColumns'] = [
  2000.                     [
  2001.                         'name' => $this->namingStrategy->joinKeyColumnName($mapping['sourceEntity'], $selfReferencingEntityWithoutJoinColumns ? 'source' : null),
  2002.                         'referencedColumnName' => $this->namingStrategy->referenceColumnName(),
  2003.                         'onDelete' => 'CASCADE',
  2004.                     ],
  2005.                 ];
  2006.             }
  2008.             if (! isset($mapping['joinTable']['inverseJoinColumns'])) {
  2009.                 $mapping['joinTable']['inverseJoinColumns'] = [
  2010.                     [
  2011.                         'name' => $this->namingStrategy->joinKeyColumnName($mapping['targetEntity'], $selfReferencingEntityWithoutJoinColumns ? 'target' : null),
  2012.                         'referencedColumnName' => $this->namingStrategy->referenceColumnName(),
  2013.                         'onDelete' => 'CASCADE',
  2014.                     ],
  2015.                 ];
  2016.             }
  2018.             $mapping['joinTableColumns'] = [];
  2020.             foreach ($mapping['joinTable']['joinColumns'] as &$joinColumn) {
  2021.                 if (empty($joinColumn['name'])) {
  2022.                     $joinColumn['name'] = $this->namingStrategy->joinKeyColumnName($mapping['sourceEntity'], $joinColumn['referencedColumnName']);
  2023.                 }
  2025.                 if (empty($joinColumn['referencedColumnName'])) {
  2026.                     $joinColumn['referencedColumnName'] = $this->namingStrategy->referenceColumnName();
  2027.                 }
  2029.                 if ($joinColumn['name'][0] === '`') {
  2030.                     $joinColumn['name']   = trim($joinColumn['name'], '`');
  2031.                     $joinColumn['quoted'] = true;
  2032.                 }
  2034.                 if ($joinColumn['referencedColumnName'][0] === '`') {
  2035.                     $joinColumn['referencedColumnName'] = trim($joinColumn['referencedColumnName'], '`');
  2036.                     $joinColumn['quoted']               = true;
  2037.                 }
  2039.                 if (isset($joinColumn['onDelete']) && strtolower($joinColumn['onDelete']) === 'cascade') {
  2040.                     $mapping['isOnDeleteCascade'] = true;
  2041.                 }
  2043.                 $mapping['relationToSourceKeyColumns'][$joinColumn['name']] = $joinColumn['referencedColumnName'];
  2044.                 $mapping['joinTableColumns'][]                              = $joinColumn['name'];
  2045.             }
  2047.             foreach ($mapping['joinTable']['inverseJoinColumns'] as &$inverseJoinColumn) {
  2048.                 if (empty($inverseJoinColumn['name'])) {
  2049.                     $inverseJoinColumn['name'] = $this->namingStrategy->joinKeyColumnName($mapping['targetEntity'], $inverseJoinColumn['referencedColumnName']);
  2050.                 }
  2052.                 if (empty($inverseJoinColumn['referencedColumnName'])) {
  2053.                     $inverseJoinColumn['referencedColumnName'] = $this->namingStrategy->referenceColumnName();
  2054.                 }
  2056.                 if ($inverseJoinColumn['name'][0] === '`') {
  2057.                     $inverseJoinColumn['name']   = trim($inverseJoinColumn['name'], '`');
  2058.                     $inverseJoinColumn['quoted'] = true;
  2059.                 }
  2061.                 if ($inverseJoinColumn['referencedColumnName'][0] === '`') {
  2062.                     $inverseJoinColumn['referencedColumnName'] = trim($inverseJoinColumn['referencedColumnName'], '`');
  2063.                     $inverseJoinColumn['quoted']               = true;
  2064.                 }
  2066.                 if (isset($inverseJoinColumn['onDelete']) && strtolower($inverseJoinColumn['onDelete']) === 'cascade') {
  2067.                     $mapping['isOnDeleteCascade'] = true;
  2068.                 }
  2070.                 $mapping['relationToTargetKeyColumns'][$inverseJoinColumn['name']] = $inverseJoinColumn['referencedColumnName'];
  2071.                 $mapping['joinTableColumns'][]                                     = $inverseJoinColumn['name'];
  2072.             }
  2073.         }
  2075.         $mapping['orphanRemoval'] = isset($mapping['orphanRemoval']) && $mapping['orphanRemoval'];
  2077.         $this->assertMappingOrderBy($mapping);
  2079.         return $mapping;
  2080.     }
  2082.     /**
  2083.      * {@inheritDoc}
  2084.      */
  2085.     public function getIdentifierFieldNames()
  2086.     {
  2087.         return $this->identifier;
  2088.     }
  2090.     /**
  2091.      * Gets the name of the single id field. Note that this only works on
  2092.      * entity classes that have a single-field pk.
  2093.      *
  2094.      * @return string
  2095.      *
  2096.      * @throws MappingException If the class doesn't have an identifier or it has a composite primary key.
  2097.      */
  2098.     public function getSingleIdentifierFieldName()
  2099.     {
  2100.         if ($this->isIdentifierComposite) {
  2101.             throw MappingException::singleIdNotAllowedOnCompositePrimaryKey($this->name);
  2102.         }
  2104.         if (! isset($this->identifier[0])) {
  2105.             throw MappingException::noIdDefined($this->name);
  2106.         }
  2108.         return $this->identifier[0];
  2109.     }
  2111.     /**
  2112.      * Gets the column name of the single id column. Note that this only works on
  2113.      * entity classes that have a single-field pk.
  2114.      *
  2115.      * @return string
  2116.      *
  2117.      * @throws MappingException If the class doesn't have an identifier or it has a composite primary key.
  2118.      */
  2119.     public function getSingleIdentifierColumnName()
  2120.     {
  2121.         return $this->getColumnName($this->getSingleIdentifierFieldName());
  2122.     }
  2124.     /**
  2125.      * INTERNAL:
  2126.      * Sets the mapped identifier/primary key fields of this class.
  2127.      * Mainly used by the ClassMetadataFactory to assign inherited identifiers.
  2128.      *
  2129.      * @psalm-param list<mixed> $identifier
  2130.      *
  2131.      * @return void
  2132.      */
  2133.     public function setIdentifier(array $identifier)
  2134.     {
  2135.         $this->identifier            = $identifier;
  2136.         $this->isIdentifierComposite = (count($this->identifier) > 1);
  2137.     }
  2139.     /**
  2140.      * {@inheritDoc}
  2141.      */
  2142.     public function getIdentifier()
  2143.     {
  2144.         return $this->identifier;
  2145.     }
  2147.     /**
  2148.      * {@inheritDoc}
  2149.      */
  2150.     public function hasField($fieldName)
  2151.     {
  2152.         return isset($this->fieldMappings[$fieldName]) || isset($this->embeddedClasses[$fieldName]);
  2153.     }
  2155.     /**
  2156.      * Gets an array containing all the column names.
  2157.      *
  2158.      * @psalm-param list<string>|null $fieldNames
  2159.      *
  2160.      * @return mixed[]
  2161.      * @psalm-return list<string>
  2162.      */
  2163.     public function getColumnNames(?array $fieldNames = null)
  2164.     {
  2165.         if ($fieldNames === null) {
  2166.             return array_keys($this->fieldNames);
  2167.         }
  2169.         return array_values(array_map([$this, 'getColumnName'], $fieldNames));
  2170.     }
  2172.     /**
  2173.      * Returns an array with all the identifier column names.
  2174.      *
  2175.      * @psalm-return list<string>
  2176.      */
  2177.     public function getIdentifierColumnNames()
  2178.     {
  2179.         $columnNames = [];
  2181.         foreach ($this->identifier as $idProperty) {
  2182.             if (isset($this->fieldMappings[$idProperty])) {
  2183.                 $columnNames[] = $this->fieldMappings[$idProperty]['columnName'];
  2185.                 continue;
  2186.             }
  2188.             // Association defined as Id field
  2189.             $joinColumns      = $this->associationMappings[$idProperty]['joinColumns'];
  2190.             $assocColumnNames = array_map(static function ($joinColumn) {
  2191.                 return $joinColumn['name'];
  2192.             }, $joinColumns);
  2194.             $columnNames = array_merge($columnNames, $assocColumnNames);
  2195.         }
  2197.         return $columnNames;
  2198.     }
  2200.     /**
  2201.      * Sets the type of Id generator to use for the mapped class.
  2202.      *
  2203.      * @param int $generatorType
  2204.      * @psalm-param self::GENERATOR_TYPE_* $generatorType
  2205.      *
  2206.      * @return void
  2207.      */
  2208.     public function setIdGeneratorType($generatorType)
  2209.     {
  2210.         $this->generatorType = $generatorType;
  2211.     }
  2213.     /**
  2214.      * Checks whether the mapped class uses an Id generator.
  2215.      *
  2216.      * @return bool TRUE if the mapped class uses an Id generator, FALSE otherwise.
  2217.      */
  2218.     public function usesIdGenerator()
  2219.     {
  2220.         return $this->generatorType !== self::GENERATOR_TYPE_NONE;
  2221.     }
  2223.     /** @return bool */
  2224.     public function isInheritanceTypeNone()
  2225.     {
  2226.         return $this->inheritanceType === self::INHERITANCE_TYPE_NONE;
  2227.     }
  2229.     /**
  2230.      * Checks whether the mapped class uses the JOINED inheritance mapping strategy.
  2231.      *
  2232.      * @return bool TRUE if the class participates in a JOINED inheritance mapping,
  2233.      * FALSE otherwise.
  2234.      */
  2235.     public function isInheritanceTypeJoined()
  2236.     {
  2237.         return $this->inheritanceType === self::INHERITANCE_TYPE_JOINED;
  2238.     }
  2240.     /**
  2241.      * Checks whether the mapped class uses the SINGLE_TABLE inheritance mapping strategy.
  2242.      *
  2243.      * @return bool TRUE if the class participates in a SINGLE_TABLE inheritance mapping,
  2244.      * FALSE otherwise.
  2245.      */
  2246.     public function isInheritanceTypeSingleTable()
  2247.     {
  2248.         return $this->inheritanceType === self::INHERITANCE_TYPE_SINGLE_TABLE;
  2249.     }
  2251.     /**
  2252.      * Checks whether the mapped class uses the TABLE_PER_CLASS inheritance mapping strategy.
  2253.      *
  2254.      * @deprecated
  2255.      *
  2256.      * @return bool TRUE if the class participates in a TABLE_PER_CLASS inheritance mapping,
  2257.      * FALSE otherwise.
  2258.      */
  2259.     public function isInheritanceTypeTablePerClass()
  2260.     {
  2261.         Deprecation::triggerIfCalledFromOutside(
  2262.             'doctrine/orm',
  2263.             'https://github.com/doctrine/orm/pull/10414/',
  2264.             'Concrete table inheritance has never been implemented, and its stubs will be removed in Doctrine ORM 3.0 with no replacement'
  2265.         );
  2267.         return $this->inheritanceType === self::INHERITANCE_TYPE_TABLE_PER_CLASS;
  2268.     }
  2270.     /**
  2271.      * Checks whether the class uses an identity column for the Id generation.
  2272.      *
  2273.      * @return bool TRUE if the class uses the IDENTITY generator, FALSE otherwise.
  2274.      */
  2275.     public function isIdGeneratorIdentity()
  2276.     {
  2277.         return $this->generatorType === self::GENERATOR_TYPE_IDENTITY;
  2278.     }
  2280.     /**
  2281.      * Checks whether the class uses a sequence for id generation.
  2282.      *
  2283.      * @return bool TRUE if the class uses the SEQUENCE generator, FALSE otherwise.
  2284.      *
  2285.      * @psalm-assert-if-true !null $this->sequenceGeneratorDefinition
  2286.      */
  2287.     public function isIdGeneratorSequence()
  2288.     {
  2289.         return $this->generatorType === self::GENERATOR_TYPE_SEQUENCE;
  2290.     }
  2292.     /**
  2293.      * Checks whether the class uses a table for id generation.
  2294.      *
  2295.      * @deprecated
  2296.      *
  2297.      * @return false
  2298.      */
  2299.     public function isIdGeneratorTable()
  2300.     {
  2301.         Deprecation::trigger(
  2302.             'doctrine/orm',
  2303.             'https://github.com/doctrine/orm/pull/9046',
  2304.             '%s is deprecated',
  2305.             __METHOD__
  2306.         );
  2308.         return false;
  2309.     }
  2311.     /**
  2312.      * Checks whether the class has a natural identifier/pk (which means it does
  2313.      * not use any Id generator.
  2314.      *
  2315.      * @return bool
  2316.      */
  2317.     public function isIdentifierNatural()
  2318.     {
  2319.         return $this->generatorType === self::GENERATOR_TYPE_NONE;
  2320.     }
  2322.     /**
  2323.      * Checks whether the class use a UUID for id generation.
  2324.      *
  2325.      * @deprecated
  2326.      *
  2327.      * @return bool
  2328.      */
  2329.     public function isIdentifierUuid()
  2330.     {
  2331.         Deprecation::trigger(
  2332.             'doctrine/orm',
  2333.             'https://github.com/doctrine/orm/pull/9046',
  2334.             '%s is deprecated',
  2335.             __METHOD__
  2336.         );
  2338.         return $this->generatorType === self::GENERATOR_TYPE_UUID;
  2339.     }
  2341.     /**
  2342.      * Gets the type of a field.
  2343.      *
  2344.      * @param string $fieldName
  2345.      *
  2346.      * @return string|null
  2347.      *
  2348.      * @todo 3.0 Remove this. PersisterHelper should fix it somehow
  2349.      */
  2350.     public function getTypeOfField($fieldName)
  2351.     {
  2352.         return isset($this->fieldMappings[$fieldName])
  2353.             ? $this->fieldMappings[$fieldName]['type']
  2354.             : null;
  2355.     }
  2357.     /**
  2358.      * Gets the type of a column.
  2359.      *
  2360.      * @deprecated 3.0 remove this. this method is bogus and unreliable, since it cannot resolve the type of a column
  2361.      *             that is derived by a referenced field on a different entity.
  2362.      *
  2363.      * @param string $columnName
  2364.      *
  2365.      * @return string|null
  2366.      */
  2367.     public function getTypeOfColumn($columnName)
  2368.     {
  2369.         return $this->getTypeOfField($this->getFieldName($columnName));
  2370.     }
  2372.     /**
  2373.      * Gets the name of the primary table.
  2374.      *
  2375.      * @return string
  2376.      */
  2377.     public function getTableName()
  2378.     {
  2379.         return $this->table['name'];
  2380.     }
  2382.     /**
  2383.      * Gets primary table's schema name.
  2384.      *
  2385.      * @return string|null
  2386.      */
  2387.     public function getSchemaName()
  2388.     {
  2389.         return $this->table['schema'] ?? null;
  2390.     }
  2392.     /**
  2393.      * Gets the table name to use for temporary identifier tables of this class.
  2394.      *
  2395.      * @return string
  2396.      */
  2397.     public function getTemporaryIdTableName()
  2398.     {
  2399.         // replace dots with underscores because PostgreSQL creates temporary tables in a special schema
  2400.         return str_replace('.', '_', $this->getTableName() . '_id_tmp');
  2401.     }
  2403.     /**
  2404.      * Sets the mapped subclasses of this class.
  2405.      *
  2406.      * @psalm-param list<string> $subclasses The names of all mapped subclasses.
  2407.      *
  2408.      * @return void
  2409.      */
  2410.     public function setSubclasses(array $subclasses)
  2411.     {
  2412.         foreach ($subclasses as $subclass) {
  2413.             $this->subClasses[] = $this->fullyQualifiedClassName($subclass);
  2414.         }
  2415.     }
  2417.     /**
  2418.      * Sets the parent class names. Only <em>entity</em> classes may be given.
  2419.      *
  2420.      * Assumes that the class names in the passed array are in the order:
  2421.      * directParent -> directParentParent -> directParentParentParent ... -> root.
  2422.      *
  2423.      * @param list<class-string> $classNames
  2424.      *
  2425.      * @return void
  2426.      */
  2427.     public function setParentClasses(array $classNames)
  2428.     {
  2429.         $this->parentClasses = $classNames;
  2431.         if (count($classNames) > 0) {
  2432.             $this->rootEntityName = array_pop($classNames);
  2433.         }
  2434.     }
  2436.     /**
  2437.      * Sets the inheritance type used by the class and its subclasses.
  2438.      *
  2439.      * @param int $type
  2440.      * @psalm-param self::INHERITANCE_TYPE_* $type
  2441.      *
  2442.      * @return void
  2443.      *
  2444.      * @throws MappingException
  2445.      */
  2446.     public function setInheritanceType($type)
  2447.     {
  2448.         if (! $this->isInheritanceType($type)) {
  2449.             throw MappingException::invalidInheritanceType($this->name, $type);
  2450.         }
  2452.         $this->inheritanceType = $type;
  2453.     }
  2455.     /**
  2456.      * Sets the association to override association mapping of property for an entity relationship.
  2457.      *
  2458.      * @param string $fieldName
  2459.      * @psalm-param array<string, mixed> $overrideMapping
  2460.      *
  2461.      * @return void
  2462.      *
  2463.      * @throws MappingException
  2464.      */
  2465.     public function setAssociationOverride($fieldName, array $overrideMapping)
  2466.     {
  2467.         if (! isset($this->associationMappings[$fieldName])) {
  2468.             throw MappingException::invalidOverrideFieldName($this->name, $fieldName);
  2469.         }
  2471.         $mapping = $this->associationMappings[$fieldName];
  2473.         if (isset($mapping['inherited'])) {
  2474.             Deprecation::trigger(
  2475.                 'doctrine/orm',
  2476.                 'https://github.com/doctrine/orm/pull/10470',
  2477.                 'Overrides are only allowed for fields or associations declared in mapped superclasses or traits. This is not the case for %s::%s, which was inherited from %s. This is a misconfiguration and will be an error in Doctrine ORM 3.0.',
  2478.                 $this->name,
  2479.                 $fieldName,
  2480.                 $mapping['inherited']
  2481.             );
  2482.         }
  2484.         if (isset($overrideMapping['joinColumns'])) {
  2485.             $mapping['joinColumns'] = $overrideMapping['joinColumns'];
  2486.         }
  2488.         if (isset($overrideMapping['inversedBy'])) {
  2489.             $mapping['inversedBy'] = $overrideMapping['inversedBy'];
  2490.         }
  2492.         if (isset($overrideMapping['joinTable'])) {
  2493.             $mapping['joinTable'] = $overrideMapping['joinTable'];
  2494.         }
  2496.         if (isset($overrideMapping['fetch'])) {
  2497.             $mapping['fetch'] = $overrideMapping['fetch'];
  2498.         }
  2500.         $mapping['joinColumnFieldNames']       = null;
  2501.         $mapping['joinTableColumns']           = null;
  2502.         $mapping['sourceToTargetKeyColumns']   = null;
  2503.         $mapping['relationToSourceKeyColumns'] = null;
  2504.         $mapping['relationToTargetKeyColumns'] = null;
  2506.         switch ($mapping['type']) {
  2507.             case self::ONE_TO_ONE:
  2508.                 $mapping = $this->_validateAndCompleteOneToOneMapping($mapping);
  2509.                 break;
  2510.             case self::ONE_TO_MANY:
  2511.                 $mapping = $this->_validateAndCompleteOneToManyMapping($mapping);
  2512.                 break;
  2513.             case self::MANY_TO_ONE:
  2514.                 $mapping = $this->_validateAndCompleteOneToOneMapping($mapping);
  2515.                 break;
  2516.             case self::MANY_TO_MANY:
  2517.                 $mapping = $this->_validateAndCompleteManyToManyMapping($mapping);
  2518.                 break;
  2519.         }
  2521.         $this->associationMappings[$fieldName] = $mapping;
  2522.     }
  2524.     /**
  2525.      * Sets the override for a mapped field.
  2526.      *
  2527.      * @param string $fieldName
  2528.      * @psalm-param array<string, mixed> $overrideMapping
  2529.      *
  2530.      * @return void
  2531.      *
  2532.      * @throws MappingException
  2533.      */
  2534.     public function setAttributeOverride($fieldName, array $overrideMapping)
  2535.     {
  2536.         if (! isset($this->fieldMappings[$fieldName])) {
  2537.             throw MappingException::invalidOverrideFieldName($this->name, $fieldName);
  2538.         }
  2540.         $mapping = $this->fieldMappings[$fieldName];
  2542.         if (isset($mapping['inherited'])) {
  2543.             Deprecation::trigger(
  2544.                 'doctrine/orm',
  2545.                 'https://github.com/doctrine/orm/pull/10470',
  2546.                 'Overrides are only allowed for fields or associations declared in mapped superclasses or traits. This is not the case for %s::%s, which was inherited from %s. This is a misconfiguration and will be an error in Doctrine ORM 3.0.',
  2547.                 $this->name,
  2548.                 $fieldName,
  2549.                 $mapping['inherited']
  2550.             );
  2551.             //throw MappingException::illegalOverrideOfInheritedProperty($this->name, $fieldName);
  2552.         }
  2554.         if (isset($mapping['id'])) {
  2555.             $overrideMapping['id'] = $mapping['id'];
  2556.         }
  2558.         if (isset($mapping['declared'])) {
  2559.             $overrideMapping['declared'] = $mapping['declared'];
  2560.         }
  2562.         if (! isset($overrideMapping['type'])) {
  2563.             $overrideMapping['type'] = $mapping['type'];
  2564.         }
  2566.         if (! isset($overrideMapping['fieldName'])) {
  2567.             $overrideMapping['fieldName'] = $mapping['fieldName'];
  2568.         }
  2570.         if ($overrideMapping['type'] !== $mapping['type']) {
  2571.             throw MappingException::invalidOverrideFieldType($this->name, $fieldName);
  2572.         }
  2574.         unset($this->fieldMappings[$fieldName]);
  2575.         unset($this->fieldNames[$mapping['columnName']]);
  2576.         // @phpstan-ignore property.deprecated
  2577.         unset($this->columnNames[$mapping['fieldName']]);
  2579.         $overrideMapping = $this->validateAndCompleteFieldMapping($overrideMapping);
  2581.         $this->fieldMappings[$fieldName] = $overrideMapping;
  2582.     }
  2584.     /**
  2585.      * Checks whether a mapped field is inherited from an entity superclass.
  2586.      *
  2587.      * @param string $fieldName
  2588.      *
  2589.      * @return bool TRUE if the field is inherited, FALSE otherwise.
  2590.      */
  2591.     public function isInheritedField($fieldName)
  2592.     {
  2593.         return isset($this->fieldMappings[$fieldName]['inherited']);
  2594.     }
  2596.     /**
  2597.      * Checks if this entity is the root in any entity-inheritance-hierarchy.
  2598.      *
  2599.      * @return bool
  2600.      */
  2601.     public function isRootEntity()
  2602.     {
  2603.         return $this->name === $this->rootEntityName;
  2604.     }
  2606.     /**
  2607.      * Checks whether a mapped association field is inherited from a superclass.
  2608.      *
  2609.      * @param string $fieldName
  2610.      *
  2611.      * @return bool TRUE if the field is inherited, FALSE otherwise.
  2612.      */
  2613.     public function isInheritedAssociation($fieldName)
  2614.     {
  2615.         return isset($this->associationMappings[$fieldName]['inherited']);
  2616.     }
  2618.     /**
  2619.      * @param string $fieldName
  2620.      *
  2621.      * @return bool
  2622.      */
  2623.     public function isInheritedEmbeddedClass($fieldName)
  2624.     {
  2625.         return isset($this->embeddedClasses[$fieldName]['inherited']);
  2626.     }
  2628.     /**
  2629.      * Sets the name of the primary table the class is mapped to.
  2630.      *
  2631.      * @deprecated Use {@link setPrimaryTable}.
  2632.      *
  2633.      * @param string $tableName The table name.
  2634.      *
  2635.      * @return void
  2636.      */
  2637.     public function setTableName($tableName)
  2638.     {
  2639.         $this->table['name'] = $tableName;
  2640.     }
  2642.     /**
  2643.      * Sets the primary table definition. The provided array supports the
  2644.      * following structure:
  2645.      *
  2646.      * name => <tableName> (optional, defaults to class name)
  2647.      * indexes => array of indexes (optional)
  2648.      * uniqueConstraints => array of constraints (optional)
  2649.      *
  2650.      * If a key is omitted, the current value is kept.
  2651.      *
  2652.      * @psalm-param array<string, mixed> $table The table description.
  2653.      *
  2654.      * @return void
  2655.      */
  2656.     public function setPrimaryTable(array $table)
  2657.     {
  2658.         if (isset($table['name'])) {
  2659.             // Split schema and table name from a table name like "myschema.mytable"
  2660.             if (str_contains($table['name'], '.')) {
  2661.                 [$this->table['schema'], $table['name']] = explode('.', $table['name'], 2);
  2662.             }
  2664.             if ($table['name'][0] === '`') {
  2665.                 $table['name']         = trim($table['name'], '`');
  2666.                 $this->table['quoted'] = true;
  2667.             }
  2669.             $this->table['name'] = $table['name'];
  2670.         }
  2672.         if (isset($table['quoted'])) {
  2673.             $this->table['quoted'] = $table['quoted'];
  2674.         }
  2676.         if (isset($table['schema'])) {
  2677.             $this->table['schema'] = $table['schema'];
  2678.         }
  2680.         if (isset($table['indexes'])) {
  2681.             $this->table['indexes'] = $table['indexes'];
  2682.         }
  2684.         if (isset($table['uniqueConstraints'])) {
  2685.             $this->table['uniqueConstraints'] = $table['uniqueConstraints'];
  2686.         }
  2688.         if (isset($table['options'])) {
  2689.             $this->table['options'] = $table['options'];
  2690.         }
  2691.     }
  2693.     /**
  2694.      * Checks whether the given type identifies an inheritance type.
  2695.      *
  2696.      * @return bool TRUE if the given type identifies an inheritance type, FALSE otherwise.
  2697.      */
  2698.     private function isInheritanceType(int $type): bool
  2699.     {
  2700.         // @phpstan-ignore classConstant.deprecated
  2701.         if ($type === self::INHERITANCE_TYPE_TABLE_PER_CLASS) {
  2702.             Deprecation::trigger(
  2703.                 'doctrine/orm',
  2704.                 'https://github.com/doctrine/orm/pull/10414/',
  2705.                 'Concrete table inheritance has never been implemented, and its stubs will be removed in Doctrine ORM 3.0 with no replacement'
  2706.             );
  2707.         }
  2709.         return $type === self::INHERITANCE_TYPE_NONE ||
  2710.                 $type === self::INHERITANCE_TYPE_SINGLE_TABLE ||
  2711.                 $type === self::INHERITANCE_TYPE_JOINED ||
  2712.                 // @phpstan-ignore classConstant.deprecated
  2713.                 $type === self::INHERITANCE_TYPE_TABLE_PER_CLASS;
  2714.     }
  2716.     /**
  2717.      * Adds a mapped field to the class.
  2718.      *
  2719.      * @psalm-param array<string, mixed> $mapping The field mapping.
  2720.      *
  2721.      * @return void
  2722.      *
  2723.      * @throws MappingException
  2724.      */
  2725.     public function mapField(array $mapping)
  2726.     {
  2727.         $mapping = $this->validateAndCompleteFieldMapping($mapping);
  2728.         $this->assertFieldNotMapped($mapping['fieldName']);
  2730.         if (isset($mapping['generated'])) {
  2731.             $this->requiresFetchAfterChange = true;
  2732.         }
  2734.         $this->fieldMappings[$mapping['fieldName']] = $mapping;
  2735.     }
  2737.     /**
  2738.      * INTERNAL:
  2739.      * Adds an association mapping without completing/validating it.
  2740.      * This is mainly used to add inherited association mappings to derived classes.
  2741.      *
  2742.      * @psalm-param AssociationMapping $mapping
  2743.      *
  2744.      * @return void
  2745.      *
  2746.      * @throws MappingException
  2747.      */
  2748.     public function addInheritedAssociationMapping(array $mapping/*, $owningClassName = null*/)
  2749.     {
  2750.         if (isset($this->associationMappings[$mapping['fieldName']])) {
  2751.             throw MappingException::duplicateAssociationMapping($this->name, $mapping['fieldName']);
  2752.         }
  2754.         $this->associationMappings[$mapping['fieldName']] = $mapping;
  2755.     }
  2757.     /**
  2758.      * INTERNAL:
  2759.      * Adds a field mapping without completing/validating it.
  2760.      * This is mainly used to add inherited field mappings to derived classes.
  2761.      *
  2762.      * @psalm-param FieldMapping $fieldMapping
  2763.      *
  2764.      * @return void
  2765.      */
  2766.     public function addInheritedFieldMapping(array $fieldMapping)
  2767.     {
  2768.         $this->fieldMappings[$fieldMapping['fieldName']] = $fieldMapping;
  2769.         // @phpstan-ignore property.deprecated
  2770.         $this->columnNames[$fieldMapping['fieldName']] = $fieldMapping['columnName'];
  2771.         $this->fieldNames[$fieldMapping['columnName']] = $fieldMapping['fieldName'];
  2773.         if (isset($fieldMapping['generated'])) {
  2774.             $this->requiresFetchAfterChange = true;
  2775.         }
  2776.     }
  2778.     /**
  2779.      * INTERNAL:
  2780.      * Adds a named query to this class.
  2781.      *
  2782.      * @deprecated
  2783.      *
  2784.      * @psalm-param array<string, mixed> $queryMapping
  2785.      *
  2786.      * @return void
  2787.      *
  2788.      * @throws MappingException
  2789.      */
  2790.     public function addNamedQuery(array $queryMapping)
  2791.     {
  2792.         if (! isset($queryMapping['name'])) {
  2793.             throw MappingException::nameIsMandatoryForQueryMapping($this->name);
  2794.         }
  2796.         Deprecation::trigger(
  2797.             'doctrine/orm',
  2798.             'https://github.com/doctrine/orm/issues/8592',
  2799.             'Named Queries are deprecated, here "%s" on entity %s. Move the query logic into EntityRepository',
  2800.             $queryMapping['name'],
  2801.             $this->name
  2802.         );
  2804.         if (isset($this->namedQueries[$queryMapping['name']])) {
  2805.             throw MappingException::duplicateQueryMapping($this->name, $queryMapping['name']);
  2806.         }
  2808.         if (! isset($queryMapping['query'])) {
  2809.             throw MappingException::emptyQueryMapping($this->name, $queryMapping['name']);
  2810.         }
  2812.         $name  = $queryMapping['name'];
  2813.         $query = $queryMapping['query'];
  2814.         $dql   = str_replace('__CLASS__', $this->name, $query);
  2816.         $this->namedQueries[$name] = [
  2817.             'name'  => $name,
  2818.             'query' => $query,
  2819.             'dql'   => $dql,
  2820.         ];
  2821.     }
  2823.     /**
  2824.      * INTERNAL:
  2825.      * Adds a named native query to this class.
  2826.      *
  2827.      * @deprecated
  2828.      *
  2829.      * @psalm-param array<string, mixed> $queryMapping
  2830.      *
  2831.      * @return void
  2832.      *
  2833.      * @throws MappingException
  2834.      */
  2835.     public function addNamedNativeQuery(array $queryMapping)
  2836.     {
  2837.         if (! isset($queryMapping['name'])) {
  2838.             throw MappingException::nameIsMandatoryForQueryMapping($this->name);
  2839.         }
  2841.         Deprecation::trigger(
  2842.             'doctrine/orm',
  2843.             'https://github.com/doctrine/orm/issues/8592',
  2844.             'Named Native Queries are deprecated, here "%s" on entity %s. Move the query logic into EntityRepository',
  2845.             $queryMapping['name'],
  2846.             $this->name
  2847.         );
  2849.         if (isset($this->namedNativeQueries[$queryMapping['name']])) {
  2850.             throw MappingException::duplicateQueryMapping($this->name, $queryMapping['name']);
  2851.         }
  2853.         if (! isset($queryMapping['query'])) {
  2854.             throw MappingException::emptyQueryMapping($this->name, $queryMapping['name']);
  2855.         }
  2857.         if (! isset($queryMapping['resultClass']) && ! isset($queryMapping['resultSetMapping'])) {
  2858.             throw MappingException::missingQueryMapping($this->name, $queryMapping['name']);
  2859.         }
  2861.         $queryMapping['isSelfClass'] = false;
  2863.         if (isset($queryMapping['resultClass'])) {
  2864.             if ($queryMapping['resultClass'] === '__CLASS__') {
  2865.                 $queryMapping['isSelfClass'] = true;
  2866.                 $queryMapping['resultClass'] = $this->name;
  2867.             }
  2869.             $queryMapping['resultClass'] = $this->fullyQualifiedClassName($queryMapping['resultClass']);
  2870.             $queryMapping['resultClass'] = ltrim($queryMapping['resultClass'], '\\');
  2871.         }
  2873.         $this->namedNativeQueries[$queryMapping['name']] = $queryMapping;
  2874.     }
  2876.     /**
  2877.      * INTERNAL:
  2878.      * Adds a sql result set mapping to this class.
  2879.      *
  2880.      * @psalm-param array<string, mixed> $resultMapping
  2881.      *
  2882.      * @return void
  2883.      *
  2884.      * @throws MappingException
  2885.      */
  2886.     public function addSqlResultSetMapping(array $resultMapping)
  2887.     {
  2888.         if (! isset($resultMapping['name'])) {
  2889.             throw MappingException::nameIsMandatoryForSqlResultSetMapping($this->name);
  2890.         }
  2892.         if (isset($this->sqlResultSetMappings[$resultMapping['name']])) {
  2893.             throw MappingException::duplicateResultSetMapping($this->name, $resultMapping['name']);
  2894.         }
  2896.         if (isset($resultMapping['entities'])) {
  2897.             foreach ($resultMapping['entities'] as $key => $entityResult) {
  2898.                 if (! isset($entityResult['entityClass'])) {
  2899.                     throw MappingException::missingResultSetMappingEntity($this->name, $resultMapping['name']);
  2900.                 }
  2902.                 $entityResult['isSelfClass'] = false;
  2903.                 if ($entityResult['entityClass'] === '__CLASS__') {
  2904.                     $entityResult['isSelfClass'] = true;
  2905.                     $entityResult['entityClass'] = $this->name;
  2906.                 }
  2908.                 $entityResult['entityClass'] = $this->fullyQualifiedClassName($entityResult['entityClass']);
  2910.                 $resultMapping['entities'][$key]['entityClass'] = ltrim($entityResult['entityClass'], '\\');
  2911.                 $resultMapping['entities'][$key]['isSelfClass'] = $entityResult['isSelfClass'];
  2913.                 if (isset($entityResult['fields'])) {
  2914.                     foreach ($entityResult['fields'] as $k => $field) {
  2915.                         if (! isset($field['name'])) {
  2916.                             throw MappingException::missingResultSetMappingFieldName($this->name, $resultMapping['name']);
  2917.                         }
  2919.                         if (! isset($field['column'])) {
  2920.                             $fieldName = $field['name'];
  2921.                             if (str_contains($fieldName, '.')) {
  2922.                                 [, $fieldName] = explode('.', $fieldName);
  2923.                             }
  2925.                             $resultMapping['entities'][$key]['fields'][$k]['column'] = $fieldName;
  2926.                         }
  2927.                     }
  2928.                 }
  2929.             }
  2930.         }
  2932.         $this->sqlResultSetMappings[$resultMapping['name']] = $resultMapping;
  2933.     }
  2935.     /**
  2936.      * Adds a one-to-one mapping.
  2937.      *
  2938.      * @param array<string, mixed> $mapping The mapping.
  2939.      *
  2940.      * @return void
  2941.      */
  2942.     public function mapOneToOne(array $mapping)
  2943.     {
  2944.         $mapping['type'] = self::ONE_TO_ONE;
  2946.         $mapping = $this->_validateAndCompleteOneToOneMapping($mapping);
  2948.         $this->_storeAssociationMapping($mapping);
  2949.     }
  2951.     /**
  2952.      * Adds a one-to-many mapping.
  2953.      *
  2954.      * @psalm-param array<string, mixed> $mapping The mapping.
  2955.      *
  2956.      * @return void
  2957.      */
  2958.     public function mapOneToMany(array $mapping)
  2959.     {
  2960.         $mapping['type'] = self::ONE_TO_MANY;
  2962.         $mapping = $this->_validateAndCompleteOneToManyMapping($mapping);
  2964.         $this->_storeAssociationMapping($mapping);
  2965.     }
  2967.     /**
  2968.      * Adds a many-to-one mapping.
  2969.      *
  2970.      * @psalm-param array<string, mixed> $mapping The mapping.
  2971.      *
  2972.      * @return void
  2973.      */
  2974.     public function mapManyToOne(array $mapping)
  2975.     {
  2976.         $mapping['type'] = self::MANY_TO_ONE;
  2978.         // A many-to-one mapping is essentially a one-one backreference
  2979.         $mapping = $this->_validateAndCompleteOneToOneMapping($mapping);
  2981.         $this->_storeAssociationMapping($mapping);
  2982.     }
  2984.     /**
  2985.      * Adds a many-to-many mapping.
  2986.      *
  2987.      * @psalm-param array<string, mixed> $mapping The mapping.
  2988.      *
  2989.      * @return void
  2990.      */
  2991.     public function mapManyToMany(array $mapping)
  2992.     {
  2993.         $mapping['type'] = self::MANY_TO_MANY;
  2995.         $mapping = $this->_validateAndCompleteManyToManyMapping($mapping);
  2997.         $this->_storeAssociationMapping($mapping);
  2998.     }
  3000.     /**
  3001.      * Stores the association mapping.
  3002.      *
  3003.      * @psalm-param AssociationMapping $assocMapping
  3004.      *
  3005.      * @return void
  3006.      *
  3007.      * @throws MappingException
  3008.      */
  3009.     protected function _storeAssociationMapping(array $assocMapping)
  3010.     {
  3011.         $sourceFieldName = $assocMapping['fieldName'];
  3013.         $this->assertFieldNotMapped($sourceFieldName);
  3015.         $this->associationMappings[$sourceFieldName] = $assocMapping;
  3016.     }
  3018.     /**
  3019.      * Registers a custom repository class for the entity class.
  3020.      *
  3021.      * @param class-string<EntityRepository>|null $repositoryClassName The class name of the custom mapper.
  3022.      *
  3023.      * @return void
  3024.      */
  3025.     public function setCustomRepositoryClass($repositoryClassName)
  3026.     {
  3027.         $this->customRepositoryClassName = $this->fullyQualifiedClassName($repositoryClassName);
  3028.     }
  3030.     /**
  3031.      * Dispatches the lifecycle event of the given entity to the registered
  3032.      * lifecycle callbacks and lifecycle listeners.
  3033.      *
  3034.      * @deprecated Deprecated since version 2.4 in favor of \Doctrine\ORM\Event\ListenersInvoker
  3035.      *
  3036.      * @param string $lifecycleEvent The lifecycle event.
  3037.      * @param object $entity         The Entity on which the event occurred.
  3038.      *
  3039.      * @return void
  3040.      */
  3041.     public function invokeLifecycleCallbacks($lifecycleEvent, $entity)
  3042.     {
  3043.         foreach ($this->lifecycleCallbacks[$lifecycleEvent] as $callback) {
  3044.             $entity->$callback();
  3045.         }
  3046.     }
  3048.     /**
  3049.      * Whether the class has any attached lifecycle listeners or callbacks for a lifecycle event.
  3050.      *
  3051.      * @param string $lifecycleEvent
  3052.      *
  3053.      * @return bool
  3054.      */
  3055.     public function hasLifecycleCallbacks($lifecycleEvent)
  3056.     {
  3057.         return isset($this->lifecycleCallbacks[$lifecycleEvent]);
  3058.     }
  3060.     /**
  3061.      * Gets the registered lifecycle callbacks for an event.
  3062.      *
  3063.      * @param string $event
  3064.      *
  3065.      * @return string[]
  3066.      * @psalm-return list<string>
  3067.      */
  3068.     public function getLifecycleCallbacks($event)
  3069.     {
  3070.         return $this->lifecycleCallbacks[$event] ?? [];
  3071.     }
  3073.     /**
  3074.      * Adds a lifecycle callback for entities of this class.
  3075.      *
  3076.      * @param string $callback
  3077.      * @param string $event
  3078.      *
  3079.      * @return void
  3080.      */
  3081.     public function addLifecycleCallback($callback, $event)
  3082.     {
  3083.         if ($this->isEmbeddedClass) {
  3084.             Deprecation::trigger(
  3085.                 'doctrine/orm',
  3086.                 'https://github.com/doctrine/orm/pull/8381',
  3087.                 'Registering lifecycle callback %s on Embedded class %s is not doing anything and will throw exception in 3.0',
  3088.                 $event,
  3089.                 $this->name
  3090.             );
  3091.         }
  3093.         if (isset($this->lifecycleCallbacks[$event]) && in_array($callback, $this->lifecycleCallbacks[$event], true)) {
  3094.             return;
  3095.         }
  3097.         $this->lifecycleCallbacks[$event][] = $callback;
  3098.     }
  3100.     /**
  3101.      * Sets the lifecycle callbacks for entities of this class.
  3102.      * Any previously registered callbacks are overwritten.
  3103.      *
  3104.      * @psalm-param array<string, list<string>> $callbacks
  3105.      *
  3106.      * @return void
  3107.      */
  3108.     public function setLifecycleCallbacks(array $callbacks)
  3109.     {
  3110.         $this->lifecycleCallbacks = $callbacks;
  3111.     }
  3113.     /**
  3114.      * Adds a entity listener for entities of this class.
  3115.      *
  3116.      * @param string $eventName The entity lifecycle event.
  3117.      * @param string $class     The listener class.
  3118.      * @param string $method    The listener callback method.
  3119.      *
  3120.      * @return void
  3121.      *
  3122.      * @throws MappingException
  3123.      */
  3124.     public function addEntityListener($eventName, $class, $method)
  3125.     {
  3126.         $class = $this->fullyQualifiedClassName($class);
  3128.         $listener = [
  3129.             'class'  => $class,
  3130.             'method' => $method,
  3131.         ];
  3133.         if (! class_exists($class)) {
  3134.             throw MappingException::entityListenerClassNotFound($class, $this->name);
  3135.         }
  3137.         if (! method_exists($class, $method)) {
  3138.             throw MappingException::entityListenerMethodNotFound($class, $method, $this->name);
  3139.         }
  3141.         if (isset($this->entityListeners[$eventName]) && in_array($listener, $this->entityListeners[$eventName], true)) {
  3142.             throw MappingException::duplicateEntityListener($class, $method, $this->name);
  3143.         }
  3145.         $this->entityListeners[$eventName][] = $listener;
  3146.     }
  3148.     /**
  3149.      * Sets the discriminator column definition.
  3150.      *
  3151.      * @see getDiscriminatorColumn()
  3152.      *
  3153.      * @param mixed[]|null $columnDef
  3154.      * @psalm-param array{name: string|null, fieldName?: string, type?: string, length?: int, columnDefinition?: string|null, enumType?: class-string<BackedEnum>|null, options?: array<string, mixed>}|null $columnDef
  3155.      *
  3156.      * @return void
  3157.      *
  3158.      * @throws MappingException
  3159.      */
  3160.     public function setDiscriminatorColumn($columnDef)
  3161.     {
  3162.         if ($columnDef !== null) {
  3163.             if (! isset($columnDef['name'])) {
  3164.                 throw MappingException::nameIsMandatoryForDiscriminatorColumns($this->name);
  3165.             }
  3167.             if (isset($this->fieldNames[$columnDef['name']])) {
  3168.                 throw MappingException::duplicateColumnName($this->name, $columnDef['name']);
  3169.             }
  3171.             if (! isset($columnDef['fieldName'])) {
  3172.                 $columnDef['fieldName'] = $columnDef['name'];
  3173.             }
  3175.             if (! isset($columnDef['type'])) {
  3176.                 $columnDef['type'] = 'string';
  3177.             }
  3179.             if (in_array($columnDef['type'], ['boolean', 'array', 'object', 'datetime', 'time', 'date'], true)) {
  3180.                 throw MappingException::invalidDiscriminatorColumnType($this->name, $columnDef['type']);
  3181.             }
  3183.             $this->discriminatorColumn = $columnDef;
  3184.         }
  3185.     }
  3187.     /**
  3188.      * @return array<string, mixed>
  3189.      * @psalm-return DiscriminatorColumnMapping
  3190.      */
  3191.     final public function getDiscriminatorColumn(): array
  3192.     {
  3193.         if ($this->discriminatorColumn === null) {
  3194.             throw new LogicException('The discriminator column was not set.');
  3195.         }
  3197.         return $this->discriminatorColumn;
  3198.     }
  3200.     /**
  3201.      * Sets the discriminator values used by this class.
  3202.      * Used for JOINED and SINGLE_TABLE inheritance mapping strategies.
  3203.      *
  3204.      * @param array<int|string, string> $map
  3205.      *
  3206.      * @return void
  3207.      */
  3208.     public function setDiscriminatorMap(array $map)
  3209.     {
  3210.         foreach ($map as $value => $className) {
  3211.             $this->addDiscriminatorMapClass($value, $className);
  3212.         }
  3213.     }
  3215.     /**
  3216.      * Adds one entry of the discriminator map with a new class and corresponding name.
  3217.      *
  3218.      * @param int|string $name
  3219.      * @param string     $className
  3220.      *
  3221.      * @return void
  3222.      *
  3223.      * @throws MappingException
  3224.      */
  3225.     public function addDiscriminatorMapClass($name, $className)
  3226.     {
  3227.         $className = $this->fullyQualifiedClassName($className);
  3228.         $className = ltrim($className, '\\');
  3230.         $this->discriminatorMap[$name] = $className;
  3232.         if ($this->name === $className) {
  3233.             $this->discriminatorValue = $name;
  3235.             return;
  3236.         }
  3238.         if (! (class_exists($className) || interface_exists($className))) {
  3239.             throw MappingException::invalidClassInDiscriminatorMap($className, $this->name);
  3240.         }
  3242.         $this->addSubClass($className);
  3243.     }
  3245.     /** @param array<class-string> $classes */
  3246.     public function addSubClasses(array $classes): void
  3247.     {
  3248.         foreach ($classes as $className) {
  3249.             $this->addSubClass($className);
  3250.         }
  3251.     }
  3253.     public function addSubClass(string $className): void
  3254.     {
  3255.         // By ignoring classes that are not subclasses of the current class, we simplify inheriting
  3256.         // the subclass list from a parent class at the beginning of \Doctrine\ORM\Mapping\ClassMetadataFactory::doLoadMetadata.
  3257.         if (is_subclass_of($className, $this->name) && ! in_array($className, $this->subClasses, true)) {
  3258.             $this->subClasses[] = $className;
  3259.         }
  3260.     }
  3262.     /**
  3263.      * Checks whether the class has a named query with the given query name.
  3264.      *
  3265.      * @param string $queryName
  3266.      *
  3267.      * @return bool
  3268.      */
  3269.     public function hasNamedQuery($queryName)
  3270.     {
  3271.         return isset($this->namedQueries[$queryName]);
  3272.     }
  3274.     /**
  3275.      * Checks whether the class has a named native query with the given query name.
  3276.      *
  3277.      * @param string $queryName
  3278.      *
  3279.      * @return bool
  3280.      */
  3281.     public function hasNamedNativeQuery($queryName)
  3282.     {
  3283.         return isset($this->namedNativeQueries[$queryName]);
  3284.     }
  3286.     /**
  3287.      * Checks whether the class has a named native query with the given query name.
  3288.      *
  3289.      * @param string $name
  3290.      *
  3291.      * @return bool
  3292.      */
  3293.     public function hasSqlResultSetMapping($name)
  3294.     {
  3295.         return isset($this->sqlResultSetMappings[$name]);
  3296.     }
  3298.     /**
  3299.      * {@inheritDoc}
  3300.      */
  3301.     public function hasAssociation($fieldName)
  3302.     {
  3303.         return isset($this->associationMappings[$fieldName]);
  3304.     }
  3306.     /**
  3307.      * {@inheritDoc}
  3308.      */
  3309.     public function isSingleValuedAssociation($fieldName)
  3310.     {
  3311.         return isset($this->associationMappings[$fieldName])
  3312.             && ($this->associationMappings[$fieldName]['type'] & self::TO_ONE);
  3313.     }
  3315.     /**
  3316.      * {@inheritDoc}
  3317.      */
  3318.     public function isCollectionValuedAssociation($fieldName)
  3319.     {
  3320.         return isset($this->associationMappings[$fieldName])
  3321.             && ! ($this->associationMappings[$fieldName]['type'] & self::TO_ONE);
  3322.     }
  3324.     /**
  3325.      * Is this an association that only has a single join column?
  3326.      *
  3327.      * @param string $fieldName
  3328.      *
  3329.      * @return bool
  3330.      */
  3331.     public function isAssociationWithSingleJoinColumn($fieldName)
  3332.     {
  3333.         return isset($this->associationMappings[$fieldName])
  3334.             && isset($this->associationMappings[$fieldName]['joinColumns'][0])
  3335.             && ! isset($this->associationMappings[$fieldName]['joinColumns'][1]);
  3336.     }
  3338.     /**
  3339.      * Returns the single association join column (if any).
  3340.      *
  3341.      * @param string $fieldName
  3342.      *
  3343.      * @return string
  3344.      *
  3345.      * @throws MappingException
  3346.      */
  3347.     public function getSingleAssociationJoinColumnName($fieldName)
  3348.     {
  3349.         if (! $this->isAssociationWithSingleJoinColumn($fieldName)) {
  3350.             throw MappingException::noSingleAssociationJoinColumnFound($this->name, $fieldName);
  3351.         }
  3353.         return $this->associationMappings[$fieldName]['joinColumns'][0]['name'];
  3354.     }
  3356.     /**
  3357.      * Returns the single association referenced join column name (if any).
  3358.      *
  3359.      * @param string $fieldName
  3360.      *
  3361.      * @return string
  3362.      *
  3363.      * @throws MappingException
  3364.      */
  3365.     public function getSingleAssociationReferencedJoinColumnName($fieldName)
  3366.     {
  3367.         if (! $this->isAssociationWithSingleJoinColumn($fieldName)) {
  3368.             throw MappingException::noSingleAssociationJoinColumnFound($this->name, $fieldName);
  3369.         }
  3371.         return $this->associationMappings[$fieldName]['joinColumns'][0]['referencedColumnName'];
  3372.     }
  3374.     /**
  3375.      * Used to retrieve a fieldname for either field or association from a given column.
  3376.      *
  3377.      * This method is used in foreign-key as primary-key contexts.
  3378.      *
  3379.      * @param string $columnName
  3380.      *
  3381.      * @return string
  3382.      *
  3383.      * @throws MappingException
  3384.      */
  3385.     public function getFieldForColumn($columnName)
  3386.     {
  3387.         if (isset($this->fieldNames[$columnName])) {
  3388.             return $this->fieldNames[$columnName];
  3389.         }
  3391.         foreach ($this->associationMappings as $assocName => $mapping) {
  3392.             if (
  3393.                 $this->isAssociationWithSingleJoinColumn($assocName) &&
  3394.                 $this->associationMappings[$assocName]['joinColumns'][0]['name'] === $columnName
  3395.             ) {
  3396.                 return $assocName;
  3397.             }
  3398.         }
  3400.         throw MappingException::noFieldNameFoundForColumn($this->name, $columnName);
  3401.     }
  3403.     /**
  3404.      * Sets the ID generator used to generate IDs for instances of this class.
  3405.      *
  3406.      * @param AbstractIdGenerator $generator
  3407.      *
  3408.      * @return void
  3409.      */
  3410.     public function setIdGenerator($generator)
  3411.     {
  3412.         $this->idGenerator = $generator;
  3413.     }
  3415.     /**
  3416.      * Sets definition.
  3417.      *
  3418.      * @psalm-param array<string, string|null> $definition
  3419.      *
  3420.      * @return void
  3421.      */
  3422.     public function setCustomGeneratorDefinition(array $definition)
  3423.     {
  3424.         $this->customGeneratorDefinition = $definition;
  3425.     }
  3427.     /**
  3428.      * Sets the definition of the sequence ID generator for this class.
  3429.      *
  3430.      * The definition must have the following structure:
  3431.      * <code>
  3432.      * array(
  3433.      *     'sequenceName'   => 'name',
  3434.      *     'allocationSize' => 20,
  3435.      *     'initialValue'   => 1
  3436.      *     'quoted'         => 1
  3437.      * )
  3438.      * </code>
  3439.      *
  3440.      * @psalm-param array{sequenceName?: string, allocationSize?: int|string, initialValue?: int|string, quoted?: mixed} $definition
  3441.      *
  3442.      * @return void
  3443.      *
  3444.      * @throws MappingException
  3445.      */
  3446.     public function setSequenceGeneratorDefinition(array $definition)
  3447.     {
  3448.         if (! isset($definition['sequenceName']) || trim($definition['sequenceName']) === '') {
  3449.             throw MappingException::missingSequenceName($this->name);
  3450.         }
  3452.         if ($definition['sequenceName'][0] === '`') {
  3453.             $definition['sequenceName'] = trim($definition['sequenceName'], '`');
  3454.             $definition['quoted']       = true;
  3455.         }
  3457.         if (! isset($definition['allocationSize']) || trim((string) $definition['allocationSize']) === '') {
  3458.             $definition['allocationSize'] = '1';
  3459.         }
  3461.         if (! isset($definition['initialValue']) || trim((string) $definition['initialValue']) === '') {
  3462.             $definition['initialValue'] = '1';
  3463.         }
  3465.         $definition['allocationSize'] = (string) $definition['allocationSize'];
  3466.         $definition['initialValue']   = (string) $definition['initialValue'];
  3468.         $this->sequenceGeneratorDefinition = $definition;
  3469.     }
  3471.     /**
  3472.      * Sets the version field mapping used for versioning. Sets the default
  3473.      * value to use depending on the column type.
  3474.      *
  3475.      * @psalm-param array<string, mixed> $mapping The version field mapping array.
  3476.      *
  3477.      * @return void
  3478.      *
  3479.      * @throws MappingException
  3480.      */
  3481.     public function setVersionMapping(array &$mapping)
  3482.     {
  3483.         $this->isVersioned              = true;
  3484.         $this->versionField             = $mapping['fieldName'];
  3485.         $this->requiresFetchAfterChange = true;
  3487.         if (! isset($mapping['default'])) {
  3488.             if (in_array($mapping['type'], ['integer', 'bigint', 'smallint'], true)) {
  3489.                 $mapping['default'] = 1;
  3490.             } elseif ($mapping['type'] === 'datetime') {
  3491.                 $mapping['default'] = 'CURRENT_TIMESTAMP';
  3492.             } else {
  3493.                 throw MappingException::unsupportedOptimisticLockingType($this->name, $mapping['fieldName'], $mapping['type']);
  3494.             }
  3495.         }
  3496.     }
  3498.     /**
  3499.      * Sets whether this class is to be versioned for optimistic locking.
  3500.      *
  3501.      * @param bool $bool
  3502.      *
  3503.      * @return void
  3504.      */
  3505.     public function setVersioned($bool)
  3506.     {
  3507.         $this->isVersioned = $bool;
  3509.         if ($bool) {
  3510.             $this->requiresFetchAfterChange = true;
  3511.         }
  3512.     }
  3514.     /**
  3515.      * Sets the name of the field that is to be used for versioning if this class is
  3516.      * versioned for optimistic locking.
  3517.      *
  3518.      * @param string|null $versionField
  3519.      *
  3520.      * @return void
  3521.      */
  3522.     public function setVersionField($versionField)
  3523.     {
  3524.         $this->versionField = $versionField;
  3525.     }
  3527.     /**
  3528.      * Marks this class as read only, no change tracking is applied to it.
  3529.      *
  3530.      * @return void
  3531.      */
  3532.     public function markReadOnly()
  3533.     {
  3534.         $this->isReadOnly = true;
  3535.     }
  3537.     /**
  3538.      * {@inheritDoc}
  3539.      */
  3540.     public function getFieldNames()
  3541.     {
  3542.         return array_keys($this->fieldMappings);
  3543.     }
  3545.     /**
  3546.      * {@inheritDoc}
  3547.      */
  3548.     public function getAssociationNames()
  3549.     {
  3550.         return array_keys($this->associationMappings);
  3551.     }
  3553.     /**
  3554.      * {@inheritDoc}
  3555.      *
  3556.      * @param string $assocName
  3557.      *
  3558.      * @return class-string
  3559.      *
  3560.      * @throws InvalidArgumentException
  3561.      */
  3562.     public function getAssociationTargetClass($assocName)
  3563.     {
  3564.         if (! isset($this->associationMappings[$assocName])) {
  3565.             throw new InvalidArgumentException("Association name expected, '" . $assocName . "' is not an association.");
  3566.         }
  3568.         return $this->associationMappings[$assocName]['targetEntity'];
  3569.     }
  3571.     /**
  3572.      * {@inheritDoc}
  3573.      */
  3574.     public function getName()
  3575.     {
  3576.         return $this->name;
  3577.     }
  3579.     /**
  3580.      * Gets the (possibly quoted) identifier column names for safe use in an SQL statement.
  3581.      *
  3582.      * @deprecated Deprecated since version 2.3 in favor of \Doctrine\ORM\Mapping\QuoteStrategy
  3583.      *
  3584.      * @param AbstractPlatform $platform
  3585.      *
  3586.      * @return string[]
  3587.      * @psalm-return list<string>
  3588.      */
  3589.     public function getQuotedIdentifierColumnNames($platform)
  3590.     {
  3591.         $quotedColumnNames = [];
  3593.         foreach ($this->identifier as $idProperty) {
  3594.             if (isset($this->fieldMappings[$idProperty])) {
  3595.                 $quotedColumnNames[] = isset($this->fieldMappings[$idProperty]['quoted'])
  3596.                     ? $platform->quoteIdentifier($this->fieldMappings[$idProperty]['columnName'])
  3597.                     : $this->fieldMappings[$idProperty]['columnName'];
  3599.                 continue;
  3600.             }
  3602.             // Association defined as Id field
  3603.             $joinColumns            = $this->associationMappings[$idProperty]['joinColumns'];
  3604.             $assocQuotedColumnNames = array_map(
  3605.                 static function ($joinColumn) use ($platform) {
  3606.                     return isset($joinColumn['quoted'])
  3607.                         ? $platform->quoteIdentifier($joinColumn['name'])
  3608.                         : $joinColumn['name'];
  3609.                 },
  3610.                 $joinColumns
  3611.             );
  3613.             $quotedColumnNames = array_merge($quotedColumnNames, $assocQuotedColumnNames);
  3614.         }
  3616.         return $quotedColumnNames;
  3617.     }
  3619.     /**
  3620.      * Gets the (possibly quoted) column name of a mapped field for safe use  in an SQL statement.
  3621.      *
  3622.      * @deprecated Deprecated since version 2.3 in favor of \Doctrine\ORM\Mapping\QuoteStrategy
  3623.      *
  3624.      * @param string           $field
  3625.      * @param AbstractPlatform $platform
  3626.      *
  3627.      * @return string
  3628.      */
  3629.     public function getQuotedColumnName($field, $platform)
  3630.     {
  3631.         return isset($this->fieldMappings[$field]['quoted'])
  3632.             ? $platform->quoteIdentifier($this->fieldMappings[$field]['columnName'])
  3633.             : $this->fieldMappings[$field]['columnName'];
  3634.     }
  3636.     /**
  3637.      * Gets the (possibly quoted) primary table name of this class for safe use in an SQL statement.
  3638.      *
  3639.      * @deprecated Deprecated since version 2.3 in favor of \Doctrine\ORM\Mapping\QuoteStrategy
  3640.      *
  3641.      * @param AbstractPlatform $platform
  3642.      *
  3643.      * @return string
  3644.      */
  3645.     public function getQuotedTableName($platform)
  3646.     {
  3647.         return isset($this->table['quoted'])
  3648.             ? $platform->quoteIdentifier($this->table['name'])
  3649.             : $this->table['name'];
  3650.     }
  3652.     /**
  3653.      * Gets the (possibly quoted) name of the join table.
  3654.      *
  3655.      * @deprecated Deprecated since version 2.3 in favor of \Doctrine\ORM\Mapping\QuoteStrategy
  3656.      *
  3657.      * @param mixed[]          $assoc
  3658.      * @param AbstractPlatform $platform
  3659.      *
  3660.      * @return string
  3661.      */
  3662.     public function getQuotedJoinTableName(array $assoc, $platform)
  3663.     {
  3664.         return isset($assoc['joinTable']['quoted'])
  3665.             ? $platform->quoteIdentifier($assoc['joinTable']['name'])
  3666.             : $assoc['joinTable']['name'];
  3667.     }
  3669.     /**
  3670.      * {@inheritDoc}
  3671.      */
  3672.     public function isAssociationInverseSide($fieldName)
  3673.     {
  3674.         return isset($this->associationMappings[$fieldName])
  3675.             && ! $this->associationMappings[$fieldName]['isOwningSide'];
  3676.     }
  3678.     /**
  3679.      * {@inheritDoc}
  3680.      */
  3681.     public function getAssociationMappedByTargetField($fieldName)
  3682.     {
  3683.         if (! $this->isAssociationInverseSide($fieldName)) {
  3684.             Deprecation::trigger(
  3685.                 'doctrine/orm',
  3686.                 'https://github.com/doctrine/orm/pull/11309',
  3687.                 'Calling %s with owning side field %s is deprecated and will no longer be supported in Doctrine ORM 3.0. Call %s::isAssociationInverseSide() to check first.',
  3688.                 __METHOD__,
  3689.                 $fieldName,
  3690.                 self::class
  3691.             );
  3692.         }
  3694.         return $this->associationMappings[$fieldName]['mappedBy'];
  3695.     }
  3697.     /**
  3698.      * @param string $targetClass
  3699.      *
  3700.      * @return mixed[][]
  3701.      * @psalm-return array<string, array<string, mixed>>
  3702.      */
  3703.     public function getAssociationsByTargetClass($targetClass)
  3704.     {
  3705.         $relations = [];
  3707.         foreach ($this->associationMappings as $mapping) {
  3708.             if ($mapping['targetEntity'] === $targetClass) {
  3709.                 $relations[$mapping['fieldName']] = $mapping;
  3710.             }
  3711.         }
  3713.         return $relations;
  3714.     }
  3716.     /**
  3717.      * @param string|null $className
  3718.      *
  3719.      * @return string|null null if the input value is null
  3720.      */
  3721.     public function fullyQualifiedClassName($className)
  3722.     {
  3723.         if (empty($className)) {
  3724.             return $className;
  3725.         }
  3727.         if (! str_contains($className, '\\') && $this->namespace) {
  3728.             return $this->namespace . '\\' . $className;
  3729.         }
  3731.         return $className;
  3732.     }
  3734.     /**
  3735.      * @param string $name
  3736.      *
  3737.      * @return mixed
  3738.      */
  3739.     public function getMetadataValue($name)
  3740.     {
  3741.         if (isset($this->$name)) {
  3742.             return $this->$name;
  3743.         }
  3745.         return null;
  3746.     }
  3748.     /**
  3749.      * Map Embedded Class
  3750.      *
  3751.      * @psalm-param array<string, mixed> $mapping
  3752.      *
  3753.      * @return void
  3754.      *
  3755.      * @throws MappingException
  3756.      */
  3757.     public function mapEmbedded(array $mapping)
  3758.     {
  3759.         $this->assertFieldNotMapped($mapping['fieldName']);
  3761.         if (! isset($mapping['class']) && $this->isTypedProperty($mapping['fieldName'])) {
  3762.             $type = $this->reflClass->getProperty($mapping['fieldName'])->getType();
  3763.             if ($type instanceof ReflectionNamedType) {
  3764.                 $mapping['class'] = $type->getName();
  3765.             }
  3766.         }
  3768.         if (! (isset($mapping['class']) && $mapping['class'])) {
  3769.             throw MappingException::missingEmbeddedClass($mapping['fieldName']);
  3770.         }
  3772.         $fqcn = $this->fullyQualifiedClassName($mapping['class']);
  3774.         assert($fqcn !== null);
  3776.         $this->embeddedClasses[$mapping['fieldName']] = [
  3777.             'class' => $fqcn,
  3778.             'columnPrefix' => $mapping['columnPrefix'] ?? null,
  3779.             'declaredField' => $mapping['declaredField'] ?? null,
  3780.             'originalField' => $mapping['originalField'] ?? null,
  3781.         ];
  3782.     }
  3784.     /**
  3785.      * Inline the embeddable class
  3786.      *
  3787.      * @param string $property
  3788.      *
  3789.      * @return void
  3790.      */
  3791.     public function inlineEmbeddable($property, ClassMetadataInfo $embeddable)
  3792.     {
  3793.         foreach ($embeddable->fieldMappings as $fieldMapping) {
  3794.             $fieldMapping['originalClass'] = $fieldMapping['originalClass'] ?? $embeddable->name;
  3795.             $fieldMapping['declaredField'] = isset($fieldMapping['declaredField'])
  3796.                 ? $property . '.' . $fieldMapping['declaredField']
  3797.                 : $property;
  3798.             $fieldMapping['originalField'] = $fieldMapping['originalField'] ?? $fieldMapping['fieldName'];
  3799.             $fieldMapping['fieldName']     = $property . '.' . $fieldMapping['fieldName'];
  3801.             if (! empty($this->embeddedClasses[$property]['columnPrefix'])) {
  3802.                 $fieldMapping['columnName'] = $this->embeddedClasses[$property]['columnPrefix'] . $fieldMapping['columnName'];
  3803.             } elseif ($this->embeddedClasses[$property]['columnPrefix'] !== false) {
  3804.                 $fieldMapping['columnName'] = $this->namingStrategy
  3805.                     ->embeddedFieldToColumnName(
  3806.                         $property,
  3807.                         $fieldMapping['columnName'],
  3808.                         $this->reflClass->name,
  3809.                         $embeddable->reflClass->name
  3810.                     );
  3811.             }
  3813.             $this->mapField($fieldMapping);
  3814.         }
  3815.     }
  3817.     /** @throws MappingException */
  3818.     private function assertFieldNotMapped(string $fieldName): void
  3819.     {
  3820.         if (
  3821.             isset($this->fieldMappings[$fieldName]) ||
  3822.             isset($this->associationMappings[$fieldName]) ||
  3823.             isset($this->embeddedClasses[$fieldName])
  3824.         ) {
  3825.             throw MappingException::duplicateFieldMapping($this->name, $fieldName);
  3826.         }
  3827.     }
  3829.     /**
  3830.      * Gets the sequence name based on class metadata.
  3831.      *
  3832.      * @return string
  3833.      *
  3834.      * @todo Sequence names should be computed in DBAL depending on the platform
  3835.      */
  3836.     public function getSequenceName(AbstractPlatform $platform)
  3837.     {
  3838.         $sequencePrefix = $this->getSequencePrefix($platform);
  3839.         $columnName     = $this->getSingleIdentifierColumnName();
  3841.         return $sequencePrefix . '_' . $columnName . '_seq';
  3842.     }
  3844.     /**
  3845.      * Gets the sequence name prefix based on class metadata.
  3846.      *
  3847.      * @return string
  3848.      *
  3849.      * @todo Sequence names should be computed in DBAL depending on the platform
  3850.      */
  3851.     public function getSequencePrefix(AbstractPlatform $platform)
  3852.     {
  3853.         $tableName      = $this->getTableName();
  3854.         $sequencePrefix = $tableName;
  3856.         // Prepend the schema name to the table name if there is one
  3857.         $schemaName = $this->getSchemaName();
  3858.         if ($schemaName) {
  3859.             $sequencePrefix = $schemaName . '.' . $tableName;
  3861.             // @phpstan-ignore method.deprecated
  3862.             if (! $platform->supportsSchemas() && $platform->canEmulateSchemas()) {
  3863.                 $sequencePrefix = $schemaName . '__' . $tableName;
  3864.             }
  3865.         }
  3867.         return $sequencePrefix;
  3868.     }
  3870.     /** @psalm-param AssociationMapping $mapping */
  3871.     private function assertMappingOrderBy(array $mapping): void
  3872.     {
  3873.         if (isset($mapping['orderBy']) && ! is_array($mapping['orderBy'])) {
  3874.             throw new InvalidArgumentException("'orderBy' is expected to be an array, not " . gettype($mapping['orderBy']));
  3875.         }
  3876.     }
  3878.     /** @param class-string $class */
  3879.     private function getAccessibleProperty(ReflectionService $reflService, string $class, string $field): ?ReflectionProperty
  3880.     {
  3881.         $reflectionProperty = $reflService->getAccessibleProperty($class, $field);
  3882.         if ($reflectionProperty !== null && PHP_VERSION_ID >= 80100 && $reflectionProperty->isReadOnly()) {
  3883.             $declaringClass = $reflectionProperty->class;
  3884.             if ($declaringClass !== $class) {
  3885.                 $reflectionProperty = $reflService->getAccessibleProperty($declaringClass, $field);
  3886.             }
  3888.             if ($reflectionProperty !== null) {
  3889.                 $reflectionProperty = new ReflectionReadonlyProperty($reflectionProperty);
  3890.             }
  3891.         }
  3893.         if (PHP_VERSION_ID >= 80400 && $reflectionProperty !== null && count($reflectionProperty->getHooks()) > 0) {
  3894.             throw new LogicException('Doctrine ORM does not support property hooks in this version. Check https://github.com/doctrine/orm/issues/11624 for details of versions that support property hooks.');
  3895.         }
  3897.         return $reflectionProperty;
  3898.     }
  3899. }