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

Open in your IDE?
  1. <?php
  2. /*
  3.  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  4.  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  5.  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  6.  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  7.  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  8.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  9.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  10.  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  11.  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  12.  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  13.  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14.  *
  15.  * This software consists of voluntary contributions made by many individuals
  16.  * and is licensed under the MIT license. For more information, see
  17.  * <http://www.doctrine-project.org>.
  18.  */
  20. namespace Doctrine\ORM\Mapping;
  22. use BadMethodCallException;
  23. use Doctrine\DBAL\Types\Type;
  24. use Doctrine\DBAL\Platforms\AbstractPlatform;
  25. use Doctrine\Instantiator\Instantiator;
  26. use Doctrine\ORM\Cache\CacheException;
  27. use Doctrine\Persistence\Mapping\ClassMetadata;
  28. use Doctrine\Persistence\Mapping\ReflectionService;
  29. use InvalidArgumentException;
  30. use ReflectionClass;
  31. use RuntimeException;
  33. /**
  34.  * A <tt>ClassMetadata</tt> instance holds all the object-relational mapping metadata
  35.  * of an entity and its associations.
  36.  *
  37.  * Once populated, ClassMetadata instances are usually cached in a serialized form.
  38.  *
  39.  * <b>IMPORTANT NOTE:</b>
  40.  *
  41.  * The fields of this class are only public for 2 reasons:
  42.  * 1) To allow fast READ access.
  43.  * 2) To drastically reduce the size of a serialized instance (private/protected members
  44.  *    get the whole class name, namespace inclusive, prepended to every property in
  45.  *    the serialized representation).
  46.  *
  47.  * @author Roman Borschel <[email protected]>
  48.  * @author Jonathan H. Wage <[email protected]>
  49.  * @since 2.0
  50.  */
  51. class ClassMetadataInfo implements ClassMetadata
  52. {
  53.     /* The inheritance mapping types */
  54.     /**
  55.      * NONE means the class does not participate in an inheritance hierarchy
  56.      * and therefore does not need an inheritance mapping type.
  57.      */
  58.     const INHERITANCE_TYPE_NONE = 1;
  60.     /**
  61.      * JOINED means the class will be persisted according to the rules of
  62.      * <tt>Class Table Inheritance</tt>.
  63.      */
  64.     const INHERITANCE_TYPE_JOINED = 2;
  66.     /**
  67.      * SINGLE_TABLE means the class will be persisted according to the rules of
  68.      * <tt>Single Table Inheritance</tt>.
  69.      */
  70.     const INHERITANCE_TYPE_SINGLE_TABLE = 3;
  72.     /**
  73.      * TABLE_PER_CLASS means the class will be persisted according to the rules
  74.      * of <tt>Concrete Table Inheritance</tt>.
  75.      */
  76.     const INHERITANCE_TYPE_TABLE_PER_CLASS = 4;
  78.     /* The Id generator types. */
  79.     /**
  80.      * AUTO means the generator type will depend on what the used platform prefers.
  81.      * Offers full portability.
  82.      */
  83.     const GENERATOR_TYPE_AUTO = 1;
  85.     /**
  86.      * SEQUENCE means a separate sequence object will be used. Platforms that do
  87.      * not have native sequence support may emulate it. Full portability is currently
  88.      * not guaranteed.
  89.      */
  90.     const GENERATOR_TYPE_SEQUENCE = 2;
  92.     /**
  93.      * TABLE means a separate table is used for id generation.
  94.      * Offers full portability.
  95.      */
  96.     const GENERATOR_TYPE_TABLE = 3;
  98.     /**
  99.      * IDENTITY means an identity column is used for id generation. The database
  100.      * will fill in the id column on insertion. Platforms that do not support
  101.      * native identity columns may emulate them. Full portability is currently
  102.      * not guaranteed.
  103.      */
  104.     const GENERATOR_TYPE_IDENTITY = 4;
  106.     /**
  107.      * NONE means the class does not have a generated id. That means the class
  108.      * must have a natural, manually assigned id.
  109.      */
  110.     const GENERATOR_TYPE_NONE = 5;
  112.     /**
  113.      * UUID means that a UUID/GUID expression is used for id generation. Full
  114.      * portability is currently not guaranteed.
  115.      */
  116.     const GENERATOR_TYPE_UUID = 6;
  118.     /**
  119.      * CUSTOM means that customer will use own ID generator that supposedly work
  120.      */
  121.     const GENERATOR_TYPE_CUSTOM = 7;
  123.     /**
  124.      * DEFERRED_IMPLICIT means that changes of entities are calculated at commit-time
  125.      * by doing a property-by-property comparison with the original data. This will
  126.      * be done for all entities that are in MANAGED state at commit-time.
  127.      *
  128.      * This is the default change tracking policy.
  129.      */
  130.     const CHANGETRACKING_DEFERRED_IMPLICIT = 1;
  132.     /**
  133.      * DEFERRED_EXPLICIT means that changes of entities are calculated at commit-time
  134.      * by doing a property-by-property comparison with the original data. This will
  135.      * be done only for entities that were explicitly saved (through persist() or a cascade).
  136.      */
  137.     const CHANGETRACKING_DEFERRED_EXPLICIT = 2;
  139.     /**
  140.      * NOTIFY means that Doctrine relies on the entities sending out notifications
  141.      * when their properties change. Such entity classes must implement
  142.      * the <tt>NotifyPropertyChanged</tt> interface.
  143.      */
  144.     const CHANGETRACKING_NOTIFY = 3;
  146.     /**
  147.      * Specifies that an association is to be fetched when it is first accessed.
  148.      */
  149.     const FETCH_LAZY = 2;
  151.     /**
  152.      * Specifies that an association is to be fetched when the owner of the
  153.      * association is fetched.
  154.      */
  155.     const FETCH_EAGER = 3;
  157.     /**
  158.      * Specifies that an association is to be fetched lazy (on first access) and that
  159.      * commands such as Collection#count, Collection#slice are issued directly against
  160.      * the database if the collection is not yet initialized.
  161.      */
  162.     const FETCH_EXTRA_LAZY = 4;
  164.     /**
  165.      * Identifies a one-to-one association.
  166.      */
  167.     const ONE_TO_ONE = 1;
  169.     /**
  170.      * Identifies a many-to-one association.
  171.      */
  172.     const MANY_TO_ONE = 2;
  174.     /**
  175.      * Identifies a one-to-many association.
  176.      */
  177.     const ONE_TO_MANY = 4;
  179.     /**
  180.      * Identifies a many-to-many association.
  181.      */
  182.     const MANY_TO_MANY = 8;
  184.     /**
  185.      * Combined bitmask for to-one (single-valued) associations.
  186.      */
  187.     const TO_ONE = 3;
  189.     /**
  190.      * Combined bitmask for to-many (collection-valued) associations.
  191.      */
  192.     const TO_MANY = 12;
  194.     /**
  195.      * ReadOnly cache can do reads, inserts and deletes, cannot perform updates or employ any locks,
  196.      */
  197.     const CACHE_USAGE_READ_ONLY = 1;
  199.     /**
  200.      * Nonstrict Read Write Cache doesn’t employ any locks but can do inserts, update and deletes.
  201.      */
  202.     const CACHE_USAGE_NONSTRICT_READ_WRITE = 2;
  204.     /**
  205.      * Read Write Attempts to lock the entity before update/delete.
  206.      */
  207.     const CACHE_USAGE_READ_WRITE = 3;
  209.     /**
  210.      * READ-ONLY: The name of the entity class.
  211.      *
  212.      * @var string
  213.      */
  214.     public $name;
  216.     /**
  217.      * READ-ONLY: The namespace the entity class is contained in.
  218.      *
  219.      * @var string
  220.      *
  221.      * @todo Not really needed. Usage could be localized.
  222.      */
  223.     public $namespace;
  225.     /**
  226.      * READ-ONLY: The name of the entity class that is at the root of the mapped entity inheritance
  227.      * hierarchy. If the entity is not part of a mapped inheritance hierarchy this is the same
  228.      * as {@link $name}.
  229.      *
  230.      * @var string
  231.      */
  232.     public $rootEntityName;
  234.     /**
  235.      * READ-ONLY: The definition of custom generator. Only used for CUSTOM
  236.      * generator type
  237.      *
  238.      * The definition has the following structure:
  239.      * <code>
  240.      * array(
  241.      *     'class' => 'ClassName',
  242.      * )
  243.      * </code>
  244.      *
  245.      * @todo Merge with tableGeneratorDefinition into generic generatorDefinition
  246.      *
  247.      * @var array<string, string>|null
  248.      */
  249.     public $customGeneratorDefinition;
  251.     /**
  252.      * The name of the custom repository class used for the entity class.
  253.      * (Optional).
  254.      *
  255.      * @var string|null
  256.      * @psalm-var ?class-string
  257.      */
  258.     public $customRepositoryClassName;
  260.     /**
  261.      * READ-ONLY: Whether this class describes the mapping of a mapped superclass.
  262.      *
  263.      * @var boolean
  264.      */
  265.     public $isMappedSuperclass = false;
  267.     /**
  268.      * READ-ONLY: Whether this class describes the mapping of an embeddable class.
  269.      *
  270.      * @var boolean
  271.      */
  272.     public $isEmbeddedClass = false;
  274.     /**
  275.      * READ-ONLY: The names of the parent classes (ancestors).
  276.      *
  277.      * @var array
  278.      */
  279.     public $parentClasses = [];
  281.     /**
  282.      * READ-ONLY: The names of all subclasses (descendants).
  283.      *
  284.      * @var array
  285.      */
  286.     public $subClasses = [];
  288.     /**
  289.      * READ-ONLY: The names of all embedded classes based on properties.
  290.      *
  291.      * @var array
  292.      */
  293.     public $embeddedClasses = [];
  295.     /**
  296.      * READ-ONLY: The named queries allowed to be called directly from Repository.
  297.      *
  298.      * @var array
  299.      */
  300.     public $namedQueries = [];
  302.     /**
  303.      * READ-ONLY: The named native queries allowed to be called directly from Repository.
  304.      *
  305.      * A native SQL named query definition has the following structure:
  306.      * <pre>
  307.      * array(
  308.      *     'name'               => <query name>,
  309.      *     'query'              => <sql query>,
  310.      *     'resultClass'        => <class of the result>,
  311.      *     'resultSetMapping'   => <name of a SqlResultSetMapping>
  312.      * )
  313.      * </pre>
  314.      *
  315.      * @var array
  316.      */
  317.     public $namedNativeQueries = [];
  319.     /**
  320.      * READ-ONLY: The mappings of the results of native SQL queries.
  321.      *
  322.      * A native result mapping definition has the following structure:
  323.      * <pre>
  324.      * array(
  325.      *     'name'               => <result name>,
  326.      *     'entities'           => array(<entity result mapping>),
  327.      *     'columns'            => array(<column result mapping>)
  328.      * )
  329.      * </pre>
  330.      *
  331.      * @var array
  332.      */
  333.     public $sqlResultSetMappings = [];
  335.     /**
  336.      * READ-ONLY: The field names of all fields that are part of the identifier/primary key
  337.      * of the mapped entity class.
  338.      *
  339.      * @var array
  340.      */
  341.     public $identifier = [];
  343.     /**
  344.      * READ-ONLY: The inheritance mapping type used by the class.
  345.      *
  346.      * @var integer
  347.      */
  348.     public $inheritanceType = self::INHERITANCE_TYPE_NONE;
  350.     /**
  351.      * READ-ONLY: The Id generator type used by the class.
  352.      *
  353.      * @var int
  354.      */
  355.     public $generatorType = self::GENERATOR_TYPE_NONE;
  357.     /**
  358.      * READ-ONLY: The field mappings of the class.
  359.      * Keys are field names and values are mapping definitions.
  360.      *
  361.      * The mapping definition array has the following values:
  362.      *
  363.      * - <b>fieldName</b> (string)
  364.      * The name of the field in the Entity.
  365.      *
  366.      * - <b>type</b> (string)
  367.      * The type name of the mapped field. Can be one of Doctrine's mapping types
  368.      * or a custom mapping type.
  369.      *
  370.      * - <b>columnName</b> (string, optional)
  371.      * The column name. Optional. Defaults to the field name.
  372.      *
  373.      * - <b>length</b> (integer, optional)
  374.      * The database length of the column. Optional. Default value taken from
  375.      * the type.
  376.      *
  377.      * - <b>id</b> (boolean, optional)
  378.      * Marks the field as the primary key of the entity. Multiple fields of an
  379.      * entity can have the id attribute, forming a composite key.
  380.      *
  381.      * - <b>nullable</b> (boolean, optional)
  382.      * Whether the column is nullable. Defaults to FALSE.
  383.      *
  384.      * - <b>columnDefinition</b> (string, optional, schema-only)
  385.      * The SQL fragment that is used when generating the DDL for the column.
  386.      *
  387.      * - <b>precision</b> (integer, optional, schema-only)
  388.      * The precision of a decimal column. Only valid if the column type is decimal.
  389.      *
  390.      * - <b>scale</b> (integer, optional, schema-only)
  391.      * The scale of a decimal column. Only valid if the column type is decimal.
  392.      *
  393.      * - <b>'unique'</b> (string, optional, schema-only)
  394.      * Whether a unique constraint should be generated for the column.
  395.      *
  396.      * @var array
  397.      */
  398.     public $fieldMappings = [];
  400.     /**
  401.      * READ-ONLY: An array of field names. Used to look up field names from column names.
  402.      * Keys are column names and values are field names.
  403.      *
  404.      * @var array
  405.      */
  406.     public $fieldNames = [];
  408.     /**
  409.      * READ-ONLY: A map of field names to column names. Keys are field names and values column names.
  410.      * Used to look up column names from field names.
  411.      * This is the reverse lookup map of $_fieldNames.
  412.      *
  413.      * @var array
  414.      *
  415.      * @deprecated 3.0 Remove this.
  416.      */
  417.     public $columnNames = [];
  419.     /**
  420.      * READ-ONLY: The discriminator value of this class.
  421.      *
  422.      * <b>This does only apply to the JOINED and SINGLE_TABLE inheritance mapping strategies
  423.      * where a discriminator column is used.</b>
  424.      *
  425.      * @var mixed
  426.      *
  427.      * @see discriminatorColumn
  428.      */
  429.     public $discriminatorValue;
  431.     /**
  432.      * READ-ONLY: The discriminator map of all mapped classes in the hierarchy.
  433.      *
  434.      * <b>This does only apply to the JOINED and SINGLE_TABLE inheritance mapping strategies
  435.      * where a discriminator column is used.</b>
  436.      *
  437.      * @var mixed
  438.      *
  439.      * @see discriminatorColumn
  440.      */
  441.     public $discriminatorMap = [];
  443.     /**
  444.      * READ-ONLY: The definition of the discriminator column used in JOINED and SINGLE_TABLE
  445.      * inheritance mappings.
  446.      *
  447.      * @var array
  448.      */
  449.     public $discriminatorColumn;
  451.     /**
  452.      * READ-ONLY: The primary table definition. The definition is an array with the
  453.      * following entries:
  454.      *
  455.      * name => <tableName>
  456.      * schema => <schemaName>
  457.      * indexes => array
  458.      * uniqueConstraints => array
  459.      *
  460.      * @var array
  461.      */
  462.     public $table;
  464.     /**
  465.      * READ-ONLY: The registered lifecycle callbacks for entities of this class.
  466.      *
  467.      * @var array[]
  468.      */
  469.     public $lifecycleCallbacks = [];
  471.     /**
  472.      * READ-ONLY: The registered entity listeners.
  473.      *
  474.      * @var array
  475.      */
  476.     public $entityListeners = [];
  478.     /**
  479.      * READ-ONLY: The association mappings of this class.
  480.      *
  481.      * The mapping definition array supports the following keys:
  482.      *
  483.      * - <b>fieldName</b> (string)
  484.      * The name of the field in the entity the association is mapped to.
  485.      *
  486.      * - <b>targetEntity</b> (string)
  487.      * The class name of the target entity. If it is fully-qualified it is used as is.
  488.      * If it is a simple, unqualified class name the namespace is assumed to be the same
  489.      * as the namespace of the source entity.
  490.      *
  491.      * - <b>mappedBy</b> (string, required for bidirectional associations)
  492.      * The name of the field that completes the bidirectional association on the owning side.
  493.      * This key must be specified on the inverse side of a bidirectional association.
  494.      *
  495.      * - <b>inversedBy</b> (string, required for bidirectional associations)
  496.      * The name of the field that completes the bidirectional association on the inverse side.
  497.      * This key must be specified on the owning side of a bidirectional association.
  498.      *
  499.      * - <b>cascade</b> (array, optional)
  500.      * The names of persistence operations to cascade on the association. The set of possible
  501.      * values are: "persist", "remove", "detach", "merge", "refresh", "all" (implies all others).
  502.      *
  503.      * - <b>orderBy</b> (array, one-to-many/many-to-many only)
  504.      * A map of field names (of the target entity) to sorting directions (ASC/DESC).
  505.      * Example: array('priority' => 'desc')
  506.      *
  507.      * - <b>fetch</b> (integer, optional)
  508.      * The fetching strategy to use for the association, usually defaults to FETCH_LAZY.
  509.      * Possible values are: ClassMetadata::FETCH_EAGER, ClassMetadata::FETCH_LAZY.
  510.      *
  511.      * - <b>joinTable</b> (array, optional, many-to-many only)
  512.      * Specification of the join table and its join columns (foreign keys).
  513.      * Only valid for many-to-many mappings. Note that one-to-many associations can be mapped
  514.      * through a join table by simply mapping the association as many-to-many with a unique
  515.      * constraint on the join table.
  516.      *
  517.      * - <b>indexBy</b> (string, optional, to-many only)
  518.      * Specification of a field on target-entity that is used to index the collection by.
  519.      * This field HAS to be either the primary key or a unique column. Otherwise the collection
  520.      * does not contain all the entities that are actually related.
  521.      *
  522.      * A join table definition has the following structure:
  523.      * <pre>
  524.      * array(
  525.      *     'name' => <join table name>,
  526.      *      'joinColumns' => array(<join column mapping from join table to source table>),
  527.      *      'inverseJoinColumns' => array(<join column mapping from join table to target table>)
  528.      * )
  529.      * </pre>
  530.      *
  531.      * @var array
  532.      */
  533.     public $associationMappings = [];
  535.     /**
  536.      * READ-ONLY: Flag indicating whether the identifier/primary key of the class is composite.
  537.      *
  538.      * @var boolean
  539.      */
  540.     public $isIdentifierComposite = false;
  542.     /**
  543.      * READ-ONLY: Flag indicating whether the identifier/primary key contains at least one foreign key association.
  544.      *
  545.      * This flag is necessary because some code blocks require special treatment of this cases.
  546.      *
  547.      * @var boolean
  548.      */
  549.     public $containsForeignIdentifier = false;
  551.     /**
  552.      * READ-ONLY: The ID generator used for generating IDs for this class.
  553.      *
  554.      * @var \Doctrine\ORM\Id\AbstractIdGenerator
  555.      *
  556.      * @todo Remove!
  557.      */
  558.     public $idGenerator;
  560.     /**
  561.      * READ-ONLY: The definition of the sequence generator of this class. Only used for the
  562.      * SEQUENCE generation strategy.
  563.      *
  564.      * The definition has the following structure:
  565.      * <code>
  566.      * array(
  567.      *     'sequenceName' => 'name',
  568.      *     'allocationSize' => 20,
  569.      *     'initialValue' => 1
  570.      * )
  571.      * </code>
  572.      *
  573.      * @var array
  574.      *
  575.      * @todo Merge with tableGeneratorDefinition into generic generatorDefinition
  576.      */
  577.     public $sequenceGeneratorDefinition;
  579.     /**
  580.      * READ-ONLY: The definition of the table generator of this class. Only used for the
  581.      * TABLE generation strategy.
  582.      *
  583.      * @var array
  584.      *
  585.      * @todo Merge with tableGeneratorDefinition into generic generatorDefinition
  586.      */
  587.     public $tableGeneratorDefinition;
  589.     /**
  590.      * READ-ONLY: The policy used for change-tracking on entities of this class.
  591.      *
  592.      * @var integer
  593.      */
  594.     public $changeTrackingPolicy = self::CHANGETRACKING_DEFERRED_IMPLICIT;
  596.     /**
  597.      * READ-ONLY: A flag for whether or not instances of this class are to be versioned
  598.      * with optimistic locking.
  599.      *
  600.      * @var boolean
  601.      */
  602.     public $isVersioned;
  604.     /**
  605.      * READ-ONLY: The name of the field which is used for versioning in optimistic locking (if any).
  606.      *
  607.      * @var mixed
  608.      */
  609.     public $versionField;
  611.     /**
  612.      * @var array
  613.      */
  614.     public $cache = null;
  616.     /**
  617.      * The ReflectionClass instance of the mapped class.
  618.      *
  619.      * @var ReflectionClass
  620.      */
  621.     public $reflClass;
  623.     /**
  624.      * Is this entity marked as "read-only"?
  625.      *
  626.      * That means it is never considered for change-tracking in the UnitOfWork. It is a very helpful performance
  627.      * optimization for entities that are immutable, either in your domain or through the relation database
  628.      * (coming from a view, or a history table for example).
  629.      *
  630.      * @var bool
  631.      */
  632.     public $isReadOnly = false;
  634.     /**
  635.      * NamingStrategy determining the default column and table names.
  636.      *
  637.      * @var \Doctrine\ORM\Mapping\NamingStrategy
  638.      */
  639.     protected $namingStrategy;
  641.     /**
  642.      * The ReflectionProperty instances of the mapped class.
  643.      *
  644.      * @var \ReflectionProperty[]
  645.      */
  646.     public $reflFields = [];
  648.     /**
  649.      * @var \Doctrine\Instantiator\InstantiatorInterface|null
  650.      */
  651.     private $instantiator;
  653.     /**
  654.      * Initializes a new ClassMetadata instance that will hold the object-relational mapping
  655.      * metadata of the class with the given name.
  656.      *
  657.      * @param string              $entityName     The name of the entity class the new instance is used for.
  658.      * @param NamingStrategy|null $namingStrategy
  659.      */
  660.     public function __construct($entityName, NamingStrategy $namingStrategy = null)
  661.     {
  662.         $this->name = $entityName;
  663.         $this->rootEntityName = $entityName;
  664.         $this->namingStrategy = $namingStrategy ?: new DefaultNamingStrategy();
  665.         $this->instantiator   = new Instantiator();
  666.     }
  668.     /**
  669.      * Gets the ReflectionProperties of the mapped class.
  670.      *
  671.      * @return array An array of ReflectionProperty instances.
  672.      */
  673.     public function getReflectionProperties()
  674.     {
  675.         return $this->reflFields;
  676.     }
  678.     /**
  679.      * Gets a ReflectionProperty for a specific field of the mapped class.
  680.      *
  681.      * @param string $name
  682.      *
  683.      * @return \ReflectionProperty
  684.      */
  685.     public function getReflectionProperty($name)
  686.     {
  687.         return $this->reflFields[$name];
  688.     }
  690.     /**
  691.      * Gets the ReflectionProperty for the single identifier field.
  692.      *
  693.      * @return \ReflectionProperty
  694.      *
  695.      * @throws BadMethodCallException If the class has a composite identifier.
  696.      */
  697.     public function getSingleIdReflectionProperty()
  698.     {
  699.         if ($this->isIdentifierComposite) {
  700.             throw new BadMethodCallException("Class " . $this->name . " has a composite identifier.");
  701.         }
  703.         return $this->reflFields[$this->identifier[0]];
  704.     }
  706.     /**
  707.      * Extracts the identifier values of an entity of this class.
  708.      *
  709.      * For composite identifiers, the identifier values are returned as an array
  710.      * with the same order as the field order in {@link identifier}.
  711.      *
  712.      * @param object $entity
  713.      *
  714.      * @return array
  715.      */
  716.     public function getIdentifierValues($entity)
  717.     {
  718.         if ($this->isIdentifierComposite) {
  719.             $id = [];
  721.             foreach ($this->identifier as $idField) {
  722.                 $value = $this->reflFields[$idField]->getValue($entity);
  724.                 if (null !== $value) {
  725.                     $id[$idField] = $value;
  726.                 }
  727.             }
  729.             return $id;
  730.         }
  732.         $id = $this->identifier[0];
  733.         $value = $this->reflFields[$id]->getValue($entity);
  735.         if (null === $value) {
  736.             return [];
  737.         }
  739.         return [$id => $value];
  740.     }
  742.     /**
  743.      * Populates the entity identifier of an entity.
  744.      *
  745.      * @param object $entity
  746.      * @param array  $id
  747.      *
  748.      * @return void
  749.      *
  750.      * @todo Rename to assignIdentifier()
  751.      */
  752.     public function setIdentifierValues($entity, array $id)
  753.     {
  754.         foreach ($id as $idField => $idValue) {
  755.             $this->reflFields[$idField]->setValue($entity, $idValue);
  756.         }
  757.     }
  759.     /**
  760.      * Sets the specified field to the specified value on the given entity.
  761.      *
  762.      * @param object $entity
  763.      * @param string $field
  764.      * @param mixed  $value
  765.      *
  766.      * @return void
  767.      */
  768.     public function setFieldValue($entity, $field, $value)
  769.     {
  770.         $this->reflFields[$field]->setValue($entity, $value);
  771.     }
  773.     /**
  774.      * Gets the specified field's value off the given entity.
  775.      *
  776.      * @param object $entity
  777.      * @param string $field
  778.      *
  779.      * @return mixed
  780.      */
  781.     public function getFieldValue($entity, $field)
  782.     {
  783.         return $this->reflFields[$field]->getValue($entity);
  784.     }
  786.     /**
  787.      * Creates a string representation of this instance.
  788.      *
  789.      * @return string The string representation of this instance.
  790.      *
  791.      * @todo Construct meaningful string representation.
  792.      */
  793.     public function __toString()
  794.     {
  795.         return __CLASS__ . '@' . spl_object_hash($this);
  796.     }
  798.     /**
  799.      * Determines which fields get serialized.
  800.      *
  801.      * It is only serialized what is necessary for best unserialization performance.
  802.      * That means any metadata properties that are not set or empty or simply have
  803.      * their default value are NOT serialized.
  804.      *
  805.      * Parts that are also NOT serialized because they can not be properly unserialized:
  806.      *      - reflClass (ReflectionClass)
  807.      *      - reflFields (ReflectionProperty array)
  808.      *
  809.      * @return array The names of all the fields that should be serialized.
  810.      */
  811.     public function __sleep()
  812.     {
  813.         // This metadata is always serialized/cached.
  814.         $serialized = [
  815.             'associationMappings',
  816.             'columnNames', //TODO: 3.0 Remove this. Can use fieldMappings[$fieldName]['columnName']
  817.             'fieldMappings',
  818.             'fieldNames',
  819.             'embeddedClasses',
  820.             'identifier',
  821.             'isIdentifierComposite', // TODO: REMOVE
  822.             'name',
  823.             'namespace', // TODO: REMOVE
  824.             'table',
  825.             'rootEntityName',
  826.             'idGenerator', //TODO: Does not really need to be serialized. Could be moved to runtime.
  827.         ];
  829.         // The rest of the metadata is only serialized if necessary.
  830.         if ($this->changeTrackingPolicy != self::CHANGETRACKING_DEFERRED_IMPLICIT) {
  831.             $serialized[] = 'changeTrackingPolicy';
  832.         }
  834.         if ($this->customRepositoryClassName) {
  835.             $serialized[] = 'customRepositoryClassName';
  836.         }
  838.         if ($this->inheritanceType != self::INHERITANCE_TYPE_NONE) {
  839.             $serialized[] = 'inheritanceType';
  840.             $serialized[] = 'discriminatorColumn';
  841.             $serialized[] = 'discriminatorValue';
  842.             $serialized[] = 'discriminatorMap';
  843.             $serialized[] = 'parentClasses';
  844.             $serialized[] = 'subClasses';
  845.         }
  847.         if ($this->generatorType != self::GENERATOR_TYPE_NONE) {
  848.             $serialized[] = 'generatorType';
  849.             if ($this->generatorType == self::GENERATOR_TYPE_SEQUENCE) {
  850.                 $serialized[] = 'sequenceGeneratorDefinition';
  851.             }
  852.         }
  854.         if ($this->isMappedSuperclass) {
  855.             $serialized[] = 'isMappedSuperclass';
  856.         }
  858.         if ($this->isEmbeddedClass) {
  859.             $serialized[] = 'isEmbeddedClass';
  860.         }
  862.         if ($this->containsForeignIdentifier) {
  863.             $serialized[] = 'containsForeignIdentifier';
  864.         }
  866.         if ($this->isVersioned) {
  867.             $serialized[] = 'isVersioned';
  868.             $serialized[] = 'versionField';
  869.         }
  871.         if ($this->lifecycleCallbacks) {
  872.             $serialized[] = 'lifecycleCallbacks';
  873.         }
  875.         if ($this->entityListeners) {
  876.             $serialized[] = 'entityListeners';
  877.         }
  879.         if ($this->namedQueries) {
  880.             $serialized[] = 'namedQueries';
  881.         }
  883.         if ($this->namedNativeQueries) {
  884.             $serialized[] = 'namedNativeQueries';
  885.         }
  887.         if ($this->sqlResultSetMappings) {
  888.             $serialized[] = 'sqlResultSetMappings';
  889.         }
  891.         if ($this->isReadOnly) {
  892.             $serialized[] = 'isReadOnly';
  893.         }
  895.         if ($this->customGeneratorDefinition) {
  896.             $serialized[] = "customGeneratorDefinition";
  897.         }
  899.         if ($this->cache) {
  900.             $serialized[] = 'cache';
  901.         }
  903.         return $serialized;
  904.     }
  906.     /**
  907.      * Creates a new instance of the mapped class, without invoking the constructor.
  908.      *
  909.      * @return object
  910.      */
  911.     public function newInstance()
  912.     {
  913.         return $this->instantiator->instantiate($this->name);
  914.     }
  916.     /**
  917.      * Restores some state that can not be serialized/unserialized.
  918.      *
  919.      * @param ReflectionService $reflService
  920.      *
  921.      * @return void
  922.      */
  923.     public function wakeupReflection($reflService)
  924.     {
  925.         // Restore ReflectionClass and properties
  926.         $this->reflClass    = $reflService->getClass($this->name);
  927.         $this->instantiator = $this->instantiator ?: new Instantiator();
  929.         $parentReflFields = [];
  931.         foreach ($this->embeddedClasses as $property => $embeddedClass) {
  932.             if (isset($embeddedClass['declaredField'])) {
  933.                 $parentReflFields[$property] = new ReflectionEmbeddedProperty(
  934.                     $parentReflFields[$embeddedClass['declaredField']],
  935.                     $reflService->getAccessibleProperty(
  936.                         $this->embeddedClasses[$embeddedClass['declaredField']]['class'],
  937.                         $embeddedClass['originalField']
  938.                     ),
  939.                     $this->embeddedClasses[$embeddedClass['declaredField']]['class']
  940.                 );
  942.                 continue;
  943.             }
  945.             $fieldRefl = $reflService->getAccessibleProperty(
  946.                 $embeddedClass['declared'] ?? $this->name,
  947.                 $property
  948.             );
  950.             $parentReflFields[$property] = $fieldRefl;
  951.             $this->reflFields[$property] = $fieldRefl;
  952.         }
  954.         foreach ($this->fieldMappings as $field => $mapping) {
  955.             if (isset($mapping['declaredField']) && isset($parentReflFields[$mapping['declaredField']])) {
  956.                 $this->reflFields[$field] = new ReflectionEmbeddedProperty(
  957.                     $parentReflFields[$mapping['declaredField']],
  958.                     $reflService->getAccessibleProperty($mapping['originalClass'], $mapping['originalField']),
  959.                     $mapping['originalClass']
  960.                 );
  961.                 continue;
  962.             }
  964.             $this->reflFields[$field] = isset($mapping['declared'])
  965.                 ? $reflService->getAccessibleProperty($mapping['declared'], $field)
  966.                 : $reflService->getAccessibleProperty($this->name, $field);
  967.         }
  969.         foreach ($this->associationMappings as $field => $mapping) {
  970.             $this->reflFields[$field] = isset($mapping['declared'])
  971.                 ? $reflService->getAccessibleProperty($mapping['declared'], $field)
  972.                 : $reflService->getAccessibleProperty($this->name, $field);
  973.         }
  974.     }
  976.     /**
  977.      * Initializes a new ClassMetadata instance that will hold the object-relational mapping
  978.      * metadata of the class with the given name.
  979.      *
  980.      * @param ReflectionService $reflService The reflection service.
  981.      *
  982.      * @return void
  983.      */
  984.     public function initializeReflection($reflService)
  985.     {
  986.         $this->reflClass = $reflService->getClass($this->name);
  987.         $this->namespace = $reflService->getClassNamespace($this->name);
  989.         if ($this->reflClass) {
  990.             $this->name = $this->rootEntityName = $this->reflClass->getName();
  991.         }
  993.         $this->table['name'] = $this->namingStrategy->classToTableName($this->name);
  994.     }
  996.     /**
  997.      * Validates Identifier.
  998.      *
  999.      * @return void
  1000.      *
  1001.      * @throws MappingException
  1002.      */
  1003.     public function validateIdentifier()
  1004.     {
  1005.         if ($this->isMappedSuperclass || $this->isEmbeddedClass) {
  1006.             return;
  1007.         }
  1009.         // Verify & complete identifier mapping
  1010.         if ( ! $this->identifier) {
  1011.             throw MappingException::identifierRequired($this->name);
  1012.         }
  1014.         if ($this->usesIdGenerator() && $this->isIdentifierComposite) {
  1015.             throw MappingException::compositeKeyAssignedIdGeneratorRequired($this->name);
  1016.         }
  1017.     }
  1019.     /**
  1020.      * Validates association targets actually exist.
  1021.      *
  1022.      * @return void
  1023.      *
  1024.      * @throws MappingException
  1025.      */
  1026.     public function validateAssociations()
  1027.     {
  1028.         foreach ($this->associationMappings as $mapping) {
  1029.             if (
  1030.                 ! class_exists($mapping['targetEntity'])
  1031.                 && ! interface_exists($mapping['targetEntity'])
  1032.                 && ! trait_exists($mapping['targetEntity'])
  1033.             ) {
  1034.                 throw MappingException::invalidTargetEntityClass($mapping['targetEntity'], $this->name, $mapping['fieldName']);
  1035.             }
  1036.         }
  1037.     }
  1039.     /**
  1040.      * Validates lifecycle callbacks.
  1041.      *
  1042.      * @param ReflectionService $reflService
  1043.      *
  1044.      * @return void
  1045.      *
  1046.      * @throws MappingException
  1047.      */
  1048.     public function validateLifecycleCallbacks($reflService)
  1049.     {
  1050.         foreach ($this->lifecycleCallbacks as $callbacks) {
  1051.             foreach ($callbacks as $callbackFuncName) {
  1052.                 if ( ! $reflService->hasPublicMethod($this->name, $callbackFuncName)) {
  1053.                     throw MappingException::lifecycleCallbackMethodNotFound($this->name, $callbackFuncName);
  1054.                 }
  1055.             }
  1056.         }
  1057.     }
  1059.     /**
  1060.      * {@inheritDoc}
  1061.      */
  1062.     public function getReflectionClass()
  1063.     {
  1064.         return $this->reflClass;
  1065.     }
  1067.     /**
  1068.      * @param array $cache
  1069.      *
  1070.      * @return void
  1071.      */
  1072.     public function enableCache(array $cache)
  1073.     {
  1074.         if ( ! isset($cache['usage'])) {
  1075.             $cache['usage'] = self::CACHE_USAGE_READ_ONLY;
  1076.         }
  1078.         if ( ! isset($cache['region'])) {
  1079.             $cache['region'] = strtolower(str_replace('\\', '_', $this->rootEntityName));
  1080.         }
  1082.         $this->cache = $cache;
  1083.     }
  1085.     /**
  1086.      * @param string $fieldName
  1087.      * @param array  $cache
  1088.      *
  1089.      * @return void
  1090.      */
  1091.     public function enableAssociationCache($fieldName, array $cache)
  1092.     {
  1093.         $this->associationMappings[$fieldName]['cache'] = $this->getAssociationCacheDefaults($fieldName, $cache);
  1094.     }
  1096.     /**
  1097.      * @param string $fieldName
  1098.      * @param array  $cache
  1099.      *
  1100.      * @return array
  1101.      */
  1102.     public function getAssociationCacheDefaults($fieldName, array $cache)
  1103.     {
  1104.         if ( ! isset($cache['usage'])) {
  1105.             $cache['usage'] = isset($this->cache['usage'])
  1106.                 ? $this->cache['usage']
  1107.                 : self::CACHE_USAGE_READ_ONLY;
  1108.         }
  1110.         if ( ! isset($cache['region'])) {
  1111.             $cache['region'] = strtolower(str_replace('\\', '_', $this->rootEntityName)) . '__' . $fieldName;
  1112.         }
  1114.         return $cache;
  1115.     }
  1117.     /**
  1118.      * Sets the change tracking policy used by this class.
  1119.      *
  1120.      * @param integer $policy
  1121.      *
  1122.      * @return void
  1123.      */
  1124.     public function setChangeTrackingPolicy($policy)
  1125.     {
  1126.         $this->changeTrackingPolicy = $policy;
  1127.     }
  1129.     /**
  1130.      * Whether the change tracking policy of this class is "deferred explicit".
  1131.      *
  1132.      * @return boolean
  1133.      */
  1134.     public function isChangeTrackingDeferredExplicit()
  1135.     {
  1136.         return self::CHANGETRACKING_DEFERRED_EXPLICIT === $this->changeTrackingPolicy;
  1137.     }
  1139.     /**
  1140.      * Whether the change tracking policy of this class is "deferred implicit".
  1141.      *
  1142.      * @return boolean
  1143.      */
  1144.     public function isChangeTrackingDeferredImplicit()
  1145.     {
  1146.         return self::CHANGETRACKING_DEFERRED_IMPLICIT === $this->changeTrackingPolicy;
  1147.     }
  1149.     /**
  1150.      * Whether the change tracking policy of this class is "notify".
  1151.      *
  1152.      * @return boolean
  1153.      */
  1154.     public function isChangeTrackingNotify()
  1155.     {
  1156.         return self::CHANGETRACKING_NOTIFY === $this->changeTrackingPolicy;
  1157.     }
  1159.     /**
  1160.      * Checks whether a field is part of the identifier/primary key field(s).
  1161.      *
  1162.      * @param string $fieldName The field name.
  1163.      *
  1164.      * @return boolean TRUE if the field is part of the table identifier/primary key field(s),
  1165.      *                 FALSE otherwise.
  1166.      */
  1167.     public function isIdentifier($fieldName)
  1168.     {
  1169.         if ( ! $this->identifier) {
  1170.             return false;
  1171.         }
  1173.         if ( ! $this->isIdentifierComposite) {
  1174.             return $fieldName === $this->identifier[0];
  1175.         }
  1177.         return in_array($fieldName, $this->identifier, true);
  1178.     }
  1180.     /**
  1181.      * Checks if the field is unique.
  1182.      *
  1183.      * @param string $fieldName The field name.
  1184.      *
  1185.      * @return boolean TRUE if the field is unique, FALSE otherwise.
  1186.      */
  1187.     public function isUniqueField($fieldName)
  1188.     {
  1189.         $mapping = $this->getFieldMapping($fieldName);
  1191.         return false !== $mapping && isset($mapping['unique']) && $mapping['unique'];
  1192.     }
  1194.     /**
  1195.      * Checks if the field is not null.
  1196.      *
  1197.      * @param string $fieldName The field name.
  1198.      *
  1199.      * @return boolean TRUE if the field is not null, FALSE otherwise.
  1200.      */
  1201.     public function isNullable($fieldName)
  1202.     {
  1203.         $mapping = $this->getFieldMapping($fieldName);
  1205.         return false !== $mapping && isset($mapping['nullable']) && $mapping['nullable'];
  1206.     }
  1208.     /**
  1209.      * Gets a column name for a field name.
  1210.      * If the column name for the field cannot be found, the given field name
  1211.      * is returned.
  1212.      *
  1213.      * @param string $fieldName The field name.
  1214.      *
  1215.      * @return string The column name.
  1216.      */
  1217.     public function getColumnName($fieldName)
  1218.     {
  1219.         return isset($this->columnNames[$fieldName])
  1220.             ? $this->columnNames[$fieldName]
  1221.             : $fieldName;
  1222.     }
  1224.     /**
  1225.      * Gets the mapping of a (regular) field that holds some data but not a
  1226.      * reference to another object.
  1227.      *
  1228.      * @param string $fieldName The field name.
  1229.      *
  1230.      * @return array The field mapping.
  1231.      *
  1232.      * @throws MappingException
  1233.      */
  1234.     public function getFieldMapping($fieldName)
  1235.     {
  1236.         if ( ! isset($this->fieldMappings[$fieldName])) {
  1237.             throw MappingException::mappingNotFound($this->name, $fieldName);
  1238.         }
  1240.         return $this->fieldMappings[$fieldName];
  1241.     }
  1243.     /**
  1244.      * Gets the mapping of an association.
  1245.      *
  1246.      * @see ClassMetadataInfo::$associationMappings
  1247.      *
  1248.      * @param string $fieldName The field name that represents the association in
  1249.      *                          the object model.
  1250.      *
  1251.      * @return array The mapping.
  1252.      *
  1253.      * @throws MappingException
  1254.      */
  1255.     public function getAssociationMapping($fieldName)
  1256.     {
  1257.         if ( ! isset($this->associationMappings[$fieldName])) {
  1258.             throw MappingException::mappingNotFound($this->name, $fieldName);
  1259.         }
  1261.         return $this->associationMappings[$fieldName];
  1262.     }
  1264.     /**
  1265.      * Gets all association mappings of the class.
  1266.      *
  1267.      * @return array
  1268.      */
  1269.     public function getAssociationMappings()
  1270.     {
  1271.         return $this->associationMappings;
  1272.     }
  1274.     /**
  1275.      * Gets the field name for a column name.
  1276.      * If no field name can be found the column name is returned.
  1277.      *
  1278.      * @param string $columnName The column name.
  1279.      *
  1280.      * @return string The column alias.
  1281.      */
  1282.     public function getFieldName($columnName)
  1283.     {
  1284.         return isset($this->fieldNames[$columnName])
  1285.             ? $this->fieldNames[$columnName]
  1286.             : $columnName;
  1287.     }
  1289.     /**
  1290.      * Gets the named query.
  1291.      *
  1292.      * @see ClassMetadataInfo::$namedQueries
  1293.      *
  1294.      * @param string $queryName The query name.
  1295.      *
  1296.      * @return string
  1297.      *
  1298.      * @throws MappingException
  1299.      */
  1300.     public function getNamedQuery($queryName)
  1301.     {
  1302.         if ( ! isset($this->namedQueries[$queryName])) {
  1303.             throw MappingException::queryNotFound($this->name, $queryName);
  1304.         }
  1306.         return $this->namedQueries[$queryName]['dql'];
  1307.     }
  1309.     /**
  1310.      * Gets all named queries of the class.
  1311.      *
  1312.      * @return array
  1313.      */
  1314.     public function getNamedQueries()
  1315.     {
  1316.         return $this->namedQueries;
  1317.     }
  1319.     /**
  1320.      * Gets the named native query.
  1321.      *
  1322.      * @see ClassMetadataInfo::$namedNativeQueries
  1323.      *
  1324.      * @param string $queryName The query name.
  1325.      *
  1326.      * @return array
  1327.      *
  1328.      * @throws MappingException
  1329.      */
  1330.     public function getNamedNativeQuery($queryName)
  1331.     {
  1332.         if ( ! isset($this->namedNativeQueries[$queryName])) {
  1333.             throw MappingException::queryNotFound($this->name, $queryName);
  1334.         }
  1336.         return $this->namedNativeQueries[$queryName];
  1337.     }
  1339.     /**
  1340.      * Gets all named native queries of the class.
  1341.      *
  1342.      * @return array
  1343.      */
  1344.     public function getNamedNativeQueries()
  1345.     {
  1346.         return $this->namedNativeQueries;
  1347.     }
  1349.     /**
  1350.      * Gets the result set mapping.
  1351.      *
  1352.      * @see ClassMetadataInfo::$sqlResultSetMappings
  1353.      *
  1354.      * @param string $name The result set mapping name.
  1355.      *
  1356.      * @return array
  1357.      *
  1358.      * @throws MappingException
  1359.      */
  1360.     public function getSqlResultSetMapping($name)
  1361.     {
  1362.         if ( ! isset($this->sqlResultSetMappings[$name])) {
  1363.             throw MappingException::resultMappingNotFound($this->name, $name);
  1364.         }
  1366.         return $this->sqlResultSetMappings[$name];
  1367.     }
  1369.     /**
  1370.      * Gets all sql result set mappings of the class.
  1371.      *
  1372.      * @return array
  1373.      */
  1374.     public function getSqlResultSetMappings()
  1375.     {
  1376.         return $this->sqlResultSetMappings;
  1377.     }
  1379.     /**
  1380.      * Validates & completes the given field mapping.
  1381.      *
  1382.      * @param array $mapping The field mapping to validate & complete.
  1383.      *
  1384.      * @return void
  1385.      *
  1386.      * @throws MappingException
  1387.      */
  1388.     protected function _validateAndCompleteFieldMapping(array &$mapping)
  1389.     {
  1390.         // Check mandatory fields
  1391.         if ( ! isset($mapping['fieldName']) || !$mapping['fieldName']) {
  1392.             throw MappingException::missingFieldName($this->name);
  1393.         }
  1395.         if ( ! isset($mapping['type'])) {
  1396.             // Default to string
  1397.             $mapping['type'] = 'string';
  1398.         }
  1400.         // Complete fieldName and columnName mapping
  1401.         if ( ! isset($mapping['columnName'])) {
  1402.             $mapping['columnName'] = $this->namingStrategy->propertyToColumnName($mapping['fieldName'], $this->name);
  1403.         }
  1405.         if ('`' === $mapping['columnName'][0]) {
  1406.             $mapping['columnName']  = trim($mapping['columnName'], '`');
  1407.             $mapping['quoted']      = true;
  1408.         }
  1410.         $this->columnNames[$mapping['fieldName']] = $mapping['columnName'];
  1412.         if (isset($this->fieldNames[$mapping['columnName']]) || ($this->discriminatorColumn && $this->discriminatorColumn['name'] === $mapping['columnName'])) {
  1413.             throw MappingException::duplicateColumnName($this->name, $mapping['columnName']);
  1414.         }
  1416.         $this->fieldNames[$mapping['columnName']] = $mapping['fieldName'];
  1418.         // Complete id mapping
  1419.         if (isset($mapping['id']) && true === $mapping['id']) {
  1420.             if ($this->versionField == $mapping['fieldName']) {
  1421.                 throw MappingException::cannotVersionIdField($this->name, $mapping['fieldName']);
  1422.             }
  1424.             if ( ! in_array($mapping['fieldName'], $this->identifier)) {
  1425.                 $this->identifier[] = $mapping['fieldName'];
  1426.             }
  1428.             // Check for composite key
  1429.             if ( ! $this->isIdentifierComposite && count($this->identifier) > 1) {
  1430.                 $this->isIdentifierComposite = true;
  1431.             }
  1432.         }
  1434.         if (Type::hasType($mapping['type']) && Type::getType($mapping['type'])->canRequireSQLConversion()) {
  1435.             if (isset($mapping['id']) && true === $mapping['id']) {
  1436.                  throw MappingException::sqlConversionNotAllowedForIdentifiers($this->name, $mapping['fieldName'], $mapping['type']);
  1437.             }
  1439.             $mapping['requireSQLConversion'] = true;
  1440.         }
  1441.     }
  1443.     /**
  1444.      * Validates & completes the basic mapping information that is common to all
  1445.      * association mappings (one-to-one, many-ot-one, one-to-many, many-to-many).
  1446.      *
  1447.      * @param array $mapping The mapping.
  1448.      *
  1449.      * @return array The updated mapping.
  1450.      *
  1451.      * @throws MappingException If something is wrong with the mapping.
  1452.      */
  1453.     protected function _validateAndCompleteAssociationMapping(array $mapping)
  1454.     {
  1455.         if ( ! isset($mapping['mappedBy'])) {
  1456.             $mapping['mappedBy'] = null;
  1457.         }
  1459.         if ( ! isset($mapping['inversedBy'])) {
  1460.             $mapping['inversedBy'] = null;
  1461.         }
  1463.         $mapping['isOwningSide'] = true; // assume owning side until we hit mappedBy
  1465.         if (empty($mapping['indexBy'])) {
  1466.             unset($mapping['indexBy']);
  1467.         }
  1469.         // If targetEntity is unqualified, assume it is in the same namespace as
  1470.         // the sourceEntity.
  1471.         $mapping['sourceEntity'] = $this->name;
  1473.         if (isset($mapping['targetEntity'])) {
  1474.             $mapping['targetEntity'] = $this->fullyQualifiedClassName($mapping['targetEntity']);
  1475.             $mapping['targetEntity'] = ltrim($mapping['targetEntity'], '\\');
  1476.         }
  1478.         if (($mapping['type'] & self::MANY_TO_ONE) > 0 && isset($mapping['orphanRemoval']) && $mapping['orphanRemoval']) {
  1479.             throw MappingException::illegalOrphanRemoval($this->name, $mapping['fieldName']);
  1480.         }
  1482.         // Complete id mapping
  1483.         if (isset($mapping['id']) && true === $mapping['id']) {
  1484.             if (isset($mapping['orphanRemoval']) && $mapping['orphanRemoval']) {
  1485.                 throw MappingException::illegalOrphanRemovalOnIdentifierAssociation($this->name, $mapping['fieldName']);
  1486.             }
  1488.             if ( ! in_array($mapping['fieldName'], $this->identifier)) {
  1489.                 if (isset($mapping['joinColumns']) && count($mapping['joinColumns']) >= 2) {
  1490.                     throw MappingException::cannotMapCompositePrimaryKeyEntitiesAsForeignId(
  1491.                         $mapping['targetEntity'], $this->name, $mapping['fieldName']
  1492.                     );
  1493.                 }
  1495.                 $this->identifier[] = $mapping['fieldName'];
  1496.                 $this->containsForeignIdentifier = true;
  1497.             }
  1499.             // Check for composite key
  1500.             if ( ! $this->isIdentifierComposite && count($this->identifier) > 1) {
  1501.                 $this->isIdentifierComposite = true;
  1502.             }
  1504.             if ($this->cache && !isset($mapping['cache'])) {
  1505.                 throw CacheException::nonCacheableEntityAssociation($this->name, $mapping['fieldName']);
  1506.             }
  1507.         }
  1509.         // Mandatory attributes for both sides
  1510.         // Mandatory: fieldName, targetEntity
  1511.         if ( ! isset($mapping['fieldName']) || !$mapping['fieldName']) {
  1512.             throw MappingException::missingFieldName($this->name);
  1513.         }
  1515.         if ( ! isset($mapping['targetEntity'])) {
  1516.             throw MappingException::missingTargetEntity($mapping['fieldName']);
  1517.         }
  1519.         // Mandatory and optional attributes for either side
  1520.         if ( ! $mapping['mappedBy']) {
  1521.             if (isset($mapping['joinTable']) && $mapping['joinTable']) {
  1522.                 if (isset($mapping['joinTable']['name']) && $mapping['joinTable']['name'][0] === '`') {
  1523.                     $mapping['joinTable']['name']   = trim($mapping['joinTable']['name'], '`');
  1524.                     $mapping['joinTable']['quoted'] = true;
  1525.                 }
  1526.             }
  1527.         } else {
  1528.             $mapping['isOwningSide'] = false;
  1529.         }
  1531.         if (isset($mapping['id']) && true === $mapping['id'] && $mapping['type'] & self::TO_MANY) {
  1532.             throw MappingException::illegalToManyIdentifierAssociation($this->name, $mapping['fieldName']);
  1533.         }
  1535.         // Fetch mode. Default fetch mode to LAZY, if not set.
  1536.         if ( ! isset($mapping['fetch'])) {
  1537.             $mapping['fetch'] = self::FETCH_LAZY;
  1538.         }
  1540.         // Cascades
  1541.         $cascades = isset($mapping['cascade']) ? array_map('strtolower', $mapping['cascade']) : [];
  1543.         $allCascades = ['remove', 'persist', 'refresh', 'merge', 'detach'];
  1544.         if (in_array('all', $cascades)) {
  1545.             $cascades = $allCascades;
  1546.         } elseif (count($cascades) !== count(array_intersect($cascades, $allCascades))) {
  1547.             throw MappingException::invalidCascadeOption(
  1548.                 array_diff($cascades, $allCascades),
  1549.                 $this->name,
  1550.                 $mapping['fieldName']
  1551.             );
  1552.         }
  1554.         $mapping['cascade'] = $cascades;
  1555.         $mapping['isCascadeRemove']  = in_array('remove', $cascades);
  1556.         $mapping['isCascadePersist'] = in_array('persist', $cascades);
  1557.         $mapping['isCascadeRefresh'] = in_array('refresh', $cascades);
  1558.         $mapping['isCascadeMerge']   = in_array('merge', $cascades);
  1559.         $mapping['isCascadeDetach']  = in_array('detach', $cascades);
  1561.         return $mapping;
  1562.     }
  1564.     /**
  1565.      * Validates & completes a one-to-one association mapping.
  1566.      *
  1567.      * @param array $mapping The mapping to validate & complete.
  1568.      *
  1569.      * @return array The validated & completed mapping.
  1570.      *
  1571.      * @throws RuntimeException
  1572.      * @throws MappingException
  1573.      */
  1574.     protected function _validateAndCompleteOneToOneMapping(array $mapping)
  1575.     {
  1576.         $mapping = $this->_validateAndCompleteAssociationMapping($mapping);
  1578.         if (isset($mapping['joinColumns']) && $mapping['joinColumns']) {
  1579.             $mapping['isOwningSide'] = true;
  1580.         }
  1582.         if ($mapping['isOwningSide']) {
  1583.             if (empty($mapping['joinColumns'])) {
  1584.                 // Apply default join column
  1585.                 $mapping['joinColumns'] = [
  1586.                     [
  1587.                         'name' => $this->namingStrategy->joinColumnName($mapping['fieldName'], $this->name),
  1588.                         'referencedColumnName' => $this->namingStrategy->referenceColumnName()
  1589.                     ]
  1590.                 ];
  1591.             }
  1593.             $uniqueConstraintColumns = [];
  1595.             foreach ($mapping['joinColumns'] as &$joinColumn) {
  1596.                 if ($mapping['type'] === self::ONE_TO_ONE && ! $this->isInheritanceTypeSingleTable()) {
  1597.                     if (count($mapping['joinColumns']) === 1) {
  1598.                         if (empty($mapping['id'])) {
  1599.                             $joinColumn['unique'] = true;
  1600.                         }
  1601.                     } else {
  1602.                         $uniqueConstraintColumns[] = $joinColumn['name'];
  1603.                     }
  1604.                 }
  1606.                 if (empty($joinColumn['name'])) {
  1607.                     $joinColumn['name'] = $this->namingStrategy->joinColumnName($mapping['fieldName'], $this->name);
  1608.                 }
  1610.                 if (empty($joinColumn['referencedColumnName'])) {
  1611.                     $joinColumn['referencedColumnName'] = $this->namingStrategy->referenceColumnName();
  1612.                 }
  1614.                 if ($joinColumn['name'][0] === '`') {
  1615.                     $joinColumn['name']   = trim($joinColumn['name'], '`');
  1616.                     $joinColumn['quoted'] = true;
  1617.                 }
  1619.                 if ($joinColumn['referencedColumnName'][0] === '`') {
  1620.                     $joinColumn['referencedColumnName'] = trim($joinColumn['referencedColumnName'], '`');
  1621.                     $joinColumn['quoted']               = true;
  1622.                 }
  1624.                 $mapping['sourceToTargetKeyColumns'][$joinColumn['name']] = $joinColumn['referencedColumnName'];
  1625.                 $mapping['joinColumnFieldNames'][$joinColumn['name']] = $joinColumn['fieldName'] ?? $joinColumn['name'];
  1626.             }
  1628.             if ($uniqueConstraintColumns) {
  1629.                 if ( ! $this->table) {
  1630.                     throw new RuntimeException("ClassMetadataInfo::setTable() has to be called before defining a one to one relationship.");
  1631.                 }
  1633.                 $this->table['uniqueConstraints'][$mapping['fieldName'] . "_uniq"] = [
  1634.                     'columns' => $uniqueConstraintColumns
  1635.                 ];
  1636.             }
  1638.             $mapping['targetToSourceKeyColumns'] = array_flip($mapping['sourceToTargetKeyColumns']);
  1639.         }
  1641.         $mapping['orphanRemoval']   = isset($mapping['orphanRemoval']) && $mapping['orphanRemoval'];
  1642.         $mapping['isCascadeRemove'] = $mapping['orphanRemoval'] || $mapping['isCascadeRemove'];
  1644.         if ($mapping['orphanRemoval']) {
  1645.             unset($mapping['unique']);
  1646.         }
  1648.         if (isset($mapping['id']) && $mapping['id'] === true && !$mapping['isOwningSide']) {
  1649.             throw MappingException::illegalInverseIdentifierAssociation($this->name, $mapping['fieldName']);
  1650.         }
  1652.         return $mapping;
  1653.     }
  1655.     /**
  1656.      * Validates & completes a one-to-many association mapping.
  1657.      *
  1658.      * @param array $mapping The mapping to validate and complete.
  1659.      *
  1660.      * @return array The validated and completed mapping.
  1661.      *
  1662.      * @throws MappingException
  1663.      * @throws InvalidArgumentException
  1664.      */
  1665.     protected function _validateAndCompleteOneToManyMapping(array $mapping)
  1666.     {
  1667.         $mapping = $this->_validateAndCompleteAssociationMapping($mapping);
  1669.         // OneToMany-side MUST be inverse (must have mappedBy)
  1670.         if ( ! isset($mapping['mappedBy'])) {
  1671.             throw MappingException::oneToManyRequiresMappedBy($mapping['fieldName']);
  1672.         }
  1674.         $mapping['orphanRemoval']   = isset($mapping['orphanRemoval']) && $mapping['orphanRemoval'];
  1675.         $mapping['isCascadeRemove'] = $mapping['orphanRemoval'] || $mapping['isCascadeRemove'];
  1677.         $this->assertMappingOrderBy($mapping);
  1679.         return $mapping;
  1680.     }
  1682.     /**
  1683.      * Validates & completes a many-to-many association mapping.
  1684.      *
  1685.      * @param array $mapping The mapping to validate & complete.
  1686.      *
  1687.      * @return array The validated & completed mapping.
  1688.      *
  1689.      * @throws \InvalidArgumentException
  1690.      */
  1691.     protected function _validateAndCompleteManyToManyMapping(array $mapping)
  1692.     {
  1693.         $mapping = $this->_validateAndCompleteAssociationMapping($mapping);
  1695.         if ($mapping['isOwningSide']) {
  1696.             // owning side MUST have a join table
  1697.             if ( ! isset($mapping['joinTable']['name'])) {
  1698.                 $mapping['joinTable']['name'] = $this->namingStrategy->joinTableName($mapping['sourceEntity'], $mapping['targetEntity'], $mapping['fieldName']);
  1699.             }
  1701.             $selfReferencingEntityWithoutJoinColumns = $mapping['sourceEntity'] == $mapping['targetEntity']
  1702.                 && (! (isset($mapping['joinTable']['joinColumns']) || isset($mapping['joinTable']['inverseJoinColumns'])));
  1704.             if ( ! isset($mapping['joinTable']['joinColumns'])) {
  1705.                 $mapping['joinTable']['joinColumns'] = [
  1706.                     [
  1707.                         'name' => $this->namingStrategy->joinKeyColumnName($mapping['sourceEntity'], $selfReferencingEntityWithoutJoinColumns ? 'source' : null),
  1708.                         'referencedColumnName' => $this->namingStrategy->referenceColumnName(),
  1709.                         'onDelete' => 'CASCADE'
  1710.                     ]
  1711.                 ];
  1712.             }
  1714.             if ( ! isset($mapping['joinTable']['inverseJoinColumns'])) {
  1715.                 $mapping['joinTable']['inverseJoinColumns'] = [
  1716.                     [
  1717.                         'name' => $this->namingStrategy->joinKeyColumnName($mapping['targetEntity'], $selfReferencingEntityWithoutJoinColumns ? 'target' : null),
  1718.                         'referencedColumnName' => $this->namingStrategy->referenceColumnName(),
  1719.                         'onDelete' => 'CASCADE'
  1720.                     ]
  1721.                 ];
  1722.             }
  1724.             $mapping['joinTableColumns'] = [];
  1726.             foreach ($mapping['joinTable']['joinColumns'] as &$joinColumn) {
  1727.                 if (empty($joinColumn['name'])) {
  1728.                     $joinColumn['name'] = $this->namingStrategy->joinKeyColumnName($mapping['sourceEntity'], $joinColumn['referencedColumnName']);
  1729.                 }
  1731.                 if (empty($joinColumn['referencedColumnName'])) {
  1732.                     $joinColumn['referencedColumnName'] = $this->namingStrategy->referenceColumnName();
  1733.                 }
  1735.                 if ($joinColumn['name'][0] === '`') {
  1736.                     $joinColumn['name']   = trim($joinColumn['name'], '`');
  1737.                     $joinColumn['quoted'] = true;
  1738.                 }
  1740.                 if ($joinColumn['referencedColumnName'][0] === '`') {
  1741.                     $joinColumn['referencedColumnName'] = trim($joinColumn['referencedColumnName'], '`');
  1742.                     $joinColumn['quoted']               = true;
  1743.                 }
  1745.                 if (isset($joinColumn['onDelete']) && strtolower($joinColumn['onDelete']) == 'cascade') {
  1746.                     $mapping['isOnDeleteCascade'] = true;
  1747.                 }
  1749.                 $mapping['relationToSourceKeyColumns'][$joinColumn['name']] = $joinColumn['referencedColumnName'];
  1750.                 $mapping['joinTableColumns'][] = $joinColumn['name'];
  1751.             }
  1753.             foreach ($mapping['joinTable']['inverseJoinColumns'] as &$inverseJoinColumn) {
  1754.                 if (empty($inverseJoinColumn['name'])) {
  1755.                     $inverseJoinColumn['name'] = $this->namingStrategy->joinKeyColumnName($mapping['targetEntity'], $inverseJoinColumn['referencedColumnName']);
  1756.                 }
  1758.                 if (empty($inverseJoinColumn['referencedColumnName'])) {
  1759.                     $inverseJoinColumn['referencedColumnName'] = $this->namingStrategy->referenceColumnName();
  1760.                 }
  1762.                 if ($inverseJoinColumn['name'][0] === '`') {
  1763.                     $inverseJoinColumn['name']   = trim($inverseJoinColumn['name'], '`');
  1764.                     $inverseJoinColumn['quoted'] = true;
  1765.                 }
  1767.                 if ($inverseJoinColumn['referencedColumnName'][0] === '`') {
  1768.                     $inverseJoinColumn['referencedColumnName']  = trim($inverseJoinColumn['referencedColumnName'], '`');
  1769.                     $inverseJoinColumn['quoted']                = true;
  1770.                 }
  1772.                 if (isset($inverseJoinColumn['onDelete']) && strtolower($inverseJoinColumn['onDelete']) == 'cascade') {
  1773.                     $mapping['isOnDeleteCascade'] = true;
  1774.                 }
  1776.                 $mapping['relationToTargetKeyColumns'][$inverseJoinColumn['name']] = $inverseJoinColumn['referencedColumnName'];
  1777.                 $mapping['joinTableColumns'][] = $inverseJoinColumn['name'];
  1778.             }
  1779.         }
  1781.         $mapping['orphanRemoval'] = isset($mapping['orphanRemoval']) && $mapping['orphanRemoval'];
  1783.         $this->assertMappingOrderBy($mapping);
  1785.         return $mapping;
  1786.     }
  1788.     /**
  1789.      * {@inheritDoc}
  1790.      */
  1791.     public function getIdentifierFieldNames()
  1792.     {
  1793.         return $this->identifier;
  1794.     }
  1796.     /**
  1797.      * Gets the name of the single id field. Note that this only works on
  1798.      * entity classes that have a single-field pk.
  1799.      *
  1800.      * @return string
  1801.      *
  1802.      * @throws MappingException If the class doesn't have an identifier or it has a composite primary key.
  1803.      */
  1804.     public function getSingleIdentifierFieldName()
  1805.     {
  1806.         if ($this->isIdentifierComposite) {
  1807.             throw MappingException::singleIdNotAllowedOnCompositePrimaryKey($this->name);
  1808.         }
  1810.         if ( ! isset($this->identifier[0])) {
  1811.             throw MappingException::noIdDefined($this->name);
  1812.         }
  1814.         return $this->identifier[0];
  1815.     }
  1817.     /**
  1818.      * Gets the column name of the single id column. Note that this only works on
  1819.      * entity classes that have a single-field pk.
  1820.      *
  1821.      * @return string
  1822.      *
  1823.      * @throws MappingException If the class doesn't have an identifier or it has a composite primary key.
  1824.      */
  1825.     public function getSingleIdentifierColumnName()
  1826.     {
  1827.         return $this->getColumnName($this->getSingleIdentifierFieldName());
  1828.     }
  1830.     /**
  1831.      * INTERNAL:
  1832.      * Sets the mapped identifier/primary key fields of this class.
  1833.      * Mainly used by the ClassMetadataFactory to assign inherited identifiers.
  1834.      *
  1835.      * @param array $identifier
  1836.      *
  1837.      * @return void
  1838.      */
  1839.     public function setIdentifier(array $identifier)
  1840.     {
  1841.         $this->identifier = $identifier;
  1842.         $this->isIdentifierComposite = (count($this->identifier) > 1);
  1843.     }
  1845.     /**
  1846.      * {@inheritDoc}
  1847.      */
  1848.     public function getIdentifier()
  1849.     {
  1850.         return $this->identifier;
  1851.     }
  1853.     /**
  1854.      * {@inheritDoc}
  1855.      */
  1856.     public function hasField($fieldName)
  1857.     {
  1858.         return isset($this->fieldMappings[$fieldName]) || isset($this->embeddedClasses[$fieldName]);
  1859.     }
  1861.     /**
  1862.      * Gets an array containing all the column names.
  1863.      *
  1864.      * @param array|null $fieldNames
  1865.      *
  1866.      * @return array
  1867.      */
  1868.     public function getColumnNames(array $fieldNames = null)
  1869.     {
  1870.         if (null === $fieldNames) {
  1871.             return array_keys($this->fieldNames);
  1872.         }
  1874.         return array_values(array_map([$this, 'getColumnName'], $fieldNames));
  1875.     }
  1877.     /**
  1878.      * Returns an array with all the identifier column names.
  1879.      *
  1880.      * @return array
  1881.      */
  1882.     public function getIdentifierColumnNames()
  1883.     {
  1884.         $columnNames = [];
  1886.         foreach ($this->identifier as $idProperty) {
  1887.             if (isset($this->fieldMappings[$idProperty])) {
  1888.                 $columnNames[] = $this->fieldMappings[$idProperty]['columnName'];
  1890.                 continue;
  1891.             }
  1893.             // Association defined as Id field
  1894.             $joinColumns      = $this->associationMappings[$idProperty]['joinColumns'];
  1895.             $assocColumnNames = array_map(function ($joinColumn) { return $joinColumn['name']; }, $joinColumns);
  1897.             $columnNames = array_merge($columnNames, $assocColumnNames);
  1898.         }
  1900.         return $columnNames;
  1901.     }
  1903.     /**
  1904.      * Sets the type of Id generator to use for the mapped class.
  1905.      *
  1906.      * @param int $generatorType
  1907.      *
  1908.      * @return void
  1909.      */
  1910.     public function setIdGeneratorType($generatorType)
  1911.     {
  1912.         $this->generatorType = $generatorType;
  1913.     }
  1915.     /**
  1916.      * Checks whether the mapped class uses an Id generator.
  1917.      *
  1918.      * @return boolean TRUE if the mapped class uses an Id generator, FALSE otherwise.
  1919.      */
  1920.     public function usesIdGenerator()
  1921.     {
  1922.         return $this->generatorType != self::GENERATOR_TYPE_NONE;
  1923.     }
  1925.     /**
  1926.      * @return boolean
  1927.      */
  1928.     public function isInheritanceTypeNone()
  1929.     {
  1930.         return $this->inheritanceType == self::INHERITANCE_TYPE_NONE;
  1931.     }
  1933.     /**
  1934.      * Checks whether the mapped class uses the JOINED inheritance mapping strategy.
  1935.      *
  1936.      * @return boolean TRUE if the class participates in a JOINED inheritance mapping,
  1937.      *                 FALSE otherwise.
  1938.      */
  1939.     public function isInheritanceTypeJoined()
  1940.     {
  1941.         return $this->inheritanceType == self::INHERITANCE_TYPE_JOINED;
  1942.     }
  1944.     /**
  1945.      * Checks whether the mapped class uses the SINGLE_TABLE inheritance mapping strategy.
  1946.      *
  1947.      * @return boolean TRUE if the class participates in a SINGLE_TABLE inheritance mapping,
  1948.      *                 FALSE otherwise.
  1949.      */
  1950.     public function isInheritanceTypeSingleTable()
  1951.     {
  1952.         return $this->inheritanceType == self::INHERITANCE_TYPE_SINGLE_TABLE;
  1953.     }
  1955.     /**
  1956.      * Checks whether the mapped class uses the TABLE_PER_CLASS inheritance mapping strategy.
  1957.      *
  1958.      * @return boolean TRUE if the class participates in a TABLE_PER_CLASS inheritance mapping,
  1959.      *                 FALSE otherwise.
  1960.      */
  1961.     public function isInheritanceTypeTablePerClass()
  1962.     {
  1963.         return $this->inheritanceType == self::INHERITANCE_TYPE_TABLE_PER_CLASS;
  1964.     }
  1966.     /**
  1967.      * Checks whether the class uses an identity column for the Id generation.
  1968.      *
  1969.      * @return boolean TRUE if the class uses the IDENTITY generator, FALSE otherwise.
  1970.      */
  1971.     public function isIdGeneratorIdentity()
  1972.     {
  1973.         return $this->generatorType == self::GENERATOR_TYPE_IDENTITY;
  1974.     }
  1976.     /**
  1977.      * Checks whether the class uses a sequence for id generation.
  1978.      *
  1979.      * @return boolean TRUE if the class uses the SEQUENCE generator, FALSE otherwise.
  1980.      */
  1981.     public function isIdGeneratorSequence()
  1982.     {
  1983.         return $this->generatorType == self::GENERATOR_TYPE_SEQUENCE;
  1984.     }
  1986.     /**
  1987.      * Checks whether the class uses a table for id generation.
  1988.      *
  1989.      * @return boolean TRUE if the class uses the TABLE generator, FALSE otherwise.
  1990.      */
  1991.     public function isIdGeneratorTable()
  1992.     {
  1993.         return $this->generatorType == self::GENERATOR_TYPE_TABLE;
  1994.     }
  1996.     /**
  1997.      * Checks whether the class has a natural identifier/pk (which means it does
  1998.      * not use any Id generator.
  1999.      *
  2000.      * @return boolean
  2001.      */
  2002.     public function isIdentifierNatural()
  2003.     {
  2004.         return $this->generatorType == self::GENERATOR_TYPE_NONE;
  2005.     }
  2007.     /**
  2008.      * Checks whether the class use a UUID for id generation.
  2009.      *
  2010.      * @return boolean
  2011.      */
  2012.     public function isIdentifierUuid()
  2013.     {
  2014.         return $this->generatorType == self::GENERATOR_TYPE_UUID;
  2015.     }
  2017.     /**
  2018.      * Gets the type of a field.
  2019.      *
  2020.      * @param string $fieldName
  2021.      *
  2022.      * @return string|null
  2023.      *
  2024.      * @todo 3.0 Remove this. PersisterHelper should fix it somehow
  2025.      */
  2026.     public function getTypeOfField($fieldName)
  2027.     {
  2028.         return isset($this->fieldMappings[$fieldName])
  2029.             ? $this->fieldMappings[$fieldName]['type']
  2030.             : null;
  2031.     }
  2033.     /**
  2034.      * Gets the type of a column.
  2035.      *
  2036.      * @param string $columnName
  2037.      *
  2038.      * @return string|null
  2039.      *
  2040.      * @deprecated 3.0 remove this. this method is bogus and unreliable, since it cannot resolve the type of a column
  2041.      *             that is derived by a referenced field on a different entity.
  2042.      */
  2043.     public function getTypeOfColumn($columnName)
  2044.     {
  2045.         return $this->getTypeOfField($this->getFieldName($columnName));
  2046.     }
  2048.     /**
  2049.      * Gets the name of the primary table.
  2050.      *
  2051.      * @return string
  2052.      */
  2053.     public function getTableName()
  2054.     {
  2055.         return $this->table['name'];
  2056.     }
  2058.     /**
  2059.      * Gets primary table's schema name.
  2060.      *
  2061.      * @return string|null
  2062.      */
  2063.     public function getSchemaName()
  2064.     {
  2065.         return isset($this->table['schema']) ? $this->table['schema'] : null;
  2066.     }
  2068.     /**
  2069.      * Gets the table name to use for temporary identifier tables of this class.
  2070.      *
  2071.      * @return string
  2072.      */
  2073.     public function getTemporaryIdTableName()
  2074.     {
  2075.         // replace dots with underscores because PostgreSQL creates temporary tables in a special schema
  2076.         return str_replace('.', '_', $this->getTableName() . '_id_tmp');
  2077.     }
  2079.     /**
  2080.      * Sets the mapped subclasses of this class.
  2081.      *
  2082.      * @param array $subclasses The names of all mapped subclasses.
  2083.      *
  2084.      * @return void
  2085.      */
  2086.     public function setSubclasses(array $subclasses)
  2087.     {
  2088.         foreach ($subclasses as $subclass) {
  2089.             $this->subClasses[] = $this->fullyQualifiedClassName($subclass);
  2090.         }
  2091.     }
  2093.     /**
  2094.      * Sets the parent class names.
  2095.      * Assumes that the class names in the passed array are in the order:
  2096.      * directParent -> directParentParent -> directParentParentParent ... -> root.
  2097.      *
  2098.      * @param array $classNames
  2099.      *
  2100.      * @return void
  2101.      */
  2102.     public function setParentClasses(array $classNames)
  2103.     {
  2104.         $this->parentClasses = $classNames;
  2106.         if (count($classNames) > 0) {
  2107.             $this->rootEntityName = array_pop($classNames);
  2108.         }
  2109.     }
  2111.     /**
  2112.      * Sets the inheritance type used by the class and its subclasses.
  2113.      *
  2114.      * @param integer $type
  2115.      *
  2116.      * @return void
  2117.      *
  2118.      * @throws MappingException
  2119.      */
  2120.     public function setInheritanceType($type)
  2121.     {
  2122.         if ( ! $this->_isInheritanceType($type)) {
  2123.             throw MappingException::invalidInheritanceType($this->name, $type);
  2124.         }
  2126.         $this->inheritanceType = $type;
  2127.     }
  2129.     /**
  2130.      * Sets the association to override association mapping of property for an entity relationship.
  2131.      *
  2132.      * @param string $fieldName
  2133.      * @param array  $overrideMapping
  2134.      *
  2135.      * @return void
  2136.      *
  2137.      * @throws MappingException
  2138.      */
  2139.     public function setAssociationOverride($fieldName, array $overrideMapping)
  2140.     {
  2141.         if ( ! isset($this->associationMappings[$fieldName])) {
  2142.             throw MappingException::invalidOverrideFieldName($this->name, $fieldName);
  2143.         }
  2145.         $mapping = $this->associationMappings[$fieldName];
  2147.         if (isset($overrideMapping['joinColumns'])) {
  2148.             $mapping['joinColumns'] = $overrideMapping['joinColumns'];
  2149.         }
  2151.         if (isset($overrideMapping['inversedBy'])) {
  2152.             $mapping['inversedBy'] = $overrideMapping['inversedBy'];
  2153.         }
  2155.         if (isset($overrideMapping['joinTable'])) {
  2156.             $mapping['joinTable'] = $overrideMapping['joinTable'];
  2157.         }
  2159.         if (isset($overrideMapping['fetch'])) {
  2160.             $mapping['fetch'] = $overrideMapping['fetch'];
  2161.         }
  2163.         $mapping['joinColumnFieldNames']        = null;
  2164.         $mapping['joinTableColumns']            = null;
  2165.         $mapping['sourceToTargetKeyColumns']    = null;
  2166.         $mapping['relationToSourceKeyColumns']  = null;
  2167.         $mapping['relationToTargetKeyColumns']  = null;
  2169.         switch ($mapping['type']) {
  2170.             case self::ONE_TO_ONE:
  2171.                 $mapping = $this->_validateAndCompleteOneToOneMapping($mapping);
  2172.                 break;
  2173.             case self::ONE_TO_MANY:
  2174.                 $mapping = $this->_validateAndCompleteOneToManyMapping($mapping);
  2175.                 break;
  2176.             case self::MANY_TO_ONE:
  2177.                 $mapping = $this->_validateAndCompleteOneToOneMapping($mapping);
  2178.                 break;
  2179.             case self::MANY_TO_MANY:
  2180.                 $mapping = $this->_validateAndCompleteManyToManyMapping($mapping);
  2181.                 break;
  2182.         }
  2184.         $this->associationMappings[$fieldName] = $mapping;
  2185.     }
  2187.     /**
  2188.      * Sets the override for a mapped field.
  2189.      *
  2190.      * @param string $fieldName
  2191.      * @param array  $overrideMapping
  2192.      *
  2193.      * @return void
  2194.      *
  2195.      * @throws MappingException
  2196.      */
  2197.     public function setAttributeOverride($fieldName, array $overrideMapping)
  2198.     {
  2199.         if ( ! isset($this->fieldMappings[$fieldName])) {
  2200.             throw MappingException::invalidOverrideFieldName($this->name, $fieldName);
  2201.         }
  2203.         $mapping = $this->fieldMappings[$fieldName];
  2205.         if (isset($mapping['id'])) {
  2206.             $overrideMapping['id'] = $mapping['id'];
  2207.         }
  2209.         if ( ! isset($overrideMapping['type'])) {
  2210.             $overrideMapping['type'] = $mapping['type'];
  2211.         }
  2213.         if ( ! isset($overrideMapping['fieldName'])) {
  2214.             $overrideMapping['fieldName'] = $mapping['fieldName'];
  2215.         }
  2217.         if ($overrideMapping['type'] !== $mapping['type']) {
  2218.             throw MappingException::invalidOverrideFieldType($this->name, $fieldName);
  2219.         }
  2221.         unset($this->fieldMappings[$fieldName]);
  2222.         unset($this->fieldNames[$mapping['columnName']]);
  2223.         unset($this->columnNames[$mapping['fieldName']]);
  2225.         $this->_validateAndCompleteFieldMapping($overrideMapping);
  2227.         $this->fieldMappings[$fieldName] = $overrideMapping;
  2228.     }
  2230.     /**
  2231.      * Checks whether a mapped field is inherited from an entity superclass.
  2232.      *
  2233.      * @param string $fieldName
  2234.      *
  2235.      * @return bool TRUE if the field is inherited, FALSE otherwise.
  2236.      */
  2237.     public function isInheritedField($fieldName)
  2238.     {
  2239.         return isset($this->fieldMappings[$fieldName]['inherited']);
  2240.     }
  2242.     /**
  2243.      * Checks if this entity is the root in any entity-inheritance-hierarchy.
  2244.      *
  2245.      * @return bool
  2246.      */
  2247.     public function isRootEntity()
  2248.     {
  2249.         return $this->name == $this->rootEntityName;
  2250.     }
  2252.     /**
  2253.      * Checks whether a mapped association field is inherited from a superclass.
  2254.      *
  2255.      * @param string $fieldName
  2256.      *
  2257.      * @return boolean TRUE if the field is inherited, FALSE otherwise.
  2258.      */
  2259.     public function isInheritedAssociation($fieldName)
  2260.     {
  2261.         return isset($this->associationMappings[$fieldName]['inherited']);
  2262.     }
  2264.     public function isInheritedEmbeddedClass($fieldName)
  2265.     {
  2266.         return isset($this->embeddedClasses[$fieldName]['inherited']);
  2267.     }
  2269.     /**
  2270.      * Sets the name of the primary table the class is mapped to.
  2271.      *
  2272.      * @param string $tableName The table name.
  2273.      *
  2274.      * @return void
  2275.      *
  2276.      * @deprecated Use {@link setPrimaryTable}.
  2277.      */
  2278.     public function setTableName($tableName)
  2279.     {
  2280.         $this->table['name'] = $tableName;
  2281.     }
  2283.     /**
  2284.      * Sets the primary table definition. The provided array supports the
  2285.      * following structure:
  2286.      *
  2287.      * name => <tableName> (optional, defaults to class name)
  2288.      * indexes => array of indexes (optional)
  2289.      * uniqueConstraints => array of constraints (optional)
  2290.      *
  2291.      * If a key is omitted, the current value is kept.
  2292.      *
  2293.      * @param array $table The table description.
  2294.      *
  2295.      * @return void
  2296.      */
  2297.     public function setPrimaryTable(array $table)
  2298.     {
  2299.         if (isset($table['name'])) {
  2300.             // Split schema and table name from a table name like "myschema.mytable"
  2301.             if (strpos($table['name'], '.') !== false) {
  2302.                 list($this->table['schema'], $table['name']) = explode('.', $table['name'], 2);
  2303.             }
  2305.             if ($table['name'][0] === '`') {
  2306.                 $table['name']          = trim($table['name'], '`');
  2307.                 $this->table['quoted']  = true;
  2308.             }
  2310.             $this->table['name'] = $table['name'];
  2311.         }
  2313.         if (isset($table['quoted'])) {
  2314.             $this->table['quoted'] = $table['quoted'];
  2315.         }
  2317.         if (isset($table['schema'])) {
  2318.             $this->table['schema'] = $table['schema'];
  2319.         }
  2321.         if (isset($table['indexes'])) {
  2322.             $this->table['indexes'] = $table['indexes'];
  2323.         }
  2325.         if (isset($table['uniqueConstraints'])) {
  2326.             $this->table['uniqueConstraints'] = $table['uniqueConstraints'];
  2327.         }
  2329.         if (isset($table['options'])) {
  2330.             $this->table['options'] = $table['options'];
  2331.         }
  2332.     }
  2334.     /**
  2335.      * Checks whether the given type identifies an inheritance type.
  2336.      *
  2337.      * @param integer $type
  2338.      *
  2339.      * @return boolean TRUE if the given type identifies an inheritance type, FALSe otherwise.
  2340.      */
  2341.     private function _isInheritanceType($type)
  2342.     {
  2343.         return $type == self::INHERITANCE_TYPE_NONE ||
  2344.                 $type == self::INHERITANCE_TYPE_SINGLE_TABLE ||
  2345.                 $type == self::INHERITANCE_TYPE_JOINED ||
  2346.                 $type == self::INHERITANCE_TYPE_TABLE_PER_CLASS;
  2347.     }
  2349.     /**
  2350.      * Adds a mapped field to the class.
  2351.      *
  2352.      * @param array $mapping The field mapping.
  2353.      *
  2354.      * @return void
  2355.      *
  2356.      * @throws MappingException
  2357.      */
  2358.     public function mapField(array $mapping)
  2359.     {
  2360.         $this->_validateAndCompleteFieldMapping($mapping);
  2361.         $this->assertFieldNotMapped($mapping['fieldName']);
  2363.         $this->fieldMappings[$mapping['fieldName']] = $mapping;
  2364.     }
  2366.     /**
  2367.      * INTERNAL:
  2368.      * Adds an association mapping without completing/validating it.
  2369.      * This is mainly used to add inherited association mappings to derived classes.
  2370.      *
  2371.      * @param array $mapping
  2372.      *
  2373.      * @return void
  2374.      *
  2375.      * @throws MappingException
  2376.      */
  2377.     public function addInheritedAssociationMapping(array $mapping/*, $owningClassName = null*/)
  2378.     {
  2379.         if (isset($this->associationMappings[$mapping['fieldName']])) {
  2380.             throw MappingException::duplicateAssociationMapping($this->name, $mapping['fieldName']);
  2381.         }
  2382.         $this->associationMappings[$mapping['fieldName']] = $mapping;
  2383.     }
  2385.     /**
  2386.      * INTERNAL:
  2387.      * Adds a field mapping without completing/validating it.
  2388.      * This is mainly used to add inherited field mappings to derived classes.
  2389.      *
  2390.      * @param array $fieldMapping
  2391.      *
  2392.      * @return void
  2393.      */
  2394.     public function addInheritedFieldMapping(array $fieldMapping)
  2395.     {
  2396.         $this->fieldMappings[$fieldMapping['fieldName']] = $fieldMapping;
  2397.         $this->columnNames[$fieldMapping['fieldName']] = $fieldMapping['columnName'];
  2398.         $this->fieldNames[$fieldMapping['columnName']] = $fieldMapping['fieldName'];
  2399.     }
  2401.     /**
  2402.      * INTERNAL:
  2403.      * Adds a named query to this class.
  2404.      *
  2405.      * @param array $queryMapping
  2406.      *
  2407.      * @return void
  2408.      *
  2409.      * @throws MappingException
  2410.      */
  2411.     public function addNamedQuery(array $queryMapping)
  2412.     {
  2413.         if (!isset($queryMapping['name'])) {
  2414.             throw MappingException::nameIsMandatoryForQueryMapping($this->name);
  2415.         }
  2417.         if (isset($this->namedQueries[$queryMapping['name']])) {
  2418.             throw MappingException::duplicateQueryMapping($this->name, $queryMapping['name']);
  2419.         }
  2421.         if (!isset($queryMapping['query'])) {
  2422.             throw MappingException::emptyQueryMapping($this->name, $queryMapping['name']);
  2423.         }
  2425.         $name   = $queryMapping['name'];
  2426.         $query  = $queryMapping['query'];
  2427.         $dql    = str_replace('__CLASS__', $this->name, $query);
  2429.         $this->namedQueries[$name] = [
  2430.             'name'  => $name,
  2431.             'query' => $query,
  2432.             'dql'   => $dql,
  2433.         ];
  2434.     }
  2436.     /**
  2437.      * INTERNAL:
  2438.      * Adds a named native query to this class.
  2439.      *
  2440.      * @param array $queryMapping
  2441.      *
  2442.      * @return void
  2443.      *
  2444.      * @throws MappingException
  2445.      */
  2446.     public function addNamedNativeQuery(array $queryMapping)
  2447.     {
  2448.         if (!isset($queryMapping['name'])) {
  2449.             throw MappingException::nameIsMandatoryForQueryMapping($this->name);
  2450.         }
  2452.         if (isset($this->namedNativeQueries[$queryMapping['name']])) {
  2453.             throw MappingException::duplicateQueryMapping($this->name, $queryMapping['name']);
  2454.         }
  2456.         if (!isset($queryMapping['query'])) {
  2457.             throw MappingException::emptyQueryMapping($this->name, $queryMapping['name']);
  2458.         }
  2460.         if (!isset($queryMapping['resultClass']) && !isset($queryMapping['resultSetMapping'])) {
  2461.             throw MappingException::missingQueryMapping($this->name, $queryMapping['name']);
  2462.         }
  2464.         $queryMapping['isSelfClass'] = false;
  2466.         if (isset($queryMapping['resultClass'])) {
  2467.             if ($queryMapping['resultClass'] === '__CLASS__') {
  2469.                 $queryMapping['isSelfClass'] = true;
  2470.                 $queryMapping['resultClass'] = $this->name;
  2471.             }
  2473.             $queryMapping['resultClass'] = $this->fullyQualifiedClassName($queryMapping['resultClass']);
  2474.             $queryMapping['resultClass'] = ltrim($queryMapping['resultClass'], '\\');
  2475.         }
  2477.         $this->namedNativeQueries[$queryMapping['name']] = $queryMapping;
  2478.     }
  2480.     /**
  2481.      * INTERNAL:
  2482.      * Adds a sql result set mapping to this class.
  2483.      *
  2484.      * @param array $resultMapping
  2485.      *
  2486.      * @return void
  2487.      *
  2488.      * @throws MappingException
  2489.      */
  2490.     public function addSqlResultSetMapping(array $resultMapping)
  2491.     {
  2492.         if (!isset($resultMapping['name'])) {
  2493.             throw MappingException::nameIsMandatoryForSqlResultSetMapping($this->name);
  2494.         }
  2496.         if (isset($this->sqlResultSetMappings[$resultMapping['name']])) {
  2497.             throw MappingException::duplicateResultSetMapping($this->name, $resultMapping['name']);
  2498.         }
  2500.         if (isset($resultMapping['entities'])) {
  2501.             foreach ($resultMapping['entities'] as $key => $entityResult) {
  2502.                 if (!isset($entityResult['entityClass'])) {
  2503.                     throw MappingException::missingResultSetMappingEntity($this->name, $resultMapping['name']);
  2504.                 }
  2506.                 $entityResult['isSelfClass'] = false;
  2507.                 if ($entityResult['entityClass'] === '__CLASS__') {
  2509.                     $entityResult['isSelfClass'] = true;
  2510.                     $entityResult['entityClass'] = $this->name;
  2512.                 }
  2514.                 $entityResult['entityClass'] = $this->fullyQualifiedClassName($entityResult['entityClass']);
  2516.                 $resultMapping['entities'][$key]['entityClass'] = ltrim($entityResult['entityClass'], '\\');
  2517.                 $resultMapping['entities'][$key]['isSelfClass'] = $entityResult['isSelfClass'];
  2519.                 if (isset($entityResult['fields'])) {
  2520.                     foreach ($entityResult['fields'] as $k => $field) {
  2521.                         if (!isset($field['name'])) {
  2522.                             throw MappingException::missingResultSetMappingFieldName($this->name, $resultMapping['name']);
  2523.                         }
  2525.                         if (!isset($field['column'])) {
  2526.                             $fieldName = $field['name'];
  2527.                             if (strpos($fieldName, '.')) {
  2528.                                 list(, $fieldName) = explode('.', $fieldName);
  2529.                             }
  2531.                             $resultMapping['entities'][$key]['fields'][$k]['column'] = $fieldName;
  2532.                         }
  2533.                     }
  2534.                 }
  2535.             }
  2536.         }
  2538.         $this->sqlResultSetMappings[$resultMapping['name']] = $resultMapping;
  2539.     }
  2541.     /**
  2542.      * Adds a one-to-one mapping.
  2543.      *
  2544.      * @param array $mapping The mapping.
  2545.      *
  2546.      * @return void
  2547.      */
  2548.     public function mapOneToOne(array $mapping)
  2549.     {
  2550.         $mapping['type'] = self::ONE_TO_ONE;
  2552.         $mapping = $this->_validateAndCompleteOneToOneMapping($mapping);
  2554.         $this->_storeAssociationMapping($mapping);
  2555.     }
  2557.     /**
  2558.      * Adds a one-to-many mapping.
  2559.      *
  2560.      * @param array $mapping The mapping.
  2561.      *
  2562.      * @return void
  2563.      */
  2564.     public function mapOneToMany(array $mapping)
  2565.     {
  2566.         $mapping['type'] = self::ONE_TO_MANY;
  2568.         $mapping = $this->_validateAndCompleteOneToManyMapping($mapping);
  2570.         $this->_storeAssociationMapping($mapping);
  2571.     }
  2573.     /**
  2574.      * Adds a many-to-one mapping.
  2575.      *
  2576.      * @param array $mapping The mapping.
  2577.      *
  2578.      * @return void
  2579.      */
  2580.     public function mapManyToOne(array $mapping)
  2581.     {
  2582.         $mapping['type'] = self::MANY_TO_ONE;
  2584.         // A many-to-one mapping is essentially a one-one backreference
  2585.         $mapping = $this->_validateAndCompleteOneToOneMapping($mapping);
  2587.         $this->_storeAssociationMapping($mapping);
  2588.     }
  2590.     /**
  2591.      * Adds a many-to-many mapping.
  2592.      *
  2593.      * @param array $mapping The mapping.
  2594.      *
  2595.      * @return void
  2596.      */
  2597.     public function mapManyToMany(array $mapping)
  2598.     {
  2599.         $mapping['type'] = self::MANY_TO_MANY;
  2601.         $mapping = $this->_validateAndCompleteManyToManyMapping($mapping);
  2603.         $this->_storeAssociationMapping($mapping);
  2604.     }
  2606.     /**
  2607.      * Stores the association mapping.
  2608.      *
  2609.      * @param array $assocMapping
  2610.      *
  2611.      * @return void
  2612.      *
  2613.      * @throws MappingException
  2614.      */
  2615.     protected function _storeAssociationMapping(array $assocMapping)
  2616.     {
  2617.         $sourceFieldName = $assocMapping['fieldName'];
  2619.         $this->assertFieldNotMapped($sourceFieldName);
  2621.         $this->associationMappings[$sourceFieldName] = $assocMapping;
  2622.     }
  2624.     /**
  2625.      * Registers a custom repository class for the entity class.
  2626.      *
  2627.      * @param string $repositoryClassName The class name of the custom mapper.
  2628.      *
  2629.      * @return void
  2630.      *
  2631.      * @psalm-param class-string $repositoryClassName
  2632.      */
  2633.     public function setCustomRepositoryClass($repositoryClassName)
  2634.     {
  2635.         $this->customRepositoryClassName = $this->fullyQualifiedClassName($repositoryClassName);
  2636.     }
  2638.     /**
  2639.      * Dispatches the lifecycle event of the given entity to the registered
  2640.      * lifecycle callbacks and lifecycle listeners.
  2641.      *
  2642.      * @deprecated Deprecated since version 2.4 in favor of \Doctrine\ORM\Event\ListenersInvoker
  2643.      *
  2644.      * @param string $lifecycleEvent The lifecycle event.
  2645.      * @param object $entity         The Entity on which the event occurred.
  2646.      *
  2647.      * @return void
  2648.      */
  2649.     public function invokeLifecycleCallbacks($lifecycleEvent, $entity)
  2650.     {
  2651.         foreach ($this->lifecycleCallbacks[$lifecycleEvent] as $callback) {
  2652.             $entity->$callback();
  2653.         }
  2654.     }
  2656.     /**
  2657.      * Whether the class has any attached lifecycle listeners or callbacks for a lifecycle event.
  2658.      *
  2659.      * @param string $lifecycleEvent
  2660.      *
  2661.      * @return boolean
  2662.      */
  2663.     public function hasLifecycleCallbacks($lifecycleEvent)
  2664.     {
  2665.         return isset($this->lifecycleCallbacks[$lifecycleEvent]);
  2666.     }
  2668.     /**
  2669.      * Gets the registered lifecycle callbacks for an event.
  2670.      *
  2671.      * @param string $event
  2672.      *
  2673.      * @return array
  2674.      */
  2675.     public function getLifecycleCallbacks($event)
  2676.     {
  2677.         return isset($this->lifecycleCallbacks[$event]) ? $this->lifecycleCallbacks[$event] : [];
  2678.     }
  2680.     /**
  2681.      * Adds a lifecycle callback for entities of this class.
  2682.      *
  2683.      * @param string $callback
  2684.      * @param string $event
  2685.      *
  2686.      * @return void
  2687.      */
  2688.     public function addLifecycleCallback($callback, $event)
  2689.     {
  2690.         if (isset($this->lifecycleCallbacks[$event]) && in_array($callback, $this->lifecycleCallbacks[$event])) {
  2691.             return;
  2692.         }
  2694.         $this->lifecycleCallbacks[$event][] = $callback;
  2695.     }
  2697.     /**
  2698.      * Sets the lifecycle callbacks for entities of this class.
  2699.      * Any previously registered callbacks are overwritten.
  2700.      *
  2701.      * @param array $callbacks
  2702.      *
  2703.      * @return void
  2704.      */
  2705.     public function setLifecycleCallbacks(array $callbacks)
  2706.     {
  2707.         $this->lifecycleCallbacks = $callbacks;
  2708.     }
  2710.     /**
  2711.      * Adds a entity listener for entities of this class.
  2712.      *
  2713.      * @param string $eventName The entity lifecycle event.
  2714.      * @param string $class     The listener class.
  2715.      * @param string $method    The listener callback method.
  2716.      *
  2717.      * @throws \Doctrine\ORM\Mapping\MappingException
  2718.      */
  2719.     public function addEntityListener($eventName, $class, $method)
  2720.     {
  2721.         $class    = $this->fullyQualifiedClassName($class);
  2723.         $listener = [
  2724.             'class'  => $class,
  2725.             'method' => $method,
  2726.         ];
  2728.         if ( ! class_exists($class)) {
  2729.             throw MappingException::entityListenerClassNotFound($class, $this->name);
  2730.         }
  2732.         if ( ! method_exists($class, $method)) {
  2733.             throw MappingException::entityListenerMethodNotFound($class, $method, $this->name);
  2734.         }
  2736.         if (isset($this->entityListeners[$eventName]) && in_array($listener, $this->entityListeners[$eventName])) {
  2737.             throw MappingException::duplicateEntityListener($class, $method, $this->name);
  2738.         }
  2740.         $this->entityListeners[$eventName][] = $listener;
  2741.     }
  2743.     /**
  2744.      * Sets the discriminator column definition.
  2745.      *
  2746.      * @param array $columnDef
  2747.      *
  2748.      * @return void
  2749.      *
  2750.      * @throws MappingException
  2751.      *
  2752.      * @see getDiscriminatorColumn()
  2753.      */
  2754.     public function setDiscriminatorColumn($columnDef)
  2755.     {
  2756.         if ($columnDef !== null) {
  2757.             if ( ! isset($columnDef['name'])) {
  2758.                 throw MappingException::nameIsMandatoryForDiscriminatorColumns($this->name);
  2759.             }
  2761.             if (isset($this->fieldNames[$columnDef['name']])) {
  2762.                 throw MappingException::duplicateColumnName($this->name, $columnDef['name']);
  2763.             }
  2765.             if ( ! isset($columnDef['fieldName'])) {
  2766.                 $columnDef['fieldName'] = $columnDef['name'];
  2767.             }
  2769.             if ( ! isset($columnDef['type'])) {
  2770.                 $columnDef['type'] = "string";
  2771.             }
  2773.             if (in_array($columnDef['type'], ["boolean", "array", "object", "datetime", "time", "date"])) {
  2774.                 throw MappingException::invalidDiscriminatorColumnType($this->name, $columnDef['type']);
  2775.             }
  2777.             $this->discriminatorColumn = $columnDef;
  2778.         }
  2779.     }
  2781.     /**
  2782.      * Sets the discriminator values used by this class.
  2783.      * Used for JOINED and SINGLE_TABLE inheritance mapping strategies.
  2784.      *
  2785.      * @param array $map
  2786.      *
  2787.      * @return void
  2788.      */
  2789.     public function setDiscriminatorMap(array $map)
  2790.     {
  2791.         foreach ($map as $value => $className) {
  2792.             $this->addDiscriminatorMapClass($value, $className);
  2793.         }
  2794.     }
  2796.     /**
  2797.      * Adds one entry of the discriminator map with a new class and corresponding name.
  2798.      *
  2799.      * @param string $name
  2800.      * @param string $className
  2801.      *
  2802.      * @return void
  2803.      *
  2804.      * @throws MappingException
  2805.      */
  2806.     public function addDiscriminatorMapClass($name, $className)
  2807.     {
  2808.         $className = $this->fullyQualifiedClassName($className);
  2809.         $className = ltrim($className, '\\');
  2811.         $this->discriminatorMap[$name] = $className;
  2813.         if ($this->name === $className) {
  2814.             $this->discriminatorValue = $name;
  2816.             return;
  2817.         }
  2819.         if ( ! (class_exists($className) || interface_exists($className))) {
  2820.             throw MappingException::invalidClassInDiscriminatorMap($className, $this->name);
  2821.         }
  2823.         if (is_subclass_of($className, $this->name) && ! in_array($className, $this->subClasses)) {
  2824.             $this->subClasses[] = $className;
  2825.         }
  2826.     }
  2828.     /**
  2829.      * Checks whether the class has a named query with the given query name.
  2830.      *
  2831.      * @param string $queryName
  2832.      *
  2833.      * @return boolean
  2834.      */
  2835.     public function hasNamedQuery($queryName)
  2836.     {
  2837.         return isset($this->namedQueries[$queryName]);
  2838.     }
  2840.     /**
  2841.      * Checks whether the class has a named native query with the given query name.
  2842.      *
  2843.      * @param string $queryName
  2844.      *
  2845.      * @return boolean
  2846.      */
  2847.     public function hasNamedNativeQuery($queryName)
  2848.     {
  2849.         return isset($this->namedNativeQueries[$queryName]);
  2850.     }
  2852.     /**
  2853.      * Checks whether the class has a named native query with the given query name.
  2854.      *
  2855.      * @param string $name
  2856.      *
  2857.      * @return boolean
  2858.      */
  2859.     public function hasSqlResultSetMapping($name)
  2860.     {
  2861.         return isset($this->sqlResultSetMappings[$name]);
  2862.     }
  2864.     /**
  2865.      * {@inheritDoc}
  2866.      */
  2867.     public function hasAssociation($fieldName)
  2868.     {
  2869.         return isset($this->associationMappings[$fieldName]);
  2870.     }
  2872.     /**
  2873.      * {@inheritDoc}
  2874.      */
  2875.     public function isSingleValuedAssociation($fieldName)
  2876.     {
  2877.         return isset($this->associationMappings[$fieldName])
  2878.             && ($this->associationMappings[$fieldName]['type'] & self::TO_ONE);
  2879.     }
  2881.     /**
  2882.      * {@inheritDoc}
  2883.      */
  2884.     public function isCollectionValuedAssociation($fieldName)
  2885.     {
  2886.         return isset($this->associationMappings[$fieldName])
  2887.             && ! ($this->associationMappings[$fieldName]['type'] & self::TO_ONE);
  2888.     }
  2890.     /**
  2891.      * Is this an association that only has a single join column?
  2892.      *
  2893.      * @param string $fieldName
  2894.      *
  2895.      * @return bool
  2896.      */
  2897.     public function isAssociationWithSingleJoinColumn($fieldName)
  2898.     {
  2899.         return isset($this->associationMappings[$fieldName])
  2900.             && isset($this->associationMappings[$fieldName]['joinColumns'][0])
  2901.             && ! isset($this->associationMappings[$fieldName]['joinColumns'][1]);
  2902.     }
  2904.     /**
  2905.      * Returns the single association join column (if any).
  2906.      *
  2907.      * @param string $fieldName
  2908.      *
  2909.      * @return string
  2910.      *
  2911.      * @throws MappingException
  2912.      */
  2913.     public function getSingleAssociationJoinColumnName($fieldName)
  2914.     {
  2915.         if ( ! $this->isAssociationWithSingleJoinColumn($fieldName)) {
  2916.             throw MappingException::noSingleAssociationJoinColumnFound($this->name, $fieldName);
  2917.         }
  2919.         return $this->associationMappings[$fieldName]['joinColumns'][0]['name'];
  2920.     }
  2922.     /**
  2923.      * Returns the single association referenced join column name (if any).
  2924.      *
  2925.      * @param string $fieldName
  2926.      *
  2927.      * @return string
  2928.      *
  2929.      * @throws MappingException
  2930.      */
  2931.     public function getSingleAssociationReferencedJoinColumnName($fieldName)
  2932.     {
  2933.         if ( ! $this->isAssociationWithSingleJoinColumn($fieldName)) {
  2934.             throw MappingException::noSingleAssociationJoinColumnFound($this->name, $fieldName);
  2935.         }
  2937.         return $this->associationMappings[$fieldName]['joinColumns'][0]['referencedColumnName'];
  2938.     }
  2940.     /**
  2941.      * Used to retrieve a fieldname for either field or association from a given column.
  2942.      *
  2943.      * This method is used in foreign-key as primary-key contexts.
  2944.      *
  2945.      * @param string $columnName
  2946.      *
  2947.      * @return string
  2948.      *
  2949.      * @throws MappingException
  2950.      */
  2951.     public function getFieldForColumn($columnName)
  2952.     {
  2953.         if (isset($this->fieldNames[$columnName])) {
  2954.             return $this->fieldNames[$columnName];
  2955.         }
  2957.         foreach ($this->associationMappings as $assocName => $mapping) {
  2958.             if ($this->isAssociationWithSingleJoinColumn($assocName) &&
  2959.                 $this->associationMappings[$assocName]['joinColumns'][0]['name'] == $columnName) {
  2961.                 return $assocName;
  2962.             }
  2963.         }
  2965.         throw MappingException::noFieldNameFoundForColumn($this->name, $columnName);
  2966.     }
  2968.     /**
  2969.      * Sets the ID generator used to generate IDs for instances of this class.
  2970.      *
  2971.      * @param \Doctrine\ORM\Id\AbstractIdGenerator $generator
  2972.      *
  2973.      * @return void
  2974.      */
  2975.     public function setIdGenerator($generator)
  2976.     {
  2977.         $this->idGenerator = $generator;
  2978.     }
  2980.     /**
  2981.      * Sets definition.
  2982.      *
  2983.      * @param array $definition
  2984.      *
  2985.      * @return void
  2986.      */
  2987.     public function setCustomGeneratorDefinition(array $definition)
  2988.     {
  2989.         $this->customGeneratorDefinition = $definition;
  2990.     }
  2992.     /**
  2993.      * Sets the definition of the sequence ID generator for this class.
  2994.      *
  2995.      * The definition must have the following structure:
  2996.      * <code>
  2997.      * array(
  2998.      *     'sequenceName'   => 'name',
  2999.      *     'allocationSize' => 20,
  3000.      *     'initialValue'   => 1
  3001.      *     'quoted'         => 1
  3002.      * )
  3003.      * </code>
  3004.      *
  3005.      * @param array $definition
  3006.      *
  3007.      * @return void
  3008.      *
  3009.      * @throws MappingException
  3010.      */
  3011.     public function setSequenceGeneratorDefinition(array $definition)
  3012.     {
  3013.         if ( ! isset($definition['sequenceName']) || trim($definition['sequenceName']) === '') {
  3014.             throw MappingException::missingSequenceName($this->name);
  3015.         }
  3017.         if ($definition['sequenceName'][0] == '`') {
  3018.             $definition['sequenceName']   = trim($definition['sequenceName'], '`');
  3019.             $definition['quoted'] = true;
  3020.         }
  3022.         if ( ! isset($definition['allocationSize']) || trim($definition['allocationSize']) === '') {
  3023.             $definition['allocationSize'] = '1';
  3024.         }
  3026.         if ( ! isset($definition['initialValue']) || trim($definition['initialValue']) === '') {
  3027.             $definition['initialValue'] = '1';
  3028.         }
  3030.         $this->sequenceGeneratorDefinition = $definition;
  3031.     }
  3033.     /**
  3034.      * Sets the version field mapping used for versioning. Sets the default
  3035.      * value to use depending on the column type.
  3036.      *
  3037.      * @param array $mapping The version field mapping array.
  3038.      *
  3039.      * @return void
  3040.      *
  3041.      * @throws MappingException
  3042.      */
  3043.     public function setVersionMapping(array &$mapping)
  3044.     {
  3045.         $this->isVersioned = true;
  3046.         $this->versionField = $mapping['fieldName'];
  3048.         if ( ! isset($mapping['default'])) {
  3049.             if (in_array($mapping['type'], ['integer', 'bigint', 'smallint'])) {
  3050.                 $mapping['default'] = 1;
  3051.             } else if ($mapping['type'] == 'datetime') {
  3052.                 $mapping['default'] = 'CURRENT_TIMESTAMP';
  3053.             } else {
  3054.                 throw MappingException::unsupportedOptimisticLockingType($this->name, $mapping['fieldName'], $mapping['type']);
  3055.             }
  3056.         }
  3057.     }
  3059.     /**
  3060.      * Sets whether this class is to be versioned for optimistic locking.
  3061.      *
  3062.      * @param boolean $bool
  3063.      *
  3064.      * @return void
  3065.      */
  3066.     public function setVersioned($bool)
  3067.     {
  3068.         $this->isVersioned = $bool;
  3069.     }
  3071.     /**
  3072.      * Sets the name of the field that is to be used for versioning if this class is
  3073.      * versioned for optimistic locking.
  3074.      *
  3075.      * @param string $versionField
  3076.      *
  3077.      * @return void
  3078.      */
  3079.     public function setVersionField($versionField)
  3080.     {
  3081.         $this->versionField = $versionField;
  3082.     }
  3084.     /**
  3085.      * Marks this class as read only, no change tracking is applied to it.
  3086.      *
  3087.      * @return void
  3088.      */
  3089.     public function markReadOnly()
  3090.     {
  3091.         $this->isReadOnly = true;
  3092.     }
  3094.     /**
  3095.      * {@inheritDoc}
  3096.      */
  3097.     public function getFieldNames()
  3098.     {
  3099.         return array_keys($this->fieldMappings);
  3100.     }
  3102.     /**
  3103.      * {@inheritDoc}
  3104.      */
  3105.     public function getAssociationNames()
  3106.     {
  3107.         return array_keys($this->associationMappings);
  3108.     }
  3110.     /**
  3111.      * {@inheritDoc}
  3112.      *
  3113.      * @throws InvalidArgumentException
  3114.      */
  3115.     public function getAssociationTargetClass($assocName)
  3116.     {
  3117.         if ( ! isset($this->associationMappings[$assocName])) {
  3118.             throw new InvalidArgumentException("Association name expected, '" . $assocName ."' is not an association.");
  3119.         }
  3121.         return $this->associationMappings[$assocName]['targetEntity'];
  3122.     }
  3124.     /**
  3125.      * {@inheritDoc}
  3126.      */
  3127.     public function getName()
  3128.     {
  3129.         return $this->name;
  3130.     }
  3132.     /**
  3133.      * Gets the (possibly quoted) identifier column names for safe use in an SQL statement.
  3134.      *
  3135.      * @deprecated Deprecated since version 2.3 in favor of \Doctrine\ORM\Mapping\QuoteStrategy
  3136.      *
  3137.      * @param \Doctrine\DBAL\Platforms\AbstractPlatform $platform
  3138.      *
  3139.      * @return array
  3140.      */
  3141.     public function getQuotedIdentifierColumnNames($platform)
  3142.     {
  3143.         $quotedColumnNames = [];
  3145.         foreach ($this->identifier as $idProperty) {
  3146.             if (isset($this->fieldMappings[$idProperty])) {
  3147.                 $quotedColumnNames[] = isset($this->fieldMappings[$idProperty]['quoted'])
  3148.                     ? $platform->quoteIdentifier($this->fieldMappings[$idProperty]['columnName'])
  3149.                     : $this->fieldMappings[$idProperty]['columnName'];
  3151.                 continue;
  3152.             }
  3154.             // Association defined as Id field
  3155.             $joinColumns            = $this->associationMappings[$idProperty]['joinColumns'];
  3156.             $assocQuotedColumnNames = array_map(
  3157.                 function ($joinColumn) use ($platform) {
  3158.                     return isset($joinColumn['quoted'])
  3159.                         ? $platform->quoteIdentifier($joinColumn['name'])
  3160.                         : $joinColumn['name'];
  3161.                 },
  3162.                 $joinColumns
  3163.             );
  3165.             $quotedColumnNames = array_merge($quotedColumnNames, $assocQuotedColumnNames);
  3166.         }
  3168.         return $quotedColumnNames;
  3169.     }
  3171.     /**
  3172.      * Gets the (possibly quoted) column name of a mapped field for safe use  in an SQL statement.
  3173.      *
  3174.      * @deprecated Deprecated since version 2.3 in favor of \Doctrine\ORM\Mapping\QuoteStrategy
  3175.      *
  3176.      * @param string                                    $field
  3177.      * @param \Doctrine\DBAL\Platforms\AbstractPlatform $platform
  3178.      *
  3179.      * @return string
  3180.      */
  3181.     public function getQuotedColumnName($field, $platform)
  3182.     {
  3183.         return isset($this->fieldMappings[$field]['quoted'])
  3184.             ? $platform->quoteIdentifier($this->fieldMappings[$field]['columnName'])
  3185.             : $this->fieldMappings[$field]['columnName'];
  3186.     }
  3188.     /**
  3189.      * Gets the (possibly quoted) primary table name of this class for safe use in an SQL statement.
  3190.      *
  3191.      * @deprecated Deprecated since version 2.3 in favor of \Doctrine\ORM\Mapping\QuoteStrategy
  3192.      *
  3193.      * @param \Doctrine\DBAL\Platforms\AbstractPlatform $platform
  3194.      *
  3195.      * @return string
  3196.      */
  3197.     public function getQuotedTableName($platform)
  3198.     {
  3199.         return isset($this->table['quoted'])
  3200.             ? $platform->quoteIdentifier($this->table['name'])
  3201.             : $this->table['name'];
  3202.     }
  3204.     /**
  3205.      * Gets the (possibly quoted) name of the join table.
  3206.      *
  3207.      * @deprecated Deprecated since version 2.3 in favor of \Doctrine\ORM\Mapping\QuoteStrategy
  3208.      *
  3209.      * @param array                                     $assoc
  3210.      * @param \Doctrine\DBAL\Platforms\AbstractPlatform $platform
  3211.      *
  3212.      * @return string
  3213.      */
  3214.     public function getQuotedJoinTableName(array $assoc, $platform)
  3215.     {
  3216.         return isset($assoc['joinTable']['quoted'])
  3217.             ? $platform->quoteIdentifier($assoc['joinTable']['name'])
  3218.             : $assoc['joinTable']['name'];
  3219.     }
  3221.     /**
  3222.      * {@inheritDoc}
  3223.      */
  3224.     public function isAssociationInverseSide($fieldName)
  3225.     {
  3226.         return isset($this->associationMappings[$fieldName])
  3227.             && ! $this->associationMappings[$fieldName]['isOwningSide'];
  3228.     }
  3230.     /**
  3231.      * {@inheritDoc}
  3232.      */
  3233.     public function getAssociationMappedByTargetField($fieldName)
  3234.     {
  3235.         return $this->associationMappings[$fieldName]['mappedBy'];
  3236.     }
  3238.     /**
  3239.      * @param string $targetClass
  3240.      *
  3241.      * @return array
  3242.      */
  3243.     public function getAssociationsByTargetClass($targetClass)
  3244.     {
  3245.         $relations = [];
  3247.         foreach ($this->associationMappings as $mapping) {
  3248.             if ($mapping['targetEntity'] == $targetClass) {
  3249.                 $relations[$mapping['fieldName']] = $mapping;
  3250.             }
  3251.         }
  3253.         return $relations;
  3254.     }
  3256.     /**
  3257.      * @param  string|null $className
  3258.      *
  3259.      * @return string|null null if the input value is null
  3260.      *
  3261.      * @psalm-param ?class-string $className
  3262.      */
  3263.     public function fullyQualifiedClassName($className)
  3264.     {
  3265.         if (empty($className)) {
  3266.             return $className;
  3267.         }
  3269.         if ($className !== null && strpos($className, '\\') === false && $this->namespace) {
  3270.             return $this->namespace . '\\' . $className;
  3271.         }
  3273.         return $className;
  3274.     }
  3276.     /**
  3277.      * @param string $name
  3278.      *
  3279.      * @return mixed
  3280.      */
  3281.     public function getMetadataValue($name)
  3282.     {
  3284.         if (isset($this->$name)) {
  3285.             return $this->$name;
  3286.         }
  3288.         return null;
  3289.     }
  3291.     /**
  3292.      * Map Embedded Class
  3293.      *
  3294.      * @param array $mapping
  3295.      *
  3296.      * @throws MappingException
  3297.      * @return void
  3298.      */
  3299.     public function mapEmbedded(array $mapping)
  3300.     {
  3301.         $this->assertFieldNotMapped($mapping['fieldName']);
  3303.         $this->embeddedClasses[$mapping['fieldName']] = [
  3304.             'class' => $this->fullyQualifiedClassName($mapping['class']),
  3305.             'columnPrefix' => $mapping['columnPrefix'],
  3306.             'declaredField' => $mapping['declaredField'] ?? null,
  3307.             'originalField' => $mapping['originalField'] ?? null,
  3308.         ];
  3309.     }
  3311.     /**
  3312.      * Inline the embeddable class
  3313.      *
  3314.      * @param string            $property
  3315.      * @param ClassMetadataInfo $embeddable
  3316.      */
  3317.     public function inlineEmbeddable($property, ClassMetadataInfo $embeddable)
  3318.     {
  3319.         foreach ($embeddable->fieldMappings as $fieldMapping) {
  3320.             $fieldMapping['originalClass'] = $fieldMapping['originalClass'] ?? $embeddable->name;
  3321.             $fieldMapping['declaredField'] = isset($fieldMapping['declaredField'])
  3322.                 ? $property . '.' . $fieldMapping['declaredField']
  3323.                 : $property;
  3324.             $fieldMapping['originalField'] = $fieldMapping['originalField'] ?? $fieldMapping['fieldName'];
  3325.             $fieldMapping['fieldName'] = $property . "." . $fieldMapping['fieldName'];
  3327.             if (! empty($this->embeddedClasses[$property]['columnPrefix'])) {
  3328.                 $fieldMapping['columnName'] = $this->embeddedClasses[$property]['columnPrefix'] . $fieldMapping['columnName'];
  3329.             } elseif ($this->embeddedClasses[$property]['columnPrefix'] !== false) {
  3330.                 $fieldMapping['columnName'] = $this->namingStrategy
  3331.                     ->embeddedFieldToColumnName(
  3332.                         $property,
  3333.                         $fieldMapping['columnName'],
  3334.                         $this->reflClass->name,
  3335.                         $embeddable->reflClass->name
  3336.                     );
  3337.             }
  3339.             $this->mapField($fieldMapping);
  3340.         }
  3341.     }
  3343.     /**
  3344.      * @param string $fieldName
  3345.      * @throws MappingException
  3346.      */
  3347.     private function assertFieldNotMapped($fieldName)
  3348.     {
  3349.         if (isset($this->fieldMappings[$fieldName]) ||
  3350.             isset($this->associationMappings[$fieldName]) ||
  3351.             isset($this->embeddedClasses[$fieldName])) {
  3353.             throw MappingException::duplicateFieldMapping($this->name, $fieldName);
  3354.         }
  3355.     }
  3357.     /**
  3358.      * Gets the sequence name based on class metadata.
  3359.      *
  3360.      * @param AbstractPlatform $platform
  3361.      * @return string
  3362.      *
  3363.      * @todo Sequence names should be computed in DBAL depending on the platform
  3364.      */
  3365.     public function getSequenceName(AbstractPlatform $platform)
  3366.     {
  3367.         $sequencePrefix = $this->getSequencePrefix($platform);
  3368.         $columnName     = $this->getSingleIdentifierColumnName();
  3369.         $sequenceName   = $sequencePrefix . '_' . $columnName . '_seq';
  3371.         return $sequenceName;
  3372.     }
  3374.     /**
  3375.      * Gets the sequence name prefix based on class metadata.
  3376.      *
  3377.      * @param AbstractPlatform $platform
  3378.      * @return string
  3379.      *
  3380.      * @todo Sequence names should be computed in DBAL depending on the platform
  3381.      */
  3382.     public function getSequencePrefix(AbstractPlatform $platform)
  3383.     {
  3384.         $tableName      = $this->getTableName();
  3385.         $sequencePrefix = $tableName;
  3387.         // Prepend the schema name to the table name if there is one
  3388.         if ($schemaName = $this->getSchemaName()) {
  3389.             $sequencePrefix = $schemaName . '.' . $tableName;
  3391.             if ( ! $platform->supportsSchemas() && $platform->canEmulateSchemas()) {
  3392.                 $sequencePrefix = $schemaName . '__' . $tableName;
  3393.             }
  3394.         }
  3396.         return $sequencePrefix;
  3397.     }
  3399.     /**
  3400.      * @param array $mapping
  3401.      */
  3402.     private function assertMappingOrderBy(array $mapping)
  3403.     {
  3404.         if (isset($mapping['orderBy']) && !is_array($mapping['orderBy'])) {
  3405.             throw new InvalidArgumentException("'orderBy' is expected to be an array, not " . gettype($mapping['orderBy']));
  3406.         }
  3407.     }
  3408. }