vendor/doctrine/orm/src/Mapping/ClassMetadata.php line 907

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\Deprecations\Deprecation;
  11. use Doctrine\Instantiator\Instantiator;
  12. use Doctrine\Instantiator\InstantiatorInterface;
  13. use Doctrine\ORM\Cache\Exception\NonCacheableEntityAssociation;
  14. use Doctrine\ORM\EntityRepository;
  15. use Doctrine\ORM\Id\AbstractIdGenerator;
  16. use Doctrine\Persistence\Mapping\ClassMetadata as PersistenceClassMetadata;
  17. use Doctrine\Persistence\Mapping\ReflectionService;
  18. use Doctrine\Persistence\Reflection\EnumReflectionProperty;
  19. use InvalidArgumentException;
  20. use LogicException;
  21. use ReflectionClass;
  22. use ReflectionNamedType;
  23. use ReflectionProperty;
  24. use Stringable;
  26. use function array_diff;
  27. use function array_intersect;
  28. use function array_key_exists;
  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 in_array;
  40. use function interface_exists;
  41. use function is_string;
  42. use function is_subclass_of;
  43. use function ltrim;
  44. use function method_exists;
  45. use function spl_object_id;
  46. use function sprintf;
  47. use function str_contains;
  48. use function str_replace;
  49. use function strtolower;
  50. use function trait_exists;
  51. use function trim;
  53. /**
  54.  * A <tt>ClassMetadata</tt> instance holds all the object-relational mapping metadata
  55.  * of an entity and its associations.
  56.  *
  57.  * Once populated, ClassMetadata instances are usually cached in a serialized form.
  58.  *
  59.  * <b>IMPORTANT NOTE:</b>
  60.  *
  61.  * The fields of this class are only public for 2 reasons:
  62.  * 1) To allow fast READ access.
  63.  * 2) To drastically reduce the size of a serialized instance (private/protected members
  64.  *    get the whole class name, namespace inclusive, prepended to every property in
  65.  *    the serialized representation).
  66.  *
  67.  * @psalm-type ConcreteAssociationMapping = OneToOneOwningSideMapping|OneToOneInverseSideMapping|ManyToOneAssociationMapping|OneToManyAssociationMapping|ManyToManyOwningSideMapping|ManyToManyInverseSideMapping
  68.  * @template-covariant T of object
  69.  * @template-implements PersistenceClassMetadata<T>
  70.  */
  71. class ClassMetadata implements PersistenceClassMetadata, Stringable
  72. {
  73.     /* The inheritance mapping types */
  74.     /**
  75.      * NONE means the class does not participate in an inheritance hierarchy
  76.      * and therefore does not need an inheritance mapping type.
  77.      */
  78.     public const INHERITANCE_TYPE_NONE = 1;
  80.     /**
  81.      * JOINED means the class will be persisted according to the rules of
  82.      * <tt>Class Table Inheritance</tt>.
  83.      */
  84.     public const INHERITANCE_TYPE_JOINED = 2;
  86.     /**
  87.      * SINGLE_TABLE means the class will be persisted according to the rules of
  88.      * <tt>Single Table Inheritance</tt>.
  89.      */
  90.     public const INHERITANCE_TYPE_SINGLE_TABLE = 3;
  92.     /* The Id generator types. */
  93.     /**
  94.      * AUTO means the generator type will depend on what the used platform prefers.
  95.      * Offers full portability.
  96.      */
  97.     public const GENERATOR_TYPE_AUTO = 1;
  99.     /**
  100.      * SEQUENCE means a separate sequence object will be used. Platforms that do
  101.      * not have native sequence support may emulate it. Full portability is currently
  102.      * not guaranteed.
  103.      */
  104.     public const GENERATOR_TYPE_SEQUENCE = 2;
  106.     /**
  107.      * IDENTITY means an identity column is used for id generation. The database
  108.      * will fill in the id column on insertion. Platforms that do not support
  109.      * native identity columns may emulate them. Full portability is currently
  110.      * not guaranteed.
  111.      */
  112.     public const GENERATOR_TYPE_IDENTITY = 4;
  114.     /**
  115.      * NONE means the class does not have a generated id. That means the class
  116.      * must have a natural, manually assigned id.
  117.      */
  118.     public const GENERATOR_TYPE_NONE = 5;
  120.     /**
  121.      * CUSTOM means that customer will use own ID generator that supposedly work
  122.      */
  123.     public const GENERATOR_TYPE_CUSTOM = 7;
  125.     /**
  126.      * DEFERRED_IMPLICIT means that changes of entities are calculated at commit-time
  127.      * by doing a property-by-property comparison with the original data. This will
  128.      * be done for all entities that are in MANAGED state at commit-time.
  129.      *
  130.      * This is the default change tracking policy.
  131.      */
  132.     public const CHANGETRACKING_DEFERRED_IMPLICIT = 1;
  134.     /**
  135.      * DEFERRED_EXPLICIT means that changes of entities are calculated at commit-time
  136.      * by doing a property-by-property comparison with the original data. This will
  137.      * be done only for entities that were explicitly saved (through persist() or a cascade).
  138.      */
  139.     public const CHANGETRACKING_DEFERRED_EXPLICIT = 2;
  141.     /**
  142.      * Specifies that an association is to be fetched when it is first accessed.
  143.      */
  144.     public const FETCH_LAZY = 2;
  146.     /**
  147.      * Specifies that an association is to be fetched when the owner of the
  148.      * association is fetched.
  149.      */
  150.     public const FETCH_EAGER = 3;
  152.     /**
  153.      * Specifies that an association is to be fetched lazy (on first access) and that
  154.      * commands such as Collection#count, Collection#slice are issued directly against
  155.      * the database if the collection is not yet initialized.
  156.      */
  157.     public const FETCH_EXTRA_LAZY = 4;
  159.     /**
  160.      * Identifies a one-to-one association.
  161.      */
  162.     public const ONE_TO_ONE = 1;
  164.     /**
  165.      * Identifies a many-to-one association.
  166.      */
  167.     public const MANY_TO_ONE = 2;
  169.     /**
  170.      * Identifies a one-to-many association.
  171.      */
  172.     public const ONE_TO_MANY = 4;
  174.     /**
  175.      * Identifies a many-to-many association.
  176.      */
  177.     public const MANY_TO_MANY = 8;
  179.     /**
  180.      * Combined bitmask for to-one (single-valued) associations.
  181.      */
  182.     public const TO_ONE = 3;
  184.     /**
  185.      * Combined bitmask for to-many (collection-valued) associations.
  186.      */
  187.     public const TO_MANY = 12;
  189.     /**
  190.      * ReadOnly cache can do reads, inserts and deletes, cannot perform updates or employ any locks,
  191.      */
  192.     public const CACHE_USAGE_READ_ONLY = 1;
  194.     /**
  195.      * Nonstrict Read Write Cache doesn’t employ any locks but can do inserts, update and deletes.
  196.      */
  197.     public const CACHE_USAGE_NONSTRICT_READ_WRITE = 2;
  199.     /**
  200.      * Read Write Attempts to lock the entity before update/delete.
  201.      */
  202.     public const CACHE_USAGE_READ_WRITE = 3;
  204.     /**
  205.      * The value of this column is never generated by the database.
  206.      */
  207.     public const GENERATED_NEVER = 0;
  209.     /**
  210.      * The value of this column is generated by the database on INSERT, but not on UPDATE.
  211.      */
  212.     public const GENERATED_INSERT = 1;
  214.     /**
  215.      * The value of this column is generated by the database on both INSERT and UDPATE statements.
  216.      */
  217.     public const GENERATED_ALWAYS = 2;
  219.     /**
  220.      * READ-ONLY: The namespace the entity class is contained in.
  221.      *
  222.      * @todo Not really needed. Usage could be localized.
  223.      */
  224.     public string|null $namespace = null;
  226.     /**
  227.      * READ-ONLY: The name of the entity class that is at the root of the mapped entity inheritance
  228.      * hierarchy. If the entity is not part of a mapped inheritance hierarchy this is the same
  229.      * as {@link $name}.
  230.      *
  231.      * @psalm-var class-string
  232.      */
  233.     public string $rootEntityName;
  235.     /**
  236.      * READ-ONLY: The definition of custom generator. Only used for CUSTOM
  237.      * generator type
  238.      *
  239.      * The definition has the following structure:
  240.      * <code>
  241.      * array(
  242.      *     'class' => 'ClassName',
  243.      * )
  244.      * </code>
  245.      *
  246.      * @todo Merge with tableGeneratorDefinition into generic generatorDefinition
  247.      * @var array<string, string>|null
  248.      */
  249.     public array|null $customGeneratorDefinition = null;
  251.     /**
  252.      * The name of the custom repository class used for the entity class.
  253.      * (Optional).
  254.      *
  255.      * @psalm-var ?class-string<EntityRepository>
  256.      */
  257.     public string|null $customRepositoryClassName = null;
  259.     /**
  260.      * READ-ONLY: Whether this class describes the mapping of a mapped superclass.
  261.      */
  262.     public bool $isMappedSuperclass = false;
  264.     /**
  265.      * READ-ONLY: Whether this class describes the mapping of an embeddable class.
  266.      */
  267.     public bool $isEmbeddedClass = false;
  269.     /**
  270.      * READ-ONLY: The names of the parent <em>entity</em> classes (ancestors), starting with the
  271.      * nearest one and ending with the root entity class.
  272.      *
  273.      * @psalm-var list<class-string>
  274.      */
  275.     public array $parentClasses = [];
  277.     /**
  278.      * READ-ONLY: For classes in inheritance mapping hierarchies, this field contains the names of all
  279.      * <em>entity</em> subclasses of this class. These may also be abstract classes.
  280.      *
  281.      * This list is used, for example, to enumerate all necessary tables in JTI when querying for root
  282.      * or subclass entities, or to gather all fields comprised in an entity inheritance tree.
  283.      *
  284.      * For classes that do not use STI/JTI, this list is empty.
  285.      *
  286.      * Implementation note:
  287.      *
  288.      * In PHP, there is no general way to discover all subclasses of a given class at runtime. For that
  289.      * reason, the list of classes given in the discriminator map at the root entity is considered
  290.      * authoritative. The discriminator map must contain all <em>concrete</em> classes that can
  291.      * appear in the particular inheritance hierarchy tree. Since there can be no instances of abstract
  292.      * entity classes, users are not required to list such classes with a discriminator value.
  293.      *
  294.      * The possibly remaining "gaps" for abstract entity classes are filled after the class metadata for the
  295.      * root entity has been loaded.
  296.      *
  297.      * For subclasses of such root entities, the list can be reused/passed downwards, it only needs to
  298.      * be filtered accordingly (only keep remaining subclasses)
  299.      *
  300.      * @psalm-var list<class-string>
  301.      */
  302.     public array $subClasses = [];
  304.     /**
  305.      * READ-ONLY: The names of all embedded classes based on properties.
  306.      *
  307.      * @psalm-var array<string, EmbeddedClassMapping>
  308.      */
  309.     public array $embeddedClasses = [];
  311.     /**
  312.      * READ-ONLY: The field names of all fields that are part of the identifier/primary key
  313.      * of the mapped entity class.
  314.      *
  315.      * @psalm-var list<string>
  316.      */
  317.     public array $identifier = [];
  319.     /**
  320.      * READ-ONLY: The inheritance mapping type used by the class.
  321.      *
  322.      * @psalm-var self::INHERITANCE_TYPE_*
  323.      */
  324.     public int $inheritanceType = self::INHERITANCE_TYPE_NONE;
  326.     /**
  327.      * READ-ONLY: The Id generator type used by the class.
  328.      *
  329.      * @psalm-var self::GENERATOR_TYPE_*
  330.      */
  331.     public int $generatorType = self::GENERATOR_TYPE_NONE;
  333.     /**
  334.      * READ-ONLY: The field mappings of the class.
  335.      * Keys are field names and values are FieldMapping instances
  336.      *
  337.      * @var array<string, FieldMapping>
  338.      */
  339.     public array $fieldMappings = [];
  341.     /**
  342.      * READ-ONLY: An array of field names. Used to look up field names from column names.
  343.      * Keys are column names and values are field names.
  344.      *
  345.      * @psalm-var array<string, string>
  346.      */
  347.     public array $fieldNames = [];
  349.     /**
  350.      * READ-ONLY: A map of field names to column names. Keys are field names and values column names.
  351.      * Used to look up column names from field names.
  352.      * This is the reverse lookup map of $_fieldNames.
  353.      *
  354.      * @deprecated 3.0 Remove this.
  355.      *
  356.      * @var mixed[]
  357.      */
  358.     public array $columnNames = [];
  360.     /**
  361.      * READ-ONLY: The discriminator value of this class.
  362.      *
  363.      * <b>This does only apply to the JOINED and SINGLE_TABLE inheritance mapping strategies
  364.      * where a discriminator column is used.</b>
  365.      *
  366.      * @see discriminatorColumn
  367.      */
  368.     public mixed $discriminatorValue = null;
  370.     /**
  371.      * READ-ONLY: The discriminator map of all mapped classes in the hierarchy.
  372.      *
  373.      * <b>This does only apply to the JOINED and SINGLE_TABLE inheritance mapping strategies
  374.      * where a discriminator column is used.</b>
  375.      *
  376.      * @see discriminatorColumn
  377.      *
  378.      * @var array<int|string, string>
  379.      *
  380.      * @psalm-var array<int|string, class-string>
  381.      */
  382.     public array $discriminatorMap = [];
  384.     /**
  385.      * READ-ONLY: The definition of the discriminator column used in JOINED and SINGLE_TABLE
  386.      * inheritance mappings.
  387.      */
  388.     public DiscriminatorColumnMapping|null $discriminatorColumn = null;
  390.     /**
  391.      * READ-ONLY: The primary table definition. The definition is an array with the
  392.      * following entries:
  393.      *
  394.      * name => <tableName>
  395.      * schema => <schemaName>
  396.      * indexes => array
  397.      * uniqueConstraints => array
  398.      *
  399.      * @var mixed[]
  400.      * @psalm-var array{
  401.      *               name: string,
  402.      *               schema?: string,
  403.      *               indexes?: array,
  404.      *               uniqueConstraints?: array,
  405.      *               options?: array<string, mixed>,
  406.      *               quoted?: bool
  407.      *           }
  408.      */
  409.     public array $table;
  411.     /**
  412.      * READ-ONLY: The registered lifecycle callbacks for entities of this class.
  413.      *
  414.      * @psalm-var array<string, list<string>>
  415.      */
  416.     public array $lifecycleCallbacks = [];
  418.     /**
  419.      * READ-ONLY: The registered entity listeners.
  420.      *
  421.      * @psalm-var array<string, list<array{class: class-string, method: string}>>
  422.      */
  423.     public array $entityListeners = [];
  425.     /**
  426.      * READ-ONLY: The association mappings of this class.
  427.      *
  428.      * A join table definition has the following structure:
  429.      * <pre>
  430.      * array(
  431.      *     'name' => <join table name>,
  432.      *      'joinColumns' => array(<join column mapping from join table to source table>),
  433.      *      'inverseJoinColumns' => array(<join column mapping from join table to target table>)
  434.      * )
  435.      * </pre>
  436.      *
  437.      * @psalm-var array<string, ConcreteAssociationMapping>
  438.      */
  439.     public array $associationMappings = [];
  441.     /**
  442.      * READ-ONLY: Flag indicating whether the identifier/primary key of the class is composite.
  443.      */
  444.     public bool $isIdentifierComposite = false;
  446.     /**
  447.      * READ-ONLY: Flag indicating whether the identifier/primary key contains at least one foreign key association.
  448.      *
  449.      * This flag is necessary because some code blocks require special treatment of this cases.
  450.      */
  451.     public bool $containsForeignIdentifier = false;
  453.     /**
  454.      * READ-ONLY: Flag indicating whether the identifier/primary key contains at least one ENUM type.
  455.      *
  456.      * This flag is necessary because some code blocks require special treatment of this cases.
  457.      */
  458.     public bool $containsEnumIdentifier = false;
  460.     /**
  461.      * READ-ONLY: The ID generator used for generating IDs for this class.
  462.      *
  463.      * @todo Remove!
  464.      */
  465.     public AbstractIdGenerator $idGenerator;
  467.     /**
  468.      * READ-ONLY: The definition of the sequence generator of this class. Only used for the
  469.      * SEQUENCE generation strategy.
  470.      *
  471.      * The definition has the following structure:
  472.      * <code>
  473.      * array(
  474.      *     'sequenceName' => 'name',
  475.      *     'allocationSize' => '20',
  476.      *     'initialValue' => '1'
  477.      * )
  478.      * </code>
  479.      *
  480.      * @var array<string, mixed>|null
  481.      * @psalm-var array{sequenceName: string, allocationSize: string, initialValue: string, quoted?: mixed}|null
  482.      * @todo Merge with tableGeneratorDefinition into generic generatorDefinition
  483.      */
  484.     public array|null $sequenceGeneratorDefinition = null;
  486.     /**
  487.      * READ-ONLY: The policy used for change-tracking on entities of this class.
  488.      */
  489.     public int $changeTrackingPolicy = self::CHANGETRACKING_DEFERRED_IMPLICIT;
  491.     /**
  492.      * READ-ONLY: A Flag indicating whether one or more columns of this class
  493.      * have to be reloaded after insert / update operations.
  494.      */
  495.     public bool $requiresFetchAfterChange = false;
  497.     /**
  498.      * READ-ONLY: A flag for whether or not instances of this class are to be versioned
  499.      * with optimistic locking.
  500.      */
  501.     public bool $isVersioned = false;
  503.     /**
  504.      * READ-ONLY: The name of the field which is used for versioning in optimistic locking (if any).
  505.      */
  506.     public string|null $versionField = null;
  508.     /** @var mixed[]|null */
  509.     public array|null $cache = null;
  511.     /**
  512.      * The ReflectionClass instance of the mapped class.
  513.      *
  514.      * @var ReflectionClass<T>|null
  515.      */
  516.     public ReflectionClass|null $reflClass = null;
  518.     /**
  519.      * Is this entity marked as "read-only"?
  520.      *
  521.      * That means it is never considered for change-tracking in the UnitOfWork. It is a very helpful performance
  522.      * optimization for entities that are immutable, either in your domain or through the relation database
  523.      * (coming from a view, or a history table for example).
  524.      */
  525.     public bool $isReadOnly = false;
  527.     /**
  528.      * NamingStrategy determining the default column and table names.
  529.      */
  530.     protected NamingStrategy $namingStrategy;
  532.     /**
  533.      * The ReflectionProperty instances of the mapped class.
  534.      *
  535.      * @var array<string, ReflectionProperty|null>
  536.      */
  537.     public array $reflFields = [];
  539.     private InstantiatorInterface|null $instantiator = null;
  541.     private readonly TypedFieldMapper $typedFieldMapper;
  543.     /**
  544.      * Initializes a new ClassMetadata instance that will hold the object-relational mapping
  545.      * metadata of the class with the given name.
  546.      *
  547.      * @param string $name The name of the entity class the new instance is used for.
  548.      * @psalm-param class-string<T> $name
  549.      */
  550.     public function __construct(public string $name, NamingStrategy|null $namingStrategy = null, TypedFieldMapper|null $typedFieldMapper = null)
  551.     {
  552.         $this->rootEntityName   = $name;
  553.         $this->namingStrategy   = $namingStrategy ?? new DefaultNamingStrategy();
  554.         $this->instantiator     = new Instantiator();
  555.         $this->typedFieldMapper = $typedFieldMapper ?? new DefaultTypedFieldMapper();
  556.     }
  558.     /**
  559.      * Gets the ReflectionProperties of the mapped class.
  560.      *
  561.      * @return ReflectionProperty[]|null[] An array of ReflectionProperty instances.
  562.      * @psalm-return array<ReflectionProperty|null>
  563.      */
  564.     public function getReflectionProperties(): array
  565.     {
  566.         return $this->reflFields;
  567.     }
  569.     /**
  570.      * Gets a ReflectionProperty for a specific field of the mapped class.
  571.      */
  572.     public function getReflectionProperty(string $name): ReflectionProperty|null
  573.     {
  574.         return $this->reflFields[$name];
  575.     }
  577.     /**
  578.      * Gets the ReflectionProperty for the single identifier field.
  579.      *
  580.      * @throws BadMethodCallException If the class has a composite identifier.
  581.      */
  582.     public function getSingleIdReflectionProperty(): ReflectionProperty|null
  583.     {
  584.         if ($this->isIdentifierComposite) {
  585.             throw new BadMethodCallException('Class ' . $this->name . ' has a composite identifier.');
  586.         }
  588.         return $this->reflFields[$this->identifier[0]];
  589.     }
  591.     /**
  592.      * Extracts the identifier values of an entity of this class.
  593.      *
  594.      * For composite identifiers, the identifier values are returned as an array
  595.      * with the same order as the field order in {@link identifier}.
  596.      *
  597.      * @return array<string, mixed>
  598.      */
  599.     public function getIdentifierValues(object $entity): array
  600.     {
  601.         if ($this->isIdentifierComposite) {
  602.             $id = [];
  604.             foreach ($this->identifier as $idField) {
  605.                 $value = $this->reflFields[$idField]->getValue($entity);
  607.                 if ($value !== null) {
  608.                     $id[$idField] = $value;
  609.                 }
  610.             }
  612.             return $id;
  613.         }
  615.         $id    = $this->identifier[0];
  616.         $value = $this->reflFields[$id]->getValue($entity);
  618.         if ($value === null) {
  619.             return [];
  620.         }
  622.         return [$id => $value];
  623.     }
  625.     /**
  626.      * Populates the entity identifier of an entity.
  627.      *
  628.      * @psalm-param array<string, mixed> $id
  629.      *
  630.      * @todo Rename to assignIdentifier()
  631.      */
  632.     public function setIdentifierValues(object $entity, array $id): void
  633.     {
  634.         foreach ($id as $idField => $idValue) {
  635.             $this->reflFields[$idField]->setValue($entity, $idValue);
  636.         }
  637.     }
  639.     /**
  640.      * Sets the specified field to the specified value on the given entity.
  641.      */
  642.     public function setFieldValue(object $entity, string $field, mixed $value): void
  643.     {
  644.         $this->reflFields[$field]->setValue($entity, $value);
  645.     }
  647.     /**
  648.      * Gets the specified field's value off the given entity.
  649.      */
  650.     public function getFieldValue(object $entity, string $field): mixed
  651.     {
  652.         return $this->reflFields[$field]->getValue($entity);
  653.     }
  655.     /**
  656.      * Creates a string representation of this instance.
  657.      *
  658.      * @return string The string representation of this instance.
  659.      *
  660.      * @todo Construct meaningful string representation.
  661.      */
  662.     public function __toString(): string
  663.     {
  664.         return self::class . '@' . spl_object_id($this);
  665.     }
  667.     /**
  668.      * Determines which fields get serialized.
  669.      *
  670.      * It is only serialized what is necessary for best unserialization performance.
  671.      * That means any metadata properties that are not set or empty or simply have
  672.      * their default value are NOT serialized.
  673.      *
  674.      * Parts that are also NOT serialized because they can not be properly unserialized:
  675.      *      - reflClass (ReflectionClass)
  676.      *      - reflFields (ReflectionProperty array)
  677.      *
  678.      * @return string[] The names of all the fields that should be serialized.
  679.      */
  680.     public function __sleep(): array
  681.     {
  682.         // This metadata is always serialized/cached.
  683.         $serialized = [
  684.             'associationMappings',
  685.             'columnNames', //TODO: 3.0 Remove this. Can use fieldMappings[$fieldName]['columnName']
  686.             'fieldMappings',
  687.             'fieldNames',
  688.             'embeddedClasses',
  689.             'identifier',
  690.             'isIdentifierComposite', // TODO: REMOVE
  691.             'name',
  692.             'namespace', // TODO: REMOVE
  693.             'table',
  694.             'rootEntityName',
  695.             'idGenerator', //TODO: Does not really need to be serialized. Could be moved to runtime.
  696.         ];
  698.         // The rest of the metadata is only serialized if necessary.
  699.         if ($this->changeTrackingPolicy !== self::CHANGETRACKING_DEFERRED_IMPLICIT) {
  700.             $serialized[] = 'changeTrackingPolicy';
  701.         }
  703.         if ($this->customRepositoryClassName) {
  704.             $serialized[] = 'customRepositoryClassName';
  705.         }
  707.         if ($this->inheritanceType !== self::INHERITANCE_TYPE_NONE) {
  708.             $serialized[] = 'inheritanceType';
  709.             $serialized[] = 'discriminatorColumn';
  710.             $serialized[] = 'discriminatorValue';
  711.             $serialized[] = 'discriminatorMap';
  712.             $serialized[] = 'parentClasses';
  713.             $serialized[] = 'subClasses';
  714.         }
  716.         if ($this->generatorType !== self::GENERATOR_TYPE_NONE) {
  717.             $serialized[] = 'generatorType';
  718.             if ($this->generatorType === self::GENERATOR_TYPE_SEQUENCE) {
  719.                 $serialized[] = 'sequenceGeneratorDefinition';
  720.             }
  721.         }
  723.         if ($this->isMappedSuperclass) {
  724.             $serialized[] = 'isMappedSuperclass';
  725.         }
  727.         if ($this->isEmbeddedClass) {
  728.             $serialized[] = 'isEmbeddedClass';
  729.         }
  731.         if ($this->containsForeignIdentifier) {
  732.             $serialized[] = 'containsForeignIdentifier';
  733.         }
  735.         if ($this->containsEnumIdentifier) {
  736.             $serialized[] = 'containsEnumIdentifier';
  737.         }
  739.         if ($this->isVersioned) {
  740.             $serialized[] = 'isVersioned';
  741.             $serialized[] = 'versionField';
  742.         }
  744.         if ($this->lifecycleCallbacks) {
  745.             $serialized[] = 'lifecycleCallbacks';
  746.         }
  748.         if ($this->entityListeners) {
  749.             $serialized[] = 'entityListeners';
  750.         }
  752.         if ($this->isReadOnly) {
  753.             $serialized[] = 'isReadOnly';
  754.         }
  756.         if ($this->customGeneratorDefinition) {
  757.             $serialized[] = 'customGeneratorDefinition';
  758.         }
  760.         if ($this->cache) {
  761.             $serialized[] = 'cache';
  762.         }
  764.         if ($this->requiresFetchAfterChange) {
  765.             $serialized[] = 'requiresFetchAfterChange';
  766.         }
  768.         return $serialized;
  769.     }
  771.     /**
  772.      * Creates a new instance of the mapped class, without invoking the constructor.
  773.      */
  774.     public function newInstance(): object
  775.     {
  776.         return $this->instantiator->instantiate($this->name);
  777.     }
  779.     /**
  780.      * Restores some state that can not be serialized/unserialized.
  781.      */
  782.     public function wakeupReflection(ReflectionService $reflService): void
  783.     {
  784.         // Restore ReflectionClass and properties
  785.         $this->reflClass    = $reflService->getClass($this->name);
  786.         $this->instantiator = $this->instantiator ?: new Instantiator();
  788.         $parentReflFields = [];
  790.         foreach ($this->embeddedClasses as $property => $embeddedClass) {
  791.             if (isset($embeddedClass->declaredField)) {
  792.                 assert($embeddedClass->originalField !== null);
  793.                 $childProperty = $this->getAccessibleProperty(
  794.                     $reflService,
  795.                     $this->embeddedClasses[$embeddedClass->declaredField]->class,
  796.                     $embeddedClass->originalField,
  797.                 );
  798.                 assert($childProperty !== null);
  799.                 $parentReflFields[$property] = new ReflectionEmbeddedProperty(
  800.                     $parentReflFields[$embeddedClass->declaredField],
  801.                     $childProperty,
  802.                     $this->embeddedClasses[$embeddedClass->declaredField]->class,
  803.                 );
  805.                 continue;
  806.             }
  808.             $fieldRefl = $this->getAccessibleProperty(
  809.                 $reflService,
  810.                 $embeddedClass->declared ?? $this->name,
  811.                 $property,
  812.             );
  814.             $parentReflFields[$property] = $fieldRefl;
  815.             $this->reflFields[$property] = $fieldRefl;
  816.         }
  818.         foreach ($this->fieldMappings as $field => $mapping) {
  819.             if (isset($mapping->declaredField) && isset($parentReflFields[$mapping->declaredField])) {
  820.                 assert($mapping->originalField !== null);
  821.                 assert($mapping->originalClass !== null);
  822.                 $childProperty = $this->getAccessibleProperty($reflService, $mapping->originalClass, $mapping->originalField);
  823.                 assert($childProperty !== null);
  825.                 if (isset($mapping->enumType)) {
  826.                     $childProperty = new EnumReflectionProperty(
  827.                         $childProperty,
  828.                         $mapping->enumType,
  829.                     );
  830.                 }
  832.                 $this->reflFields[$field] = new ReflectionEmbeddedProperty(
  833.                     $parentReflFields[$mapping->declaredField],
  834.                     $childProperty,
  835.                     $mapping->originalClass,
  836.                 );
  837.                 continue;
  838.             }
  840.             $this->reflFields[$field] = isset($mapping->declared)
  841.                 ? $this->getAccessibleProperty($reflService, $mapping->declared, $field)
  842.                 : $this->getAccessibleProperty($reflService, $this->name, $field);
  844.             if (isset($mapping->enumType) && $this->reflFields[$field] !== null) {
  845.                 $this->reflFields[$field] = new EnumReflectionProperty(
  846.                     $this->reflFields[$field],
  847.                     $mapping->enumType,
  848.                 );
  849.             }
  850.         }
  852.         foreach ($this->associationMappings as $field => $mapping) {
  853.             $this->reflFields[$field] = isset($mapping->declared)
  854.                 ? $this->getAccessibleProperty($reflService, $mapping->declared, $field)
  855.                 : $this->getAccessibleProperty($reflService, $this->name, $field);
  856.         }
  857.     }
  859.     /**
  860.      * Initializes a new ClassMetadata instance that will hold the object-relational mapping
  861.      * metadata of the class with the given name.
  862.      *
  863.      * @param ReflectionService $reflService The reflection service.
  864.      */
  865.     public function initializeReflection(ReflectionService $reflService): void
  866.     {
  867.         $this->reflClass = $reflService->getClass($this->name);
  868.         $this->namespace = $reflService->getClassNamespace($this->name);
  870.         if ($this->reflClass) {
  871.             $this->name = $this->rootEntityName = $this->reflClass->name;
  872.         }
  874.         $this->table['name'] = $this->namingStrategy->classToTableName($this->name);
  875.     }
  877.     /**
  878.      * Validates Identifier.
  879.      *
  880.      * @throws MappingException
  881.      */
  882.     public function validateIdentifier(): void
  883.     {
  884.         if ($this->isMappedSuperclass || $this->isEmbeddedClass) {
  885.             return;
  886.         }
  888.         // Verify & complete identifier mapping
  889.         if (! $this->identifier) {
  890.             throw MappingException::identifierRequired($this->name);
  891.         }
  893.         if ($this->usesIdGenerator() && $this->isIdentifierComposite) {
  894.             throw MappingException::compositeKeyAssignedIdGeneratorRequired($this->name);
  895.         }
  896.     }
  898.     /**
  899.      * Validates association targets actually exist.
  900.      *
  901.      * @throws MappingException
  902.      */
  903.     public function validateAssociations(): void
  904.     {
  905.         foreach ($this->associationMappings as $mapping) {
  906.             if (
  907.                 ! class_exists($mapping->targetEntity)
  908.                 && ! interface_exists($mapping->targetEntity)
  909.                 && ! trait_exists($mapping->targetEntity)
  910.             ) {
  911.                 throw MappingException::invalidTargetEntityClass($mapping->targetEntity, $this->name, $mapping->fieldName);
  912.             }
  913.         }
  914.     }
  916.     /**
  917.      * Validates lifecycle callbacks.
  918.      *
  919.      * @throws MappingException
  920.      */
  921.     public function validateLifecycleCallbacks(ReflectionService $reflService): void
  922.     {
  923.         foreach ($this->lifecycleCallbacks as $callbacks) {
  924.             foreach ($callbacks as $callbackFuncName) {
  925.                 if (! $reflService->hasPublicMethod($this->name, $callbackFuncName)) {
  926.                     throw MappingException::lifecycleCallbackMethodNotFound($this->name, $callbackFuncName);
  927.                 }
  928.             }
  929.         }
  930.     }
  932.     /**
  933.      * {@inheritDoc}
  934.      *
  935.      * Can return null when using static reflection, in violation of the LSP
  936.      */
  937.     public function getReflectionClass(): ReflectionClass|null
  938.     {
  939.         return $this->reflClass;
  940.     }
  942.     /** @psalm-param array{usage?: mixed, region?: mixed} $cache */
  943.     public function enableCache(array $cache): void
  944.     {
  945.         if (! isset($cache['usage'])) {
  946.             $cache['usage'] = self::CACHE_USAGE_READ_ONLY;
  947.         }
  949.         if (! isset($cache['region'])) {
  950.             $cache['region'] = strtolower(str_replace('\\', '_', $this->rootEntityName));
  951.         }
  953.         $this->cache = $cache;
  954.     }
  956.     /** @psalm-param array{usage?: int, region?: string} $cache */
  957.     public function enableAssociationCache(string $fieldName, array $cache): void
  958.     {
  959.         $this->associationMappings[$fieldName]->cache = $this->getAssociationCacheDefaults($fieldName, $cache);
  960.     }
  962.     /**
  963.      * @psalm-param array{usage?: int, region?: string|null} $cache
  964.      *
  965.      * @return int[]|string[]
  966.      * @psalm-return array{usage: int, region: string|null}
  967.      */
  968.     public function getAssociationCacheDefaults(string $fieldName, array $cache): array
  969.     {
  970.         if (! isset($cache['usage'])) {
  971.             $cache['usage'] = $this->cache['usage'] ?? self::CACHE_USAGE_READ_ONLY;
  972.         }
  974.         if (! isset($cache['region'])) {
  975.             $cache['region'] = strtolower(str_replace('\\', '_', $this->rootEntityName)) . '__' . $fieldName;
  976.         }
  978.         return $cache;
  979.     }
  981.     /**
  982.      * Sets the change tracking policy used by this class.
  983.      */
  984.     public function setChangeTrackingPolicy(int $policy): void
  985.     {
  986.         $this->changeTrackingPolicy = $policy;
  987.     }
  989.     /**
  990.      * Whether the change tracking policy of this class is "deferred explicit".
  991.      */
  992.     public function isChangeTrackingDeferredExplicit(): bool
  993.     {
  994.         return $this->changeTrackingPolicy === self::CHANGETRACKING_DEFERRED_EXPLICIT;
  995.     }
  997.     /**
  998.      * Whether the change tracking policy of this class is "deferred implicit".
  999.      */
  1000.     public function isChangeTrackingDeferredImplicit(): bool
  1001.     {
  1002.         return $this->changeTrackingPolicy === self::CHANGETRACKING_DEFERRED_IMPLICIT;
  1003.     }
  1005.     /**
  1006.      * Checks whether a field is part of the identifier/primary key field(s).
  1007.      */
  1008.     public function isIdentifier(string $fieldName): bool
  1009.     {
  1010.         if (! $this->identifier) {
  1011.             return false;
  1012.         }
  1014.         if (! $this->isIdentifierComposite) {
  1015.             return $fieldName === $this->identifier[0];
  1016.         }
  1018.         return in_array($fieldName, $this->identifier, true);
  1019.     }
  1021.     public function isUniqueField(string $fieldName): bool
  1022.     {
  1023.         $mapping = $this->getFieldMapping($fieldName);
  1025.         return $mapping !== false && isset($mapping->unique) && $mapping->unique;
  1026.     }
  1028.     public function isNullable(string $fieldName): bool
  1029.     {
  1030.         $mapping = $this->getFieldMapping($fieldName);
  1032.         return $mapping !== false && isset($mapping->nullable) && $mapping->nullable;
  1033.     }
  1035.     /**
  1036.      * Gets a column name for a field name.
  1037.      * If the column name for the field cannot be found, the given field name
  1038.      * is returned.
  1039.      */
  1040.     public function getColumnName(string $fieldName): string
  1041.     {
  1042.         return $this->columnNames[$fieldName] ?? $fieldName;
  1043.     }
  1045.     /**
  1046.      * Gets the mapping of a (regular) field that holds some data but not a
  1047.      * reference to another object.
  1048.      *
  1049.      * @throws MappingException
  1050.      */
  1051.     public function getFieldMapping(string $fieldName): FieldMapping
  1052.     {
  1053.         if (! isset($this->fieldMappings[$fieldName])) {
  1054.             throw MappingException::mappingNotFound($this->name, $fieldName);
  1055.         }
  1057.         return $this->fieldMappings[$fieldName];
  1058.     }
  1060.     /**
  1061.      * Gets the mapping of an association.
  1062.      *
  1063.      * @see ClassMetadata::$associationMappings
  1064.      *
  1065.      * @param string $fieldName The field name that represents the association in
  1066.      *                          the object model.
  1067.      *
  1068.      * @throws MappingException
  1069.      */
  1070.     public function getAssociationMapping(string $fieldName): AssociationMapping
  1071.     {
  1072.         if (! isset($this->associationMappings[$fieldName])) {
  1073.             throw MappingException::mappingNotFound($this->name, $fieldName);
  1074.         }
  1076.         return $this->associationMappings[$fieldName];
  1077.     }
  1079.     /**
  1080.      * Gets all association mappings of the class.
  1081.      *
  1082.      * @psalm-return array<string, AssociationMapping>
  1083.      */
  1084.     public function getAssociationMappings(): array
  1085.     {
  1086.         return $this->associationMappings;
  1087.     }
  1089.     /**
  1090.      * Gets the field name for a column name.
  1091.      * If no field name can be found the column name is returned.
  1092.      *
  1093.      * @return string The column alias.
  1094.      */
  1095.     public function getFieldName(string $columnName): string
  1096.     {
  1097.         return $this->fieldNames[$columnName] ?? $columnName;
  1098.     }
  1100.     /**
  1101.      * Checks whether given property has type
  1102.      */
  1103.     private function isTypedProperty(string $name): bool
  1104.     {
  1105.         return isset($this->reflClass)
  1106.                && $this->reflClass->hasProperty($name)
  1107.                && $this->reflClass->getProperty($name)->hasType();
  1108.     }
  1110.     /**
  1111.      * Validates & completes the given field mapping based on typed property.
  1112.      *
  1113.      * @param  array{fieldName: string, type?: string} $mapping The field mapping to validate & complete.
  1114.      *
  1115.      * @return array{fieldName: string, enumType?: class-string<BackedEnum>, type?: string} The updated mapping.
  1116.      */
  1117.     private function validateAndCompleteTypedFieldMapping(array $mapping): array
  1118.     {
  1119.         $field = $this->reflClass->getProperty($mapping['fieldName']);
  1121.         $mapping = $this->typedFieldMapper->validateAndComplete($mapping, $field);
  1123.         return $mapping;
  1124.     }
  1126.     /**
  1127.      * Validates & completes the basic mapping information based on typed property.
  1128.      *
  1129.      * @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.
  1130.      *
  1131.      * @return mixed[] The updated mapping.
  1132.      */
  1133.     private function validateAndCompleteTypedAssociationMapping(array $mapping): array
  1134.     {
  1135.         $type = $this->reflClass->getProperty($mapping['fieldName'])->getType();
  1137.         if ($type === null || ($mapping['type'] & self::TO_ONE) === 0) {
  1138.             return $mapping;
  1139.         }
  1141.         if (! isset($mapping['targetEntity']) && $type instanceof ReflectionNamedType) {
  1142.             $mapping['targetEntity'] = $type->getName();
  1143.         }
  1145.         return $mapping;
  1146.     }
  1148.     /**
  1149.      * Validates & completes the given field mapping.
  1150.      *
  1151.      * @psalm-param array{
  1152.      *     fieldName?: string,
  1153.      *     columnName?: string,
  1154.      *     id?: bool,
  1155.      *     generated?: self::GENERATED_*,
  1156.      *     enumType?: class-string,
  1157.      * } $mapping The field mapping to validate & complete.
  1158.      *
  1159.      * @return FieldMapping The updated mapping.
  1160.      *
  1161.      * @throws MappingException
  1162.      */
  1163.     protected function validateAndCompleteFieldMapping(array $mapping): FieldMapping
  1164.     {
  1165.         // Check mandatory fields
  1166.         if (! isset($mapping['fieldName']) || ! $mapping['fieldName']) {
  1167.             throw MappingException::missingFieldName($this->name);
  1168.         }
  1170.         if ($this->isTypedProperty($mapping['fieldName'])) {
  1171.             $mapping = $this->validateAndCompleteTypedFieldMapping($mapping);
  1172.         }
  1174.         if (! isset($mapping['type'])) {
  1175.             // Default to string
  1176.             $mapping['type'] = 'string';
  1177.         }
  1179.         // Complete fieldName and columnName mapping
  1180.         if (! isset($mapping['columnName'])) {
  1181.             $mapping['columnName'] = $this->namingStrategy->propertyToColumnName($mapping['fieldName'], $this->name);
  1182.         }
  1184.         $mapping = FieldMapping::fromMappingArray($mapping);
  1186.         if ($mapping->columnName[0] === '`') {
  1187.             $mapping->columnName = trim($mapping->columnName, '`');
  1188.             $mapping->quoted     = true;
  1189.         }
  1191.         $this->columnNames[$mapping->fieldName] = $mapping->columnName;
  1193.         if (isset($this->fieldNames[$mapping->columnName]) || ($this->discriminatorColumn && $this->discriminatorColumn->name === $mapping->columnName)) {
  1194.             throw MappingException::duplicateColumnName($this->name, $mapping->columnName);
  1195.         }
  1197.         $this->fieldNames[$mapping->columnName] = $mapping->fieldName;
  1199.         // Complete id mapping
  1200.         if (isset($mapping->id) && $mapping->id === true) {
  1201.             if ($this->versionField === $mapping->fieldName) {
  1202.                 throw MappingException::cannotVersionIdField($this->name, $mapping->fieldName);
  1203.             }
  1205.             if (! in_array($mapping->fieldName, $this->identifier, true)) {
  1206.                 $this->identifier[] = $mapping->fieldName;
  1207.             }
  1209.             // Check for composite key
  1210.             if (! $this->isIdentifierComposite && count($this->identifier) > 1) {
  1211.                 $this->isIdentifierComposite = true;
  1212.             }
  1213.         }
  1215.         if (isset($mapping->generated)) {
  1216.             if (! in_array($mapping->generated, [self::GENERATED_NEVER, self::GENERATED_INSERT, self::GENERATED_ALWAYS])) {
  1217.                 throw MappingException::invalidGeneratedMode($mapping->generated);
  1218.             }
  1220.             if ($mapping->generated === self::GENERATED_NEVER) {
  1221.                 unset($mapping->generated);
  1222.             }
  1223.         }
  1225.         if (isset($mapping->enumType)) {
  1226.             if (! enum_exists($mapping->enumType)) {
  1227.                 throw MappingException::nonEnumTypeMapped($this->name, $mapping->fieldName, $mapping->enumType);
  1228.             }
  1230.             if (! empty($mapping->id)) {
  1231.                 $this->containsEnumIdentifier = true;
  1232.             }
  1233.         }
  1235.         return $mapping;
  1236.     }
  1238.     /**
  1239.      * Validates & completes the basic mapping information that is common to all
  1240.      * association mappings (one-to-one, many-ot-one, one-to-many, many-to-many).
  1241.      *
  1242.      * @psalm-param array<string, mixed> $mapping The mapping.
  1243.      *
  1244.      * @return ConcreteAssociationMapping
  1245.      *
  1246.      * @throws MappingException If something is wrong with the mapping.
  1247.      */
  1248.     protected function _validateAndCompleteAssociationMapping(array $mapping): AssociationMapping
  1249.     {
  1250.         if (array_key_exists('mappedBy', $mapping) && $mapping['mappedBy'] === null) {
  1251.             unset($mapping['mappedBy']);
  1252.         }
  1254.         if (array_key_exists('inversedBy', $mapping) && $mapping['inversedBy'] === null) {
  1255.             unset($mapping['inversedBy']);
  1256.         }
  1258.         if (array_key_exists('joinColumns', $mapping) && in_array($mapping['joinColumns'], [null, []], true)) {
  1259.             unset($mapping['joinColumns']);
  1260.         }
  1262.         $mapping['isOwningSide'] = true; // assume owning side until we hit mappedBy
  1264.         if (empty($mapping['indexBy'])) {
  1265.             unset($mapping['indexBy']);
  1266.         }
  1268.         // If targetEntity is unqualified, assume it is in the same namespace as
  1269.         // the sourceEntity.
  1270.         $mapping['sourceEntity'] = $this->name;
  1272.         if ($this->isTypedProperty($mapping['fieldName'])) {
  1273.             $mapping = $this->validateAndCompleteTypedAssociationMapping($mapping);
  1274.         }
  1276.         if (isset($mapping['targetEntity'])) {
  1277.             $mapping['targetEntity'] = $this->fullyQualifiedClassName($mapping['targetEntity']);
  1278.             $mapping['targetEntity'] = ltrim($mapping['targetEntity'], '\\');
  1279.         }
  1281.         if (($mapping['type'] & self::MANY_TO_ONE) > 0 && isset($mapping['orphanRemoval']) && $mapping['orphanRemoval']) {
  1282.             throw MappingException::illegalOrphanRemoval($this->name, $mapping['fieldName']);
  1283.         }
  1285.         // Complete id mapping
  1286.         if (isset($mapping['id']) && $mapping['id'] === true) {
  1287.             if (isset($mapping['orphanRemoval']) && $mapping['orphanRemoval']) {
  1288.                 throw MappingException::illegalOrphanRemovalOnIdentifierAssociation($this->name, $mapping['fieldName']);
  1289.             }
  1291.             if (! in_array($mapping['fieldName'], $this->identifier, true)) {
  1292.                 if (isset($mapping['joinColumns']) && count($mapping['joinColumns']) >= 2) {
  1293.                     throw MappingException::cannotMapCompositePrimaryKeyEntitiesAsForeignId(
  1294.                         $mapping['targetEntity'],
  1295.                         $this->name,
  1296.                         $mapping['fieldName'],
  1297.                     );
  1298.                 }
  1300.                 assert(is_string($mapping['fieldName']));
  1301.                 $this->identifier[]              = $mapping['fieldName'];
  1302.                 $this->containsForeignIdentifier = true;
  1303.             }
  1305.             // Check for composite key
  1306.             if (! $this->isIdentifierComposite && count($this->identifier) > 1) {
  1307.                 $this->isIdentifierComposite = true;
  1308.             }
  1310.             if ($this->cache && ! isset($mapping['cache'])) {
  1311.                 throw NonCacheableEntityAssociation::fromEntityAndField(
  1312.                     $this->name,
  1313.                     $mapping['fieldName'],
  1314.                 );
  1315.             }
  1316.         }
  1318.         // Mandatory attributes for both sides
  1319.         // Mandatory: fieldName, targetEntity
  1320.         if (! isset($mapping['fieldName']) || ! $mapping['fieldName']) {
  1321.             throw MappingException::missingFieldName($this->name);
  1322.         }
  1324.         if (! isset($mapping['targetEntity'])) {
  1325.             throw MappingException::missingTargetEntity($mapping['fieldName']);
  1326.         }
  1328.         // Mandatory and optional attributes for either side
  1329.         if (! isset($mapping['mappedBy'])) {
  1330.             if (isset($mapping['joinTable'])) {
  1331.                 if (isset($mapping['joinTable']['name']) && $mapping['joinTable']['name'][0] === '`') {
  1332.                     $mapping['joinTable']['name']   = trim($mapping['joinTable']['name'], '`');
  1333.                     $mapping['joinTable']['quoted'] = true;
  1334.                 }
  1335.             }
  1336.         } else {
  1337.             $mapping['isOwningSide'] = false;
  1338.         }
  1340.         if (isset($mapping['id']) && $mapping['id'] === true && $mapping['type'] & self::TO_MANY) {
  1341.             throw MappingException::illegalToManyIdentifierAssociation($this->name, $mapping['fieldName']);
  1342.         }
  1344.         // Fetch mode. Default fetch mode to LAZY, if not set.
  1345.         if (! isset($mapping['fetch'])) {
  1346.             $mapping['fetch'] = self::FETCH_LAZY;
  1347.         }
  1349.         // Cascades
  1350.         $cascades = isset($mapping['cascade']) ? array_map('strtolower', $mapping['cascade']) : [];
  1352.         $allCascades = ['remove', 'persist', 'refresh', 'detach'];
  1353.         if (in_array('all', $cascades, true)) {
  1354.             $cascades = $allCascades;
  1355.         } elseif (count($cascades) !== count(array_intersect($cascades, $allCascades))) {
  1356.             throw MappingException::invalidCascadeOption(
  1357.                 array_diff($cascades, $allCascades),
  1358.                 $this->name,
  1359.                 $mapping['fieldName'],
  1360.             );
  1361.         }
  1363.         $mapping['cascade'] = $cascades;
  1365.         switch ($mapping['type']) {
  1366.             case self::ONE_TO_ONE:
  1367.                 if (isset($mapping['joinColumns']) && $mapping['joinColumns'] && ! $mapping['isOwningSide']) {
  1368.                     throw MappingException::joinColumnNotAllowedOnOneToOneInverseSide(
  1369.                         $this->name,
  1370.                         $mapping['fieldName'],
  1371.                     );
  1372.                 }
  1374.                 return $mapping['isOwningSide'] ?
  1375.                     OneToOneOwningSideMapping::fromMappingArrayAndName(
  1376.                         $mapping,
  1377.                         $this->namingStrategy,
  1378.                         $this->name,
  1379.                         $this->table ?? null,
  1380.                         $this->isInheritanceTypeSingleTable(),
  1381.                     ) :
  1382.                     OneToOneInverseSideMapping::fromMappingArrayAndName($mapping, $this->name);
  1384.             case self::MANY_TO_ONE:
  1385.                 return ManyToOneAssociationMapping::fromMappingArrayAndName(
  1386.                     $mapping,
  1387.                     $this->namingStrategy,
  1388.                     $this->name,
  1389.                     $this->table ?? null,
  1390.                     $this->isInheritanceTypeSingleTable(),
  1391.                 );
  1393.             case self::ONE_TO_MANY:
  1394.                 return OneToManyAssociationMapping::fromMappingArrayAndName($mapping, $this->name);
  1396.             case self::MANY_TO_MANY:
  1397.                 if (isset($mapping['joinColumns'])) {
  1398.                     unset($mapping['joinColumns']);
  1399.                 }
  1401.                 return $mapping['isOwningSide'] ?
  1402.                     ManyToManyOwningSideMapping::fromMappingArrayAndNamingStrategy($mapping, $this->namingStrategy) :
  1403.                     ManyToManyInverseSideMapping::fromMappingArray($mapping);
  1405.             default:
  1406.                 throw MappingException::invalidAssociationType(
  1407.                     $this->name,
  1408.                     $mapping['fieldName'],
  1409.                     $mapping['type'],
  1410.                 );
  1411.         }
  1412.     }
  1414.     /**
  1415.      * {@inheritDoc}
  1416.      */
  1417.     public function getIdentifierFieldNames(): array
  1418.     {
  1419.         return $this->identifier;
  1420.     }
  1422.     /**
  1423.      * Gets the name of the single id field. Note that this only works on
  1424.      * entity classes that have a single-field pk.
  1425.      *
  1426.      * @throws MappingException If the class doesn't have an identifier or it has a composite primary key.
  1427.      */
  1428.     public function getSingleIdentifierFieldName(): string
  1429.     {
  1430.         if ($this->isIdentifierComposite) {
  1431.             throw MappingException::singleIdNotAllowedOnCompositePrimaryKey($this->name);
  1432.         }
  1434.         if (! isset($this->identifier[0])) {
  1435.             throw MappingException::noIdDefined($this->name);
  1436.         }
  1438.         return $this->identifier[0];
  1439.     }
  1441.     /**
  1442.      * Gets the column name of the single id column. Note that this only works on
  1443.      * entity classes that have a single-field pk.
  1444.      *
  1445.      * @throws MappingException If the class doesn't have an identifier or it has a composite primary key.
  1446.      */
  1447.     public function getSingleIdentifierColumnName(): string
  1448.     {
  1449.         return $this->getColumnName($this->getSingleIdentifierFieldName());
  1450.     }
  1452.     /**
  1453.      * INTERNAL:
  1454.      * Sets the mapped identifier/primary key fields of this class.
  1455.      * Mainly used by the ClassMetadataFactory to assign inherited identifiers.
  1456.      *
  1457.      * @psalm-param list<mixed> $identifier
  1458.      */
  1459.     public function setIdentifier(array $identifier): void
  1460.     {
  1461.         $this->identifier            = $identifier;
  1462.         $this->isIdentifierComposite = (count($this->identifier) > 1);
  1463.     }
  1465.     /**
  1466.      * {@inheritDoc}
  1467.      */
  1468.     public function getIdentifier(): array
  1469.     {
  1470.         return $this->identifier;
  1471.     }
  1473.     public function hasField(string $fieldName): bool
  1474.     {
  1475.         return isset($this->fieldMappings[$fieldName]) || isset($this->embeddedClasses[$fieldName]);
  1476.     }
  1478.     /**
  1479.      * Gets an array containing all the column names.
  1480.      *
  1481.      * @psalm-param list<string>|null $fieldNames
  1482.      *
  1483.      * @return mixed[]
  1484.      * @psalm-return list<string>
  1485.      */
  1486.     public function getColumnNames(array|null $fieldNames = null): array
  1487.     {
  1488.         if ($fieldNames === null) {
  1489.             return array_keys($this->fieldNames);
  1490.         }
  1492.         return array_values(array_map($this->getColumnName(...), $fieldNames));
  1493.     }
  1495.     /**
  1496.      * Returns an array with all the identifier column names.
  1497.      *
  1498.      * @psalm-return list<string>
  1499.      */
  1500.     public function getIdentifierColumnNames(): array
  1501.     {
  1502.         $columnNames = [];
  1504.         foreach ($this->identifier as $idProperty) {
  1505.             if (isset($this->fieldMappings[$idProperty])) {
  1506.                 $columnNames[] = $this->fieldMappings[$idProperty]->columnName;
  1508.                 continue;
  1509.             }
  1511.             // Association defined as Id field
  1512.             assert($this->associationMappings[$idProperty]->isToOneOwningSide());
  1513.             $joinColumns      = $this->associationMappings[$idProperty]->joinColumns;
  1514.             $assocColumnNames = array_map(static fn (JoinColumnMapping $joinColumn): string => $joinColumn->name, $joinColumns);
  1516.             $columnNames = array_merge($columnNames, $assocColumnNames);
  1517.         }
  1519.         return $columnNames;
  1520.     }
  1522.     /**
  1523.      * Sets the type of Id generator to use for the mapped class.
  1524.      *
  1525.      * @psalm-param self::GENERATOR_TYPE_* $generatorType
  1526.      */
  1527.     public function setIdGeneratorType(int $generatorType): void
  1528.     {
  1529.         $this->generatorType = $generatorType;
  1530.     }
  1532.     /**
  1533.      * Checks whether the mapped class uses an Id generator.
  1534.      */
  1535.     public function usesIdGenerator(): bool
  1536.     {
  1537.         return $this->generatorType !== self::GENERATOR_TYPE_NONE;
  1538.     }
  1540.     public function isInheritanceTypeNone(): bool
  1541.     {
  1542.         return $this->inheritanceType === self::INHERITANCE_TYPE_NONE;
  1543.     }
  1545.     /**
  1546.      * Checks whether the mapped class uses the JOINED inheritance mapping strategy.
  1547.      *
  1548.      * @return bool TRUE if the class participates in a JOINED inheritance mapping,
  1549.      * FALSE otherwise.
  1550.      */
  1551.     public function isInheritanceTypeJoined(): bool
  1552.     {
  1553.         return $this->inheritanceType === self::INHERITANCE_TYPE_JOINED;
  1554.     }
  1556.     /**
  1557.      * Checks whether the mapped class uses the SINGLE_TABLE inheritance mapping strategy.
  1558.      *
  1559.      * @return bool TRUE if the class participates in a SINGLE_TABLE inheritance mapping,
  1560.      * FALSE otherwise.
  1561.      */
  1562.     public function isInheritanceTypeSingleTable(): bool
  1563.     {
  1564.         return $this->inheritanceType === self::INHERITANCE_TYPE_SINGLE_TABLE;
  1565.     }
  1567.     /**
  1568.      * Checks whether the class uses an identity column for the Id generation.
  1569.      */
  1570.     public function isIdGeneratorIdentity(): bool
  1571.     {
  1572.         return $this->generatorType === self::GENERATOR_TYPE_IDENTITY;
  1573.     }
  1575.     /**
  1576.      * Checks whether the class uses a sequence for id generation.
  1577.      *
  1578.      * @psalm-assert-if-true !null $this->sequenceGeneratorDefinition
  1579.      */
  1580.     public function isIdGeneratorSequence(): bool
  1581.     {
  1582.         return $this->generatorType === self::GENERATOR_TYPE_SEQUENCE;
  1583.     }
  1585.     /**
  1586.      * Checks whether the class has a natural identifier/pk (which means it does
  1587.      * not use any Id generator.
  1588.      */
  1589.     public function isIdentifierNatural(): bool
  1590.     {
  1591.         return $this->generatorType === self::GENERATOR_TYPE_NONE;
  1592.     }
  1594.     /**
  1595.      * Gets the type of a field.
  1596.      *
  1597.      * @todo 3.0 Remove this. PersisterHelper should fix it somehow
  1598.      */
  1599.     public function getTypeOfField(string $fieldName): string|null
  1600.     {
  1601.         return isset($this->fieldMappings[$fieldName])
  1602.             ? $this->fieldMappings[$fieldName]->type
  1603.             : null;
  1604.     }
  1606.     /**
  1607.      * Gets the name of the primary table.
  1608.      */
  1609.     public function getTableName(): string
  1610.     {
  1611.         return $this->table['name'];
  1612.     }
  1614.     /**
  1615.      * Gets primary table's schema name.
  1616.      */
  1617.     public function getSchemaName(): string|null
  1618.     {
  1619.         return $this->table['schema'] ?? null;
  1620.     }
  1622.     /**
  1623.      * Gets the table name to use for temporary identifier tables of this class.
  1624.      */
  1625.     public function getTemporaryIdTableName(): string
  1626.     {
  1627.         // replace dots with underscores because PostgreSQL creates temporary tables in a special schema
  1628.         return str_replace('.', '_', $this->getTableName() . '_id_tmp');
  1629.     }
  1631.     /**
  1632.      * Sets the mapped subclasses of this class.
  1633.      *
  1634.      * @psalm-param list<string> $subclasses The names of all mapped subclasses.
  1635.      */
  1636.     public function setSubclasses(array $subclasses): void
  1637.     {
  1638.         foreach ($subclasses as $subclass) {
  1639.             $this->subClasses[] = $this->fullyQualifiedClassName($subclass);
  1640.         }
  1641.     }
  1643.     /**
  1644.      * Sets the parent class names. Only <em>entity</em> classes may be given.
  1645.      *
  1646.      * Assumes that the class names in the passed array are in the order:
  1647.      * directParent -> directParentParent -> directParentParentParent ... -> root.
  1648.      *
  1649.      * @psalm-param list<class-string> $classNames
  1650.      */
  1651.     public function setParentClasses(array $classNames): void
  1652.     {
  1653.         $this->parentClasses = $classNames;
  1655.         if (count($classNames) > 0) {
  1656.             $this->rootEntityName = array_pop($classNames);
  1657.         }
  1658.     }
  1660.     /**
  1661.      * Sets the inheritance type used by the class and its subclasses.
  1662.      *
  1663.      * @psalm-param self::INHERITANCE_TYPE_* $type
  1664.      *
  1665.      * @throws MappingException
  1666.      */
  1667.     public function setInheritanceType(int $type): void
  1668.     {
  1669.         if (! $this->isInheritanceType($type)) {
  1670.             throw MappingException::invalidInheritanceType($this->name, $type);
  1671.         }
  1673.         $this->inheritanceType = $type;
  1674.     }
  1676.     /**
  1677.      * Sets the association to override association mapping of property for an entity relationship.
  1678.      *
  1679.      * @psalm-param array<string, mixed> $overrideMapping
  1680.      *
  1681.      * @throws MappingException
  1682.      */
  1683.     public function setAssociationOverride(string $fieldName, array $overrideMapping): void
  1684.     {
  1685.         if (! isset($this->associationMappings[$fieldName])) {
  1686.             throw MappingException::invalidOverrideFieldName($this->name, $fieldName);
  1687.         }
  1689.         $mapping = $this->associationMappings[$fieldName]->toArray();
  1691.         if (isset($mapping['inherited'])) {
  1692.             throw MappingException::illegalOverrideOfInheritedProperty(
  1693.                 $this->name,
  1694.                 $fieldName,
  1695.                 $mapping['inherited'],
  1696.             );
  1697.         }
  1699.         if (isset($overrideMapping['joinColumns'])) {
  1700.             $mapping['joinColumns'] = $overrideMapping['joinColumns'];
  1701.         }
  1703.         if (isset($overrideMapping['inversedBy'])) {
  1704.             $mapping['inversedBy'] = $overrideMapping['inversedBy'];
  1705.         }
  1707.         if (isset($overrideMapping['joinTable'])) {
  1708.             $mapping['joinTable'] = $overrideMapping['joinTable'];
  1709.         }
  1711.         if (isset($overrideMapping['fetch'])) {
  1712.             $mapping['fetch'] = $overrideMapping['fetch'];
  1713.         }
  1715.         switch ($mapping['type']) {
  1716.             case self::ONE_TO_ONE:
  1717.             case self::MANY_TO_ONE:
  1718.                 $mapping['joinColumnFieldNames']     = [];
  1719.                 $mapping['sourceToTargetKeyColumns'] = [];
  1720.                 break;
  1721.             case self::MANY_TO_MANY:
  1722.                 $mapping['relationToSourceKeyColumns'] = [];
  1723.                 $mapping['relationToTargetKeyColumns'] = [];
  1724.                 break;
  1725.         }
  1727.         $this->associationMappings[$fieldName] = $this->_validateAndCompleteAssociationMapping($mapping);
  1728.     }
  1730.     /**
  1731.      * Sets the override for a mapped field.
  1732.      *
  1733.      * @psalm-param array<string, mixed> $overrideMapping
  1734.      *
  1735.      * @throws MappingException
  1736.      */
  1737.     public function setAttributeOverride(string $fieldName, array $overrideMapping): void
  1738.     {
  1739.         if (! isset($this->fieldMappings[$fieldName])) {
  1740.             throw MappingException::invalidOverrideFieldName($this->name, $fieldName);
  1741.         }
  1743.         $mapping = $this->fieldMappings[$fieldName];
  1745.         if (isset($mapping->inherited)) {
  1746.             throw MappingException::illegalOverrideOfInheritedProperty($this->name, $fieldName, $mapping->inherited);
  1747.         }
  1749.         if (isset($mapping->id)) {
  1750.             $overrideMapping['id'] = $mapping->id;
  1751.         }
  1753.         if (isset($mapping->declared)) {
  1754.             $overrideMapping['declared'] = $mapping->declared;
  1755.         }
  1757.         if (! isset($overrideMapping['type'])) {
  1758.             $overrideMapping['type'] = $mapping->type;
  1759.         }
  1761.         if (! isset($overrideMapping['fieldName'])) {
  1762.             $overrideMapping['fieldName'] = $mapping->fieldName;
  1763.         }
  1765.         if ($overrideMapping['type'] !== $mapping->type) {
  1766.             throw MappingException::invalidOverrideFieldType($this->name, $fieldName);
  1767.         }
  1769.         unset($this->fieldMappings[$fieldName]);
  1770.         unset($this->fieldNames[$mapping->columnName]);
  1771.         unset($this->columnNames[$mapping->fieldName]);
  1773.         $overrideMapping = $this->validateAndCompleteFieldMapping($overrideMapping);
  1775.         $this->fieldMappings[$fieldName] = $overrideMapping;
  1776.     }
  1778.     /**
  1779.      * Checks whether a mapped field is inherited from an entity superclass.
  1780.      */
  1781.     public function isInheritedField(string $fieldName): bool
  1782.     {
  1783.         return isset($this->fieldMappings[$fieldName]->inherited);
  1784.     }
  1786.     /**
  1787.      * Checks if this entity is the root in any entity-inheritance-hierarchy.
  1788.      */
  1789.     public function isRootEntity(): bool
  1790.     {
  1791.         return $this->name === $this->rootEntityName;
  1792.     }
  1794.     /**
  1795.      * Checks whether a mapped association field is inherited from a superclass.
  1796.      */
  1797.     public function isInheritedAssociation(string $fieldName): bool
  1798.     {
  1799.         return isset($this->associationMappings[$fieldName]->inherited);
  1800.     }
  1802.     public function isInheritedEmbeddedClass(string $fieldName): bool
  1803.     {
  1804.         return isset($this->embeddedClasses[$fieldName]->inherited);
  1805.     }
  1807.     /**
  1808.      * Sets the name of the primary table the class is mapped to.
  1809.      *
  1810.      * @deprecated Use {@link setPrimaryTable}.
  1811.      */
  1812.     public function setTableName(string $tableName): void
  1813.     {
  1814.         $this->table['name'] = $tableName;
  1815.     }
  1817.     /**
  1818.      * Sets the primary table definition. The provided array supports the
  1819.      * following structure:
  1820.      *
  1821.      * name => <tableName> (optional, defaults to class name)
  1822.      * indexes => array of indexes (optional)
  1823.      * uniqueConstraints => array of constraints (optional)
  1824.      *
  1825.      * If a key is omitted, the current value is kept.
  1826.      *
  1827.      * @psalm-param array<string, mixed> $table The table description.
  1828.      */
  1829.     public function setPrimaryTable(array $table): void
  1830.     {
  1831.         if (isset($table['name'])) {
  1832.             // Split schema and table name from a table name like "myschema.mytable"
  1833.             if (str_contains($table['name'], '.')) {
  1834.                 [$this->table['schema'], $table['name']] = explode('.', $table['name'], 2);
  1835.             }
  1837.             if ($table['name'][0] === '`') {
  1838.                 $table['name']         = trim($table['name'], '`');
  1839.                 $this->table['quoted'] = true;
  1840.             }
  1842.             $this->table['name'] = $table['name'];
  1843.         }
  1845.         if (isset($table['quoted'])) {
  1846.             $this->table['quoted'] = $table['quoted'];
  1847.         }
  1849.         if (isset($table['schema'])) {
  1850.             $this->table['schema'] = $table['schema'];
  1851.         }
  1853.         if (isset($table['indexes'])) {
  1854.             $this->table['indexes'] = $table['indexes'];
  1855.         }
  1857.         if (isset($table['uniqueConstraints'])) {
  1858.             $this->table['uniqueConstraints'] = $table['uniqueConstraints'];
  1859.         }
  1861.         if (isset($table['options'])) {
  1862.             $this->table['options'] = $table['options'];
  1863.         }
  1864.     }
  1866.     /**
  1867.      * Checks whether the given type identifies an inheritance type.
  1868.      */
  1869.     private function isInheritanceType(int $type): bool
  1870.     {
  1871.         return $type === self::INHERITANCE_TYPE_NONE ||
  1872.                 $type === self::INHERITANCE_TYPE_SINGLE_TABLE ||
  1873.                 $type === self::INHERITANCE_TYPE_JOINED;
  1874.     }
  1876.     /**
  1877.      * Adds a mapped field to the class.
  1878.      *
  1879.      * @psalm-param array<string, mixed> $mapping The field mapping.
  1880.      *
  1881.      * @throws MappingException
  1882.      */
  1883.     public function mapField(array $mapping): void
  1884.     {
  1885.         $mapping = $this->validateAndCompleteFieldMapping($mapping);
  1886.         $this->assertFieldNotMapped($mapping->fieldName);
  1888.         if (isset($mapping->generated)) {
  1889.             $this->requiresFetchAfterChange = true;
  1890.         }
  1892.         $this->fieldMappings[$mapping->fieldName] = $mapping;
  1893.     }
  1895.     /**
  1896.      * INTERNAL:
  1897.      * Adds an association mapping without completing/validating it.
  1898.      * This is mainly used to add inherited association mappings to derived classes.
  1899.      *
  1900.      * @param ConcreteAssociationMapping $mapping
  1901.      *
  1902.      * @throws MappingException
  1903.      */
  1904.     public function addInheritedAssociationMapping(AssociationMapping $mapping/*, $owningClassName = null*/): void
  1905.     {
  1906.         if (isset($this->associationMappings[$mapping->fieldName])) {
  1907.             throw MappingException::duplicateAssociationMapping($this->name, $mapping->fieldName);
  1908.         }
  1910.         $this->associationMappings[$mapping->fieldName] = $mapping;
  1911.     }
  1913.     /**
  1914.      * INTERNAL:
  1915.      * Adds a field mapping without completing/validating it.
  1916.      * This is mainly used to add inherited field mappings to derived classes.
  1917.      */
  1918.     public function addInheritedFieldMapping(FieldMapping $fieldMapping): void
  1919.     {
  1920.         $this->fieldMappings[$fieldMapping->fieldName] = $fieldMapping;
  1921.         $this->columnNames[$fieldMapping->fieldName]   = $fieldMapping->columnName;
  1922.         $this->fieldNames[$fieldMapping->columnName]   = $fieldMapping->fieldName;
  1924.         if (isset($fieldMapping->generated)) {
  1925.             $this->requiresFetchAfterChange = true;
  1926.         }
  1927.     }
  1929.     /**
  1930.      * Adds a one-to-one mapping.
  1931.      *
  1932.      * @param array<string, mixed> $mapping The mapping.
  1933.      */
  1934.     public function mapOneToOne(array $mapping): void
  1935.     {
  1936.         $mapping['type'] = self::ONE_TO_ONE;
  1938.         $mapping = $this->_validateAndCompleteAssociationMapping($mapping);
  1940.         $this->_storeAssociationMapping($mapping);
  1941.     }
  1943.     /**
  1944.      * Adds a one-to-many mapping.
  1945.      *
  1946.      * @psalm-param array<string, mixed> $mapping The mapping.
  1947.      */
  1948.     public function mapOneToMany(array $mapping): void
  1949.     {
  1950.         $mapping['type'] = self::ONE_TO_MANY;
  1952.         $mapping = $this->_validateAndCompleteAssociationMapping($mapping);
  1954.         $this->_storeAssociationMapping($mapping);
  1955.     }
  1957.     /**
  1958.      * Adds a many-to-one mapping.
  1959.      *
  1960.      * @psalm-param array<string, mixed> $mapping The mapping.
  1961.      */
  1962.     public function mapManyToOne(array $mapping): void
  1963.     {
  1964.         $mapping['type'] = self::MANY_TO_ONE;
  1966.         $mapping = $this->_validateAndCompleteAssociationMapping($mapping);
  1968.         $this->_storeAssociationMapping($mapping);
  1969.     }
  1971.     /**
  1972.      * Adds a many-to-many mapping.
  1973.      *
  1974.      * @psalm-param array<string, mixed> $mapping The mapping.
  1975.      */
  1976.     public function mapManyToMany(array $mapping): void
  1977.     {
  1978.         $mapping['type'] = self::MANY_TO_MANY;
  1980.         $mapping = $this->_validateAndCompleteAssociationMapping($mapping);
  1982.         $this->_storeAssociationMapping($mapping);
  1983.     }
  1985.     /**
  1986.      * Stores the association mapping.
  1987.      *
  1988.      * @param ConcreteAssociationMapping $assocMapping
  1989.      *
  1990.      * @throws MappingException
  1991.      */
  1992.     protected function _storeAssociationMapping(AssociationMapping $assocMapping): void
  1993.     {
  1994.         $sourceFieldName = $assocMapping->fieldName;
  1996.         $this->assertFieldNotMapped($sourceFieldName);
  1998.         $this->associationMappings[$sourceFieldName] = $assocMapping;
  1999.     }
  2001.     /**
  2002.      * Registers a custom repository class for the entity class.
  2003.      *
  2004.      * @param string|null $repositoryClassName The class name of the custom mapper.
  2005.      * @psalm-param class-string<EntityRepository>|null $repositoryClassName
  2006.      */
  2007.     public function setCustomRepositoryClass(string|null $repositoryClassName): void
  2008.     {
  2009.         if ($repositoryClassName === null) {
  2010.             $this->customRepositoryClassName = null;
  2012.             return;
  2013.         }
  2015.         $this->customRepositoryClassName = $this->fullyQualifiedClassName($repositoryClassName);
  2016.     }
  2018.     /**
  2019.      * Dispatches the lifecycle event of the given entity to the registered
  2020.      * lifecycle callbacks and lifecycle listeners.
  2021.      *
  2022.      * @deprecated Deprecated since version 2.4 in favor of \Doctrine\ORM\Event\ListenersInvoker
  2023.      *
  2024.      * @param string $lifecycleEvent The lifecycle event.
  2025.      */
  2026.     public function invokeLifecycleCallbacks(string $lifecycleEvent, object $entity): void
  2027.     {
  2028.         foreach ($this->lifecycleCallbacks[$lifecycleEvent] as $callback) {
  2029.             $entity->$callback();
  2030.         }
  2031.     }
  2033.     /**
  2034.      * Whether the class has any attached lifecycle listeners or callbacks for a lifecycle event.
  2035.      */
  2036.     public function hasLifecycleCallbacks(string $lifecycleEvent): bool
  2037.     {
  2038.         return isset($this->lifecycleCallbacks[$lifecycleEvent]);
  2039.     }
  2041.     /**
  2042.      * Gets the registered lifecycle callbacks for an event.
  2043.      *
  2044.      * @return string[]
  2045.      * @psalm-return list<string>
  2046.      */
  2047.     public function getLifecycleCallbacks(string $event): array
  2048.     {
  2049.         return $this->lifecycleCallbacks[$event] ?? [];
  2050.     }
  2052.     /**
  2053.      * Adds a lifecycle callback for entities of this class.
  2054.      */
  2055.     public function addLifecycleCallback(string $callback, string $event): void
  2056.     {
  2057.         if ($this->isEmbeddedClass) {
  2058.             throw MappingException::illegalLifecycleCallbackOnEmbeddedClass($callback, $this->name);
  2059.         }
  2061.         if (isset($this->lifecycleCallbacks[$event]) && in_array($callback, $this->lifecycleCallbacks[$event], true)) {
  2062.             return;
  2063.         }
  2065.         $this->lifecycleCallbacks[$event][] = $callback;
  2066.     }
  2068.     /**
  2069.      * Sets the lifecycle callbacks for entities of this class.
  2070.      * Any previously registered callbacks are overwritten.
  2071.      *
  2072.      * @psalm-param array<string, list<string>> $callbacks
  2073.      */
  2074.     public function setLifecycleCallbacks(array $callbacks): void
  2075.     {
  2076.         $this->lifecycleCallbacks = $callbacks;
  2077.     }
  2079.     /**
  2080.      * Adds a entity listener for entities of this class.
  2081.      *
  2082.      * @param string $eventName The entity lifecycle event.
  2083.      * @param string $class     The listener class.
  2084.      * @param string $method    The listener callback method.
  2085.      *
  2086.      * @throws MappingException
  2087.      */
  2088.     public function addEntityListener(string $eventName, string $class, string $method): void
  2089.     {
  2090.         $class = $this->fullyQualifiedClassName($class);
  2092.         $listener = [
  2093.             'class'  => $class,
  2094.             'method' => $method,
  2095.         ];
  2097.         if (! class_exists($class)) {
  2098.             throw MappingException::entityListenerClassNotFound($class, $this->name);
  2099.         }
  2101.         if (! method_exists($class, $method)) {
  2102.             throw MappingException::entityListenerMethodNotFound($class, $method, $this->name);
  2103.         }
  2105.         if (isset($this->entityListeners[$eventName]) && in_array($listener, $this->entityListeners[$eventName], true)) {
  2106.             throw MappingException::duplicateEntityListener($class, $method, $this->name);
  2107.         }
  2109.         $this->entityListeners[$eventName][] = $listener;
  2110.     }
  2112.     /**
  2113.      * Sets the discriminator column definition.
  2114.      *
  2115.      * @see getDiscriminatorColumn()
  2116.      *
  2117.      * @param DiscriminatorColumnMapping|mixed[]|null $columnDef
  2118.      * @psalm-param DiscriminatorColumnMapping|array{
  2119.      *     name: string|null,
  2120.      *     fieldName?: string|null,
  2121.      *     type?: string|null,
  2122.      *     length?: int|null,
  2123.      *     columnDefinition?: string|null,
  2124.      *     enumType?: class-string<BackedEnum>|null,
  2125.      *     options?: array<string, mixed>|null
  2126.      * }|null $columnDef
  2127.      *
  2128.      * @throws MappingException
  2129.      */
  2130.     public function setDiscriminatorColumn(DiscriminatorColumnMapping|array|null $columnDef): void
  2131.     {
  2132.         if ($columnDef instanceof DiscriminatorColumnMapping) {
  2133.             $this->discriminatorColumn = $columnDef;
  2135.             return;
  2136.         }
  2138.         if ($columnDef !== null) {
  2139.             if (! isset($columnDef['name'])) {
  2140.                 throw MappingException::nameIsMandatoryForDiscriminatorColumns($this->name);
  2141.             }
  2143.             if (isset($this->fieldNames[$columnDef['name']])) {
  2144.                 throw MappingException::duplicateColumnName($this->name, $columnDef['name']);
  2145.             }
  2147.             $columnDef['fieldName'] ??= $columnDef['name'];
  2148.             $columnDef['type']      ??= 'string';
  2149.             $columnDef['options']   ??= [];
  2151.             if (in_array($columnDef['type'], ['boolean', 'array', 'object', 'datetime', 'time', 'date'], true)) {
  2152.                 throw MappingException::invalidDiscriminatorColumnType($this->name, $columnDef['type']);
  2153.             }
  2155.             $this->discriminatorColumn = DiscriminatorColumnMapping::fromMappingArray($columnDef);
  2156.         }
  2157.     }
  2159.     final public function getDiscriminatorColumn(): DiscriminatorColumnMapping
  2160.     {
  2161.         if ($this->discriminatorColumn === null) {
  2162.             throw new LogicException('The discriminator column was not set.');
  2163.         }
  2165.         return $this->discriminatorColumn;
  2166.     }
  2168.     /**
  2169.      * Sets the discriminator values used by this class.
  2170.      * Used for JOINED and SINGLE_TABLE inheritance mapping strategies.
  2171.      *
  2172.      * @param array<int|string, string> $map
  2173.      */
  2174.     public function setDiscriminatorMap(array $map): void
  2175.     {
  2176.         foreach ($map as $value => $className) {
  2177.             $this->addDiscriminatorMapClass($value, $className);
  2178.         }
  2179.     }
  2181.     /**
  2182.      * Adds one entry of the discriminator map with a new class and corresponding name.
  2183.      *
  2184.      * @throws MappingException
  2185.      */
  2186.     public function addDiscriminatorMapClass(int|string $name, string $className): void
  2187.     {
  2188.         $className = $this->fullyQualifiedClassName($className);
  2189.         $className = ltrim($className, '\\');
  2191.         $this->discriminatorMap[$name] = $className;
  2193.         if ($this->name === $className) {
  2194.             $this->discriminatorValue = $name;
  2196.             return;
  2197.         }
  2199.         if (! (class_exists($className) || interface_exists($className))) {
  2200.             throw MappingException::invalidClassInDiscriminatorMap($className, $this->name);
  2201.         }
  2203.         $this->addSubClass($className);
  2204.     }
  2206.     /** @param array<class-string> $classes */
  2207.     public function addSubClasses(array $classes): void
  2208.     {
  2209.         foreach ($classes as $className) {
  2210.             $this->addSubClass($className);
  2211.         }
  2212.     }
  2214.     public function addSubClass(string $className): void
  2215.     {
  2216.         // By ignoring classes that are not subclasses of the current class, we simplify inheriting
  2217.         // the subclass list from a parent class at the beginning of \Doctrine\ORM\Mapping\ClassMetadataFactory::doLoadMetadata.
  2219.         if (is_subclass_of($className, $this->name) && ! in_array($className, $this->subClasses, true)) {
  2220.             $this->subClasses[] = $className;
  2221.         }
  2222.     }
  2224.     public function hasAssociation(string $fieldName): bool
  2225.     {
  2226.         return isset($this->associationMappings[$fieldName]);
  2227.     }
  2229.     public function isSingleValuedAssociation(string $fieldName): bool
  2230.     {
  2231.         return isset($this->associationMappings[$fieldName])
  2232.             && ($this->associationMappings[$fieldName]->isToOne());
  2233.     }
  2235.     public function isCollectionValuedAssociation(string $fieldName): bool
  2236.     {
  2237.         return isset($this->associationMappings[$fieldName])
  2238.             && ! $this->associationMappings[$fieldName]->isToOne();
  2239.     }
  2241.     /**
  2242.      * Is this an association that only has a single join column?
  2243.      */
  2244.     public function isAssociationWithSingleJoinColumn(string $fieldName): bool
  2245.     {
  2246.         return isset($this->associationMappings[$fieldName])
  2247.             && isset($this->associationMappings[$fieldName]->joinColumns[0])
  2248.             && ! isset($this->associationMappings[$fieldName]->joinColumns[1]);
  2249.     }
  2251.     /**
  2252.      * Returns the single association join column (if any).
  2253.      *
  2254.      * @throws MappingException
  2255.      */
  2256.     public function getSingleAssociationJoinColumnName(string $fieldName): string
  2257.     {
  2258.         if (! $this->isAssociationWithSingleJoinColumn($fieldName)) {
  2259.             throw MappingException::noSingleAssociationJoinColumnFound($this->name, $fieldName);
  2260.         }
  2262.         $assoc = $this->associationMappings[$fieldName];
  2264.         assert($assoc->isToOneOwningSide());
  2266.         return $assoc->joinColumns[0]->name;
  2267.     }
  2269.     /**
  2270.      * Returns the single association referenced join column name (if any).
  2271.      *
  2272.      * @throws MappingException
  2273.      */
  2274.     public function getSingleAssociationReferencedJoinColumnName(string $fieldName): string
  2275.     {
  2276.         if (! $this->isAssociationWithSingleJoinColumn($fieldName)) {
  2277.             throw MappingException::noSingleAssociationJoinColumnFound($this->name, $fieldName);
  2278.         }
  2280.         $assoc = $this->associationMappings[$fieldName];
  2282.         assert($assoc->isToOneOwningSide());
  2284.         return $assoc->joinColumns[0]->referencedColumnName;
  2285.     }
  2287.     /**
  2288.      * Used to retrieve a fieldname for either field or association from a given column.
  2289.      *
  2290.      * This method is used in foreign-key as primary-key contexts.
  2291.      *
  2292.      * @throws MappingException
  2293.      */
  2294.     public function getFieldForColumn(string $columnName): string
  2295.     {
  2296.         if (isset($this->fieldNames[$columnName])) {
  2297.             return $this->fieldNames[$columnName];
  2298.         }
  2300.         foreach ($this->associationMappings as $assocName => $mapping) {
  2301.             if (
  2302.                 $this->isAssociationWithSingleJoinColumn($assocName) &&
  2303.                 assert($this->associationMappings[$assocName]->isToOneOwningSide()) &&
  2304.                 $this->associationMappings[$assocName]->joinColumns[0]->name === $columnName
  2305.             ) {
  2306.                 return $assocName;
  2307.             }
  2308.         }
  2310.         throw MappingException::noFieldNameFoundForColumn($this->name, $columnName);
  2311.     }
  2313.     /**
  2314.      * Sets the ID generator used to generate IDs for instances of this class.
  2315.      */
  2316.     public function setIdGenerator(AbstractIdGenerator $generator): void
  2317.     {
  2318.         $this->idGenerator = $generator;
  2319.     }
  2321.     /**
  2322.      * Sets definition.
  2323.      *
  2324.      * @psalm-param array<string, string|null> $definition
  2325.      */
  2326.     public function setCustomGeneratorDefinition(array $definition): void
  2327.     {
  2328.         $this->customGeneratorDefinition = $definition;
  2329.     }
  2331.     /**
  2332.      * Sets the definition of the sequence ID generator for this class.
  2333.      *
  2334.      * The definition must have the following structure:
  2335.      * <code>
  2336.      * array(
  2337.      *     'sequenceName'   => 'name',
  2338.      *     'allocationSize' => 20,
  2339.      *     'initialValue'   => 1
  2340.      *     'quoted'         => 1
  2341.      * )
  2342.      * </code>
  2343.      *
  2344.      * @psalm-param array{sequenceName?: string, allocationSize?: int|string, initialValue?: int|string, quoted?: mixed} $definition
  2345.      *
  2346.      * @throws MappingException
  2347.      */
  2348.     public function setSequenceGeneratorDefinition(array $definition): void
  2349.     {
  2350.         if (! isset($definition['sequenceName']) || trim($definition['sequenceName']) === '') {
  2351.             throw MappingException::missingSequenceName($this->name);
  2352.         }
  2354.         if ($definition['sequenceName'][0] === '`') {
  2355.             $definition['sequenceName'] = trim($definition['sequenceName'], '`');
  2356.             $definition['quoted']       = true;
  2357.         }
  2359.         if (! isset($definition['allocationSize']) || trim((string) $definition['allocationSize']) === '') {
  2360.             $definition['allocationSize'] = '1';
  2361.         }
  2363.         if (! isset($definition['initialValue']) || trim((string) $definition['initialValue']) === '') {
  2364.             $definition['initialValue'] = '1';
  2365.         }
  2367.         $definition['allocationSize'] = (string) $definition['allocationSize'];
  2368.         $definition['initialValue']   = (string) $definition['initialValue'];
  2370.         $this->sequenceGeneratorDefinition = $definition;
  2371.     }
  2373.     /**
  2374.      * Sets the version field mapping used for versioning. Sets the default
  2375.      * value to use depending on the column type.
  2376.      *
  2377.      * @psalm-param array<string, mixed> $mapping The version field mapping array.
  2378.      *
  2379.      * @throws MappingException
  2380.      */
  2381.     public function setVersionMapping(array &$mapping): void
  2382.     {
  2383.         $this->isVersioned              = true;
  2384.         $this->versionField             = $mapping['fieldName'];
  2385.         $this->requiresFetchAfterChange = true;
  2387.         if (! isset($mapping['default'])) {
  2388.             if (in_array($mapping['type'], ['integer', 'bigint', 'smallint'], true)) {
  2389.                 $mapping['default'] = 1;
  2390.             } elseif ($mapping['type'] === 'datetime') {
  2391.                 $mapping['default'] = 'CURRENT_TIMESTAMP';
  2392.             } else {
  2393.                 throw MappingException::unsupportedOptimisticLockingType($this->name, $mapping['fieldName'], $mapping['type']);
  2394.             }
  2395.         }
  2396.     }
  2398.     /**
  2399.      * Sets whether this class is to be versioned for optimistic locking.
  2400.      */
  2401.     public function setVersioned(bool $bool): void
  2402.     {
  2403.         $this->isVersioned = $bool;
  2405.         if ($bool) {
  2406.             $this->requiresFetchAfterChange = true;
  2407.         }
  2408.     }
  2410.     /**
  2411.      * Sets the name of the field that is to be used for versioning if this class is
  2412.      * versioned for optimistic locking.
  2413.      */
  2414.     public function setVersionField(string|null $versionField): void
  2415.     {
  2416.         $this->versionField = $versionField;
  2417.     }
  2419.     /**
  2420.      * Marks this class as read only, no change tracking is applied to it.
  2421.      */
  2422.     public function markReadOnly(): void
  2423.     {
  2424.         $this->isReadOnly = true;
  2425.     }
  2427.     /**
  2428.      * {@inheritDoc}
  2429.      */
  2430.     public function getFieldNames(): array
  2431.     {
  2432.         return array_keys($this->fieldMappings);
  2433.     }
  2435.     /**
  2436.      * {@inheritDoc}
  2437.      */
  2438.     public function getAssociationNames(): array
  2439.     {
  2440.         return array_keys($this->associationMappings);
  2441.     }
  2443.     /**
  2444.      * {@inheritDoc}
  2445.      *
  2446.      * @psalm-return class-string
  2447.      *
  2448.      * @throws InvalidArgumentException
  2449.      */
  2450.     public function getAssociationTargetClass(string $assocName): string
  2451.     {
  2452.         return $this->associationMappings[$assocName]->targetEntity
  2453.             ?? throw new InvalidArgumentException("Association name expected, '" . $assocName . "' is not an association.");
  2454.     }
  2456.     public function getName(): string
  2457.     {
  2458.         return $this->name;
  2459.     }
  2461.     public function isAssociationInverseSide(string $assocName): bool
  2462.     {
  2463.         return isset($this->associationMappings[$assocName])
  2464.             && ! $this->associationMappings[$assocName]->isOwningSide();
  2465.     }
  2467.     public function getAssociationMappedByTargetField(string $assocName): string
  2468.     {
  2469.         $assoc = $this->getAssociationMapping($assocName);
  2471.         if (! $assoc instanceof InverseSideMapping) {
  2472.             throw new LogicException(sprintf(
  2473.                 <<<'EXCEPTION'
  2474.                 Context: Calling %s() with "%s", which is the owning side of an association.
  2475.                 Problem: The owning side of an association has no "mappedBy" field.
  2476.                 Solution: Call %s::isAssociationInverseSide() to check first.
  2477.                 EXCEPTION,
  2478.                 __METHOD__,
  2479.                 $assocName,
  2480.                 self::class,
  2481.             ));
  2482.         }
  2484.         return $assoc->mappedBy;
  2485.     }
  2487.     /**
  2488.      * @param C $className
  2489.      *
  2490.      * @return string|null null if and only if the input value is null
  2491.      * @psalm-return (C is class-string ? class-string : (C is string ? string : null))
  2492.      *
  2493.      * @template C of string|null
  2494.      */
  2495.     public function fullyQualifiedClassName(string|null $className): string|null
  2496.     {
  2497.         if ($className === null) {
  2498.             Deprecation::trigger(
  2499.                 'doctrine/orm',
  2500.                 'https://github.com/doctrine/orm/pull/11294',
  2501.                 'Passing null to %s is deprecated and will not be supported in Doctrine ORM 4.0',
  2502.                 __METHOD__,
  2503.             );
  2505.             return null;
  2506.         }
  2508.         if (! str_contains($className, '\\') && $this->namespace) {
  2509.             return $this->namespace . '\\' . $className;
  2510.         }
  2512.         return $className;
  2513.     }
  2515.     public function getMetadataValue(string $name): mixed
  2516.     {
  2517.         return $this->$name ?? null;
  2518.     }
  2520.     /**
  2521.      * Map Embedded Class
  2522.      *
  2523.      * @psalm-param array{
  2524.      *     fieldName: string,
  2525.      *     class?: class-string,
  2526.      *     declaredField?: string,
  2527.      *     columnPrefix?: string|false|null,
  2528.      *     originalField?: string
  2529.      * } $mapping
  2530.      *
  2531.      * @throws MappingException
  2532.      */
  2533.     public function mapEmbedded(array $mapping): void
  2534.     {
  2535.         $this->assertFieldNotMapped($mapping['fieldName']);
  2537.         if (! isset($mapping['class']) && $this->isTypedProperty($mapping['fieldName'])) {
  2538.             $type = $this->reflClass->getProperty($mapping['fieldName'])->getType();
  2539.             if ($type instanceof ReflectionNamedType) {
  2540.                 $mapping['class'] = $type->getName();
  2541.             }
  2542.         }
  2544.         if (! (isset($mapping['class']) && $mapping['class'])) {
  2545.             throw MappingException::missingEmbeddedClass($mapping['fieldName']);
  2546.         }
  2548.         $this->embeddedClasses[$mapping['fieldName']] = EmbeddedClassMapping::fromMappingArray([
  2549.             'class' => $this->fullyQualifiedClassName($mapping['class']),
  2550.             'columnPrefix' => $mapping['columnPrefix'] ?? null,
  2551.             'declaredField' => $mapping['declaredField'] ?? null,
  2552.             'originalField' => $mapping['originalField'] ?? null,
  2553.         ]);
  2554.     }
  2556.     /**
  2557.      * Inline the embeddable class
  2558.      */
  2559.     public function inlineEmbeddable(string $property, ClassMetadata $embeddable): void
  2560.     {
  2561.         foreach ($embeddable->fieldMappings as $originalFieldMapping) {
  2562.             $fieldMapping                    = (array) $originalFieldMapping;
  2563.             $fieldMapping['originalClass'] ??= $embeddable->name;
  2564.             $fieldMapping['declaredField']   = isset($fieldMapping['declaredField'])
  2565.                 ? $property . '.' . $fieldMapping['declaredField']
  2566.                 : $property;
  2567.             $fieldMapping['originalField'] ??= $fieldMapping['fieldName'];
  2568.             $fieldMapping['fieldName']       = $property . '.' . $fieldMapping['fieldName'];
  2570.             if (! empty($this->embeddedClasses[$property]->columnPrefix)) {
  2571.                 $fieldMapping['columnName'] = $this->embeddedClasses[$property]->columnPrefix . $fieldMapping['columnName'];
  2572.             } elseif ($this->embeddedClasses[$property]->columnPrefix !== false) {
  2573.                 assert($this->reflClass !== null);
  2574.                 assert($embeddable->reflClass !== null);
  2575.                 $fieldMapping['columnName'] = $this->namingStrategy
  2576.                     ->embeddedFieldToColumnName(
  2577.                         $property,
  2578.                         $fieldMapping['columnName'],
  2579.                         $this->reflClass->name,
  2580.                         $embeddable->reflClass->name,
  2581.                     );
  2582.             }
  2584.             $this->mapField($fieldMapping);
  2585.         }
  2586.     }
  2588.     /** @throws MappingException */
  2589.     private function assertFieldNotMapped(string $fieldName): void
  2590.     {
  2591.         if (
  2592.             isset($this->fieldMappings[$fieldName]) ||
  2593.             isset($this->associationMappings[$fieldName]) ||
  2594.             isset($this->embeddedClasses[$fieldName])
  2595.         ) {
  2596.             throw MappingException::duplicateFieldMapping($this->name, $fieldName);
  2597.         }
  2598.     }
  2600.     /**
  2601.      * Gets the sequence name based on class metadata.
  2602.      *
  2603.      * @todo Sequence names should be computed in DBAL depending on the platform
  2604.      */
  2605.     public function getSequenceName(AbstractPlatform $platform): string
  2606.     {
  2607.         $sequencePrefix = $this->getSequencePrefix($platform);
  2608.         $columnName     = $this->getSingleIdentifierColumnName();
  2610.         return $sequencePrefix . '_' . $columnName . '_seq';
  2611.     }
  2613.     /**
  2614.      * Gets the sequence name prefix based on class metadata.
  2615.      *
  2616.      * @todo Sequence names should be computed in DBAL depending on the platform
  2617.      */
  2618.     public function getSequencePrefix(AbstractPlatform $platform): string
  2619.     {
  2620.         $tableName      = $this->getTableName();
  2621.         $sequencePrefix = $tableName;
  2623.         // Prepend the schema name to the table name if there is one
  2624.         $schemaName = $this->getSchemaName();
  2625.         if ($schemaName) {
  2626.             $sequencePrefix = $schemaName . '.' . $tableName;
  2627.         }
  2629.         return $sequencePrefix;
  2630.     }
  2632.     /** @psalm-param class-string $class */
  2633.     private function getAccessibleProperty(ReflectionService $reflService, string $class, string $field): ReflectionProperty|null
  2634.     {
  2635.         $reflectionProperty = $reflService->getAccessibleProperty($class, $field);
  2636.         if ($reflectionProperty?->isReadOnly()) {
  2637.             $declaringClass = $reflectionProperty->class;
  2638.             if ($declaringClass !== $class) {
  2639.                 $reflectionProperty = $reflService->getAccessibleProperty($declaringClass, $field);
  2640.             }
  2642.             if ($reflectionProperty !== null) {
  2643.                 $reflectionProperty = new ReflectionReadonlyProperty($reflectionProperty);
  2644.             }
  2645.         }
  2647.         return $reflectionProperty;
  2648.     }
  2649. }