vendor/doctrine/orm/lib/Doctrine/ORM/Mapping/ClassMetadataInfo.php line 1267

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