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

Open in your IDE?
  1. <?php
  3. /*
  4.  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  5.  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  6.  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  7.  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  8.  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  9.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  10.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  11.  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  12.  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  13.  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  14.  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  15.  *
  16.  * This software consists of voluntary contributions made by many individuals
  17.  * and is licensed under the MIT license. For more information, see
  18.  * <http://www.doctrine-project.org>.
  19.  */
  21. namespace Doctrine\ORM\Mapping;
  23. use BadMethodCallException;
  24. use DateInterval;
  25. use DateTime;
  26. use DateTimeImmutable;
  27. use Doctrine\DBAL\Platforms\AbstractPlatform;
  28. use Doctrine\DBAL\Types\Type;
  29. use Doctrine\DBAL\Types\Types;
  30. use Doctrine\Deprecations\Deprecation;
  31. use Doctrine\Instantiator\Instantiator;
  32. use Doctrine\Instantiator\InstantiatorInterface;
  33. use Doctrine\ORM\Cache\CacheException;
  34. use Doctrine\ORM\Id\AbstractIdGenerator;
  35. use Doctrine\Persistence\Mapping\ClassMetadata;
  36. use Doctrine\Persistence\Mapping\ReflectionService;
  37. use InvalidArgumentException;
  38. use ReflectionClass;
  39. use ReflectionNamedType;
  40. use ReflectionProperty;
  41. use RuntimeException;
  43. use function array_diff;
  44. use function array_flip;
  45. use function array_intersect;
  46. use function array_keys;
  47. use function array_map;
  48. use function array_merge;
  49. use function array_pop;
  50. use function array_values;
  51. use function class_exists;
  52. use function count;
  53. use function explode;
  54. use function gettype;
  55. use function in_array;
  56. use function interface_exists;
  57. use function is_array;
  58. use function is_subclass_of;
  59. use function ltrim;
  60. use function method_exists;
  61. use function spl_object_hash;
  62. use function str_replace;
  63. use function strpos;
  64. use function strtolower;
  65. use function trait_exists;
  66. use function trim;
  68. use const PHP_VERSION_ID;
  70. /**
  71.  * A <tt>ClassMetadata</tt> instance holds all the object-relational mapping metadata
  72.  * of an entity and its associations.
  73.  *
  74.  * Once populated, ClassMetadata instances are usually cached in a serialized form.
  75.  *
  76.  * <b>IMPORTANT NOTE:</b>
  77.  *
  78.  * The fields of this class are only public for 2 reasons:
  79.  * 1) To allow fast READ access.
  80.  * 2) To drastically reduce the size of a serialized instance (private/protected members
  81.  *    get the whole class name, namespace inclusive, prepended to every property in
  82.  *    the serialized representation).
  83.  *
  84.  * @template T of object
  85.  * @template-implements ClassMetadata<T>
  86.  */
  87. class ClassMetadataInfo implements ClassMetadata
  88. {
  89.     /* The inheritance mapping types */
  90.     /**
  91.      * NONE means the class does not participate in an inheritance hierarchy
  92.      * and therefore does not need an inheritance mapping type.
  93.      */
  94.     public const INHERITANCE_TYPE_NONE = 1;
  96.     /**
  97.      * JOINED means the class will be persisted according to the rules of
  98.      * <tt>Class Table Inheritance</tt>.
  99.      */
  100.     public const INHERITANCE_TYPE_JOINED = 2;
  102.     /**
  103.      * SINGLE_TABLE means the class will be persisted according to the rules of
  104.      * <tt>Single Table Inheritance</tt>.
  105.      */
  106.     public const INHERITANCE_TYPE_SINGLE_TABLE = 3;
  108.     /**
  109.      * TABLE_PER_CLASS means the class will be persisted according to the rules
  110.      * of <tt>Concrete Table Inheritance</tt>.
  111.      */
  112.     public const INHERITANCE_TYPE_TABLE_PER_CLASS = 4;
  114.     /* The Id generator types. */
  115.     /**
  116.      * AUTO means the generator type will depend on what the used platform prefers.
  117.      * Offers full portability.
  118.      */
  119.     public const GENERATOR_TYPE_AUTO = 1;
  121.     /**
  122.      * SEQUENCE means a separate sequence object will be used. Platforms that do
  123.      * not have native sequence support may emulate it. Full portability is currently
  124.      * not guaranteed.
  125.      */
  126.     public const GENERATOR_TYPE_SEQUENCE = 2;
  128.     /**
  129.      * TABLE means a separate table is used for id generation.
  130.      * Offers full portability.
  131.      */
  132.     public const GENERATOR_TYPE_TABLE = 3;
  134.     /**
  135.      * IDENTITY means an identity column is used for id generation. The database
  136.      * will fill in the id column on insertion. Platforms that do not support
  137.      * native identity columns may emulate them. Full portability is currently
  138.      * not guaranteed.
  139.      */
  140.     public const GENERATOR_TYPE_IDENTITY = 4;
  142.     /**
  143.      * NONE means the class does not have a generated id. That means the class
  144.      * must have a natural, manually assigned id.
  145.      */
  146.     public const GENERATOR_TYPE_NONE = 5;
  148.     /**
  149.      * UUID means that a UUID/GUID expression is used for id generation. Full
  150.      * portability is currently not guaranteed.
  151.      */
  152.     public const GENERATOR_TYPE_UUID = 6;
  154.     /**
  155.      * CUSTOM means that customer will use own ID generator that supposedly work
  156.      */
  157.     public const GENERATOR_TYPE_CUSTOM = 7;
  159.     /**
  160.      * DEFERRED_IMPLICIT means that changes of entities are calculated at commit-time
  161.      * by doing a property-by-property comparison with the original data. This will
  162.      * be done for all entities that are in MANAGED state at commit-time.
  163.      *
  164.      * This is the default change tracking policy.
  165.      */
  166.     public const CHANGETRACKING_DEFERRED_IMPLICIT = 1;
  168.     /**
  169.      * DEFERRED_EXPLICIT means that changes of entities are calculated at commit-time
  170.      * by doing a property-by-property comparison with the original data. This will
  171.      * be done only for entities that were explicitly saved (through persist() or a cascade).
  172.      */
  173.     public const CHANGETRACKING_DEFERRED_EXPLICIT = 2;
  175.     /**
  176.      * NOTIFY means that Doctrine relies on the entities sending out notifications
  177.      * when their properties change. Such entity classes must implement
  178.      * the <tt>NotifyPropertyChanged</tt> interface.
  179.      */
  180.     public const CHANGETRACKING_NOTIFY = 3;
  182.     /**
  183.      * Specifies that an association is to be fetched when it is first accessed.
  184.      */
  185.     public const FETCH_LAZY = 2;
  187.     /**
  188.      * Specifies that an association is to be fetched when the owner of the
  189.      * association is fetched.
  190.      */
  191.     public const FETCH_EAGER = 3;
  193.     /**
  194.      * Specifies that an association is to be fetched lazy (on first access) and that
  195.      * commands such as Collection#count, Collection#slice are issued directly against
  196.      * the database if the collection is not yet initialized.
  197.      */
  198.     public const FETCH_EXTRA_LAZY = 4;
  200.     /**
  201.      * Identifies a one-to-one association.
  202.      */
  203.     public const ONE_TO_ONE = 1;
  205.     /**
  206.      * Identifies a many-to-one association.
  207.      */
  208.     public const MANY_TO_ONE = 2;
  210.     /**
  211.      * Identifies a one-to-many association.
  212.      */
  213.     public const ONE_TO_MANY = 4;
  215.     /**
  216.      * Identifies a many-to-many association.
  217.      */
  218.     public const MANY_TO_MANY = 8;
  220.     /**
  221.      * Combined bitmask for to-one (single-valued) associations.
  222.      */
  223.     public const TO_ONE = 3;
  225.     /**
  226.      * Combined bitmask for to-many (collection-valued) associations.
  227.      */
  228.     public const TO_MANY = 12;
  230.     /**
  231.      * ReadOnly cache can do reads, inserts and deletes, cannot perform updates or employ any locks,
  232.      */
  233.     public const CACHE_USAGE_READ_ONLY = 1;
  235.     /**
  236.      * Nonstrict Read Write Cache doesn’t employ any locks but can do inserts, update and deletes.
  237.      */
  238.     public const CACHE_USAGE_NONSTRICT_READ_WRITE = 2;
  240.     /**
  241.      * Read Write Attempts to lock the entity before update/delete.
  242.      */
  243.     public const CACHE_USAGE_READ_WRITE = 3;
  245.     /**
  246.      * READ-ONLY: The name of the entity class.
  247.      *
  248.      * @var string
  249.      * @psalm-var class-string<T>
  250.      */
  251.     public $name;
  253.     /**
  254.      * READ-ONLY: The namespace the entity class is contained in.
  255.      *
  256.      * @var string
  257.      * @todo Not really needed. Usage could be localized.
  258.      */
  259.     public $namespace;
  261.     /**
  262.      * READ-ONLY: The name of the entity class that is at the root of the mapped entity inheritance
  263.      * hierarchy. If the entity is not part of a mapped inheritance hierarchy this is the same
  264.      * as {@link $name}.
  265.      *
  266.      * @var string
  267.      * @psalm-var class-string
  268.      */
  269.     public $rootEntityName;
  271.     /**
  272.      * READ-ONLY: The definition of custom generator. Only used for CUSTOM
  273.      * generator type
  274.      *
  275.      * The definition has the following structure:
  276.      * <code>
  277.      * array(
  278.      *     'class' => 'ClassName',
  279.      * )
  280.      * </code>
  281.      *
  282.      * @todo Merge with tableGeneratorDefinition into generic generatorDefinition
  283.      * @var array<string, string>|null
  284.      */
  285.     public $customGeneratorDefinition;
  287.     /**
  288.      * The name of the custom repository class used for the entity class.
  289.      * (Optional).
  290.      *
  291.      * @var string|null
  292.      * @psalm-var ?class-string
  293.      */
  294.     public $customRepositoryClassName;
  296.     /**
  297.      * READ-ONLY: Whether this class describes the mapping of a mapped superclass.
  298.      *
  299.      * @var bool
  300.      */
  301.     public $isMappedSuperclass = false;
  303.     /**
  304.      * READ-ONLY: Whether this class describes the mapping of an embeddable class.
  305.      *
  306.      * @var bool
  307.      */
  308.     public $isEmbeddedClass = false;
  310.     /**
  311.      * READ-ONLY: The names of the parent classes (ancestors).
  312.      *
  313.      * @psalm-var list<class-string>
  314.      */
  315.     public $parentClasses = [];
  317.     /**
  318.      * READ-ONLY: The names of all subclasses (descendants).
  319.      *
  320.      * @psalm-var list<class-string>
  321.      */
  322.     public $subClasses = [];
  324.     /**
  325.      * READ-ONLY: The names of all embedded classes based on properties.
  326.      *
  327.      * @psalm-var array<string, mixed[]>
  328.      */
  329.     public $embeddedClasses = [];
  331.     /**
  332.      * READ-ONLY: The named queries allowed to be called directly from Repository.
  333.      *
  334.      * @psalm-var array<string, array<string, mixed>>
  335.      */
  336.     public $namedQueries = [];
  338.     /**
  339.      * READ-ONLY: The named native queries allowed to be called directly from Repository.
  340.      *
  341.      * A native SQL named query definition has the following structure:
  342.      * <pre>
  343.      * array(
  344.      *     'name'               => <query name>,
  345.      *     'query'              => <sql query>,
  346.      *     'resultClass'        => <class of the result>,
  347.      *     'resultSetMapping'   => <name of a SqlResultSetMapping>
  348.      * )
  349.      * </pre>
  350.      *
  351.      * @psalm-var array<string, array<string, mixed>>
  352.      */
  353.     public $namedNativeQueries = [];
  355.     /**
  356.      * READ-ONLY: The mappings of the results of native SQL queries.
  357.      *
  358.      * A native result mapping definition has the following structure:
  359.      * <pre>
  360.      * array(
  361.      *     'name'               => <result name>,
  362.      *     'entities'           => array(<entity result mapping>),
  363.      *     'columns'            => array(<column result mapping>)
  364.      * )
  365.      * </pre>
  366.      *
  367.      * @psalm-var array<string, array{
  368.      *                name: string,
  369.      *                entities: mixed[],
  370.      *                columns: mixed[]
  371.      *            }>
  372.      */
  373.     public $sqlResultSetMappings = [];
  375.     /**
  376.      * READ-ONLY: The field names of all fields that are part of the identifier/primary key
  377.      * of the mapped entity class.
  378.      *
  379.      * @psalm-var list<string>
  380.      */
  381.     public $identifier = [];
  383.     /**
  384.      * READ-ONLY: The inheritance mapping type used by the class.
  385.      *
  386.      * @var int
  387.      * @psalm-var self::$INHERITANCE_TYPE_*
  388.      */
  389.     public $inheritanceType = self::INHERITANCE_TYPE_NONE;
  391.     /**
  392.      * READ-ONLY: The Id generator type used by the class.
  393.      *
  394.      * @var int
  395.      */
  396.     public $generatorType = self::GENERATOR_TYPE_NONE;
  398.     /**
  399.      * READ-ONLY: The field mappings of the class.
  400.      * Keys are field names and values are mapping definitions.
  401.      *
  402.      * The mapping definition array has the following values:
  403.      *
  404.      * - <b>fieldName</b> (string)
  405.      * The name of the field in the Entity.
  406.      *
  407.      * - <b>type</b> (string)
  408.      * The type name of the mapped field. Can be one of Doctrine's mapping types
  409.      * or a custom mapping type.
  410.      *
  411.      * - <b>columnName</b> (string, optional)
  412.      * The column name. Optional. Defaults to the field name.
  413.      *
  414.      * - <b>length</b> (integer, optional)
  415.      * The database length of the column. Optional. Default value taken from
  416.      * the type.
  417.      *
  418.      * - <b>id</b> (boolean, optional)
  419.      * Marks the field as the primary key of the entity. Multiple fields of an
  420.      * entity can have the id attribute, forming a composite key.
  421.      *
  422.      * - <b>nullable</b> (boolean, optional)
  423.      * Whether the column is nullable. Defaults to FALSE.
  424.      *
  425.      * - <b>columnDefinition</b> (string, optional, schema-only)
  426.      * The SQL fragment that is used when generating the DDL for the column.
  427.      *
  428.      * - <b>precision</b> (integer, optional, schema-only)
  429.      * The precision of a decimal column. Only valid if the column type is decimal.
  430.      *
  431.      * - <b>scale</b> (integer, optional, schema-only)
  432.      * The scale of a decimal column. Only valid if the column type is decimal.
  433.      *
  434.      * - <b>'unique'</b> (string, optional, schema-only)
  435.      * Whether a unique constraint should be generated for the column.
  436.      *
  437.      * @var mixed[]
  438.      * @psalm-var array<string, array{
  439.      *      type: string,
  440.      *      fieldName: string,
  441.      *      columnName?: string,
  442.      *      length?: int,
  443.      *      id?: bool,
  444.      *      nullable?: bool,
  445.      *      columnDefinition?: string,
  446.      *      precision?: int,
  447.      *      scale?: int,
  448.      *      unique?: string,
  449.      *      inherited?: class-string,
  450.      *      originalClass?: class-string,
  451.      *      originalField?: string,
  452.      *      quoted?: bool,
  453.      *      requireSQLConversion?: bool,
  454.      *      declaredField?: string,
  455.      *      options: array<mixed>
  456.      * }>
  457.      */
  458.     public $fieldMappings = [];
  460.     /**
  461.      * READ-ONLY: An array of field names. Used to look up field names from column names.
  462.      * Keys are column names and values are field names.
  463.      *
  464.      * @psalm-var array<string, string>
  465.      */
  466.     public $fieldNames = [];
  468.     /**
  469.      * READ-ONLY: A map of field names to column names. Keys are field names and values column names.
  470.      * Used to look up column names from field names.
  471.      * This is the reverse lookup map of $_fieldNames.
  472.      *
  473.      * @deprecated 3.0 Remove this.
  474.      *
  475.      * @var mixed[]
  476.      */
  477.     public $columnNames = [];
  479.     /**
  480.      * READ-ONLY: The discriminator value of this class.
  481.      *
  482.      * <b>This does only apply to the JOINED and SINGLE_TABLE inheritance mapping strategies
  483.      * where a discriminator column is used.</b>
  484.      *
  485.      * @see discriminatorColumn
  486.      *
  487.      * @var mixed
  488.      */
  489.     public $discriminatorValue;
  491.     /**
  492.      * READ-ONLY: The discriminator map of all mapped classes in the hierarchy.
  493.      *
  494.      * <b>This does only apply to the JOINED and SINGLE_TABLE inheritance mapping strategies
  495.      * where a discriminator column is used.</b>
  496.      *
  497.      * @see discriminatorColumn
  498.      *
  499.      * @var mixed
  500.      */
  501.     public $discriminatorMap = [];
  503.     /**
  504.      * READ-ONLY: The definition of the discriminator column used in JOINED and SINGLE_TABLE
  505.      * inheritance mappings.
  506.      *
  507.      * @psalm-var array<string, mixed>
  508.      */
  509.     public $discriminatorColumn;
  511.     /**
  512.      * READ-ONLY: The primary table definition. The definition is an array with the
  513.      * following entries:
  514.      *
  515.      * name => <tableName>
  516.      * schema => <schemaName>
  517.      * indexes => array
  518.      * uniqueConstraints => array
  519.      *
  520.      * @var mixed[]
  521.      * @psalm-var array{name: string, schema: string, indexes: array, uniqueConstraints: array}
  522.      */
  523.     public $table;
  525.     /**
  526.      * READ-ONLY: The registered lifecycle callbacks for entities of this class.
  527.      *
  528.      * @psalm-var array<string, list<string>>
  529.      */
  530.     public $lifecycleCallbacks = [];
  532.     /**
  533.      * READ-ONLY: The registered entity listeners.
  534.      *
  535.      * @psalm-var array<string, list<array{class: class-string, method: string}>>
  536.      */
  537.     public $entityListeners = [];
  539.     /**
  540.      * READ-ONLY: The association mappings of this class.
  541.      *
  542.      * The mapping definition array supports the following keys:
  543.      *
  544.      * - <b>fieldName</b> (string)
  545.      * The name of the field in the entity the association is mapped to.
  546.      *
  547.      * - <b>targetEntity</b> (string)
  548.      * The class name of the target entity. If it is fully-qualified it is used as is.
  549.      * If it is a simple, unqualified class name the namespace is assumed to be the same
  550.      * as the namespace of the source entity.
  551.      *
  552.      * - <b>mappedBy</b> (string, required for bidirectional associations)
  553.      * The name of the field that completes the bidirectional association on the owning side.
  554.      * This key must be specified on the inverse side of a bidirectional association.
  555.      *
  556.      * - <b>inversedBy</b> (string, required for bidirectional associations)
  557.      * The name of the field that completes the bidirectional association on the inverse side.
  558.      * This key must be specified on the owning side of a bidirectional association.
  559.      *
  560.      * - <b>cascade</b> (array, optional)
  561.      * The names of persistence operations to cascade on the association. The set of possible
  562.      * values are: "persist", "remove", "detach", "merge", "refresh", "all" (implies all others).
  563.      *
  564.      * - <b>orderBy</b> (array, one-to-many/many-to-many only)
  565.      * A map of field names (of the target entity) to sorting directions (ASC/DESC).
  566.      * Example: array('priority' => 'desc')
  567.      *
  568.      * - <b>fetch</b> (integer, optional)
  569.      * The fetching strategy to use for the association, usually defaults to FETCH_LAZY.
  570.      * Possible values are: ClassMetadata::FETCH_EAGER, ClassMetadata::FETCH_LAZY.
  571.      *
  572.      * - <b>joinTable</b> (array, optional, many-to-many only)
  573.      * Specification of the join table and its join columns (foreign keys).
  574.      * Only valid for many-to-many mappings. Note that one-to-many associations can be mapped
  575.      * through a join table by simply mapping the association as many-to-many with a unique
  576.      * constraint on the join table.
  577.      *
  578.      * - <b>indexBy</b> (string, optional, to-many only)
  579.      * Specification of a field on target-entity that is used to index the collection by.
  580.      * This field HAS to be either the primary key or a unique column. Otherwise the collection
  581.      * does not contain all the entities that are actually related.
  582.      *
  583.      * A join table definition has the following structure:
  584.      * <pre>
  585.      * array(
  586.      *     'name' => <join table name>,
  587.      *      'joinColumns' => array(<join column mapping from join table to source table>),
  588.      *      'inverseJoinColumns' => array(<join column mapping from join table to target table>)
  589.      * )
  590.      * </pre>
  591.      *
  592.      * @psalm-var array<string, array<string, mixed>>
  593.      */
  594.     public $associationMappings = [];
  596.     /**
  597.      * READ-ONLY: Flag indicating whether the identifier/primary key of the class is composite.
  598.      *
  599.      * @var bool
  600.      */
  601.     public $isIdentifierComposite = false;
  603.     /**
  604.      * READ-ONLY: Flag indicating whether the identifier/primary key contains at least one foreign key association.
  605.      *
  606.      * This flag is necessary because some code blocks require special treatment of this cases.
  607.      *
  608.      * @var bool
  609.      */
  610.     public $containsForeignIdentifier = false;
  612.     /**
  613.      * READ-ONLY: The ID generator used for generating IDs for this class.
  614.      *
  615.      * @var AbstractIdGenerator
  616.      * @todo Remove!
  617.      */
  618.     public $idGenerator;
  620.     /**
  621.      * READ-ONLY: The definition of the sequence generator of this class. Only used for the
  622.      * SEQUENCE generation strategy.
  623.      *
  624.      * The definition has the following structure:
  625.      * <code>
  626.      * array(
  627.      *     'sequenceName' => 'name',
  628.      *     'allocationSize' => 20,
  629.      *     'initialValue' => 1
  630.      * )
  631.      * </code>
  632.      *
  633.      * @var mixed[]
  634.      * @psalm-var array{sequenceName: string, allocationSize: int, initialValue: int}
  635.      * @todo Merge with tableGeneratorDefinition into generic generatorDefinition
  636.      */
  637.     public $sequenceGeneratorDefinition;
  639.     /**
  640.      * READ-ONLY: The definition of the table generator of this class. Only used for the
  641.      * TABLE generation strategy.
  642.      *
  643.      * @var array<string, mixed>
  644.      * @todo Merge with tableGeneratorDefinition into generic generatorDefinition
  645.      */
  646.     public $tableGeneratorDefinition;
  648.     /**
  649.      * READ-ONLY: The policy used for change-tracking on entities of this class.
  650.      *
  651.      * @var int
  652.      */
  653.     public $changeTrackingPolicy = self::CHANGETRACKING_DEFERRED_IMPLICIT;
  655.     /**
  656.      * READ-ONLY: A flag for whether or not instances of this class are to be versioned
  657.      * with optimistic locking.
  658.      *
  659.      * @var bool
  660.      */
  661.     public $isVersioned;
  663.     /**
  664.      * READ-ONLY: The name of the field which is used for versioning in optimistic locking (if any).
  665.      *
  666.      * @var mixed
  667.      */
  668.     public $versionField;
  670.     /** @var mixed[] */
  671.     public $cache = null;
  673.     /**
  674.      * The ReflectionClass instance of the mapped class.
  675.      *
  676.      * @var ReflectionClass
  677.      */
  678.     public $reflClass;
  680.     /**
  681.      * Is this entity marked as "read-only"?
  682.      *
  683.      * That means it is never considered for change-tracking in the UnitOfWork. It is a very helpful performance
  684.      * optimization for entities that are immutable, either in your domain or through the relation database
  685.      * (coming from a view, or a history table for example).
  686.      *
  687.      * @var bool
  688.      */
  689.     public $isReadOnly = false;
  691.     /**
  692.      * NamingStrategy determining the default column and table names.
  693.      *
  694.      * @var NamingStrategy
  695.      */
  696.     protected $namingStrategy;
  698.     /**
  699.      * The ReflectionProperty instances of the mapped class.
  700.      *
  701.      * @var ReflectionProperty[]|null[]
  702.      */
  703.     public $reflFields = [];
  705.     /** @var InstantiatorInterface|null */
  706.     private $instantiator;
  708.     /**
  709.      * Initializes a new ClassMetadata instance that will hold the object-relational mapping
  710.      * metadata of the class with the given name.
  711.      *
  712.      * @param string $entityName The name of the entity class the new instance is used for.
  713.      */
  714.     public function __construct($entityName, ?NamingStrategy $namingStrategy = null)
  715.     {
  716.         $this->name           = $entityName;
  717.         $this->rootEntityName = $entityName;
  718.         $this->namingStrategy = $namingStrategy ?: new DefaultNamingStrategy();
  719.         $this->instantiator   = new Instantiator();
  720.     }
  722.     /**
  723.      * Gets the ReflectionProperties of the mapped class.
  724.      *
  725.      * @return ReflectionProperty[]|null[] An array of ReflectionProperty instances.
  726.      * @psalm-return array<ReflectionProperty|null>
  727.      */
  728.     public function getReflectionProperties()
  729.     {
  730.         return $this->reflFields;
  731.     }
  733.     /**
  734.      * Gets a ReflectionProperty for a specific field of the mapped class.
  735.      *
  736.      * @param string $name
  737.      *
  738.      * @return ReflectionProperty
  739.      */
  740.     public function getReflectionProperty($name)
  741.     {
  742.         return $this->reflFields[$name];
  743.     }
  745.     /**
  746.      * Gets the ReflectionProperty for the single identifier field.
  747.      *
  748.      * @return ReflectionProperty
  749.      *
  750.      * @throws BadMethodCallException If the class has a composite identifier.
  751.      */
  752.     public function getSingleIdReflectionProperty()
  753.     {
  754.         if ($this->isIdentifierComposite) {
  755.             throw new BadMethodCallException('Class ' . $this->name . ' has a composite identifier.');
  756.         }
  758.         return $this->reflFields[$this->identifier[0]];
  759.     }
  761.     /**
  762.      * Extracts the identifier values of an entity of this class.
  763.      *
  764.      * For composite identifiers, the identifier values are returned as an array
  765.      * with the same order as the field order in {@link identifier}.
  766.      *
  767.      * @param object $entity
  768.      *
  769.      * @return array<string, mixed>
  770.      */
  771.     public function getIdentifierValues($entity)
  772.     {
  773.         if ($this->isIdentifierComposite) {
  774.             $id = [];
  776.             foreach ($this->identifier as $idField) {
  777.                 $value = $this->reflFields[$idField]->getValue($entity);
  779.                 if ($value !== null) {
  780.                     $id[$idField] = $value;
  781.                 }
  782.             }
  784.             return $id;
  785.         }
  787.         $id    = $this->identifier[0];
  788.         $value = $this->reflFields[$id]->getValue($entity);
  790.         if ($value === null) {
  791.             return [];
  792.         }
  794.         return [$id => $value];
  795.     }
  797.     /**
  798.      * Populates the entity identifier of an entity.
  799.      *
  800.      * @param object $entity
  801.      * @psalm-param array<string, mixed> $id
  802.      *
  803.      * @return void
  804.      *
  805.      * @todo Rename to assignIdentifier()
  806.      */
  807.     public function setIdentifierValues($entity, array $id)
  808.     {
  809.         foreach ($id as $idField => $idValue) {
  810.             $this->reflFields[$idField]->setValue($entity, $idValue);
  811.         }
  812.     }
  814.     /**
  815.      * Sets the specified field to the specified value on the given entity.
  816.      *
  817.      * @param object $entity
  818.      * @param string $field
  819.      * @param mixed  $value
  820.      *
  821.      * @return void
  822.      */
  823.     public function setFieldValue($entity, $field, $value)
  824.     {
  825.         $this->reflFields[$field]->setValue($entity, $value);
  826.     }
  828.     /**
  829.      * Gets the specified field's value off the given entity.
  830.      *
  831.      * @param object $entity
  832.      * @param string $field
  833.      *
  834.      * @return mixed
  835.      */
  836.     public function getFieldValue($entity, $field)
  837.     {
  838.         return $this->reflFields[$field]->getValue($entity);
  839.     }
  841.     /**
  842.      * Creates a string representation of this instance.
  843.      *
  844.      * @return string The string representation of this instance.
  845.      *
  846.      * @todo Construct meaningful string representation.
  847.      */
  848.     public function __toString()
  849.     {
  850.         return self::class . '@' . spl_object_hash($this);
  851.     }
  853.     /**
  854.      * Determines which fields get serialized.
  855.      *
  856.      * It is only serialized what is necessary for best unserialization performance.
  857.      * That means any metadata properties that are not set or empty or simply have
  858.      * their default value are NOT serialized.
  859.      *
  860.      * Parts that are also NOT serialized because they can not be properly unserialized:
  861.      *      - reflClass (ReflectionClass)
  862.      *      - reflFields (ReflectionProperty array)
  863.      *
  864.      * @return string[] The names of all the fields that should be serialized.
  865.      */
  866.     public function __sleep()
  867.     {
  868.         // This metadata is always serialized/cached.
  869.         $serialized = [
  870.             'associationMappings',
  871.             'columnNames', //TODO: 3.0 Remove this. Can use fieldMappings[$fieldName]['columnName']
  872.             'fieldMappings',
  873.             'fieldNames',
  874.             'embeddedClasses',
  875.             'identifier',
  876.             'isIdentifierComposite', // TODO: REMOVE
  877.             'name',
  878.             'namespace', // TODO: REMOVE
  879.             'table',
  880.             'rootEntityName',
  881.             'idGenerator', //TODO: Does not really need to be serialized. Could be moved to runtime.
  882.         ];
  884.         // The rest of the metadata is only serialized if necessary.
  885.         if ($this->changeTrackingPolicy !== self::CHANGETRACKING_DEFERRED_IMPLICIT) {
  886.             $serialized[] = 'changeTrackingPolicy';
  887.         }
  889.         if ($this->customRepositoryClassName) {
  890.             $serialized[] = 'customRepositoryClassName';
  891.         }
  893.         if ($this->inheritanceType !== self::INHERITANCE_TYPE_NONE) {
  894.             $serialized[] = 'inheritanceType';
  895.             $serialized[] = 'discriminatorColumn';
  896.             $serialized[] = 'discriminatorValue';
  897.             $serialized[] = 'discriminatorMap';
  898.             $serialized[] = 'parentClasses';
  899.             $serialized[] = 'subClasses';
  900.         }
  902.         if ($this->generatorType !== self::GENERATOR_TYPE_NONE) {
  903.             $serialized[] = 'generatorType';
  904.             if ($this->generatorType === self::GENERATOR_TYPE_SEQUENCE) {
  905.                 $serialized[] = 'sequenceGeneratorDefinition';
  906.             }
  907.         }
  909.         if ($this->isMappedSuperclass) {
  910.             $serialized[] = 'isMappedSuperclass';
  911.         }
  913.         if ($this->isEmbeddedClass) {
  914.             $serialized[] = 'isEmbeddedClass';
  915.         }
  917.         if ($this->containsForeignIdentifier) {
  918.             $serialized[] = 'containsForeignIdentifier';
  919.         }
  921.         if ($this->isVersioned) {
  922.             $serialized[] = 'isVersioned';
  923.             $serialized[] = 'versionField';
  924.         }
  926.         if ($this->lifecycleCallbacks) {
  927.             $serialized[] = 'lifecycleCallbacks';
  928.         }
  930.         if ($this->entityListeners) {
  931.             $serialized[] = 'entityListeners';
  932.         }
  934.         if ($this->namedQueries) {
  935.             $serialized[] = 'namedQueries';
  936.         }
  938.         if ($this->namedNativeQueries) {
  939.             $serialized[] = 'namedNativeQueries';
  940.         }
  942.         if ($this->sqlResultSetMappings) {
  943.             $serialized[] = 'sqlResultSetMappings';
  944.         }
  946.         if ($this->isReadOnly) {
  947.             $serialized[] = 'isReadOnly';
  948.         }
  950.         if ($this->customGeneratorDefinition) {
  951.             $serialized[] = 'customGeneratorDefinition';
  952.         }
  954.         if ($this->cache) {
  955.             $serialized[] = 'cache';
  956.         }
  958.         return $serialized;
  959.     }
  961.     /**
  962.      * Creates a new instance of the mapped class, without invoking the constructor.
  963.      *
  964.      * @return object
  965.      */
  966.     public function newInstance()
  967.     {
  968.         return $this->instantiator->instantiate($this->name);
  969.     }
  971.     /**
  972.      * Restores some state that can not be serialized/unserialized.
  973.      *
  974.      * @param ReflectionService $reflService
  975.      *
  976.      * @return void
  977.      */
  978.     public function wakeupReflection($reflService)
  979.     {
  980.         // Restore ReflectionClass and properties
  981.         $this->reflClass    = $reflService->getClass($this->name);
  982.         $this->instantiator = $this->instantiator ?: new Instantiator();
  984.         $parentReflFields = [];
  986.         foreach ($this->embeddedClasses as $property => $embeddedClass) {
  987.             if (isset($embeddedClass['declaredField'])) {
  988.                 $parentReflFields[$property] = new ReflectionEmbeddedProperty(
  989.                     $parentReflFields[$embeddedClass['declaredField']],
  990.                     $reflService->getAccessibleProperty(
  991.                         $this->embeddedClasses[$embeddedClass['declaredField']]['class'],
  992.                         $embeddedClass['originalField']
  993.                     ),
  994.                     $this->embeddedClasses[$embeddedClass['declaredField']]['class']
  995.                 );
  997.                 continue;
  998.             }
  1000.             $fieldRefl = $reflService->getAccessibleProperty(
  1001.                 $embeddedClass['declared'] ?? $this->name,
  1002.                 $property
  1003.             );
  1005.             $parentReflFields[$property] = $fieldRefl;
  1006.             $this->reflFields[$property] = $fieldRefl;
  1007.         }
  1009.         foreach ($this->fieldMappings as $field => $mapping) {
  1010.             if (isset($mapping['declaredField']) && isset($parentReflFields[$mapping['declaredField']])) {
  1011.                 $this->reflFields[$field] = new ReflectionEmbeddedProperty(
  1012.                     $parentReflFields[$mapping['declaredField']],
  1013.                     $reflService->getAccessibleProperty($mapping['originalClass'], $mapping['originalField']),
  1014.                     $mapping['originalClass']
  1015.                 );
  1016.                 continue;
  1017.             }
  1019.             $this->reflFields[$field] = isset($mapping['declared'])
  1020.                 ? $reflService->getAccessibleProperty($mapping['declared'], $field)
  1021.                 : $reflService->getAccessibleProperty($this->name, $field);
  1022.         }
  1024.         foreach ($this->associationMappings as $field => $mapping) {
  1025.             $this->reflFields[$field] = isset($mapping['declared'])
  1026.                 ? $reflService->getAccessibleProperty($mapping['declared'], $field)
  1027.                 : $reflService->getAccessibleProperty($this->name, $field);
  1028.         }
  1029.     }
  1031.     /**
  1032.      * Initializes a new ClassMetadata instance that will hold the object-relational mapping
  1033.      * metadata of the class with the given name.
  1034.      *
  1035.      * @param ReflectionService $reflService The reflection service.
  1036.      *
  1037.      * @return void
  1038.      */
  1039.     public function initializeReflection($reflService)
  1040.     {
  1041.         $this->reflClass = $reflService->getClass($this->name);
  1042.         $this->namespace = $reflService->getClassNamespace($this->name);
  1044.         if ($this->reflClass) {
  1045.             $this->name = $this->rootEntityName = $this->reflClass->getName();
  1046.         }
  1048.         $this->table['name'] = $this->namingStrategy->classToTableName($this->name);
  1049.     }
  1051.     /**
  1052.      * Validates Identifier.
  1053.      *
  1054.      * @return void
  1055.      *
  1056.      * @throws MappingException
  1057.      */
  1058.     public function validateIdentifier()
  1059.     {
  1060.         if ($this->isMappedSuperclass || $this->isEmbeddedClass) {
  1061.             return;
  1062.         }
  1064.         // Verify & complete identifier mapping
  1065.         if (! $this->identifier) {
  1066.             throw MappingException::identifierRequired($this->name);
  1067.         }
  1069.         if ($this->usesIdGenerator() && $this->isIdentifierComposite) {
  1070.             throw MappingException::compositeKeyAssignedIdGeneratorRequired($this->name);
  1071.         }
  1072.     }
  1074.     /**
  1075.      * Validates association targets actually exist.
  1076.      *
  1077.      * @return void
  1078.      *
  1079.      * @throws MappingException
  1080.      */
  1081.     public function validateAssociations()
  1082.     {
  1083.         foreach ($this->associationMappings as $mapping) {
  1084.             if (
  1085.                 ! class_exists($mapping['targetEntity'])
  1086.                 && ! interface_exists($mapping['targetEntity'])
  1087.                 && ! trait_exists($mapping['targetEntity'])
  1088.             ) {
  1089.                 throw MappingException::invalidTargetEntityClass($mapping['targetEntity'], $this->name, $mapping['fieldName']);
  1090.             }
  1091.         }
  1092.     }
  1094.     /**
  1095.      * Validates lifecycle callbacks.
  1096.      *
  1097.      * @param ReflectionService $reflService
  1098.      *
  1099.      * @return void
  1100.      *
  1101.      * @throws MappingException
  1102.      */
  1103.     public function validateLifecycleCallbacks($reflService)
  1104.     {
  1105.         foreach ($this->lifecycleCallbacks as $callbacks) {
  1106.             foreach ($callbacks as $callbackFuncName) {
  1107.                 if (! $reflService->hasPublicMethod($this->name, $callbackFuncName)) {
  1108.                     throw MappingException::lifecycleCallbackMethodNotFound($this->name, $callbackFuncName);
  1109.                 }
  1110.             }
  1111.         }
  1112.     }
  1114.     /**
  1115.      * {@inheritDoc}
  1116.      */
  1117.     public function getReflectionClass()
  1118.     {
  1119.         return $this->reflClass;
  1120.     }
  1122.     /**
  1123.      * @psalm-param array{usage?: mixed, region?: mixed} $cache
  1124.      *
  1125.      * @return void
  1126.      */
  1127.     public function enableCache(array $cache)
  1128.     {
  1129.         if (! isset($cache['usage'])) {
  1130.             $cache['usage'] = self::CACHE_USAGE_READ_ONLY;
  1131.         }
  1133.         if (! isset($cache['region'])) {
  1134.             $cache['region'] = strtolower(str_replace('\\', '_', $this->rootEntityName));
  1135.         }
  1137.         $this->cache = $cache;
  1138.     }
  1140.     /**
  1141.      * @param string $fieldName
  1142.      * @psalm-param array{usage?: int, region?: string} $cache
  1143.      *
  1144.      * @return void
  1145.      */
  1146.     public function enableAssociationCache($fieldName, array $cache)
  1147.     {
  1148.         $this->associationMappings[$fieldName]['cache'] = $this->getAssociationCacheDefaults($fieldName, $cache);
  1149.     }
  1151.     /**
  1152.      * @param string $fieldName
  1153.      * @param array  $cache
  1154.      * @psalm-param array{usage?: int, region?: string} $cache
  1155.      *
  1156.      * @return int[]|string[]
  1157.      * @psalm-return array{usage: int, region: string|null}
  1158.      */
  1159.     public function getAssociationCacheDefaults($fieldName, array $cache)
  1160.     {
  1161.         if (! isset($cache['usage'])) {
  1162.             $cache['usage'] = $this->cache['usage'] ?? self::CACHE_USAGE_READ_ONLY;
  1163.         }
  1165.         if (! isset($cache['region'])) {
  1166.             $cache['region'] = strtolower(str_replace('\\', '_', $this->rootEntityName)) . '__' . $fieldName;
  1167.         }
  1169.         return $cache;
  1170.     }
  1172.     /**
  1173.      * Sets the change tracking policy used by this class.
  1174.      *
  1175.      * @param int $policy
  1176.      *
  1177.      * @return void
  1178.      */
  1179.     public function setChangeTrackingPolicy($policy)
  1180.     {
  1181.         $this->changeTrackingPolicy = $policy;
  1182.     }
  1184.     /**
  1185.      * Whether the change tracking policy of this class is "deferred explicit".
  1186.      *
  1187.      * @return bool
  1188.      */
  1189.     public function isChangeTrackingDeferredExplicit()
  1190.     {
  1191.         return $this->changeTrackingPolicy === self::CHANGETRACKING_DEFERRED_EXPLICIT;
  1192.     }
  1194.     /**
  1195.      * Whether the change tracking policy of this class is "deferred implicit".
  1196.      *
  1197.      * @return bool
  1198.      */
  1199.     public function isChangeTrackingDeferredImplicit()
  1200.     {
  1201.         return $this->changeTrackingPolicy === self::CHANGETRACKING_DEFERRED_IMPLICIT;
  1202.     }
  1204.     /**
  1205.      * Whether the change tracking policy of this class is "notify".
  1206.      *
  1207.      * @return bool
  1208.      */
  1209.     public function isChangeTrackingNotify()
  1210.     {
  1211.         return $this->changeTrackingPolicy === self::CHANGETRACKING_NOTIFY;
  1212.     }
  1214.     /**
  1215.      * Checks whether a field is part of the identifier/primary key field(s).
  1216.      *
  1217.      * @param string $fieldName The field name.
  1218.      *
  1219.      * @return bool TRUE if the field is part of the table identifier/primary key field(s),
  1220.      * FALSE otherwise.
  1221.      */
  1222.     public function isIdentifier($fieldName)
  1223.     {
  1224.         if (! $this->identifier) {
  1225.             return false;
  1226.         }
  1228.         if (! $this->isIdentifierComposite) {
  1229.             return $fieldName === $this->identifier[0];
  1230.         }
  1232.         return in_array($fieldName, $this->identifier, true);
  1233.     }
  1235.     /**
  1236.      * Checks if the field is unique.
  1237.      *
  1238.      * @param string $fieldName The field name.
  1239.      *
  1240.      * @return bool TRUE if the field is unique, FALSE otherwise.
  1241.      */
  1242.     public function isUniqueField($fieldName)
  1243.     {
  1244.         $mapping = $this->getFieldMapping($fieldName);
  1246.         return $mapping !== false && isset($mapping['unique']) && $mapping['unique'];
  1247.     }
  1249.     /**
  1250.      * Checks if the field is not null.
  1251.      *
  1252.      * @param string $fieldName The field name.
  1253.      *
  1254.      * @return bool TRUE if the field is not null, FALSE otherwise.
  1255.      */
  1256.     public function isNullable($fieldName)
  1257.     {
  1258.         $mapping = $this->getFieldMapping($fieldName);
  1260.         return $mapping !== false && isset($mapping['nullable']) && $mapping['nullable'];
  1261.     }
  1263.     /**
  1264.      * Gets a column name for a field name.
  1265.      * If the column name for the field cannot be found, the given field name
  1266.      * is returned.
  1267.      *
  1268.      * @param string $fieldName The field name.
  1269.      *
  1270.      * @return string The column name.
  1271.      */
  1272.     public function getColumnName($fieldName)
  1273.     {
  1274.         return $this->columnNames[$fieldName] ?? $fieldName;
  1275.     }
  1277.     /**
  1278.      * Gets the mapping of a (regular) field that holds some data but not a
  1279.      * reference to another object.
  1280.      *
  1281.      * @param string $fieldName The field name.
  1282.      *
  1283.      * @return mixed[] The field mapping.
  1284.      * @psalm-return array{
  1285.      *      type: string,
  1286.      *      fieldName: string,
  1287.      *      columnName?: string,
  1288.      *      inherited?: class-string,
  1289.      *      nullable?: bool,
  1290.      *      originalClass?: class-string,
  1291.      *      originalField?: string,
  1292.      *      scale?: int,
  1293.      *      precision?: int,
  1294.      *      length?: int
  1295.      * }
  1296.      *
  1297.      * @throws MappingException
  1298.      */
  1299.     public function getFieldMapping($fieldName)
  1300.     {
  1301.         if (! isset($this->fieldMappings[$fieldName])) {
  1302.             throw MappingException::mappingNotFound($this->name, $fieldName);
  1303.         }
  1305.         return $this->fieldMappings[$fieldName];
  1306.     }
  1308.     /**
  1309.      * Gets the mapping of an association.
  1310.      *
  1311.      * @see ClassMetadataInfo::$associationMappings
  1312.      *
  1313.      * @param string $fieldName The field name that represents the association in
  1314.      *                          the object model.
  1315.      *
  1316.      * @psalm-return array<string, mixed> The mapping.
  1317.      *
  1318.      * @throws MappingException
  1319.      */
  1320.     public function getAssociationMapping($fieldName)
  1321.     {
  1322.         if (! isset($this->associationMappings[$fieldName])) {
  1323.             throw MappingException::mappingNotFound($this->name, $fieldName);
  1324.         }
  1326.         return $this->associationMappings[$fieldName];
  1327.     }
  1329.     /**
  1330.      * Gets all association mappings of the class.
  1331.      *
  1332.      * @psalm-return array<string, array<string, mixed>>
  1333.      */
  1334.     public function getAssociationMappings()
  1335.     {
  1336.         return $this->associationMappings;
  1337.     }
  1339.     /**
  1340.      * Gets the field name for a column name.
  1341.      * If no field name can be found the column name is returned.
  1342.      *
  1343.      * @param string $columnName The column name.
  1344.      *
  1345.      * @return string The column alias.
  1346.      */
  1347.     public function getFieldName($columnName)
  1348.     {
  1349.         return $this->fieldNames[$columnName] ?? $columnName;
  1350.     }
  1352.     /**
  1353.      * Gets the named query.
  1354.      *
  1355.      * @see ClassMetadataInfo::$namedQueries
  1356.      *
  1357.      * @param string $queryName The query name.
  1358.      *
  1359.      * @return string
  1360.      *
  1361.      * @throws MappingException
  1362.      */
  1363.     public function getNamedQuery($queryName)
  1364.     {
  1365.         if (! isset($this->namedQueries[$queryName])) {
  1366.             throw MappingException::queryNotFound($this->name, $queryName);
  1367.         }
  1369.         return $this->namedQueries[$queryName]['dql'];
  1370.     }
  1372.     /**
  1373.      * Gets all named queries of the class.
  1374.      *
  1375.      * @return mixed[][]
  1376.      * @psalm-return array<string, array<string, mixed>>
  1377.      */
  1378.     public function getNamedQueries()
  1379.     {
  1380.         return $this->namedQueries;
  1381.     }
  1383.     /**
  1384.      * Gets the named native query.
  1385.      *
  1386.      * @see ClassMetadataInfo::$namedNativeQueries
  1387.      *
  1388.      * @param string $queryName The query name.
  1389.      *
  1390.      * @psalm-return array<string, mixed>
  1391.      *
  1392.      * @throws MappingException
  1393.      */
  1394.     public function getNamedNativeQuery($queryName)
  1395.     {
  1396.         if (! isset($this->namedNativeQueries[$queryName])) {
  1397.             throw MappingException::queryNotFound($this->name, $queryName);
  1398.         }
  1400.         return $this->namedNativeQueries[$queryName];
  1401.     }
  1403.     /**
  1404.      * Gets all named native queries of the class.
  1405.      *
  1406.      * @psalm-return array<string, array<string, mixed>>
  1407.      */
  1408.     public function getNamedNativeQueries()
  1409.     {
  1410.         return $this->namedNativeQueries;
  1411.     }
  1413.     /**
  1414.      * Gets the result set mapping.
  1415.      *
  1416.      * @see ClassMetadataInfo::$sqlResultSetMappings
  1417.      *
  1418.      * @param string $name The result set mapping name.
  1419.      *
  1420.      * @return mixed[]
  1421.      * @psalm-return array{name: string, entities: array, columns: array}
  1422.      *
  1423.      * @throws MappingException
  1424.      */
  1425.     public function getSqlResultSetMapping($name)
  1426.     {
  1427.         if (! isset($this->sqlResultSetMappings[$name])) {
  1428.             throw MappingException::resultMappingNotFound($this->name, $name);
  1429.         }
  1431.         return $this->sqlResultSetMappings[$name];
  1432.     }
  1434.     /**
  1435.      * Gets all sql result set mappings of the class.
  1436.      *
  1437.      * @return mixed[]
  1438.      * @psalm-return array<string, array{name: string, entities: array, columns: array}>
  1439.      */
  1440.     public function getSqlResultSetMappings()
  1441.     {
  1442.         return $this->sqlResultSetMappings;
  1443.     }
  1445.     /**
  1446.      * Checks whether given property has type
  1447.      *
  1448.      * @param string $name Property name
  1449.      */
  1450.     private function isTypedProperty(string $name): bool
  1451.     {
  1452.         return PHP_VERSION_ID >= 70400
  1453.                && isset($this->reflClass)
  1454.                && $this->reflClass->hasProperty($name)
  1455.                && $this->reflClass->getProperty($name)->hasType();
  1456.     }
  1458.     /**
  1459.      * Validates & completes the given field mapping based on typed property.
  1460.      *
  1461.      * @param  mixed[] $mapping The field mapping to validate & complete.
  1462.      *
  1463.      * @return mixed[] The updated mapping.
  1464.      */
  1465.     private function validateAndCompleteTypedFieldMapping(array $mapping): array
  1466.     {
  1467.         $type = $this->reflClass->getProperty($mapping['fieldName'])->getType();
  1469.         if ($type) {
  1470.             if (! isset($mapping['nullable'])) {
  1471.                 $mapping['nullable'] = $type->allowsNull();
  1472.             }
  1474.             if (
  1475.                 ! isset($mapping['type'])
  1476.                 && ($type instanceof ReflectionNamedType)
  1477.             ) {
  1478.                 switch ($type->getName()) {
  1479.                     case DateInterval::class:
  1480.                         $mapping['type'] = Types::DATEINTERVAL;
  1481.                         break;
  1482.                     case DateTime::class:
  1483.                         $mapping['type'] = Types::DATETIME_MUTABLE;
  1484.                         break;
  1485.                     case DateTimeImmutable::class:
  1486.                         $mapping['type'] = Types::DATETIME_IMMUTABLE;
  1487.                         break;
  1488.                     case 'array':
  1489.                         $mapping['type'] = Types::JSON;
  1490.                         break;
  1491.                     case 'bool':
  1492.                         $mapping['type'] = Types::BOOLEAN;
  1493.                         break;
  1494.                     case 'float':
  1495.                         $mapping['type'] = Types::FLOAT;
  1496.                         break;
  1497.                     case 'int':
  1498.                         $mapping['type'] = Types::INTEGER;
  1499.                         break;
  1500.                     case 'string':
  1501.                         $mapping['type'] = Types::STRING;
  1502.                         break;
  1503.                 }
  1504.             }
  1505.         }
  1507.         return $mapping;
  1508.     }
  1510.     /**
  1511.      * Validates & completes the basic mapping information based on typed property.
  1512.      *
  1513.      * @param mixed[] $mapping The mapping.
  1514.      *
  1515.      * @return mixed[] The updated mapping.
  1516.      */
  1517.     private function validateAndCompleteTypedAssociationMapping(array $mapping): array
  1518.     {
  1519.         $type = $this->reflClass->getProperty($mapping['fieldName'])->getType();
  1521.         if ($type === null || ($mapping['type'] & self::TO_ONE) === 0) {
  1522.             return $mapping;
  1523.         }
  1525.         if (! isset($mapping['targetEntity']) && $type instanceof ReflectionNamedType) {
  1526.             $mapping['targetEntity'] = $type->getName();
  1527.         }
  1529.         if (isset($mapping['joinColumns'])) {
  1530.             foreach ($mapping['joinColumns'] as &$joinColumn) {
  1531.                 if ($type->allowsNull() === false) {
  1532.                     $joinColumn['nullable'] = false;
  1533.                 }
  1534.             }
  1535.         }
  1537.         return $mapping;
  1538.     }
  1540.     /**
  1541.      * Validates & completes the given field mapping.
  1542.      *
  1543.      * @psalm-param array<string, mixed> $mapping The field mapping to validate & complete.
  1544.      *
  1545.      * @return mixed[] The updated mapping.
  1546.      *
  1547.      * @throws MappingException
  1548.      */
  1549.     protected function validateAndCompleteFieldMapping(array $mapping): array
  1550.     {
  1551.         // Check mandatory fields
  1552.         if (! isset($mapping['fieldName']) || ! $mapping['fieldName']) {
  1553.             throw MappingException::missingFieldName($this->name);
  1554.         }
  1556.         if ($this->isTypedProperty($mapping['fieldName'])) {
  1557.             $mapping = $this->validateAndCompleteTypedFieldMapping($mapping);
  1558.         }
  1560.         if (! isset($mapping['type'])) {
  1561.             // Default to string
  1562.             $mapping['type'] = 'string';
  1563.         }
  1565.         // Complete fieldName and columnName mapping
  1566.         if (! isset($mapping['columnName'])) {
  1567.             $mapping['columnName'] = $this->namingStrategy->propertyToColumnName($mapping['fieldName'], $this->name);
  1568.         }
  1570.         if ($mapping['columnName'][0] === '`') {
  1571.             $mapping['columnName'] = trim($mapping['columnName'], '`');
  1572.             $mapping['quoted']     = true;
  1573.         }
  1575.         $this->columnNames[$mapping['fieldName']] = $mapping['columnName'];
  1577.         if (isset($this->fieldNames[$mapping['columnName']]) || ($this->discriminatorColumn && $this->discriminatorColumn['name'] === $mapping['columnName'])) {
  1578.             throw MappingException::duplicateColumnName($this->name, $mapping['columnName']);
  1579.         }
  1581.         $this->fieldNames[$mapping['columnName']] = $mapping['fieldName'];
  1583.         // Complete id mapping
  1584.         if (isset($mapping['id']) && $mapping['id'] === true) {
  1585.             if ($this->versionField === $mapping['fieldName']) {
  1586.                 throw MappingException::cannotVersionIdField($this->name, $mapping['fieldName']);
  1587.             }
  1589.             if (! in_array($mapping['fieldName'], $this->identifier)) {
  1590.                 $this->identifier[] = $mapping['fieldName'];
  1591.             }
  1593.             // Check for composite key
  1594.             if (! $this->isIdentifierComposite && count($this->identifier) > 1) {
  1595.                 $this->isIdentifierComposite = true;
  1596.             }
  1597.         }
  1599.         if (Type::hasType($mapping['type']) && Type::getType($mapping['type'])->canRequireSQLConversion()) {
  1600.             if (isset($mapping['id']) && $mapping['id'] === true) {
  1601.                  throw MappingException::sqlConversionNotAllowedForIdentifiers($this->name, $mapping['fieldName'], $mapping['type']);
  1602.             }
  1604.             $mapping['requireSQLConversion'] = true;
  1605.         }
  1607.         return $mapping;
  1608.     }
  1610.     /**
  1611.      * Validates & completes the basic mapping information that is common to all
  1612.      * association mappings (one-to-one, many-ot-one, one-to-many, many-to-many).
  1613.      *
  1614.      * @psalm-param array<string, mixed> $mapping The mapping.
  1615.      *
  1616.      * @return mixed[] The updated mapping.
  1617.      * @psalm-return array{
  1618.      *                   mappedBy: mixed|null,
  1619.      *                   inversedBy: mixed|null,
  1620.      *                   isOwningSide: bool,
  1621.      *                   sourceEntity: class-string,
  1622.      *                   targetEntity: string,
  1623.      *                   fieldName: mixed,
  1624.      *                   fetch: mixed,
  1625.      *                   cascade: array<array-key,string>,
  1626.      *                   isCascadeRemove: bool,
  1627.      *                   isCascadePersist: bool,
  1628.      *                   isCascadeRefresh: bool,
  1629.      *                   isCascadeMerge: bool,
  1630.      *                   isCascadeDetach: bool,
  1631.      *                   type: int,
  1632.      *                   originalField: string,
  1633.      *                   originalClass: class-string,
  1634.      *                   ?orphanRemoval: bool
  1635.      *               }
  1636.      *
  1637.      * @throws MappingException If something is wrong with the mapping.
  1638.      */
  1639.     protected function _validateAndCompleteAssociationMapping(array $mapping)
  1640.     {
  1641.         if (! isset($mapping['mappedBy'])) {
  1642.             $mapping['mappedBy'] = null;
  1643.         }
  1645.         if (! isset($mapping['inversedBy'])) {
  1646.             $mapping['inversedBy'] = null;
  1647.         }
  1649.         $mapping['isOwningSide'] = true; // assume owning side until we hit mappedBy
  1651.         if (empty($mapping['indexBy'])) {
  1652.             unset($mapping['indexBy']);
  1653.         }
  1655.         // If targetEntity is unqualified, assume it is in the same namespace as
  1656.         // the sourceEntity.
  1657.         $mapping['sourceEntity'] = $this->name;
  1659.         if ($this->isTypedProperty($mapping['fieldName'])) {
  1660.             $mapping = $this->validateAndCompleteTypedAssociationMapping($mapping);
  1661.         }
  1663.         if (isset($mapping['targetEntity'])) {
  1664.             $mapping['targetEntity'] = $this->fullyQualifiedClassName($mapping['targetEntity']);
  1665.             $mapping['targetEntity'] = ltrim($mapping['targetEntity'], '\\');
  1666.         }
  1668.         if (($mapping['type'] & self::MANY_TO_ONE) > 0 && isset($mapping['orphanRemoval']) && $mapping['orphanRemoval']) {
  1669.             throw MappingException::illegalOrphanRemoval($this->name, $mapping['fieldName']);
  1670.         }
  1672.         // Complete id mapping
  1673.         if (isset($mapping['id']) && $mapping['id'] === true) {
  1674.             if (isset($mapping['orphanRemoval']) && $mapping['orphanRemoval']) {
  1675.                 throw MappingException::illegalOrphanRemovalOnIdentifierAssociation($this->name, $mapping['fieldName']);
  1676.             }
  1678.             if (! in_array($mapping['fieldName'], $this->identifier)) {
  1679.                 if (isset($mapping['joinColumns']) && count($mapping['joinColumns']) >= 2) {
  1680.                     throw MappingException::cannotMapCompositePrimaryKeyEntitiesAsForeignId(
  1681.                         $mapping['targetEntity'],
  1682.                         $this->name,
  1683.                         $mapping['fieldName']
  1684.                     );
  1685.                 }
  1687.                 $this->identifier[]              = $mapping['fieldName'];
  1688.                 $this->containsForeignIdentifier = true;
  1689.             }
  1691.             // Check for composite key
  1692.             if (! $this->isIdentifierComposite && count($this->identifier) > 1) {
  1693.                 $this->isIdentifierComposite = true;
  1694.             }
  1696.             if ($this->cache && ! isset($mapping['cache'])) {
  1697.                 throw CacheException::nonCacheableEntityAssociation($this->name, $mapping['fieldName']);
  1698.             }
  1699.         }
  1701.         // Mandatory attributes for both sides
  1702.         // Mandatory: fieldName, targetEntity
  1703.         if (! isset($mapping['fieldName']) || ! $mapping['fieldName']) {
  1704.             throw MappingException::missingFieldName($this->name);
  1705.         }
  1707.         if (! isset($mapping['targetEntity'])) {
  1708.             throw MappingException::missingTargetEntity($mapping['fieldName']);
  1709.         }
  1711.         // Mandatory and optional attributes for either side
  1712.         if (! $mapping['mappedBy']) {
  1713.             if (isset($mapping['joinTable']) && $mapping['joinTable']) {
  1714.                 if (isset($mapping['joinTable']['name']) && $mapping['joinTable']['name'][0] === '`') {
  1715.                     $mapping['joinTable']['name']   = trim($mapping['joinTable']['name'], '`');
  1716.                     $mapping['joinTable']['quoted'] = true;
  1717.                 }
  1718.             }
  1719.         } else {
  1720.             $mapping['isOwningSide'] = false;
  1721.         }
  1723.         if (isset($mapping['id']) && $mapping['id'] === true && $mapping['type'] & self::TO_MANY) {
  1724.             throw MappingException::illegalToManyIdentifierAssociation($this->name, $mapping['fieldName']);
  1725.         }
  1727.         // Fetch mode. Default fetch mode to LAZY, if not set.
  1728.         if (! isset($mapping['fetch'])) {
  1729.             $mapping['fetch'] = self::FETCH_LAZY;
  1730.         }
  1732.         // Cascades
  1733.         $cascades = isset($mapping['cascade']) ? array_map('strtolower', $mapping['cascade']) : [];
  1735.         $allCascades = ['remove', 'persist', 'refresh', 'merge', 'detach'];
  1736.         if (in_array('all', $cascades)) {
  1737.             $cascades = $allCascades;
  1738.         } elseif (count($cascades) !== count(array_intersect($cascades, $allCascades))) {
  1739.             throw MappingException::invalidCascadeOption(
  1740.                 array_diff($cascades, $allCascades),
  1741.                 $this->name,
  1742.                 $mapping['fieldName']
  1743.             );
  1744.         }
  1746.         $mapping['cascade']          = $cascades;
  1747.         $mapping['isCascadeRemove']  = in_array('remove', $cascades);
  1748.         $mapping['isCascadePersist'] = in_array('persist', $cascades);
  1749.         $mapping['isCascadeRefresh'] = in_array('refresh', $cascades);
  1750.         $mapping['isCascadeMerge']   = in_array('merge', $cascades);
  1751.         $mapping['isCascadeDetach']  = in_array('detach', $cascades);
  1753.         return $mapping;
  1754.     }
  1756.     /**
  1757.      * Validates & completes a one-to-one association mapping.
  1758.      *
  1759.      * @psalm-param array<string, mixed> $mapping The mapping to validate & complete.
  1760.      * @psalm-param array<string, mixed> $mapping The mapping to validate & complete.
  1761.      *
  1762.      * @return mixed[] The validated & completed mapping.
  1763.      * @psalm-return array{isOwningSide: mixed, orphanRemoval: bool, isCascadeRemove: bool}
  1764.      * @psalm-return array{
  1765.      *      mappedBy: mixed|null,
  1766.      *      inversedBy: mixed|null,
  1767.      *      isOwningSide: bool,
  1768.      *      sourceEntity: class-string,
  1769.      *      targetEntity: string,
  1770.      *      fieldName: mixed,
  1771.      *      fetch: mixed,
  1772.      *      cascade: array<string>,
  1773.      *      isCascadeRemove: bool,
  1774.      *      isCascadePersist: bool,
  1775.      *      isCascadeRefresh: bool,
  1776.      *      isCascadeMerge: bool,
  1777.      *      isCascadeDetach: bool,
  1778.      *      type: int,
  1779.      *      originalField: string,
  1780.      *      originalClass: class-string,
  1781.      *      joinColumns?: array{0: array{name: string, referencedColumnName: string}}|mixed,
  1782.      *      id?: mixed,
  1783.      *      sourceToTargetKeyColumns?: array,
  1784.      *      joinColumnFieldNames?: array,
  1785.      *      targetToSourceKeyColumns?: array<array-key>,
  1786.      *      orphanRemoval: bool
  1787.      * }
  1788.      *
  1789.      * @throws RuntimeException
  1790.      * @throws MappingException
  1791.      */
  1792.     protected function _validateAndCompleteOneToOneMapping(array $mapping)
  1793.     {
  1794.         $mapping = $this->_validateAndCompleteAssociationMapping($mapping);
  1796.         if (isset($mapping['joinColumns']) && $mapping['joinColumns']) {
  1797.             $mapping['isOwningSide'] = true;
  1798.         }
  1800.         if ($mapping['isOwningSide']) {
  1801.             if (empty($mapping['joinColumns'])) {
  1802.                 // Apply default join column
  1803.                 $mapping['joinColumns'] = [
  1804.                     [
  1805.                         'name' => $this->namingStrategy->joinColumnName($mapping['fieldName'], $this->name),
  1806.                         'referencedColumnName' => $this->namingStrategy->referenceColumnName(),
  1807.                     ],
  1808.                 ];
  1809.             }
  1811.             $uniqueConstraintColumns = [];
  1813.             foreach ($mapping['joinColumns'] as &$joinColumn) {
  1814.                 if ($mapping['type'] === self::ONE_TO_ONE && ! $this->isInheritanceTypeSingleTable()) {
  1815.                     if (count($mapping['joinColumns']) === 1) {
  1816.                         if (empty($mapping['id'])) {
  1817.                             $joinColumn['unique'] = true;
  1818.                         }
  1819.                     } else {
  1820.                         $uniqueConstraintColumns[] = $joinColumn['name'];
  1821.                     }
  1822.                 }
  1824.                 if (empty($joinColumn['name'])) {
  1825.                     $joinColumn['name'] = $this->namingStrategy->joinColumnName($mapping['fieldName'], $this->name);
  1826.                 }
  1828.                 if (empty($joinColumn['referencedColumnName'])) {
  1829.                     $joinColumn['referencedColumnName'] = $this->namingStrategy->referenceColumnName();
  1830.                 }
  1832.                 if ($joinColumn['name'][0] === '`') {
  1833.                     $joinColumn['name']   = trim($joinColumn['name'], '`');
  1834.                     $joinColumn['quoted'] = true;
  1835.                 }
  1837.                 if ($joinColumn['referencedColumnName'][0] === '`') {
  1838.                     $joinColumn['referencedColumnName'] = trim($joinColumn['referencedColumnName'], '`');
  1839.                     $joinColumn['quoted']               = true;
  1840.                 }
  1842.                 $mapping['sourceToTargetKeyColumns'][$joinColumn['name']] = $joinColumn['referencedColumnName'];
  1843.                 $mapping['joinColumnFieldNames'][$joinColumn['name']]     = $joinColumn['fieldName'] ?? $joinColumn['name'];
  1844.             }
  1846.             if ($uniqueConstraintColumns) {
  1847.                 if (! $this->table) {
  1848.                     throw new RuntimeException('ClassMetadataInfo::setTable() has to be called before defining a one to one relationship.');
  1849.                 }
  1851.                 $this->table['uniqueConstraints'][$mapping['fieldName'] . '_uniq'] = ['columns' => $uniqueConstraintColumns];
  1852.             }
  1854.             $mapping['targetToSourceKeyColumns'] = array_flip($mapping['sourceToTargetKeyColumns']);
  1855.         }
  1857.         $mapping['orphanRemoval']   = isset($mapping['orphanRemoval']) && $mapping['orphanRemoval'];
  1858.         $mapping['isCascadeRemove'] = $mapping['orphanRemoval'] || $mapping['isCascadeRemove'];
  1860.         if ($mapping['orphanRemoval']) {
  1861.             unset($mapping['unique']);
  1862.         }
  1864.         if (isset($mapping['id']) && $mapping['id'] === true && ! $mapping['isOwningSide']) {
  1865.             throw MappingException::illegalInverseIdentifierAssociation($this->name, $mapping['fieldName']);
  1866.         }
  1868.         return $mapping;
  1869.     }
  1871.     /**
  1872.      * Validates & completes a one-to-many association mapping.
  1873.      *
  1874.      * @psalm-param array<string, mixed> $mapping The mapping to validate and complete.
  1875.      *
  1876.      * @return mixed[] The validated and completed mapping.
  1877.      * @psalm-return array{
  1878.      *                   mappedBy: mixed,
  1879.      *                   inversedBy: mixed,
  1880.      *                   isOwningSide: bool,
  1881.      *                   sourceEntity: string,
  1882.      *                   targetEntity: string,
  1883.      *                   fieldName: mixed,
  1884.      *                   fetch: int|mixed,
  1885.      *                   cascade: array<array-key,string>,
  1886.      *                   isCascadeRemove: bool,
  1887.      *                   isCascadePersist: bool,
  1888.      *                   isCascadeRefresh: bool,
  1889.      *                   isCascadeMerge: bool,
  1890.      *                   isCascadeDetach: bool,
  1891.      *                   orphanRemoval: bool
  1892.      *               }
  1893.      *
  1894.      * @throws MappingException
  1895.      * @throws InvalidArgumentException
  1896.      */
  1897.     protected function _validateAndCompleteOneToManyMapping(array $mapping)
  1898.     {
  1899.         $mapping = $this->_validateAndCompleteAssociationMapping($mapping);
  1901.         // OneToMany-side MUST be inverse (must have mappedBy)
  1902.         if (! isset($mapping['mappedBy'])) {
  1903.             throw MappingException::oneToManyRequiresMappedBy($this->name, $mapping['fieldName']);
  1904.         }
  1906.         $mapping['orphanRemoval']   = isset($mapping['orphanRemoval']) && $mapping['orphanRemoval'];
  1907.         $mapping['isCascadeRemove'] = $mapping['orphanRemoval'] || $mapping['isCascadeRemove'];
  1909.         $this->assertMappingOrderBy($mapping);
  1911.         return $mapping;
  1912.     }
  1914.     /**
  1915.      * Validates & completes a many-to-many association mapping.
  1916.      *
  1917.      * @psalm-param array<string, mixed> $mapping The mapping to validate & complete.
  1918.      * @psalm-param array<string, mixed> $mapping The mapping to validate & complete.
  1919.      *
  1920.      * @return mixed[] The validated & completed mapping.
  1921.      * @psalm-return array{
  1922.      *      mappedBy: mixed,
  1923.      *      inversedBy: mixed,
  1924.      *      isOwningSide: bool,
  1925.      *      sourceEntity: class-string,
  1926.      *      targetEntity: string,
  1927.      *      fieldName: mixed,
  1928.      *      fetch: mixed,
  1929.      *      cascade: array<string>,
  1930.      *      isCascadeRemove: bool,
  1931.      *      isCascadePersist: bool,
  1932.      *      isCascadeRefresh: bool,
  1933.      *      isCascadeMerge: bool,
  1934.      *      isCascadeDetach: bool,
  1935.      *      type: int,
  1936.      *      originalField: string,
  1937.      *      originalClass: class-string,
  1938.      *      joinTable?: array{inverseJoinColumns: mixed}|mixed,
  1939.      *      joinTableColumns?: list<mixed>,
  1940.      *      isOnDeleteCascade?: true,
  1941.      *      relationToSourceKeyColumns?: array,
  1942.      *      relationToTargetKeyColumns?: array,
  1943.      *      orphanRemoval: bool
  1944.      * }
  1945.      *
  1946.      * @throws InvalidArgumentException
  1947.      */
  1948.     protected function _validateAndCompleteManyToManyMapping(array $mapping)
  1949.     {
  1950.         $mapping = $this->_validateAndCompleteAssociationMapping($mapping);
  1952.         if ($mapping['isOwningSide']) {
  1953.             // owning side MUST have a join table
  1954.             if (! isset($mapping['joinTable']['name'])) {
  1955.                 $mapping['joinTable']['name'] = $this->namingStrategy->joinTableName($mapping['sourceEntity'], $mapping['targetEntity'], $mapping['fieldName']);
  1956.             }
  1958.             $selfReferencingEntityWithoutJoinColumns = $mapping['sourceEntity'] === $mapping['targetEntity']
  1959.                 && (! (isset($mapping['joinTable']['joinColumns']) || isset($mapping['joinTable']['inverseJoinColumns'])));
  1961.             if (! isset($mapping['joinTable']['joinColumns'])) {
  1962.                 $mapping['joinTable']['joinColumns'] = [
  1963.                     [
  1964.                         'name' => $this->namingStrategy->joinKeyColumnName($mapping['sourceEntity'], $selfReferencingEntityWithoutJoinColumns ? 'source' : null),
  1965.                         'referencedColumnName' => $this->namingStrategy->referenceColumnName(),
  1966.                         'onDelete' => 'CASCADE',
  1967.                     ],
  1968.                 ];
  1969.             }
  1971.             if (! isset($mapping['joinTable']['inverseJoinColumns'])) {
  1972.                 $mapping['joinTable']['inverseJoinColumns'] = [
  1973.                     [
  1974.                         'name' => $this->namingStrategy->joinKeyColumnName($mapping['targetEntity'], $selfReferencingEntityWithoutJoinColumns ? 'target' : null),
  1975.                         'referencedColumnName' => $this->namingStrategy->referenceColumnName(),
  1976.                         'onDelete' => 'CASCADE',
  1977.                     ],
  1978.                 ];
  1979.             }
  1981.             $mapping['joinTableColumns'] = [];
  1983.             foreach ($mapping['joinTable']['joinColumns'] as &$joinColumn) {
  1984.                 if (empty($joinColumn['name'])) {
  1985.                     $joinColumn['name'] = $this->namingStrategy->joinKeyColumnName($mapping['sourceEntity'], $joinColumn['referencedColumnName']);
  1986.                 }
  1988.                 if (empty($joinColumn['referencedColumnName'])) {
  1989.                     $joinColumn['referencedColumnName'] = $this->namingStrategy->referenceColumnName();
  1990.                 }
  1992.                 if ($joinColumn['name'][0] === '`') {
  1993.                     $joinColumn['name']   = trim($joinColumn['name'], '`');
  1994.                     $joinColumn['quoted'] = true;
  1995.                 }
  1997.                 if ($joinColumn['referencedColumnName'][0] === '`') {
  1998.                     $joinColumn['referencedColumnName'] = trim($joinColumn['referencedColumnName'], '`');
  1999.                     $joinColumn['quoted']               = true;
  2000.                 }
  2002.                 if (isset($joinColumn['onDelete']) && strtolower($joinColumn['onDelete']) === 'cascade') {
  2003.                     $mapping['isOnDeleteCascade'] = true;
  2004.                 }
  2006.                 $mapping['relationToSourceKeyColumns'][$joinColumn['name']] = $joinColumn['referencedColumnName'];
  2007.                 $mapping['joinTableColumns'][]                              = $joinColumn['name'];
  2008.             }
  2010.             foreach ($mapping['joinTable']['inverseJoinColumns'] as &$inverseJoinColumn) {
  2011.                 if (empty($inverseJoinColumn['name'])) {
  2012.                     $inverseJoinColumn['name'] = $this->namingStrategy->joinKeyColumnName($mapping['targetEntity'], $inverseJoinColumn['referencedColumnName']);
  2013.                 }
  2015.                 if (empty($inverseJoinColumn['referencedColumnName'])) {
  2016.                     $inverseJoinColumn['referencedColumnName'] = $this->namingStrategy->referenceColumnName();
  2017.                 }
  2019.                 if ($inverseJoinColumn['name'][0] === '`') {
  2020.                     $inverseJoinColumn['name']   = trim($inverseJoinColumn['name'], '`');
  2021.                     $inverseJoinColumn['quoted'] = true;
  2022.                 }
  2024.                 if ($inverseJoinColumn['referencedColumnName'][0] === '`') {
  2025.                     $inverseJoinColumn['referencedColumnName'] = trim($inverseJoinColumn['referencedColumnName'], '`');
  2026.                     $inverseJoinColumn['quoted']               = true;
  2027.                 }
  2029.                 if (isset($inverseJoinColumn['onDelete']) && strtolower($inverseJoinColumn['onDelete']) === 'cascade') {
  2030.                     $mapping['isOnDeleteCascade'] = true;
  2031.                 }
  2033.                 $mapping['relationToTargetKeyColumns'][$inverseJoinColumn['name']] = $inverseJoinColumn['referencedColumnName'];
  2034.                 $mapping['joinTableColumns'][]                                     = $inverseJoinColumn['name'];
  2035.             }
  2036.         }
  2038.         $mapping['orphanRemoval'] = isset($mapping['orphanRemoval']) && $mapping['orphanRemoval'];
  2040.         $this->assertMappingOrderBy($mapping);
  2042.         return $mapping;
  2043.     }
  2045.     /**
  2046.      * {@inheritDoc}
  2047.      */
  2048.     public function getIdentifierFieldNames()
  2049.     {
  2050.         return $this->identifier;
  2051.     }
  2053.     /**
  2054.      * Gets the name of the single id field. Note that this only works on
  2055.      * entity classes that have a single-field pk.
  2056.      *
  2057.      * @return string
  2058.      *
  2059.      * @throws MappingException If the class doesn't have an identifier or it has a composite primary key.
  2060.      */
  2061.     public function getSingleIdentifierFieldName()
  2062.     {
  2063.         if ($this->isIdentifierComposite) {
  2064.             throw MappingException::singleIdNotAllowedOnCompositePrimaryKey($this->name);
  2065.         }
  2067.         if (! isset($this->identifier[0])) {
  2068.             throw MappingException::noIdDefined($this->name);
  2069.         }
  2071.         return $this->identifier[0];
  2072.     }
  2074.     /**
  2075.      * Gets the column name of the single id column. Note that this only works on
  2076.      * entity classes that have a single-field pk.
  2077.      *
  2078.      * @return string
  2079.      *
  2080.      * @throws MappingException If the class doesn't have an identifier or it has a composite primary key.
  2081.      */
  2082.     public function getSingleIdentifierColumnName()
  2083.     {
  2084.         return $this->getColumnName($this->getSingleIdentifierFieldName());
  2085.     }
  2087.     /**
  2088.      * INTERNAL:
  2089.      * Sets the mapped identifier/primary key fields of this class.
  2090.      * Mainly used by the ClassMetadataFactory to assign inherited identifiers.
  2091.      *
  2092.      * @psalm-param list<mixed> $identifier
  2093.      *
  2094.      * @return void
  2095.      */
  2096.     public function setIdentifier(array $identifier)
  2097.     {
  2098.         $this->identifier            = $identifier;
  2099.         $this->isIdentifierComposite = (count($this->identifier) > 1);
  2100.     }
  2102.     /**
  2103.      * {@inheritDoc}
  2104.      */
  2105.     public function getIdentifier()
  2106.     {
  2107.         return $this->identifier;
  2108.     }
  2110.     /**
  2111.      * {@inheritDoc}
  2112.      */
  2113.     public function hasField($fieldName)
  2114.     {
  2115.         return isset($this->fieldMappings[$fieldName]) || isset($this->embeddedClasses[$fieldName]);
  2116.     }
  2118.     /**
  2119.      * Gets an array containing all the column names.
  2120.      *
  2121.      * @psalm-param list<string>|null $fieldNames
  2122.      *
  2123.      * @return mixed[]
  2124.      * @psalm-return list<string>
  2125.      */
  2126.     public function getColumnNames(?array $fieldNames = null)
  2127.     {
  2128.         if ($fieldNames === null) {
  2129.             return array_keys($this->fieldNames);
  2130.         }
  2132.         return array_values(array_map([$this, 'getColumnName'], $fieldNames));
  2133.     }
  2135.     /**
  2136.      * Returns an array with all the identifier column names.
  2137.      *
  2138.      * @psalm-return list<string>
  2139.      */
  2140.     public function getIdentifierColumnNames()
  2141.     {
  2142.         $columnNames = [];
  2144.         foreach ($this->identifier as $idProperty) {
  2145.             if (isset($this->fieldMappings[$idProperty])) {
  2146.                 $columnNames[] = $this->fieldMappings[$idProperty]['columnName'];
  2148.                 continue;
  2149.             }
  2151.             // Association defined as Id field
  2152.             $joinColumns      = $this->associationMappings[$idProperty]['joinColumns'];
  2153.             $assocColumnNames = array_map(static function ($joinColumn) {
  2154.                 return $joinColumn['name'];
  2155.             }, $joinColumns);
  2157.             $columnNames = array_merge($columnNames, $assocColumnNames);
  2158.         }
  2160.         return $columnNames;
  2161.     }
  2163.     /**
  2164.      * Sets the type of Id generator to use for the mapped class.
  2165.      *
  2166.      * @param int $generatorType
  2167.      *
  2168.      * @return void
  2169.      */
  2170.     public function setIdGeneratorType($generatorType)
  2171.     {
  2172.         $this->generatorType = $generatorType;
  2173.     }
  2175.     /**
  2176.      * Checks whether the mapped class uses an Id generator.
  2177.      *
  2178.      * @return bool TRUE if the mapped class uses an Id generator, FALSE otherwise.
  2179.      */
  2180.     public function usesIdGenerator()
  2181.     {
  2182.         return $this->generatorType !== self::GENERATOR_TYPE_NONE;
  2183.     }
  2185.     /**
  2186.      * @return bool
  2187.      */
  2188.     public function isInheritanceTypeNone()
  2189.     {
  2190.         return $this->inheritanceType === self::INHERITANCE_TYPE_NONE;
  2191.     }
  2193.     /**
  2194.      * Checks whether the mapped class uses the JOINED inheritance mapping strategy.
  2195.      *
  2196.      * @return bool TRUE if the class participates in a JOINED inheritance mapping,
  2197.      * FALSE otherwise.
  2198.      */
  2199.     public function isInheritanceTypeJoined()
  2200.     {
  2201.         return $this->inheritanceType === self::INHERITANCE_TYPE_JOINED;
  2202.     }
  2204.     /**
  2205.      * Checks whether the mapped class uses the SINGLE_TABLE inheritance mapping strategy.
  2206.      *
  2207.      * @return bool TRUE if the class participates in a SINGLE_TABLE inheritance mapping,
  2208.      * FALSE otherwise.
  2209.      */
  2210.     public function isInheritanceTypeSingleTable()
  2211.     {
  2212.         return $this->inheritanceType === self::INHERITANCE_TYPE_SINGLE_TABLE;
  2213.     }
  2215.     /**
  2216.      * Checks whether the mapped class uses the TABLE_PER_CLASS inheritance mapping strategy.
  2217.      *
  2218.      * @return bool TRUE if the class participates in a TABLE_PER_CLASS inheritance mapping,
  2219.      * FALSE otherwise.
  2220.      */
  2221.     public function isInheritanceTypeTablePerClass()
  2222.     {
  2223.         return $this->inheritanceType === self::INHERITANCE_TYPE_TABLE_PER_CLASS;
  2224.     }
  2226.     /**
  2227.      * Checks whether the class uses an identity column for the Id generation.
  2228.      *
  2229.      * @return bool TRUE if the class uses the IDENTITY generator, FALSE otherwise.
  2230.      */
  2231.     public function isIdGeneratorIdentity()
  2232.     {
  2233.         return $this->generatorType === self::GENERATOR_TYPE_IDENTITY;
  2234.     }
  2236.     /**
  2237.      * Checks whether the class uses a sequence for id generation.
  2238.      *
  2239.      * @return bool TRUE if the class uses the SEQUENCE generator, FALSE otherwise.
  2240.      */
  2241.     public function isIdGeneratorSequence()
  2242.     {
  2243.         return $this->generatorType === self::GENERATOR_TYPE_SEQUENCE;
  2244.     }
  2246.     /**
  2247.      * Checks whether the class uses a table for id generation.
  2248.      *
  2249.      * @return bool TRUE if the class uses the TABLE generator, FALSE otherwise.
  2250.      */
  2251.     public function isIdGeneratorTable()
  2252.     {
  2253.         return $this->generatorType === self::GENERATOR_TYPE_TABLE;
  2254.     }
  2256.     /**
  2257.      * Checks whether the class has a natural identifier/pk (which means it does
  2258.      * not use any Id generator.
  2259.      *
  2260.      * @return bool
  2261.      */
  2262.     public function isIdentifierNatural()
  2263.     {
  2264.         return $this->generatorType === self::GENERATOR_TYPE_NONE;
  2265.     }
  2267.     /**
  2268.      * Checks whether the class use a UUID for id generation.
  2269.      *
  2270.      * @return bool
  2271.      */
  2272.     public function isIdentifierUuid()
  2273.     {
  2274.         return $this->generatorType === self::GENERATOR_TYPE_UUID;
  2275.     }
  2277.     /**
  2278.      * Gets the type of a field.
  2279.      *
  2280.      * @param string $fieldName
  2281.      *
  2282.      * @return string|null
  2283.      *
  2284.      * @todo 3.0 Remove this. PersisterHelper should fix it somehow
  2285.      */
  2286.     public function getTypeOfField($fieldName)
  2287.     {
  2288.         return isset($this->fieldMappings[$fieldName])
  2289.             ? $this->fieldMappings[$fieldName]['type']
  2290.             : null;
  2291.     }
  2293.     /**
  2294.      * Gets the type of a column.
  2295.      *
  2296.      * @deprecated 3.0 remove this. this method is bogus and unreliable, since it cannot resolve the type of a column
  2297.      *             that is derived by a referenced field on a different entity.
  2298.      *
  2299.      * @param string $columnName
  2300.      *
  2301.      * @return string|null
  2302.      */
  2303.     public function getTypeOfColumn($columnName)
  2304.     {
  2305.         return $this->getTypeOfField($this->getFieldName($columnName));
  2306.     }
  2308.     /**
  2309.      * Gets the name of the primary table.
  2310.      *
  2311.      * @return string
  2312.      */
  2313.     public function getTableName()
  2314.     {
  2315.         return $this->table['name'];
  2316.     }
  2318.     /**
  2319.      * Gets primary table's schema name.
  2320.      *
  2321.      * @return string|null
  2322.      */
  2323.     public function getSchemaName()
  2324.     {
  2325.         return $this->table['schema'] ?? null;
  2326.     }
  2328.     /**
  2329.      * Gets the table name to use for temporary identifier tables of this class.
  2330.      *
  2331.      * @return string
  2332.      */
  2333.     public function getTemporaryIdTableName()
  2334.     {
  2335.         // replace dots with underscores because PostgreSQL creates temporary tables in a special schema
  2336.         return str_replace('.', '_', $this->getTableName() . '_id_tmp');
  2337.     }
  2339.     /**
  2340.      * Sets the mapped subclasses of this class.
  2341.      *
  2342.      * @psalm-param list<string> $subclasses The names of all mapped subclasses.
  2343.      *
  2344.      * @return void
  2345.      */
  2346.     public function setSubclasses(array $subclasses)
  2347.     {
  2348.         foreach ($subclasses as $subclass) {
  2349.             $this->subClasses[] = $this->fullyQualifiedClassName($subclass);
  2350.         }
  2351.     }
  2353.     /**
  2354.      * Sets the parent class names.
  2355.      * Assumes that the class names in the passed array are in the order:
  2356.      * directParent -> directParentParent -> directParentParentParent ... -> root.
  2357.      *
  2358.      * @psalm-param list<class-string> $classNames
  2359.      *
  2360.      * @return void
  2361.      */
  2362.     public function setParentClasses(array $classNames)
  2363.     {
  2364.         $this->parentClasses = $classNames;
  2366.         if (count($classNames) > 0) {
  2367.             $this->rootEntityName = array_pop($classNames);
  2368.         }
  2369.     }
  2371.     /**
  2372.      * Sets the inheritance type used by the class and its subclasses.
  2373.      *
  2374.      * @param int $type
  2375.      *
  2376.      * @return void
  2377.      *
  2378.      * @throws MappingException
  2379.      */
  2380.     public function setInheritanceType($type)
  2381.     {
  2382.         if (! $this->isInheritanceType($type)) {
  2383.             throw MappingException::invalidInheritanceType($this->name, $type);
  2384.         }
  2386.         $this->inheritanceType = $type;
  2387.     }
  2389.     /**
  2390.      * Sets the association to override association mapping of property for an entity relationship.
  2391.      *
  2392.      * @param string $fieldName
  2393.      * @psalm-param array<string, mixed> $overrideMapping
  2394.      *
  2395.      * @return void
  2396.      *
  2397.      * @throws MappingException
  2398.      */
  2399.     public function setAssociationOverride($fieldName, array $overrideMapping)
  2400.     {
  2401.         if (! isset($this->associationMappings[$fieldName])) {
  2402.             throw MappingException::invalidOverrideFieldName($this->name, $fieldName);
  2403.         }
  2405.         $mapping = $this->associationMappings[$fieldName];
  2407.         //if (isset($mapping['inherited']) && (count($overrideMapping) !== 1 || ! isset($overrideMapping['fetch']))) {
  2408.             // TODO: Deprecate overriding the fetch mode via association override for 3.0,
  2409.             // users should do this with a listener and a custom attribute/annotation
  2410.             // TODO: Enable this exception in 2.8
  2411.             //throw MappingException::illegalOverrideOfInheritedProperty($this->name, $fieldName);
  2412.         //}
  2414.         if (isset($overrideMapping['joinColumns'])) {
  2415.             $mapping['joinColumns'] = $overrideMapping['joinColumns'];
  2416.         }
  2418.         if (isset($overrideMapping['inversedBy'])) {
  2419.             $mapping['inversedBy'] = $overrideMapping['inversedBy'];
  2420.         }
  2422.         if (isset($overrideMapping['joinTable'])) {
  2423.             $mapping['joinTable'] = $overrideMapping['joinTable'];
  2424.         }
  2426.         if (isset($overrideMapping['fetch'])) {
  2427.             $mapping['fetch'] = $overrideMapping['fetch'];
  2428.         }
  2430.         $mapping['joinColumnFieldNames']       = null;
  2431.         $mapping['joinTableColumns']           = null;
  2432.         $mapping['sourceToTargetKeyColumns']   = null;
  2433.         $mapping['relationToSourceKeyColumns'] = null;
  2434.         $mapping['relationToTargetKeyColumns'] = null;
  2436.         switch ($mapping['type']) {
  2437.             case self::ONE_TO_ONE:
  2438.                 $mapping = $this->_validateAndCompleteOneToOneMapping($mapping);
  2439.                 break;
  2440.             case self::ONE_TO_MANY:
  2441.                 $mapping = $this->_validateAndCompleteOneToManyMapping($mapping);
  2442.                 break;
  2443.             case self::MANY_TO_ONE:
  2444.                 $mapping = $this->_validateAndCompleteOneToOneMapping($mapping);
  2445.                 break;
  2446.             case self::MANY_TO_MANY:
  2447.                 $mapping = $this->_validateAndCompleteManyToManyMapping($mapping);
  2448.                 break;
  2449.         }
  2451.         $this->associationMappings[$fieldName] = $mapping;
  2452.     }
  2454.     /**
  2455.      * Sets the override for a mapped field.
  2456.      *
  2457.      * @param string $fieldName
  2458.      * @psalm-param array<string, mixed> $overrideMapping
  2459.      *
  2460.      * @return void
  2461.      *
  2462.      * @throws MappingException
  2463.      */
  2464.     public function setAttributeOverride($fieldName, array $overrideMapping)
  2465.     {
  2466.         if (! isset($this->fieldMappings[$fieldName])) {
  2467.             throw MappingException::invalidOverrideFieldName($this->name, $fieldName);
  2468.         }
  2470.         $mapping = $this->fieldMappings[$fieldName];
  2472.         //if (isset($mapping['inherited'])) {
  2473.             // TODO: Enable this exception in 2.8
  2474.             //throw MappingException::illegalOverrideOfInheritedProperty($this->name, $fieldName);
  2475.         //}
  2477.         if (isset($mapping['id'])) {
  2478.             $overrideMapping['id'] = $mapping['id'];
  2479.         }
  2481.         if (! isset($overrideMapping['type'])) {
  2482.             $overrideMapping['type'] = $mapping['type'];
  2483.         }
  2485.         if (! isset($overrideMapping['fieldName'])) {
  2486.             $overrideMapping['fieldName'] = $mapping['fieldName'];
  2487.         }
  2489.         if ($overrideMapping['type'] !== $mapping['type']) {
  2490.             throw MappingException::invalidOverrideFieldType($this->name, $fieldName);
  2491.         }
  2493.         unset($this->fieldMappings[$fieldName]);
  2494.         unset($this->fieldNames[$mapping['columnName']]);
  2495.         unset($this->columnNames[$mapping['fieldName']]);
  2497.         $overrideMapping = $this->validateAndCompleteFieldMapping($overrideMapping);
  2499.         $this->fieldMappings[$fieldName] = $overrideMapping;
  2500.     }
  2502.     /**
  2503.      * Checks whether a mapped field is inherited from an entity superclass.
  2504.      *
  2505.      * @param string $fieldName
  2506.      *
  2507.      * @return bool TRUE if the field is inherited, FALSE otherwise.
  2508.      */
  2509.     public function isInheritedField($fieldName)
  2510.     {
  2511.         return isset($this->fieldMappings[$fieldName]['inherited']);
  2512.     }
  2514.     /**
  2515.      * Checks if this entity is the root in any entity-inheritance-hierarchy.
  2516.      *
  2517.      * @return bool
  2518.      */
  2519.     public function isRootEntity()
  2520.     {
  2521.         return $this->name === $this->rootEntityName;
  2522.     }
  2524.     /**
  2525.      * Checks whether a mapped association field is inherited from a superclass.
  2526.      *
  2527.      * @param string $fieldName
  2528.      *
  2529.      * @return bool TRUE if the field is inherited, FALSE otherwise.
  2530.      */
  2531.     public function isInheritedAssociation($fieldName)
  2532.     {
  2533.         return isset($this->associationMappings[$fieldName]['inherited']);
  2534.     }
  2536.     /**
  2537.      * @param string $fieldName
  2538.      *
  2539.      * @return bool
  2540.      */
  2541.     public function isInheritedEmbeddedClass($fieldName)
  2542.     {
  2543.         return isset($this->embeddedClasses[$fieldName]['inherited']);
  2544.     }
  2546.     /**
  2547.      * Sets the name of the primary table the class is mapped to.
  2548.      *
  2549.      * @deprecated Use {@link setPrimaryTable}.
  2550.      *
  2551.      * @param string $tableName The table name.
  2552.      *
  2553.      * @return void
  2554.      */
  2555.     public function setTableName($tableName)
  2556.     {
  2557.         $this->table['name'] = $tableName;
  2558.     }
  2560.     /**
  2561.      * Sets the primary table definition. The provided array supports the
  2562.      * following structure:
  2563.      *
  2564.      * name => <tableName> (optional, defaults to class name)
  2565.      * indexes => array of indexes (optional)
  2566.      * uniqueConstraints => array of constraints (optional)
  2567.      *
  2568.      * If a key is omitted, the current value is kept.
  2569.      *
  2570.      * @psalm-param array<string, mixed> $table The table description.
  2571.      *
  2572.      * @return void
  2573.      */
  2574.     public function setPrimaryTable(array $table)
  2575.     {
  2576.         if (isset($table['name'])) {
  2577.             // Split schema and table name from a table name like "myschema.mytable"
  2578.             if (strpos($table['name'], '.') !== false) {
  2579.                 [$this->table['schema'], $table['name']] = explode('.', $table['name'], 2);
  2580.             }
  2582.             if ($table['name'][0] === '`') {
  2583.                 $table['name']         = trim($table['name'], '`');
  2584.                 $this->table['quoted'] = true;
  2585.             }
  2587.             $this->table['name'] = $table['name'];
  2588.         }
  2590.         if (isset($table['quoted'])) {
  2591.             $this->table['quoted'] = $table['quoted'];
  2592.         }
  2594.         if (isset($table['schema'])) {
  2595.             $this->table['schema'] = $table['schema'];
  2596.         }
  2598.         if (isset($table['indexes'])) {
  2599.             $this->table['indexes'] = $table['indexes'];
  2600.         }
  2602.         if (isset($table['uniqueConstraints'])) {
  2603.             $this->table['uniqueConstraints'] = $table['uniqueConstraints'];
  2604.         }
  2606.         if (isset($table['options'])) {
  2607.             $this->table['options'] = $table['options'];
  2608.         }
  2609.     }
  2611.     /**
  2612.      * Checks whether the given type identifies an inheritance type.
  2613.      *
  2614.      * @return bool TRUE if the given type identifies an inheritance type, FALSE otherwise.
  2615.      */
  2616.     private function isInheritanceType(int $type): bool
  2617.     {
  2618.         return $type === self::INHERITANCE_TYPE_NONE ||
  2619.                 $type === self::INHERITANCE_TYPE_SINGLE_TABLE ||
  2620.                 $type === self::INHERITANCE_TYPE_JOINED ||
  2621.                 $type === self::INHERITANCE_TYPE_TABLE_PER_CLASS;
  2622.     }
  2624.     /**
  2625.      * Adds a mapped field to the class.
  2626.      *
  2627.      * @psalm-param array<string, mixed> $mapping The field mapping.
  2628.      *
  2629.      * @return void
  2630.      *
  2631.      * @throws MappingException
  2632.      */
  2633.     public function mapField(array $mapping)
  2634.     {
  2635.         $mapping = $this->validateAndCompleteFieldMapping($mapping);
  2636.         $this->assertFieldNotMapped($mapping['fieldName']);
  2638.         $this->fieldMappings[$mapping['fieldName']] = $mapping;
  2639.     }
  2641.     /**
  2642.      * INTERNAL:
  2643.      * Adds an association mapping without completing/validating it.
  2644.      * This is mainly used to add inherited association mappings to derived classes.
  2645.      *
  2646.      * @psalm-param array<string, mixed> $mapping
  2647.      *
  2648.      * @return void
  2649.      *
  2650.      * @throws MappingException
  2651.      */
  2652.     public function addInheritedAssociationMapping(array $mapping/*, $owningClassName = null*/)
  2653.     {
  2654.         if (isset($this->associationMappings[$mapping['fieldName']])) {
  2655.             throw MappingException::duplicateAssociationMapping($this->name, $mapping['fieldName']);
  2656.         }
  2658.         $this->associationMappings[$mapping['fieldName']] = $mapping;
  2659.     }
  2661.     /**
  2662.      * INTERNAL:
  2663.      * Adds a field mapping without completing/validating it.
  2664.      * This is mainly used to add inherited field mappings to derived classes.
  2665.      *
  2666.      * @psalm-param array<string, mixed> $fieldMapping
  2667.      *
  2668.      * @return void
  2669.      */
  2670.     public function addInheritedFieldMapping(array $fieldMapping)
  2671.     {
  2672.         $this->fieldMappings[$fieldMapping['fieldName']] = $fieldMapping;
  2673.         $this->columnNames[$fieldMapping['fieldName']]   = $fieldMapping['columnName'];
  2674.         $this->fieldNames[$fieldMapping['columnName']]   = $fieldMapping['fieldName'];
  2675.     }
  2677.     /**
  2678.      * INTERNAL:
  2679.      * Adds a named query to this class.
  2680.      *
  2681.      * @deprecated
  2682.      *
  2683.      * @psalm-param array<string, mixed> $queryMapping
  2684.      *
  2685.      * @return void
  2686.      *
  2687.      * @throws MappingException
  2688.      */
  2689.     public function addNamedQuery(array $queryMapping)
  2690.     {
  2691.         if (! isset($queryMapping['name'])) {
  2692.             throw MappingException::nameIsMandatoryForQueryMapping($this->name);
  2693.         }
  2695.         Deprecation::trigger(
  2696.             'doctrine/orm',
  2697.             'https://github.com/doctrine/orm/issues/8592',
  2698.             'Named Queries are deprecated, here "%s" on entity %s. Move the query logic into EntityRepository',
  2699.             $queryMapping['name'],
  2700.             $this->name
  2701.         );
  2703.         if (isset($this->namedQueries[$queryMapping['name']])) {
  2704.             throw MappingException::duplicateQueryMapping($this->name, $queryMapping['name']);
  2705.         }
  2707.         if (! isset($queryMapping['query'])) {
  2708.             throw MappingException::emptyQueryMapping($this->name, $queryMapping['name']);
  2709.         }
  2711.         $name  = $queryMapping['name'];
  2712.         $query = $queryMapping['query'];
  2713.         $dql   = str_replace('__CLASS__', $this->name, $query);
  2715.         $this->namedQueries[$name] = [
  2716.             'name'  => $name,
  2717.             'query' => $query,
  2718.             'dql'   => $dql,
  2719.         ];
  2720.     }
  2722.     /**
  2723.      * INTERNAL:
  2724.      * Adds a named native query to this class.
  2725.      *
  2726.      * @deprecated
  2727.      *
  2728.      * @psalm-param array<string, mixed> $queryMapping
  2729.      *
  2730.      * @return void
  2731.      *
  2732.      * @throws MappingException
  2733.      */
  2734.     public function addNamedNativeQuery(array $queryMapping)
  2735.     {
  2736.         if (! isset($queryMapping['name'])) {
  2737.             throw MappingException::nameIsMandatoryForQueryMapping($this->name);
  2738.         }
  2740.         Deprecation::trigger(
  2741.             'doctrine/orm',
  2742.             'https://github.com/doctrine/orm/issues/8592',
  2743.             'Named Native Queries are deprecated, here "%s" on entity %s. Move the query logic into EntityRepository',
  2744.             $queryMapping['name'],
  2745.             $this->name
  2746.         );
  2748.         if (isset($this->namedNativeQueries[$queryMapping['name']])) {
  2749.             throw MappingException::duplicateQueryMapping($this->name, $queryMapping['name']);
  2750.         }
  2752.         if (! isset($queryMapping['query'])) {
  2753.             throw MappingException::emptyQueryMapping($this->name, $queryMapping['name']);
  2754.         }
  2756.         if (! isset($queryMapping['resultClass']) && ! isset($queryMapping['resultSetMapping'])) {
  2757.             throw MappingException::missingQueryMapping($this->name, $queryMapping['name']);
  2758.         }
  2760.         $queryMapping['isSelfClass'] = false;
  2762.         if (isset($queryMapping['resultClass'])) {
  2763.             if ($queryMapping['resultClass'] === '__CLASS__') {
  2764.                 $queryMapping['isSelfClass'] = true;
  2765.                 $queryMapping['resultClass'] = $this->name;
  2766.             }
  2768.             $queryMapping['resultClass'] = $this->fullyQualifiedClassName($queryMapping['resultClass']);
  2769.             $queryMapping['resultClass'] = ltrim($queryMapping['resultClass'], '\\');
  2770.         }
  2772.         $this->namedNativeQueries[$queryMapping['name']] = $queryMapping;
  2773.     }
  2775.     /**
  2776.      * INTERNAL:
  2777.      * Adds a sql result set mapping to this class.
  2778.      *
  2779.      * @psalm-param array<string, mixed> $resultMapping
  2780.      *
  2781.      * @return void
  2782.      *
  2783.      * @throws MappingException
  2784.      */
  2785.     public function addSqlResultSetMapping(array $resultMapping)
  2786.     {
  2787.         if (! isset($resultMapping['name'])) {
  2788.             throw MappingException::nameIsMandatoryForSqlResultSetMapping($this->name);
  2789.         }
  2791.         if (isset($this->sqlResultSetMappings[$resultMapping['name']])) {
  2792.             throw MappingException::duplicateResultSetMapping($this->name, $resultMapping['name']);
  2793.         }
  2795.         if (isset($resultMapping['entities'])) {
  2796.             foreach ($resultMapping['entities'] as $key => $entityResult) {
  2797.                 if (! isset($entityResult['entityClass'])) {
  2798.                     throw MappingException::missingResultSetMappingEntity($this->name, $resultMapping['name']);
  2799.                 }
  2801.                 $entityResult['isSelfClass'] = false;
  2802.                 if ($entityResult['entityClass'] === '__CLASS__') {
  2803.                     $entityResult['isSelfClass'] = true;
  2804.                     $entityResult['entityClass'] = $this->name;
  2805.                 }
  2807.                 $entityResult['entityClass'] = $this->fullyQualifiedClassName($entityResult['entityClass']);
  2809.                 $resultMapping['entities'][$key]['entityClass'] = ltrim($entityResult['entityClass'], '\\');
  2810.                 $resultMapping['entities'][$key]['isSelfClass'] = $entityResult['isSelfClass'];
  2812.                 if (isset($entityResult['fields'])) {
  2813.                     foreach ($entityResult['fields'] as $k => $field) {
  2814.                         if (! isset($field['name'])) {
  2815.                             throw MappingException::missingResultSetMappingFieldName($this->name, $resultMapping['name']);
  2816.                         }
  2818.                         if (! isset($field['column'])) {
  2819.                             $fieldName = $field['name'];
  2820.                             if (strpos($fieldName, '.')) {
  2821.                                 [, $fieldName] = explode('.', $fieldName);
  2822.                             }
  2824.                             $resultMapping['entities'][$key]['fields'][$k]['column'] = $fieldName;
  2825.                         }
  2826.                     }
  2827.                 }
  2828.             }
  2829.         }
  2831.         $this->sqlResultSetMappings[$resultMapping['name']] = $resultMapping;
  2832.     }
  2834.     /**
  2835.      * Adds a one-to-one mapping.
  2836.      *
  2837.      * @param array<string, mixed> $mapping The mapping.
  2838.      *
  2839.      * @return void
  2840.      */
  2841.     public function mapOneToOne(array $mapping)
  2842.     {
  2843.         $mapping['type'] = self::ONE_TO_ONE;
  2845.         $mapping = $this->_validateAndCompleteOneToOneMapping($mapping);
  2847.         $this->_storeAssociationMapping($mapping);
  2848.     }
  2850.     /**
  2851.      * Adds a one-to-many mapping.
  2852.      *
  2853.      * @psalm-param array<string, mixed> $mapping The mapping.
  2854.      *
  2855.      * @return void
  2856.      */
  2857.     public function mapOneToMany(array $mapping)
  2858.     {
  2859.         $mapping['type'] = self::ONE_TO_MANY;
  2861.         $mapping = $this->_validateAndCompleteOneToManyMapping($mapping);
  2863.         $this->_storeAssociationMapping($mapping);
  2864.     }
  2866.     /**
  2867.      * Adds a many-to-one mapping.
  2868.      *
  2869.      * @psalm-param array<string, mixed> $mapping The mapping.
  2870.      *
  2871.      * @return void
  2872.      */
  2873.     public function mapManyToOne(array $mapping)
  2874.     {
  2875.         $mapping['type'] = self::MANY_TO_ONE;
  2877.         // A many-to-one mapping is essentially a one-one backreference
  2878.         $mapping = $this->_validateAndCompleteOneToOneMapping($mapping);
  2880.         $this->_storeAssociationMapping($mapping);
  2881.     }
  2883.     /**
  2884.      * Adds a many-to-many mapping.
  2885.      *
  2886.      * @psalm-param array<string, mixed> $mapping The mapping.
  2887.      *
  2888.      * @return void
  2889.      */
  2890.     public function mapManyToMany(array $mapping)
  2891.     {
  2892.         $mapping['type'] = self::MANY_TO_MANY;
  2894.         $mapping = $this->_validateAndCompleteManyToManyMapping($mapping);
  2896.         $this->_storeAssociationMapping($mapping);
  2897.     }
  2899.     /**
  2900.      * Stores the association mapping.
  2901.      *
  2902.      * @psalm-param array<string, mixed> $assocMapping
  2903.      *
  2904.      * @return void
  2905.      *
  2906.      * @throws MappingException
  2907.      */
  2908.     protected function _storeAssociationMapping(array $assocMapping)
  2909.     {
  2910.         $sourceFieldName = $assocMapping['fieldName'];
  2912.         $this->assertFieldNotMapped($sourceFieldName);
  2914.         $this->associationMappings[$sourceFieldName] = $assocMapping;
  2915.     }
  2917.     /**
  2918.      * Registers a custom repository class for the entity class.
  2919.      *
  2920.      * @param string $repositoryClassName The class name of the custom mapper.
  2921.      * @psalm-param class-string $repositoryClassName
  2922.      *
  2923.      * @return void
  2924.      */
  2925.     public function setCustomRepositoryClass($repositoryClassName)
  2926.     {
  2927.         $this->customRepositoryClassName = $this->fullyQualifiedClassName($repositoryClassName);
  2928.     }
  2930.     /**
  2931.      * Dispatches the lifecycle event of the given entity to the registered
  2932.      * lifecycle callbacks and lifecycle listeners.
  2933.      *
  2934.      * @deprecated Deprecated since version 2.4 in favor of \Doctrine\ORM\Event\ListenersInvoker
  2935.      *
  2936.      * @param string $lifecycleEvent The lifecycle event.
  2937.      * @param object $entity         The Entity on which the event occurred.
  2938.      *
  2939.      * @return void
  2940.      */
  2941.     public function invokeLifecycleCallbacks($lifecycleEvent, $entity)
  2942.     {
  2943.         foreach ($this->lifecycleCallbacks[$lifecycleEvent] as $callback) {
  2944.             $entity->$callback();
  2945.         }
  2946.     }
  2948.     /**
  2949.      * Whether the class has any attached lifecycle listeners or callbacks for a lifecycle event.
  2950.      *
  2951.      * @param string $lifecycleEvent
  2952.      *
  2953.      * @return bool
  2954.      */
  2955.     public function hasLifecycleCallbacks($lifecycleEvent)
  2956.     {
  2957.         return isset($this->lifecycleCallbacks[$lifecycleEvent]);
  2958.     }
  2960.     /**
  2961.      * Gets the registered lifecycle callbacks for an event.
  2962.      *
  2963.      * @param string $event
  2964.      *
  2965.      * @psalm-return list<string>
  2966.      */
  2967.     public function getLifecycleCallbacks($event)
  2968.     {
  2969.         return $this->lifecycleCallbacks[$event] ?? [];
  2970.     }
  2972.     /**
  2973.      * Adds a lifecycle callback for entities of this class.
  2974.      *
  2975.      * @param string $callback
  2976.      * @param string $event
  2977.      *
  2978.      * @return void
  2979.      */
  2980.     public function addLifecycleCallback($callback, $event)
  2981.     {
  2982.         if ($this->isEmbeddedClass) {
  2983.             Deprecation::trigger(
  2984.                 'doctrine/orm',
  2985.                 'https://github.com/doctrine/orm/pull/8381',
  2986.                 'Registering lifecycle callback %s on Embedded class %s is not doing anything and will throw exception in 3.0',
  2987.                 $event,
  2988.                 $this->name
  2989.             );
  2990.         }
  2992.         if (isset($this->lifecycleCallbacks[$event]) && in_array($callback, $this->lifecycleCallbacks[$event])) {
  2993.             return;
  2994.         }
  2996.         $this->lifecycleCallbacks[$event][] = $callback;
  2997.     }
  2999.     /**
  3000.      * Sets the lifecycle callbacks for entities of this class.
  3001.      * Any previously registered callbacks are overwritten.
  3002.      *
  3003.      * @psalm-param array<string, list<string>> $callbacks
  3004.      *
  3005.      * @return void
  3006.      */
  3007.     public function setLifecycleCallbacks(array $callbacks)
  3008.     {
  3009.         $this->lifecycleCallbacks = $callbacks;
  3010.     }
  3012.     /**
  3013.      * Adds a entity listener for entities of this class.
  3014.      *
  3015.      * @param string $eventName The entity lifecycle event.
  3016.      * @param string $class     The listener class.
  3017.      * @param string $method    The listener callback method.
  3018.      *
  3019.      * @return void
  3020.      *
  3021.      * @throws MappingException
  3022.      */
  3023.     public function addEntityListener($eventName, $class, $method)
  3024.     {
  3025.         $class = $this->fullyQualifiedClassName($class);
  3027.         $listener = [
  3028.             'class'  => $class,
  3029.             'method' => $method,
  3030.         ];
  3032.         if (! class_exists($class)) {
  3033.             throw MappingException::entityListenerClassNotFound($class, $this->name);
  3034.         }
  3036.         if (! method_exists($class, $method)) {
  3037.             throw MappingException::entityListenerMethodNotFound($class, $method, $this->name);
  3038.         }
  3040.         if (isset($this->entityListeners[$eventName]) && in_array($listener, $this->entityListeners[$eventName])) {
  3041.             throw MappingException::duplicateEntityListener($class, $method, $this->name);
  3042.         }
  3044.         $this->entityListeners[$eventName][] = $listener;
  3045.     }
  3047.     /**
  3048.      * Sets the discriminator column definition.
  3049.      *
  3050.      * @see getDiscriminatorColumn()
  3051.      *
  3052.      * @psalm-param array<string, mixed> $columnDef
  3053.      *
  3054.      * @return void
  3055.      *
  3056.      * @throws MappingException
  3057.      */
  3058.     public function setDiscriminatorColumn($columnDef)
  3059.     {
  3060.         if ($columnDef !== null) {
  3061.             if (! isset($columnDef['name'])) {
  3062.                 throw MappingException::nameIsMandatoryForDiscriminatorColumns($this->name);
  3063.             }
  3065.             if (isset($this->fieldNames[$columnDef['name']])) {
  3066.                 throw MappingException::duplicateColumnName($this->name, $columnDef['name']);
  3067.             }
  3069.             if (! isset($columnDef['fieldName'])) {
  3070.                 $columnDef['fieldName'] = $columnDef['name'];
  3071.             }
  3073.             if (! isset($columnDef['type'])) {
  3074.                 $columnDef['type'] = 'string';
  3075.             }
  3077.             if (in_array($columnDef['type'], ['boolean', 'array', 'object', 'datetime', 'time', 'date'])) {
  3078.                 throw MappingException::invalidDiscriminatorColumnType($this->name, $columnDef['type']);
  3079.             }
  3081.             $this->discriminatorColumn = $columnDef;
  3082.         }
  3083.     }
  3085.     /**
  3086.      * Sets the discriminator values used by this class.
  3087.      * Used for JOINED and SINGLE_TABLE inheritance mapping strategies.
  3088.      *
  3089.      * @psalm-param array<string, class-string> $map
  3090.      *
  3091.      * @return void
  3092.      */
  3093.     public function setDiscriminatorMap(array $map)
  3094.     {
  3095.         foreach ($map as $value => $className) {
  3096.             $this->addDiscriminatorMapClass($value, $className);
  3097.         }
  3098.     }
  3100.     /**
  3101.      * Adds one entry of the discriminator map with a new class and corresponding name.
  3102.      *
  3103.      * @param string $name
  3104.      * @psalm-param class-string $className
  3105.      *
  3106.      * @return void
  3107.      *
  3108.      * @throws MappingException
  3109.      */
  3110.     public function addDiscriminatorMapClass($name, $className)
  3111.     {
  3112.         $className = $this->fullyQualifiedClassName($className);
  3113.         $className = ltrim($className, '\\');
  3115.         $this->discriminatorMap[$name] = $className;
  3117.         if ($this->name === $className) {
  3118.             $this->discriminatorValue = $name;
  3120.             return;
  3121.         }
  3123.         if (! (class_exists($className) || interface_exists($className))) {
  3124.             throw MappingException::invalidClassInDiscriminatorMap($className, $this->name);
  3125.         }
  3127.         if (is_subclass_of($className, $this->name) && ! in_array($className, $this->subClasses)) {
  3128.             $this->subClasses[] = $className;
  3129.         }
  3130.     }
  3132.     /**
  3133.      * Checks whether the class has a named query with the given query name.
  3134.      *
  3135.      * @param string $queryName
  3136.      *
  3137.      * @return bool
  3138.      */
  3139.     public function hasNamedQuery($queryName)
  3140.     {
  3141.         return isset($this->namedQueries[$queryName]);
  3142.     }
  3144.     /**
  3145.      * Checks whether the class has a named native query with the given query name.
  3146.      *
  3147.      * @param string $queryName
  3148.      *
  3149.      * @return bool
  3150.      */
  3151.     public function hasNamedNativeQuery($queryName)
  3152.     {
  3153.         return isset($this->namedNativeQueries[$queryName]);
  3154.     }
  3156.     /**
  3157.      * Checks whether the class has a named native query with the given query name.
  3158.      *
  3159.      * @param string $name
  3160.      *
  3161.      * @return bool
  3162.      */
  3163.     public function hasSqlResultSetMapping($name)
  3164.     {
  3165.         return isset($this->sqlResultSetMappings[$name]);
  3166.     }
  3168.     /**
  3169.      * {@inheritDoc}
  3170.      */
  3171.     public function hasAssociation($fieldName)
  3172.     {
  3173.         return isset($this->associationMappings[$fieldName]);
  3174.     }
  3176.     /**
  3177.      * {@inheritDoc}
  3178.      */
  3179.     public function isSingleValuedAssociation($fieldName)
  3180.     {
  3181.         return isset($this->associationMappings[$fieldName])
  3182.             && ($this->associationMappings[$fieldName]['type'] & self::TO_ONE);
  3183.     }
  3185.     /**
  3186.      * {@inheritDoc}
  3187.      */
  3188.     public function isCollectionValuedAssociation($fieldName)
  3189.     {
  3190.         return isset($this->associationMappings[$fieldName])
  3191.             && ! ($this->associationMappings[$fieldName]['type'] & self::TO_ONE);
  3192.     }
  3194.     /**
  3195.      * Is this an association that only has a single join column?
  3196.      *
  3197.      * @param string $fieldName
  3198.      *
  3199.      * @return bool
  3200.      */
  3201.     public function isAssociationWithSingleJoinColumn($fieldName)
  3202.     {
  3203.         return isset($this->associationMappings[$fieldName])
  3204.             && isset($this->associationMappings[$fieldName]['joinColumns'][0])
  3205.             && ! isset($this->associationMappings[$fieldName]['joinColumns'][1]);
  3206.     }
  3208.     /**
  3209.      * Returns the single association join column (if any).
  3210.      *
  3211.      * @param string $fieldName
  3212.      *
  3213.      * @return string
  3214.      *
  3215.      * @throws MappingException
  3216.      */
  3217.     public function getSingleAssociationJoinColumnName($fieldName)
  3218.     {
  3219.         if (! $this->isAssociationWithSingleJoinColumn($fieldName)) {
  3220.             throw MappingException::noSingleAssociationJoinColumnFound($this->name, $fieldName);
  3221.         }
  3223.         return $this->associationMappings[$fieldName]['joinColumns'][0]['name'];
  3224.     }
  3226.     /**
  3227.      * Returns the single association referenced join column name (if any).
  3228.      *
  3229.      * @param string $fieldName
  3230.      *
  3231.      * @return string
  3232.      *
  3233.      * @throws MappingException
  3234.      */
  3235.     public function getSingleAssociationReferencedJoinColumnName($fieldName)
  3236.     {
  3237.         if (! $this->isAssociationWithSingleJoinColumn($fieldName)) {
  3238.             throw MappingException::noSingleAssociationJoinColumnFound($this->name, $fieldName);
  3239.         }
  3241.         return $this->associationMappings[$fieldName]['joinColumns'][0]['referencedColumnName'];
  3242.     }
  3244.     /**
  3245.      * Used to retrieve a fieldname for either field or association from a given column.
  3246.      *
  3247.      * This method is used in foreign-key as primary-key contexts.
  3248.      *
  3249.      * @param string $columnName
  3250.      *
  3251.      * @return string
  3252.      *
  3253.      * @throws MappingException
  3254.      */
  3255.     public function getFieldForColumn($columnName)
  3256.     {
  3257.         if (isset($this->fieldNames[$columnName])) {
  3258.             return $this->fieldNames[$columnName];
  3259.         }
  3261.         foreach ($this->associationMappings as $assocName => $mapping) {
  3262.             if (
  3263.                 $this->isAssociationWithSingleJoinColumn($assocName) &&
  3264.                 $this->associationMappings[$assocName]['joinColumns'][0]['name'] === $columnName
  3265.             ) {
  3266.                 return $assocName;
  3267.             }
  3268.         }
  3270.         throw MappingException::noFieldNameFoundForColumn($this->name, $columnName);
  3271.     }
  3273.     /**
  3274.      * Sets the ID generator used to generate IDs for instances of this class.
  3275.      *
  3276.      * @param AbstractIdGenerator $generator
  3277.      *
  3278.      * @return void
  3279.      */
  3280.     public function setIdGenerator($generator)
  3281.     {
  3282.         $this->idGenerator = $generator;
  3283.     }
  3285.     /**
  3286.      * Sets definition.
  3287.      *
  3288.      * @psalm-param array<string, string> $definition
  3289.      *
  3290.      * @return void
  3291.      */
  3292.     public function setCustomGeneratorDefinition(array $definition)
  3293.     {
  3294.         $this->customGeneratorDefinition = $definition;
  3295.     }
  3297.     /**
  3298.      * Sets the definition of the sequence ID generator for this class.
  3299.      *
  3300.      * The definition must have the following structure:
  3301.      * <code>
  3302.      * array(
  3303.      *     'sequenceName'   => 'name',
  3304.      *     'allocationSize' => 20,
  3305.      *     'initialValue'   => 1
  3306.      *     'quoted'         => 1
  3307.      * )
  3308.      * </code>
  3309.      *
  3310.      * @psalm-param array<string, string> $definition
  3311.      *
  3312.      * @return void
  3313.      *
  3314.      * @throws MappingException
  3315.      */
  3316.     public function setSequenceGeneratorDefinition(array $definition)
  3317.     {
  3318.         if (! isset($definition['sequenceName']) || trim($definition['sequenceName']) === '') {
  3319.             throw MappingException::missingSequenceName($this->name);
  3320.         }
  3322.         if ($definition['sequenceName'][0] === '`') {
  3323.             $definition['sequenceName'] = trim($definition['sequenceName'], '`');
  3324.             $definition['quoted']       = true;
  3325.         }
  3327.         if (! isset($definition['allocationSize']) || trim($definition['allocationSize']) === '') {
  3328.             $definition['allocationSize'] = '1';
  3329.         }
  3331.         if (! isset($definition['initialValue']) || trim($definition['initialValue']) === '') {
  3332.             $definition['initialValue'] = '1';
  3333.         }
  3335.         $this->sequenceGeneratorDefinition = $definition;
  3336.     }
  3338.     /**
  3339.      * Sets the version field mapping used for versioning. Sets the default
  3340.      * value to use depending on the column type.
  3341.      *
  3342.      * @psalm-param array<string, mixed> $mapping The version field mapping array.
  3343.      *
  3344.      * @return void
  3345.      *
  3346.      * @throws MappingException
  3347.      */
  3348.     public function setVersionMapping(array &$mapping)
  3349.     {
  3350.         $this->isVersioned  = true;
  3351.         $this->versionField = $mapping['fieldName'];
  3353.         if (! isset($mapping['default'])) {
  3354.             if (in_array($mapping['type'], ['integer', 'bigint', 'smallint'])) {
  3355.                 $mapping['default'] = 1;
  3356.             } elseif ($mapping['type'] === 'datetime') {
  3357.                 $mapping['default'] = 'CURRENT_TIMESTAMP';
  3358.             } else {
  3359.                 throw MappingException::unsupportedOptimisticLockingType($this->name, $mapping['fieldName'], $mapping['type']);
  3360.             }
  3361.         }
  3362.     }
  3364.     /**
  3365.      * Sets whether this class is to be versioned for optimistic locking.
  3366.      *
  3367.      * @param bool $bool
  3368.      *
  3369.      * @return void
  3370.      */
  3371.     public function setVersioned($bool)
  3372.     {
  3373.         $this->isVersioned = $bool;
  3374.     }
  3376.     /**
  3377.      * Sets the name of the field that is to be used for versioning if this class is
  3378.      * versioned for optimistic locking.
  3379.      *
  3380.      * @param string $versionField
  3381.      *
  3382.      * @return void
  3383.      */
  3384.     public function setVersionField($versionField)
  3385.     {
  3386.         $this->versionField = $versionField;
  3387.     }
  3389.     /**
  3390.      * Marks this class as read only, no change tracking is applied to it.
  3391.      *
  3392.      * @return void
  3393.      */
  3394.     public function markReadOnly()
  3395.     {
  3396.         $this->isReadOnly = true;
  3397.     }
  3399.     /**
  3400.      * {@inheritDoc}
  3401.      */
  3402.     public function getFieldNames()
  3403.     {
  3404.         return array_keys($this->fieldMappings);
  3405.     }
  3407.     /**
  3408.      * {@inheritDoc}
  3409.      */
  3410.     public function getAssociationNames()
  3411.     {
  3412.         return array_keys($this->associationMappings);
  3413.     }
  3415.     /**
  3416.      * {@inheritDoc}
  3417.      *
  3418.      * @throws InvalidArgumentException
  3419.      */
  3420.     public function getAssociationTargetClass($assocName)
  3421.     {
  3422.         if (! isset($this->associationMappings[$assocName])) {
  3423.             throw new InvalidArgumentException("Association name expected, '" . $assocName . "' is not an association.");
  3424.         }
  3426.         return $this->associationMappings[$assocName]['targetEntity'];
  3427.     }
  3429.     /**
  3430.      * {@inheritDoc}
  3431.      */
  3432.     public function getName()
  3433.     {
  3434.         return $this->name;
  3435.     }
  3437.     /**
  3438.      * Gets the (possibly quoted) identifier column names for safe use in an SQL statement.
  3439.      *
  3440.      * @deprecated Deprecated since version 2.3 in favor of \Doctrine\ORM\Mapping\QuoteStrategy
  3441.      *
  3442.      * @param AbstractPlatform $platform
  3443.      *
  3444.      * @psalm-return list<string>
  3445.      */
  3446.     public function getQuotedIdentifierColumnNames($platform)
  3447.     {
  3448.         $quotedColumnNames = [];
  3450.         foreach ($this->identifier as $idProperty) {
  3451.             if (isset($this->fieldMappings[$idProperty])) {
  3452.                 $quotedColumnNames[] = isset($this->fieldMappings[$idProperty]['quoted'])
  3453.                     ? $platform->quoteIdentifier($this->fieldMappings[$idProperty]['columnName'])
  3454.                     : $this->fieldMappings[$idProperty]['columnName'];
  3456.                 continue;
  3457.             }
  3459.             // Association defined as Id field
  3460.             $joinColumns            = $this->associationMappings[$idProperty]['joinColumns'];
  3461.             $assocQuotedColumnNames = array_map(
  3462.                 static function ($joinColumn) use ($platform) {
  3463.                     return isset($joinColumn['quoted'])
  3464.                         ? $platform->quoteIdentifier($joinColumn['name'])
  3465.                         : $joinColumn['name'];
  3466.                 },
  3467.                 $joinColumns
  3468.             );
  3470.             $quotedColumnNames = array_merge($quotedColumnNames, $assocQuotedColumnNames);
  3471.         }
  3473.         return $quotedColumnNames;
  3474.     }
  3476.     /**
  3477.      * Gets the (possibly quoted) column name of a mapped field for safe use  in an SQL statement.
  3478.      *
  3479.      * @deprecated Deprecated since version 2.3 in favor of \Doctrine\ORM\Mapping\QuoteStrategy
  3480.      *
  3481.      * @param string           $field
  3482.      * @param AbstractPlatform $platform
  3483.      *
  3484.      * @return string
  3485.      */
  3486.     public function getQuotedColumnName($field, $platform)
  3487.     {
  3488.         return isset($this->fieldMappings[$field]['quoted'])
  3489.             ? $platform->quoteIdentifier($this->fieldMappings[$field]['columnName'])
  3490.             : $this->fieldMappings[$field]['columnName'];
  3491.     }
  3493.     /**
  3494.      * Gets the (possibly quoted) primary table name of this class for safe use in an SQL statement.
  3495.      *
  3496.      * @deprecated Deprecated since version 2.3 in favor of \Doctrine\ORM\Mapping\QuoteStrategy
  3497.      *
  3498.      * @param AbstractPlatform $platform
  3499.      *
  3500.      * @return string
  3501.      */
  3502.     public function getQuotedTableName($platform)
  3503.     {
  3504.         return isset($this->table['quoted'])
  3505.             ? $platform->quoteIdentifier($this->table['name'])
  3506.             : $this->table['name'];
  3507.     }
  3509.     /**
  3510.      * Gets the (possibly quoted) name of the join table.
  3511.      *
  3512.      * @deprecated Deprecated since version 2.3 in favor of \Doctrine\ORM\Mapping\QuoteStrategy
  3513.      *
  3514.      * @param mixed[]          $assoc
  3515.      * @param AbstractPlatform $platform
  3516.      *
  3517.      * @return string
  3518.      */
  3519.     public function getQuotedJoinTableName(array $assoc, $platform)
  3520.     {
  3521.         return isset($assoc['joinTable']['quoted'])
  3522.             ? $platform->quoteIdentifier($assoc['joinTable']['name'])
  3523.             : $assoc['joinTable']['name'];
  3524.     }
  3526.     /**
  3527.      * {@inheritDoc}
  3528.      */
  3529.     public function isAssociationInverseSide($fieldName)
  3530.     {
  3531.         return isset($this->associationMappings[$fieldName])
  3532.             && ! $this->associationMappings[$fieldName]['isOwningSide'];
  3533.     }
  3535.     /**
  3536.      * {@inheritDoc}
  3537.      */
  3538.     public function getAssociationMappedByTargetField($fieldName)
  3539.     {
  3540.         return $this->associationMappings[$fieldName]['mappedBy'];
  3541.     }
  3543.     /**
  3544.      * @param string $targetClass
  3545.      *
  3546.      * @psalm-return array<string, array<string, mixed>>
  3547.      */
  3548.     public function getAssociationsByTargetClass($targetClass)
  3549.     {
  3550.         $relations = [];
  3552.         foreach ($this->associationMappings as $mapping) {
  3553.             if ($mapping['targetEntity'] === $targetClass) {
  3554.                 $relations[$mapping['fieldName']] = $mapping;
  3555.             }
  3556.         }
  3558.         return $relations;
  3559.     }
  3561.     /**
  3562.      * @param string|null $className
  3563.      * @psalm-param ?class-string $className
  3564.      *
  3565.      * @return string|null null if the input value is null
  3566.      */
  3567.     public function fullyQualifiedClassName($className)
  3568.     {
  3569.         if (empty($className)) {
  3570.             return $className;
  3571.         }
  3573.         if ($className !== null && strpos($className, '\\') === false && $this->namespace) {
  3574.             return $this->namespace . '\\' . $className;
  3575.         }
  3577.         return $className;
  3578.     }
  3580.     /**
  3581.      * @param string $name
  3582.      *
  3583.      * @return mixed
  3584.      */
  3585.     public function getMetadataValue($name)
  3586.     {
  3587.         if (isset($this->$name)) {
  3588.             return $this->$name;
  3589.         }
  3591.         return null;
  3592.     }
  3594.     /**
  3595.      * Map Embedded Class
  3596.      *
  3597.      * @psalm-param array<string, mixed> $mapping
  3598.      *
  3599.      * @return void
  3600.      *
  3601.      * @throws MappingException
  3602.      */
  3603.     public function mapEmbedded(array $mapping)
  3604.     {
  3605.         $this->assertFieldNotMapped($mapping['fieldName']);
  3607.         $this->embeddedClasses[$mapping['fieldName']] = [
  3608.             'class' => $this->fullyQualifiedClassName($mapping['class']),
  3609.             'columnPrefix' => $mapping['columnPrefix'],
  3610.             'declaredField' => $mapping['declaredField'] ?? null,
  3611.             'originalField' => $mapping['originalField'] ?? null,
  3612.         ];
  3613.     }
  3615.     /**
  3616.      * Inline the embeddable class
  3617.      *
  3618.      * @param string $property
  3619.      *
  3620.      * @return void
  3621.      */
  3622.     public function inlineEmbeddable($property, ClassMetadataInfo $embeddable)
  3623.     {
  3624.         foreach ($embeddable->fieldMappings as $fieldMapping) {
  3625.             $fieldMapping['originalClass'] = $fieldMapping['originalClass'] ?? $embeddable->name;
  3626.             $fieldMapping['declaredField'] = isset($fieldMapping['declaredField'])
  3627.                 ? $property . '.' . $fieldMapping['declaredField']
  3628.                 : $property;
  3629.             $fieldMapping['originalField'] = $fieldMapping['originalField'] ?? $fieldMapping['fieldName'];
  3630.             $fieldMapping['fieldName']     = $property . '.' . $fieldMapping['fieldName'];
  3632.             if (! empty($this->embeddedClasses[$property]['columnPrefix'])) {
  3633.                 $fieldMapping['columnName'] = $this->embeddedClasses[$property]['columnPrefix'] . $fieldMapping['columnName'];
  3634.             } elseif ($this->embeddedClasses[$property]['columnPrefix'] !== false) {
  3635.                 $fieldMapping['columnName'] = $this->namingStrategy
  3636.                     ->embeddedFieldToColumnName(
  3637.                         $property,
  3638.                         $fieldMapping['columnName'],
  3639.                         $this->reflClass->name,
  3640.                         $embeddable->reflClass->name
  3641.                     );
  3642.             }
  3644.             $this->mapField($fieldMapping);
  3645.         }
  3646.     }
  3648.     /**
  3649.      * @throws MappingException
  3650.      */
  3651.     private function assertFieldNotMapped(string $fieldName): void
  3652.     {
  3653.         if (
  3654.             isset($this->fieldMappings[$fieldName]) ||
  3655.             isset($this->associationMappings[$fieldName]) ||
  3656.             isset($this->embeddedClasses[$fieldName])
  3657.         ) {
  3658.             throw MappingException::duplicateFieldMapping($this->name, $fieldName);
  3659.         }
  3660.     }
  3662.     /**
  3663.      * Gets the sequence name based on class metadata.
  3664.      *
  3665.      * @return string
  3666.      *
  3667.      * @todo Sequence names should be computed in DBAL depending on the platform
  3668.      */
  3669.     public function getSequenceName(AbstractPlatform $platform)
  3670.     {
  3671.         $sequencePrefix = $this->getSequencePrefix($platform);
  3672.         $columnName     = $this->getSingleIdentifierColumnName();
  3674.         return $sequencePrefix . '_' . $columnName . '_seq';
  3675.     }
  3677.     /**
  3678.      * Gets the sequence name prefix based on class metadata.
  3679.      *
  3680.      * @return string
  3681.      *
  3682.      * @todo Sequence names should be computed in DBAL depending on the platform
  3683.      */
  3684.     public function getSequencePrefix(AbstractPlatform $platform)
  3685.     {
  3686.         $tableName      = $this->getTableName();
  3687.         $sequencePrefix = $tableName;
  3689.         // Prepend the schema name to the table name if there is one
  3690.         $schemaName = $this->getSchemaName();
  3691.         if ($schemaName) {
  3692.             $sequencePrefix = $schemaName . '.' . $tableName;
  3694.             if (! $platform->supportsSchemas() && $platform->canEmulateSchemas()) {
  3695.                 $sequencePrefix = $schemaName . '__' . $tableName;
  3696.             }
  3697.         }
  3699.         return $sequencePrefix;
  3700.     }
  3702.     /**
  3703.      * @psalm-param array<string, mixed> $mapping
  3704.      */
  3705.     private function assertMappingOrderBy(array $mapping): void
  3706.     {
  3707.         if (isset($mapping['orderBy']) && ! is_array($mapping['orderBy'])) {
  3708.             throw new InvalidArgumentException("'orderBy' is expected to be an array, not " . gettype($mapping['orderBy']));
  3709.         }
  3710.     }
  3711. }