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

Open in your IDE?
  1. <?php
  3. declare(strict_types=1);
  5. namespace Doctrine\ORM\Mapping;
  7. use BackedEnum;
  8. use BadMethodCallException;
  9. use Doctrine\DBAL\Platforms\AbstractPlatform;
  10. use Doctrine\DBAL\Types\Types;
  11. use Doctrine\Deprecations\Deprecation;
  12. use Doctrine\Instantiator\Instantiator;
  13. use Doctrine\Instantiator\InstantiatorInterface;
  14. use Doctrine\ORM\Cache\Exception\NonCacheableEntityAssociation;
  15. use Doctrine\ORM\EntityRepository;
  16. use Doctrine\ORM\Id\AbstractIdGenerator;
  17. use Doctrine\ORM\Mapping\PropertyAccessors\EmbeddablePropertyAccessor;
  18. use Doctrine\ORM\Mapping\PropertyAccessors\EnumPropertyAccessor;
  19. use Doctrine\ORM\Mapping\PropertyAccessors\PropertyAccessor;
  20. use Doctrine\ORM\Mapping\PropertyAccessors\PropertyAccessorFactory;
  21. use Doctrine\Persistence\Mapping\ClassMetadata as PersistenceClassMetadata;
  22. use Doctrine\Persistence\Mapping\ReflectionService;
  23. use InvalidArgumentException;
  24. use LogicException;
  25. use ReflectionClass;
  26. use ReflectionNamedType;
  27. use ReflectionProperty;
  28. use Stringable;
  30. use function array_column;
  31. use function array_count_values;
  32. use function array_diff;
  33. use function array_filter;
  34. use function array_flip;
  35. use function array_intersect;
  36. use function array_key_exists;
  37. use function array_keys;
  38. use function array_map;
  39. use function array_merge;
  40. use function array_pop;
  41. use function array_values;
  42. use function assert;
  43. use function class_exists;
  44. use function count;
  45. use function defined;
  46. use function enum_exists;
  47. use function explode;
  48. use function implode;
  49. use function in_array;
  50. use function interface_exists;
  51. use function is_string;
  52. use function is_subclass_of;
  53. use function ltrim;
  54. use function method_exists;
  55. use function spl_object_id;
  56. use function sprintf;
  57. use function str_contains;
  58. use function str_replace;
  59. use function strtolower;
  60. use function trait_exists;
  61. use function trim;
  63. /**
  64. * A <tt>ClassMetadata</tt> instance holds all the object-relational mapping metadata
  65. * of an entity and its associations.
  66. *
  67. * Once populated, ClassMetadata instances are usually cached in a serialized form.
  68. *
  69. * <b>IMPORTANT NOTE:</b>
  70. *
  71. * The fields of this class are only public for 2 reasons:
  72. * 1) To allow fast READ access.
  73. * 2) To drastically reduce the size of a serialized instance (private/protected members
  74. * get the whole class name, namespace inclusive, prepended to every property in
  75. * the serialized representation).
  76. *
  77. * @phpstan-type ConcreteAssociationMapping = OneToOneOwningSideMapping|OneToOneInverseSideMapping|ManyToOneAssociationMapping|OneToManyAssociationMapping|ManyToManyOwningSideMapping|ManyToManyInverseSideMapping
  78. * @template-covariant T of object
  79. * @template-implements PersistenceClassMetadata<T>
  80. */
  81. class ClassMetadata implements PersistenceClassMetadata, Stringable
  82. {
  83. use GetReflectionClassImplementation;
  85. /* The inheritance mapping types */
  86. /**
  87. * NONE means the class does not participate in an inheritance hierarchy
  88. * and therefore does not need an inheritance mapping type.
  89. */
  90. public const INHERITANCE_TYPE_NONE = 1;
  92. /**
  93. * JOINED means the class will be persisted according to the rules of
  94. * <tt>Class Table Inheritance</tt>.
  95. */
  96. public const INHERITANCE_TYPE_JOINED = 2;
  98. /**
  99. * SINGLE_TABLE means the class will be persisted according to the rules of
  100. * <tt>Single Table Inheritance</tt>.
  101. */
  102. public const INHERITANCE_TYPE_SINGLE_TABLE = 3;
  104. /* The Id generator types. */
  105. /**
  106. * AUTO means the generator type will depend on what the used platform prefers.
  107. * Offers full portability.
  108. */
  109. public const GENERATOR_TYPE_AUTO = 1;
  111. /**
  112. * SEQUENCE means a separate sequence object will be used. Platforms that do
  113. * not have native sequence support may emulate it. Full portability is currently
  114. * not guaranteed.
  115. */
  116. public const GENERATOR_TYPE_SEQUENCE = 2;
  118. /**
  119. * IDENTITY means an identity column is used for id generation. The database
  120. * will fill in the id column on insertion. Platforms that do not support
  121. * native identity columns may emulate them. Full portability is currently
  122. * not guaranteed.
  123. */
  124. public const GENERATOR_TYPE_IDENTITY = 4;
  126. /**
  127. * NONE means the class does not have a generated id. That means the class
  128. * must have a natural, manually assigned id.
  129. */
  130. public const GENERATOR_TYPE_NONE = 5;
  132. /**
  133. * CUSTOM means that customer will use own ID generator that supposedly work
  134. */
  135. public const GENERATOR_TYPE_CUSTOM = 7;
  137. /**
  138. * DEFERRED_IMPLICIT means that changes of entities are calculated at commit-time
  139. * by doing a property-by-property comparison with the original data. This will
  140. * be done for all entities that are in MANAGED state at commit-time.
  141. *
  142. * This is the default change tracking policy.
  143. */
  144. public const CHANGETRACKING_DEFERRED_IMPLICIT = 1;
  146. /**
  147. * DEFERRED_EXPLICIT means that changes of entities are calculated at commit-time
  148. * by doing a property-by-property comparison with the original data. This will
  149. * be done only for entities that were explicitly saved (through persist() or a cascade).
  150. */
  151. public const CHANGETRACKING_DEFERRED_EXPLICIT = 2;
  153. /**
  154. * Specifies that an association is to be fetched when it is first accessed.
  155. */
  156. public const FETCH_LAZY = 2;
  158. /**
  159. * Specifies that an association is to be fetched when the owner of the
  160. * association is fetched.
  161. */
  162. public const FETCH_EAGER = 3;
  164. /**
  165. * Specifies that an association is to be fetched lazy (on first access) and that
  166. * commands such as Collection#count, Collection#slice are issued directly against
  167. * the database if the collection is not yet initialized.
  168. */
  169. public const FETCH_EXTRA_LAZY = 4;
  171. /**
  172. * Identifies a one-to-one association.
  173. */
  174. public const ONE_TO_ONE = 1;
  176. /**
  177. * Identifies a many-to-one association.
  178. */
  179. public const MANY_TO_ONE = 2;
  181. /**
  182. * Identifies a one-to-many association.
  183. */
  184. public const ONE_TO_MANY = 4;
  186. /**
  187. * Identifies a many-to-many association.
  188. */
  189. public const MANY_TO_MANY = 8;
  191. /**
  192. * Combined bitmask for to-one (single-valued) associations.
  193. */
  194. public const TO_ONE = 3;
  196. /**
  197. * Combined bitmask for to-many (collection-valued) associations.
  198. */
  199. public const TO_MANY = 12;
  201. /**
  202. * ReadOnly cache can do reads, inserts and deletes, cannot perform updates or employ any locks,
  203. */
  204. public const CACHE_USAGE_READ_ONLY = 1;
  206. /**
  207. * Nonstrict Read Write Cache doesn’t employ any locks but can do inserts, update and deletes.
  208. */
  209. public const CACHE_USAGE_NONSTRICT_READ_WRITE = 2;
  211. /**
  212. * Read Write Attempts to lock the entity before update/delete.
  213. */
  214. public const CACHE_USAGE_READ_WRITE = 3;
  216. /**
  217. * The value of this column is never generated by the database.
  218. */
  219. public const GENERATED_NEVER = 0;
  221. /**
  222. * The value of this column is generated by the database on INSERT, but not on UPDATE.
  223. */
  224. public const GENERATED_INSERT = 1;
  226. /**
  227. * The value of this column is generated by the database on both INSERT and UDPATE statements.
  228. */
  229. public const GENERATED_ALWAYS = 2;
  231. /**
  232. * READ-ONLY: The namespace the entity class is contained in.
  233. *
  234. * @todo Not really needed. Usage could be localized.
  235. */
  236. public string|null $namespace = null;
  238. /**
  239. * READ-ONLY: The name of the entity class that is at the root of the mapped entity inheritance
  240. * hierarchy. If the entity is not part of a mapped inheritance hierarchy this is the same
  241. * as {@link $name}.
  242. *
  243. * @phpstan-var class-string
  244. */
  245. public string $rootEntityName;
  247. /**
  248. * READ-ONLY: The definition of custom generator. Only used for CUSTOM
  249. * generator type
  250. *
  251. * The definition has the following structure:
  252. * <code>
  253. * array(
  254. * 'class' => 'ClassName',
  255. * )
  256. * </code>
  257. *
  258. * @todo Merge with tableGeneratorDefinition into generic generatorDefinition
  259. * @var array<string, string>|null
  260. */
  261. public array|null $customGeneratorDefinition = null;
  263. /**
  264. * The name of the custom repository class used for the entity class.
  265. * (Optional).
  266. *
  267. * @phpstan-var ?class-string<EntityRepository>
  268. */
  269. public string|null $customRepositoryClassName = null;
  271. /**
  272. * READ-ONLY: Whether this class describes the mapping of a mapped superclass.
  273. */
  274. public bool $isMappedSuperclass = false;
  276. /**
  277. * READ-ONLY: Whether this class describes the mapping of an embeddable class.
  278. */
  279. public bool $isEmbeddedClass = false;
  281. /**
  282. * READ-ONLY: The names of the parent <em>entity</em> classes (ancestors), starting with the
  283. * nearest one and ending with the root entity class.
  284. *
  285. * @phpstan-var list<class-string>
  286. */
  287. public array $parentClasses = [];
  289. /**
  290. * READ-ONLY: For classes in inheritance mapping hierarchies, this field contains the names of all
  291. * <em>entity</em> subclasses of this class. These may also be abstract classes.
  292. *
  293. * This list is used, for example, to enumerate all necessary tables in JTI when querying for root
  294. * or subclass entities, or to gather all fields comprised in an entity inheritance tree.
  295. *
  296. * For classes that do not use STI/JTI, this list is empty.
  297. *
  298. * Implementation note:
  299. *
  300. * In PHP, there is no general way to discover all subclasses of a given class at runtime. For that
  301. * reason, the list of classes given in the discriminator map at the root entity is considered
  302. * authoritative. The discriminator map must contain all <em>concrete</em> classes that can
  303. * appear in the particular inheritance hierarchy tree. Since there can be no instances of abstract
  304. * entity classes, users are not required to list such classes with a discriminator value.
  305. *
  306. * The possibly remaining "gaps" for abstract entity classes are filled after the class metadata for the
  307. * root entity has been loaded.
  308. *
  309. * For subclasses of such root entities, the list can be reused/passed downwards, it only needs to
  310. * be filtered accordingly (only keep remaining subclasses)
  311. *
  312. * @phpstan-var list<class-string>
  313. */
  314. public array $subClasses = [];
  316. /**
  317. * READ-ONLY: The names of all embedded classes based on properties.
  318. *
  319. * @phpstan-var array<string, EmbeddedClassMapping>
  320. */
  321. public array $embeddedClasses = [];
  323. /**
  324. * READ-ONLY: The field names of all fields that are part of the identifier/primary key
  325. * of the mapped entity class.
  326. *
  327. * @phpstan-var list<string>
  328. */
  329. public array $identifier = [];
  331. /**
  332. * READ-ONLY: The inheritance mapping type used by the class.
  333. *
  334. * @phpstan-var self::INHERITANCE_TYPE_*
  335. */
  336. public int $inheritanceType = self::INHERITANCE_TYPE_NONE;
  338. /**
  339. * READ-ONLY: The Id generator type used by the class.
  340. *
  341. * @phpstan-var self::GENERATOR_TYPE_*
  342. */
  343. public int $generatorType = self::GENERATOR_TYPE_NONE;
  345. /**
  346. * READ-ONLY: The field mappings of the class.
  347. * Keys are field names and values are FieldMapping instances
  348. *
  349. * @var array<string, FieldMapping>
  350. */
  351. public array $fieldMappings = [];
  353. /**
  354. * READ-ONLY: An array of field names. Used to look up field names from column names.
  355. * Keys are column names and values are field names.
  356. *
  357. * @phpstan-var array<string, string>
  358. */
  359. public array $fieldNames = [];
  361. /**
  362. * READ-ONLY: A map of field names to column names. Keys are field names and values column names.
  363. * Used to look up column names from field names.
  364. * This is the reverse lookup map of $_fieldNames.
  365. *
  366. * @deprecated 3.0 Remove this.
  367. *
  368. * @var mixed[]
  369. */
  370. public array $columnNames = [];
  372. /**
  373. * READ-ONLY: The discriminator value of this class.
  374. *
  375. * <b>This does only apply to the JOINED and SINGLE_TABLE inheritance mapping strategies
  376. * where a discriminator column is used.</b>
  377. *
  378. * @see discriminatorColumn
  379. */
  380. public mixed $discriminatorValue = null;
  382. /**
  383. * READ-ONLY: The discriminator map of all mapped classes in the hierarchy.
  384. *
  385. * <b>This does only apply to the JOINED and SINGLE_TABLE inheritance mapping strategies
  386. * where a discriminator column is used.</b>
  387. *
  388. * @see discriminatorColumn
  389. *
  390. * @var array<int|string, string>
  391. *
  392. * @phpstan-var array<int|string, class-string>
  393. */
  394. public array $discriminatorMap = [];
  396. /**
  397. * READ-ONLY: The definition of the discriminator column used in JOINED and SINGLE_TABLE
  398. * inheritance mappings.
  399. */
  400. public DiscriminatorColumnMapping|null $discriminatorColumn = null;
  402. /**
  403. * READ-ONLY: The primary table definition.
  404. *
  405. * "quoted" indicates whether the table name is quoted (with backticks) or not
  406. *
  407. * @var mixed[]
  408. * @phpstan-var array{
  409. * name: string,
  410. * schema?: string,
  411. * indexes?: array,
  412. * uniqueConstraints?: array,
  413. * options?: array<string, mixed>,
  414. * quoted?: bool
  415. * }
  416. */
  417. public array $table;
  419. /**
  420. * READ-ONLY: The registered lifecycle callbacks for entities of this class.
  421. *
  422. * @phpstan-var array<string, list<string>>
  423. */
  424. public array $lifecycleCallbacks = [];
  426. /**
  427. * READ-ONLY: The registered entity listeners.
  428. *
  429. * @phpstan-var array<string, list<array{class: class-string, method: string}>>
  430. */
  431. public array $entityListeners = [];
  433. /**
  434. * READ-ONLY: The association mappings of this class.
  435. *
  436. * A join table definition has the following structure:
  437. * <pre>
  438. * array(
  439. * 'name' => <join table name>,
  440. * 'joinColumns' => array(<join column mapping from join table to source table>),
  441. * 'inverseJoinColumns' => array(<join column mapping from join table to target table>)
  442. * )
  443. * </pre>
  444. *
  445. * @phpstan-var array<string, ConcreteAssociationMapping>
  446. */
  447. public array $associationMappings = [];
  449. /**
  450. * READ-ONLY: Flag indicating whether the identifier/primary key of the class is composite.
  451. */
  452. public bool $isIdentifierComposite = false;
  454. /**
  455. * READ-ONLY: Flag indicating whether the identifier/primary key contains at least one foreign key association.
  456. *
  457. * This flag is necessary because some code blocks require special treatment of this cases.
  458. */
  459. public bool $containsForeignIdentifier = false;
  461. /**
  462. * READ-ONLY: Flag indicating whether the identifier/primary key contains at least one ENUM type.
  463. *
  464. * This flag is necessary because some code blocks require special treatment of this cases.
  465. */
  466. public bool $containsEnumIdentifier = false;
  468. /**
  469. * READ-ONLY: The ID generator used for generating IDs for this class.
  470. *
  471. * @todo Remove!
  472. */
  473. public AbstractIdGenerator $idGenerator;
  475. /**
  476. * READ-ONLY: The definition of the sequence generator of this class. Only used for the
  477. * SEQUENCE generation strategy.
  478. *
  479. * The definition has the following structure:
  480. * <code>
  481. * array(
  482. * 'sequenceName' => 'name',
  483. * 'allocationSize' => '20',
  484. * 'initialValue' => '1'
  485. * )
  486. * </code>
  487. *
  488. * @var array<string, mixed>|null
  489. * @phpstan-var array{sequenceName: string, allocationSize: string, initialValue: string, quoted?: mixed}|null
  490. * @todo Merge with tableGeneratorDefinition into generic generatorDefinition
  491. */
  492. public array|null $sequenceGeneratorDefinition = null;
  494. /**
  495. * READ-ONLY: The policy used for change-tracking on entities of this class.
  496. */
  497. public int $changeTrackingPolicy = self::CHANGETRACKING_DEFERRED_IMPLICIT;
  499. /**
  500. * READ-ONLY: A Flag indicating whether one or more columns of this class
  501. * have to be reloaded after insert / update operations.
  502. */
  503. public bool $requiresFetchAfterChange = false;
  505. /**
  506. * READ-ONLY: A flag for whether or not instances of this class are to be versioned
  507. * with optimistic locking.
  508. */
  509. public bool $isVersioned = false;
  511. /**
  512. * READ-ONLY: The name of the field which is used for versioning in optimistic locking (if any).
  513. */
  514. public string|null $versionField = null;
  516. /** @var mixed[]|null */
  517. public array|null $cache = null;
  519. /**
  520. * The ReflectionClass instance of the mapped class.
  521. *
  522. * @var ReflectionClass<T>|null
  523. */
  524. public ReflectionClass|null $reflClass = null;
  526. /**
  527. * Is this entity marked as "read-only"?
  528. *
  529. * That means it is never considered for change-tracking in the UnitOfWork. It is a very helpful performance
  530. * optimization for entities that are immutable, either in your domain or through the relation database
  531. * (coming from a view, or a history table for example).
  532. */
  533. public bool $isReadOnly = false;
  535. /**
  536. * NamingStrategy determining the default column and table names.
  537. */
  538. protected NamingStrategy $namingStrategy;
  540. /**
  541. * The ReflectionProperty instances of the mapped class.
  542. *
  543. * @deprecated Use $propertyAccessors instead.
  544. *
  545. * @var LegacyReflectionFields|array<string, ReflectionProperty>
  546. */
  547. public LegacyReflectionFields|array $reflFields = [];
  549. /** @var array<string, PropertyAccessors\PropertyAccessor> */
  550. public array $propertyAccessors = [];
  552. private InstantiatorInterface|null $instantiator = null;
  554. private readonly TypedFieldMapper $typedFieldMapper;
  556. /**
  557. * Initializes a new ClassMetadata instance that will hold the object-relational mapping
  558. * metadata of the class with the given name.
  559. *
  560. * @param string $name The name of the entity class the new instance is used for.
  561. * @phpstan-param class-string<T> $name
  562. */
  563. public function __construct(public string $name, NamingStrategy|null $namingStrategy = null, TypedFieldMapper|null $typedFieldMapper = null)
  564. {
  565. $this->rootEntityName = $name;
  566. $this->namingStrategy = $namingStrategy ?? new DefaultNamingStrategy();
  567. $this->instantiator = new Instantiator();
  568. $this->typedFieldMapper = $typedFieldMapper ?? new DefaultTypedFieldMapper();
  569. }
  571. /**
  572. * Gets the ReflectionProperties of the mapped class.
  573. *
  574. * @deprecated Use getPropertyAccessors() instead.
  575. *
  576. * @return LegacyReflectionFields|ReflectionProperty[] An array of ReflectionProperty instances.
  577. * @phpstan-return LegacyReflectionFields|array<string, ReflectionProperty>
  578. */
  579. public function getReflectionProperties(): array|LegacyReflectionFields
  580. {
  581. return $this->reflFields;
  582. }
  584. /**
  585. * Gets the ReflectionProperties of the mapped class.
  586. *
  587. * @return PropertyAccessor[] An array of PropertyAccessor instances.
  588. */
  589. public function getPropertyAccessors(): array
  590. {
  591. return $this->propertyAccessors;
  592. }
  594. /**
  595. * Gets a ReflectionProperty for a specific field of the mapped class.
  596. *
  597. * @deprecated Use getPropertyAccessor() instead.
  598. */
  599. public function getReflectionProperty(string $name): ReflectionProperty|null
  600. {
  601. return $this->reflFields[$name];
  602. }
  604. public function getPropertyAccessor(string $name): PropertyAccessor|null
  605. {
  606. return $this->propertyAccessors[$name] ?? null;
  607. }
  609. /**
  610. * @deprecated Use getPropertyAccessor() instead.
  611. *
  612. * @throws BadMethodCallException If the class has a composite identifier.
  613. */
  614. public function getSingleIdReflectionProperty(): ReflectionProperty|null
  615. {
  616. if ($this->isIdentifierComposite) {
  617. throw new BadMethodCallException('Class ' . $this->name . ' has a composite identifier.');
  618. }
  620. return $this->reflFields[$this->identifier[0]];
  621. }
  623. /** @throws BadMethodCallException If the class has a composite identifier. */
  624. public function getSingleIdPropertyAccessor(): PropertyAccessor|null
  625. {
  626. if ($this->isIdentifierComposite) {
  627. throw new BadMethodCallException('Class ' . $this->name . ' has a composite identifier.');
  628. }
  630. return $this->propertyAccessors[$this->identifier[0]];
  631. }
  633. /**
  634. * Extracts the identifier values of an entity of this class.
  635. *
  636. * For composite identifiers, the identifier values are returned as an array
  637. * with the same order as the field order in {@link identifier}.
  638. *
  639. * @return array<string, mixed>
  640. */
  641. public function getIdentifierValues(object $entity): array
  642. {
  643. if ($this->isIdentifierComposite) {
  644. $id = [];
  646. foreach ($this->identifier as $idField) {
  647. $value = $this->propertyAccessors[$idField]->getValue($entity);
  649. if ($value !== null) {
  650. $id[$idField] = $value;
  651. }
  652. }
  654. return $id;
  655. }
  657. $id = $this->identifier[0];
  658. $value = $this->propertyAccessors[$id]->getValue($entity);
  660. if ($value === null) {
  661. return [];
  662. }
  664. return [$id => $value];
  665. }
  667. /**
  668. * Populates the entity identifier of an entity.
  669. *
  670. * @phpstan-param array<string, mixed> $id
  671. *
  672. * @todo Rename to assignIdentifier()
  673. */
  674. public function setIdentifierValues(object $entity, array $id): void
  675. {
  676. foreach ($id as $idField => $idValue) {
  677. $this->propertyAccessors[$idField]->setValue($entity, $idValue);
  678. }
  679. }
  681. /**
  682. * Sets the specified field to the specified value on the given entity.
  683. */
  684. public function setFieldValue(object $entity, string $field, mixed $value): void
  685. {
  686. $this->propertyAccessors[$field]->setValue($entity, $value);
  687. }
  689. /**
  690. * Gets the specified field's value off the given entity.
  691. */
  692. public function getFieldValue(object $entity, string $field): mixed
  693. {
  694. return $this->propertyAccessors[$field]->getValue($entity);
  695. }
  697. /**
  698. * Creates a string representation of this instance.
  699. *
  700. * @return string The string representation of this instance.
  701. *
  702. * @todo Construct meaningful string representation.
  703. */
  704. public function __toString(): string
  705. {
  706. return self::class . '@' . spl_object_id($this);
  707. }
  709. /**
  710. * Determines which fields get serialized.
  711. *
  712. * It is only serialized what is necessary for best unserialization performance.
  713. * That means any metadata properties that are not set or empty or simply have
  714. * their default value are NOT serialized.
  715. *
  716. * Parts that are also NOT serialized because they can not be properly unserialized:
  717. * - reflClass (ReflectionClass)
  718. * - reflFields (ReflectionProperty array)
  719. *
  720. * @return string[] The names of all the fields that should be serialized.
  721. */
  722. public function __sleep(): array
  723. {
  724. // This metadata is always serialized/cached.
  725. $serialized = [
  726. 'associationMappings',
  727. 'columnNames', //TODO: 3.0 Remove this. Can use fieldMappings[$fieldName]['columnName']
  728. 'fieldMappings',
  729. 'fieldNames',
  730. 'embeddedClasses',
  731. 'identifier',
  732. 'isIdentifierComposite', // TODO: REMOVE
  733. 'name',
  734. 'namespace', // TODO: REMOVE
  735. 'table',
  736. 'rootEntityName',
  737. 'idGenerator', //TODO: Does not really need to be serialized. Could be moved to runtime.
  738. ];
  740. // The rest of the metadata is only serialized if necessary.
  741. if ($this->changeTrackingPolicy !== self::CHANGETRACKING_DEFERRED_IMPLICIT) {
  742. $serialized[] = 'changeTrackingPolicy';
  743. }
  745. if ($this->customRepositoryClassName) {
  746. $serialized[] = 'customRepositoryClassName';
  747. }
  749. if ($this->inheritanceType !== self::INHERITANCE_TYPE_NONE) {
  750. $serialized[] = 'inheritanceType';
  751. $serialized[] = 'discriminatorColumn';
  752. $serialized[] = 'discriminatorValue';
  753. $serialized[] = 'discriminatorMap';
  754. $serialized[] = 'parentClasses';
  755. $serialized[] = 'subClasses';
  756. }
  758. if ($this->generatorType !== self::GENERATOR_TYPE_NONE) {
  759. $serialized[] = 'generatorType';
  760. if ($this->generatorType === self::GENERATOR_TYPE_SEQUENCE) {
  761. $serialized[] = 'sequenceGeneratorDefinition';
  762. }
  763. }
  765. if ($this->isMappedSuperclass) {
  766. $serialized[] = 'isMappedSuperclass';
  767. }
  769. if ($this->isEmbeddedClass) {
  770. $serialized[] = 'isEmbeddedClass';
  771. }
  773. if ($this->containsForeignIdentifier) {
  774. $serialized[] = 'containsForeignIdentifier';
  775. }
  777. if ($this->containsEnumIdentifier) {
  778. $serialized[] = 'containsEnumIdentifier';
  779. }
  781. if ($this->isVersioned) {
  782. $serialized[] = 'isVersioned';
  783. $serialized[] = 'versionField';
  784. }
  786. if ($this->lifecycleCallbacks) {
  787. $serialized[] = 'lifecycleCallbacks';
  788. }
  790. if ($this->entityListeners) {
  791. $serialized[] = 'entityListeners';
  792. }
  794. if ($this->isReadOnly) {
  795. $serialized[] = 'isReadOnly';
  796. }
  798. if ($this->customGeneratorDefinition) {
  799. $serialized[] = 'customGeneratorDefinition';
  800. }
  802. if ($this->cache) {
  803. $serialized[] = 'cache';
  804. }
  806. if ($this->requiresFetchAfterChange) {
  807. $serialized[] = 'requiresFetchAfterChange';
  808. }
  810. return $serialized;
  811. }
  813. /**
  814. * Creates a new instance of the mapped class, without invoking the constructor.
  815. */
  816. public function newInstance(): object
  817. {
  818. return $this->instantiator->instantiate($this->name);
  819. }
  821. /**
  822. * Restores some state that can not be serialized/unserialized.
  823. */
  824. public function wakeupReflection(ReflectionService $reflService): void
  825. {
  826. // Restore ReflectionClass and properties
  827. $this->reflClass = $reflService->getClass($this->name);
  828. /** @phpstan-ignore property.deprecated */
  829. $this->reflFields = new LegacyReflectionFields($this, $reflService);
  830. $this->instantiator = $this->instantiator ?: new Instantiator();
  832. $parentAccessors = [];
  834. foreach ($this->embeddedClasses as $property => $embeddedClass) {
  835. if (isset($embeddedClass->declaredField)) {
  836. assert($embeddedClass->originalField !== null);
  837. $childAccessor = PropertyAccessorFactory::createPropertyAccessor(
  838. $this->embeddedClasses[$embeddedClass->declaredField]->class,
  839. $embeddedClass->originalField,
  840. );
  842. $parentAccessors[$property] = new EmbeddablePropertyAccessor(
  843. $parentAccessors[$embeddedClass->declaredField],
  844. $childAccessor,
  845. $this->embeddedClasses[$embeddedClass->declaredField]->class,
  846. );
  848. continue;
  849. }
  851. $accessor = PropertyAccessorFactory::createPropertyAccessor(
  852. $embeddedClass->declared ?? $this->name,
  853. $property,
  854. );
  856. $parentAccessors[$property] = $accessor;
  857. $this->propertyAccessors[$property] = $accessor;
  858. }
  860. foreach ($this->fieldMappings as $field => $mapping) {
  861. if (isset($mapping->declaredField) && isset($parentAccessors[$mapping->declaredField])) {
  862. assert($mapping->originalField !== null);
  863. assert($mapping->originalClass !== null);
  864. $accessor = PropertyAccessorFactory::createPropertyAccessor($mapping->originalClass, $mapping->originalField);
  866. if ($mapping->enumType !== null) {
  867. $accessor = new EnumPropertyAccessor(
  868. $accessor,
  869. $mapping->enumType,
  870. );
  871. }
  873. $this->propertyAccessors[$field] = new EmbeddablePropertyAccessor(
  874. $parentAccessors[$mapping->declaredField],
  875. $accessor,
  876. $mapping->originalClass,
  877. );
  878. continue;
  879. }
  881. $this->propertyAccessors[$field] = isset($mapping->declared)
  882. ? PropertyAccessorFactory::createPropertyAccessor($mapping->declared, $field)
  883. : PropertyAccessorFactory::createPropertyAccessor($this->name, $field);
  885. if ($mapping->enumType !== null) {
  886. $this->propertyAccessors[$field] = new EnumPropertyAccessor(
  887. $this->propertyAccessors[$field],
  888. $mapping->enumType,
  889. );
  890. }
  891. }
  893. foreach ($this->associationMappings as $field => $mapping) {
  894. $this->propertyAccessors[$field] = isset($mapping->declared)
  895. ? PropertyAccessorFactory::createPropertyAccessor($mapping->declared, $field)
  896. : PropertyAccessorFactory::createPropertyAccessor($this->name, $field);
  897. }
  898. }
  900. /**
  901. * Initializes a new ClassMetadata instance that will hold the object-relational mapping
  902. * metadata of the class with the given name.
  903. *
  904. * @param ReflectionService $reflService The reflection service.
  905. */
  906. public function initializeReflection(ReflectionService $reflService): void
  907. {
  908. $this->reflClass = $reflService->getClass($this->name);
  909. $this->namespace = $reflService->getClassNamespace($this->name);
  911. if ($this->reflClass) {
  912. $this->name = $this->rootEntityName = $this->reflClass->name;
  913. }
  915. $this->table['name'] = $this->namingStrategy->classToTableName($this->name);
  916. }
  918. /**
  919. * Validates Identifier.
  920. *
  921. * @throws MappingException
  922. */
  923. public function validateIdentifier(): void
  924. {
  925. if ($this->isMappedSuperclass || $this->isEmbeddedClass) {
  926. return;
  927. }
  929. // Verify & complete identifier mapping
  930. if (! $this->identifier) {
  931. throw MappingException::identifierRequired($this->name);
  932. }
  934. if ($this->usesIdGenerator() && $this->isIdentifierComposite) {
  935. throw MappingException::compositeKeyAssignedIdGeneratorRequired($this->name);
  936. }
  937. }
  939. /**
  940. * Validates association targets actually exist.
  941. *
  942. * @throws MappingException
  943. */
  944. public function validateAssociations(): void
  945. {
  946. foreach ($this->associationMappings as $mapping) {
  947. if (
  948. ! class_exists($mapping->targetEntity)
  949. && ! interface_exists($mapping->targetEntity)
  950. && ! trait_exists($mapping->targetEntity)
  951. ) {
  952. throw MappingException::invalidTargetEntityClass($mapping->targetEntity, $this->name, $mapping->fieldName);
  953. }
  954. }
  955. }
  957. /**
  958. * Validates lifecycle callbacks.
  959. *
  960. * @throws MappingException
  961. */
  962. public function validateLifecycleCallbacks(ReflectionService $reflService): void
  963. {
  964. foreach ($this->lifecycleCallbacks as $callbacks) {
  965. foreach ($callbacks as $callbackFuncName) {
  966. if (! $reflService->hasPublicMethod($this->name, $callbackFuncName)) {
  967. throw MappingException::lifecycleCallbackMethodNotFound($this->name, $callbackFuncName);
  968. }
  969. }
  970. }
  971. }
  973. /** @phpstan-param array{usage?: mixed, region?: mixed} $cache */
  974. public function enableCache(array $cache): void
  975. {
  976. if (! isset($cache['usage'])) {
  977. $cache['usage'] = self::CACHE_USAGE_READ_ONLY;
  978. }
  980. if (! isset($cache['region'])) {
  981. $cache['region'] = strtolower(str_replace('\\', '_', $this->rootEntityName));
  982. }
  984. $this->cache = $cache;
  985. }
  987. /** @phpstan-param array{usage?: int, region?: string} $cache */
  988. public function enableAssociationCache(string $fieldName, array $cache): void
  989. {
  990. $this->associationMappings[$fieldName]->cache = $this->getAssociationCacheDefaults($fieldName, $cache);
  991. }
  993. /**
  994. * @phpstan-param array{usage?: int, region?: string|null} $cache
  995. *
  996. * @return int[]|string[]
  997. * @phpstan-return array{usage: int, region: string|null}
  998. */
  999. public function getAssociationCacheDefaults(string $fieldName, array $cache): array
  1000. {
  1001. if (! isset($cache['usage'])) {
  1002. $cache['usage'] = $this->cache['usage'] ?? self::CACHE_USAGE_READ_ONLY;
  1003. }
  1005. if (! isset($cache['region'])) {
  1006. $cache['region'] = strtolower(str_replace('\\', '_', $this->rootEntityName)) . '__' . $fieldName;
  1007. }
  1009. return $cache;
  1010. }
  1012. /**
  1013. * Sets the change tracking policy used by this class.
  1014. */
  1015. public function setChangeTrackingPolicy(int $policy): void
  1016. {
  1017. $this->changeTrackingPolicy = $policy;
  1018. }
  1020. /**
  1021. * Whether the change tracking policy of this class is "deferred explicit".
  1022. */
  1023. public function isChangeTrackingDeferredExplicit(): bool
  1024. {
  1025. return $this->changeTrackingPolicy === self::CHANGETRACKING_DEFERRED_EXPLICIT;
  1026. }
  1028. /**
  1029. * Whether the change tracking policy of this class is "deferred implicit".
  1030. */
  1031. public function isChangeTrackingDeferredImplicit(): bool
  1032. {
  1033. return $this->changeTrackingPolicy === self::CHANGETRACKING_DEFERRED_IMPLICIT;
  1034. }
  1036. /**
  1037. * Checks whether a field is part of the identifier/primary key field(s).
  1038. */
  1039. public function isIdentifier(string $fieldName): bool
  1040. {
  1041. if (! $this->identifier) {
  1042. return false;
  1043. }
  1045. if (! $this->isIdentifierComposite) {
  1046. return $fieldName === $this->identifier[0];
  1047. }
  1049. return in_array($fieldName, $this->identifier, true);
  1050. }
  1052. public function isUniqueField(string $fieldName): bool
  1053. {
  1054. $mapping = $this->getFieldMapping($fieldName);
  1056. return $mapping !== false && isset($mapping->unique) && $mapping->unique;
  1057. }
  1059. public function isNullable(string $fieldName): bool
  1060. {
  1061. $mapping = $this->getFieldMapping($fieldName);
  1063. return $mapping !== false && isset($mapping->nullable) && $mapping->nullable;
  1064. }
  1066. public function isIndexed(string $fieldName): bool
  1067. {
  1068. $mapping = $this->getFieldMapping($fieldName);
  1070. return isset($mapping->index) && $mapping->index;
  1071. }
  1073. /**
  1074. * Gets a column name for a field name.
  1075. * If the column name for the field cannot be found, the given field name
  1076. * is returned.
  1077. */
  1078. public function getColumnName(string $fieldName): string
  1079. {
  1080. // @phpstan-ignore property.deprecated
  1081. return $this->columnNames[$fieldName] ?? $fieldName;
  1082. }
  1084. /**
  1085. * Gets the mapping of a (regular) field that holds some data but not a
  1086. * reference to another object.
  1087. *
  1088. * @throws MappingException
  1089. */
  1090. public function getFieldMapping(string $fieldName): FieldMapping
  1091. {
  1092. if (! isset($this->fieldMappings[$fieldName])) {
  1093. throw MappingException::mappingNotFound($this->name, $fieldName);
  1094. }
  1096. return $this->fieldMappings[$fieldName];
  1097. }
  1099. /**
  1100. * Gets the mapping of an association.
  1101. *
  1102. * @see ClassMetadata::$associationMappings
  1103. *
  1104. * @param string $fieldName The field name that represents the association in
  1105. * the object model.
  1106. *
  1107. * @throws MappingException
  1108. */
  1109. public function getAssociationMapping(string $fieldName): AssociationMapping
  1110. {
  1111. if (! isset($this->associationMappings[$fieldName])) {
  1112. throw MappingException::mappingNotFound($this->name, $fieldName);
  1113. }
  1115. return $this->associationMappings[$fieldName];
  1116. }
  1118. /**
  1119. * Gets all association mappings of the class.
  1120. *
  1121. * @phpstan-return array<string, AssociationMapping>
  1122. */
  1123. public function getAssociationMappings(): array
  1124. {
  1125. return $this->associationMappings;
  1126. }
  1128. /**
  1129. * Gets the field name for a column name.
  1130. * If no field name can be found the column name is returned.
  1131. *
  1132. * @return string The column alias.
  1133. */
  1134. public function getFieldName(string $columnName): string
  1135. {
  1136. return $this->fieldNames[$columnName] ?? $columnName;
  1137. }
  1139. /**
  1140. * Checks whether given property has type
  1141. */
  1142. private function isTypedProperty(string $name): bool
  1143. {
  1144. return isset($this->reflClass)
  1145. && $this->reflClass->hasProperty($name)
  1146. && $this->reflClass->getProperty($name)->hasType();
  1147. }
  1149. /**
  1150. * Validates & completes the given field mapping based on typed property.
  1151. *
  1152. * @param array{fieldName: string, type?: string} $mapping The field mapping to validate & complete.
  1153. *
  1154. * @return array{fieldName: string, enumType?: class-string<BackedEnum>, type?: string} The updated mapping.
  1155. */
  1156. private function validateAndCompleteTypedFieldMapping(array $mapping): array
  1157. {
  1158. $field = $this->reflClass->getProperty($mapping['fieldName']);
  1160. return $this->typedFieldMapper->validateAndComplete($mapping, $field);
  1161. }
  1163. /**
  1164. * Validates & completes the basic mapping information based on typed property.
  1165. *
  1166. * @param array{type: self::ONE_TO_ONE|self::MANY_TO_ONE|self::ONE_TO_MANY|self::MANY_TO_MANY, fieldName: string, targetEntity?: class-string} $mapping The mapping.
  1167. *
  1168. * @return mixed[] The updated mapping.
  1169. */
  1170. private function validateAndCompleteTypedAssociationMapping(array $mapping): array
  1171. {
  1172. $type = $this->reflClass->getProperty($mapping['fieldName'])->getType();
  1174. if ($type === null || ($mapping['type'] & self::TO_ONE) === 0) {
  1175. return $mapping;
  1176. }
  1178. if (! isset($mapping['targetEntity']) && $type instanceof ReflectionNamedType) {
  1179. $mapping['targetEntity'] = $type->getName();
  1180. }
  1182. return $mapping;
  1183. }
  1185. /**
  1186. * Validates & completes the given field mapping.
  1187. *
  1188. * @phpstan-param array{
  1189. * fieldName?: string,
  1190. * columnName?: string,
  1191. * id?: bool,
  1192. * generated?: self::GENERATED_*,
  1193. * enumType?: class-string,
  1194. * } $mapping The field mapping to validate & complete.
  1195. *
  1196. * @return FieldMapping The updated mapping.
  1197. *
  1198. * @throws MappingException
  1199. */
  1200. protected function validateAndCompleteFieldMapping(array $mapping): FieldMapping
  1201. {
  1202. // Check mandatory fields
  1203. if (! isset($mapping['fieldName']) || ! $mapping['fieldName']) {
  1204. throw MappingException::missingFieldName($this->name);
  1205. }
  1207. if ($this->isTypedProperty($mapping['fieldName'])) {
  1208. $mapping = $this->validateAndCompleteTypedFieldMapping($mapping);
  1209. }
  1211. if (! isset($mapping['type'])) {
  1212. // Default to string
  1213. $mapping['type'] = 'string';
  1214. }
  1216. // Complete fieldName and columnName mapping
  1217. if (! isset($mapping['columnName'])) {
  1218. $mapping['columnName'] = $this->namingStrategy->propertyToColumnName($mapping['fieldName'], $this->name);
  1219. }
  1221. $mapping = FieldMapping::fromMappingArray($mapping);
  1223. if ($mapping->columnName[0] === '`') {
  1224. $mapping->columnName = trim($mapping->columnName, '`');
  1225. $mapping->quoted = true;
  1226. }
  1228. // @phpstan-ignore property.deprecated
  1229. $this->columnNames[$mapping->fieldName] = $mapping->columnName;
  1231. if (isset($this->fieldNames[$mapping->columnName]) || ($this->discriminatorColumn && $this->discriminatorColumn->name === $mapping->columnName)) {
  1232. throw MappingException::duplicateColumnName($this->name, $mapping->columnName);
  1233. }
  1235. $this->fieldNames[$mapping->columnName] = $mapping->fieldName;
  1237. // Complete id mapping
  1238. if (isset($mapping->id) && $mapping->id === true) {
  1239. if ($this->versionField === $mapping->fieldName) {
  1240. throw MappingException::cannotVersionIdField($this->name, $mapping->fieldName);
  1241. }
  1243. if (! in_array($mapping->fieldName, $this->identifier, true)) {
  1244. $this->identifier[] = $mapping->fieldName;
  1245. }
  1247. // Check for composite key
  1248. if (! $this->isIdentifierComposite && count($this->identifier) > 1) {
  1249. $this->isIdentifierComposite = true;
  1250. }
  1251. }
  1253. if (isset($mapping->generated)) {
  1254. if (! in_array($mapping->generated, [self::GENERATED_NEVER, self::GENERATED_INSERT, self::GENERATED_ALWAYS])) {
  1255. throw MappingException::invalidGeneratedMode($mapping->generated);
  1256. }
  1258. if ($mapping->generated === self::GENERATED_NEVER) {
  1259. unset($mapping->generated);
  1260. }
  1261. }
  1263. if (isset($mapping->enumType)) {
  1264. if (! enum_exists($mapping->enumType)) {
  1265. throw MappingException::nonEnumTypeMapped($this->name, $mapping->fieldName, $mapping->enumType);
  1266. }
  1268. if (! empty($mapping->id)) {
  1269. $this->containsEnumIdentifier = true;
  1270. }
  1272. if (
  1273. defined('Doctrine\DBAL\Types\Types::ENUM')
  1274. && $mapping->type === Types::ENUM
  1275. && ! isset($mapping->options['values'])
  1276. ) {
  1277. $mapping->options['values'] = array_column($mapping->enumType::cases(), 'value');
  1278. }
  1279. }
  1281. return $mapping;
  1282. }
  1284. /**
  1285. * Validates & completes the basic mapping information that is common to all
  1286. * association mappings (one-to-one, many-ot-one, one-to-many, many-to-many).
  1287. *
  1288. * @phpstan-param array<string, mixed> $mapping The mapping.
  1289. *
  1290. * @return ConcreteAssociationMapping
  1291. *
  1292. * @throws MappingException If something is wrong with the mapping.
  1293. */
  1294. protected function _validateAndCompleteAssociationMapping(array $mapping): AssociationMapping
  1295. {
  1296. if (array_key_exists('mappedBy', $mapping) && $mapping['mappedBy'] === null) {
  1297. unset($mapping['mappedBy']);
  1298. }
  1300. if (array_key_exists('inversedBy', $mapping) && $mapping['inversedBy'] === null) {
  1301. unset($mapping['inversedBy']);
  1302. }
  1304. if (array_key_exists('joinColumns', $mapping) && in_array($mapping['joinColumns'], [null, []], true)) {
  1305. unset($mapping['joinColumns']);
  1306. }
  1308. $mapping['isOwningSide'] = true; // assume owning side until we hit mappedBy
  1310. if (empty($mapping['indexBy'])) {
  1311. unset($mapping['indexBy']);
  1312. }
  1314. // If targetEntity is unqualified, assume it is in the same namespace as
  1315. // the sourceEntity.
  1316. $mapping['sourceEntity'] = $this->name;
  1318. if ($this->isTypedProperty($mapping['fieldName'])) {
  1319. $mapping = $this->validateAndCompleteTypedAssociationMapping($mapping);
  1320. }
  1322. if (isset($mapping['targetEntity'])) {
  1323. $mapping['targetEntity'] = $this->fullyQualifiedClassName($mapping['targetEntity']);
  1324. $mapping['targetEntity'] = ltrim($mapping['targetEntity'], '\\');
  1325. }
  1327. if (($mapping['type'] & self::MANY_TO_ONE) > 0 && isset($mapping['orphanRemoval']) && $mapping['orphanRemoval']) {
  1328. throw MappingException::illegalOrphanRemoval($this->name, $mapping['fieldName']);
  1329. }
  1331. // Complete id mapping
  1332. if (isset($mapping['id']) && $mapping['id'] === true) {
  1333. if (isset($mapping['orphanRemoval']) && $mapping['orphanRemoval']) {
  1334. throw MappingException::illegalOrphanRemovalOnIdentifierAssociation($this->name, $mapping['fieldName']);
  1335. }
  1337. if (! in_array($mapping['fieldName'], $this->identifier, true)) {
  1338. if (isset($mapping['joinColumns']) && count($mapping['joinColumns']) >= 2) {
  1339. throw MappingException::cannotMapCompositePrimaryKeyEntitiesAsForeignId(
  1340. $mapping['targetEntity'],
  1341. $this->name,
  1342. $mapping['fieldName'],
  1343. );
  1344. }
  1346. assert(is_string($mapping['fieldName']));
  1347. $this->identifier[] = $mapping['fieldName'];
  1348. $this->containsForeignIdentifier = true;
  1349. }
  1351. // Check for composite key
  1352. if (! $this->isIdentifierComposite && count($this->identifier) > 1) {
  1353. $this->isIdentifierComposite = true;
  1354. }
  1356. if ($this->cache && ! isset($mapping['cache'])) {
  1357. throw NonCacheableEntityAssociation::fromEntityAndField(
  1358. $this->name,
  1359. $mapping['fieldName'],
  1360. );
  1361. }
  1362. }
  1364. // Mandatory attributes for both sides
  1365. // Mandatory: fieldName, targetEntity
  1366. if (! isset($mapping['fieldName']) || ! $mapping['fieldName']) {
  1367. throw MappingException::missingFieldName($this->name);
  1368. }
  1370. if (! isset($mapping['targetEntity'])) {
  1371. throw MappingException::missingTargetEntity($mapping['fieldName']);
  1372. }
  1374. // Mandatory and optional attributes for either side
  1375. if (! isset($mapping['mappedBy'])) {
  1376. if (isset($mapping['joinTable'])) {
  1377. if (isset($mapping['joinTable']['name']) && $mapping['joinTable']['name'][0] === '`') {
  1378. $mapping['joinTable']['name'] = trim($mapping['joinTable']['name'], '`');
  1379. $mapping['joinTable']['quoted'] = true;
  1380. }
  1381. }
  1382. } else {
  1383. $mapping['isOwningSide'] = false;
  1384. }
  1386. if (isset($mapping['id']) && $mapping['id'] === true && $mapping['type'] & self::TO_MANY) {
  1387. throw MappingException::illegalToManyIdentifierAssociation($this->name, $mapping['fieldName']);
  1388. }
  1390. // Fetch mode. Default fetch mode to LAZY, if not set.
  1391. if (! isset($mapping['fetch'])) {
  1392. $mapping['fetch'] = self::FETCH_LAZY;
  1393. }
  1395. // Cascades
  1396. $cascades = isset($mapping['cascade']) ? array_map('strtolower', $mapping['cascade']) : [];
  1398. $allCascades = ['remove', 'persist', 'refresh', 'detach'];
  1399. if (in_array('all', $cascades, true)) {
  1400. $cascades = $allCascades;
  1401. } elseif (count($cascades) !== count(array_intersect($cascades, $allCascades))) {
  1402. throw MappingException::invalidCascadeOption(
  1403. array_diff($cascades, $allCascades),
  1404. $this->name,
  1405. $mapping['fieldName'],
  1406. );
  1407. }
  1409. $mapping['cascade'] = $cascades;
  1411. switch ($mapping['type']) {
  1412. case self::ONE_TO_ONE:
  1413. if (isset($mapping['joinColumns']) && $mapping['joinColumns'] && ! $mapping['isOwningSide']) {
  1414. throw MappingException::joinColumnNotAllowedOnOneToOneInverseSide(
  1415. $this->name,
  1416. $mapping['fieldName'],
  1417. );
  1418. }
  1420. return $mapping['isOwningSide'] ?
  1421. OneToOneOwningSideMapping::fromMappingArrayAndName(
  1422. $mapping,
  1423. $this->namingStrategy,
  1424. $this->name,
  1425. $this->table ?? null,
  1426. $this->isInheritanceTypeSingleTable(),
  1427. ) :
  1428. OneToOneInverseSideMapping::fromMappingArrayAndName($mapping, $this->name);
  1430. case self::MANY_TO_ONE:
  1431. return ManyToOneAssociationMapping::fromMappingArrayAndName(
  1432. $mapping,
  1433. $this->namingStrategy,
  1434. $this->name,
  1435. $this->table ?? null,
  1436. $this->isInheritanceTypeSingleTable(),
  1437. );
  1439. case self::ONE_TO_MANY:
  1440. return OneToManyAssociationMapping::fromMappingArrayAndName($mapping, $this->name);
  1442. case self::MANY_TO_MANY:
  1443. if (isset($mapping['joinColumns'])) {
  1444. unset($mapping['joinColumns']);
  1445. }
  1447. return $mapping['isOwningSide'] ?
  1448. ManyToManyOwningSideMapping::fromMappingArrayAndNamingStrategy($mapping, $this->namingStrategy) :
  1449. ManyToManyInverseSideMapping::fromMappingArray($mapping);
  1451. default:
  1452. throw MappingException::invalidAssociationType(
  1453. $this->name,
  1454. $mapping['fieldName'],
  1455. $mapping['type'],
  1456. );
  1457. }
  1458. }
  1460. /**
  1461. * {@inheritDoc}
  1462. */
  1463. public function getIdentifierFieldNames(): array
  1464. {
  1465. return $this->identifier;
  1466. }
  1468. /**
  1469. * Gets the name of the single id field. Note that this only works on
  1470. * entity classes that have a single-field pk.
  1471. *
  1472. * @throws MappingException If the class doesn't have an identifier or it has a composite primary key.
  1473. */
  1474. public function getSingleIdentifierFieldName(): string
  1475. {
  1476. if ($this->isIdentifierComposite) {
  1477. throw MappingException::singleIdNotAllowedOnCompositePrimaryKey($this->name);
  1478. }
  1480. if (! isset($this->identifier[0])) {
  1481. throw MappingException::noIdDefined($this->name);
  1482. }
  1484. return $this->identifier[0];
  1485. }
  1487. /**
  1488. * Gets the column name of the single id column. Note that this only works on
  1489. * entity classes that have a single-field pk.
  1490. *
  1491. * @throws MappingException If the class doesn't have an identifier or it has a composite primary key.
  1492. */
  1493. public function getSingleIdentifierColumnName(): string
  1494. {
  1495. return $this->getColumnName($this->getSingleIdentifierFieldName());
  1496. }
  1498. /**
  1499. * INTERNAL:
  1500. * Sets the mapped identifier/primary key fields of this class.
  1501. * Mainly used by the ClassMetadataFactory to assign inherited identifiers.
  1502. *
  1503. * @phpstan-param list<mixed> $identifier
  1504. */
  1505. public function setIdentifier(array $identifier): void
  1506. {
  1507. $this->identifier = $identifier;
  1508. $this->isIdentifierComposite = (count($this->identifier) > 1);
  1509. }
  1511. /**
  1512. * {@inheritDoc}
  1513. */
  1514. public function getIdentifier(): array
  1515. {
  1516. return $this->identifier;
  1517. }
  1519. public function hasField(string $fieldName): bool
  1520. {
  1521. return isset($this->fieldMappings[$fieldName]) || isset($this->embeddedClasses[$fieldName]);
  1522. }
  1524. /**
  1525. * Gets an array containing all the column names.
  1526. *
  1527. * @phpstan-param list<string>|null $fieldNames
  1528. *
  1529. * @return mixed[]
  1530. * @phpstan-return list<string>
  1531. */
  1532. public function getColumnNames(array|null $fieldNames = null): array
  1533. {
  1534. if ($fieldNames === null) {
  1535. return array_keys($this->fieldNames);
  1536. }
  1538. return array_values(array_map($this->getColumnName(...), $fieldNames));
  1539. }
  1541. /**
  1542. * Returns an array with all the identifier column names.
  1543. *
  1544. * @phpstan-return list<string>
  1545. */
  1546. public function getIdentifierColumnNames(): array
  1547. {
  1548. $columnNames = [];
  1550. foreach ($this->identifier as $idProperty) {
  1551. if (isset($this->fieldMappings[$idProperty])) {
  1552. $columnNames[] = $this->fieldMappings[$idProperty]->columnName;
  1554. continue;
  1555. }
  1557. // Association defined as Id field
  1558. assert($this->associationMappings[$idProperty]->isToOneOwningSide());
  1559. $joinColumns = $this->associationMappings[$idProperty]->joinColumns;
  1560. $assocColumnNames = array_map(static fn (JoinColumnMapping $joinColumn): string => $joinColumn->name, $joinColumns);
  1562. $columnNames = array_merge($columnNames, $assocColumnNames);
  1563. }
  1565. return $columnNames;
  1566. }
  1568. /**
  1569. * Sets the type of Id generator to use for the mapped class.
  1570. *
  1571. * @phpstan-param self::GENERATOR_TYPE_* $generatorType
  1572. */
  1573. public function setIdGeneratorType(int $generatorType): void
  1574. {
  1575. $this->generatorType = $generatorType;
  1576. }
  1578. /**
  1579. * Checks whether the mapped class uses an Id generator.
  1580. */
  1581. public function usesIdGenerator(): bool
  1582. {
  1583. return $this->generatorType !== self::GENERATOR_TYPE_NONE;
  1584. }
  1586. public function isInheritanceTypeNone(): bool
  1587. {
  1588. return $this->inheritanceType === self::INHERITANCE_TYPE_NONE;
  1589. }
  1591. /**
  1592. * Checks whether the mapped class uses the JOINED inheritance mapping strategy.
  1593. *
  1594. * @return bool TRUE if the class participates in a JOINED inheritance mapping,
  1595. * FALSE otherwise.
  1596. */
  1597. public function isInheritanceTypeJoined(): bool
  1598. {
  1599. return $this->inheritanceType === self::INHERITANCE_TYPE_JOINED;
  1600. }
  1602. /**
  1603. * Checks whether the mapped class uses the SINGLE_TABLE inheritance mapping strategy.
  1604. *
  1605. * @return bool TRUE if the class participates in a SINGLE_TABLE inheritance mapping,
  1606. * FALSE otherwise.
  1607. */
  1608. public function isInheritanceTypeSingleTable(): bool
  1609. {
  1610. return $this->inheritanceType === self::INHERITANCE_TYPE_SINGLE_TABLE;
  1611. }
  1613. /**
  1614. * Checks whether the class uses an identity column for the Id generation.
  1615. */
  1616. public function isIdGeneratorIdentity(): bool
  1617. {
  1618. return $this->generatorType === self::GENERATOR_TYPE_IDENTITY;
  1619. }
  1621. /**
  1622. * Checks whether the class uses a sequence for id generation.
  1623. *
  1624. * @phpstan-assert-if-true !null $this->sequenceGeneratorDefinition
  1625. */
  1626. public function isIdGeneratorSequence(): bool
  1627. {
  1628. return $this->generatorType === self::GENERATOR_TYPE_SEQUENCE;
  1629. }
  1631. /**
  1632. * Checks whether the class has a natural identifier/pk (which means it does
  1633. * not use any Id generator.
  1634. */
  1635. public function isIdentifierNatural(): bool
  1636. {
  1637. return $this->generatorType === self::GENERATOR_TYPE_NONE;
  1638. }
  1640. /**
  1641. * Gets the type of a field.
  1642. *
  1643. * @todo 3.0 Remove this. PersisterHelper should fix it somehow
  1644. */
  1645. public function getTypeOfField(string $fieldName): string|null
  1646. {
  1647. return isset($this->fieldMappings[$fieldName])
  1648. ? $this->fieldMappings[$fieldName]->type
  1649. : null;
  1650. }
  1652. /**
  1653. * Gets the name of the primary table.
  1654. */
  1655. public function getTableName(): string
  1656. {
  1657. return $this->table['name'];
  1658. }
  1660. /**
  1661. * Gets primary table's schema name.
  1662. */
  1663. public function getSchemaName(): string|null
  1664. {
  1665. return $this->table['schema'] ?? null;
  1666. }
  1668. /**
  1669. * Gets the table name to use for temporary identifier tables of this class.
  1670. */
  1671. public function getTemporaryIdTableName(): string
  1672. {
  1673. // replace dots with underscores because PostgreSQL creates temporary tables in a special schema
  1674. return str_replace('.', '_', $this->getTableName() . '_id_tmp');
  1675. }
  1677. /**
  1678. * Sets the mapped subclasses of this class.
  1679. *
  1680. * @phpstan-param list<string> $subclasses The names of all mapped subclasses.
  1681. */
  1682. public function setSubclasses(array $subclasses): void
  1683. {
  1684. foreach ($subclasses as $subclass) {
  1685. $this->subClasses[] = $this->fullyQualifiedClassName($subclass);
  1686. }
  1687. }
  1689. /**
  1690. * Sets the parent class names. Only <em>entity</em> classes may be given.
  1691. *
  1692. * Assumes that the class names in the passed array are in the order:
  1693. * directParent -> directParentParent -> directParentParentParent ... -> root.
  1694. *
  1695. * @phpstan-param list<class-string> $classNames
  1696. */
  1697. public function setParentClasses(array $classNames): void
  1698. {
  1699. $this->parentClasses = $classNames;
  1701. if (count($classNames) > 0) {
  1702. $this->rootEntityName = array_pop($classNames);
  1703. }
  1704. }
  1706. /**
  1707. * Sets the inheritance type used by the class and its subclasses.
  1708. *
  1709. * @phpstan-param self::INHERITANCE_TYPE_* $type
  1710. *
  1711. * @throws MappingException
  1712. */
  1713. public function setInheritanceType(int $type): void
  1714. {
  1715. if (! $this->isInheritanceType($type)) {
  1716. throw MappingException::invalidInheritanceType($this->name, $type);
  1717. }
  1719. $this->inheritanceType = $type;
  1720. }
  1722. /**
  1723. * Sets the association to override association mapping of property for an entity relationship.
  1724. *
  1725. * @phpstan-param array{joinColumns?: array, inversedBy?: ?string, joinTable?: array, fetch?: ?string, cascade?: string[]} $overrideMapping
  1726. *
  1727. * @throws MappingException
  1728. */
  1729. public function setAssociationOverride(string $fieldName, array $overrideMapping): void
  1730. {
  1731. if (! isset($this->associationMappings[$fieldName])) {
  1732. throw MappingException::invalidOverrideFieldName($this->name, $fieldName);
  1733. }
  1735. $mapping = $this->associationMappings[$fieldName]->toArray();
  1737. if (isset($mapping['inherited'])) {
  1738. throw MappingException::illegalOverrideOfInheritedProperty(
  1739. $this->name,
  1740. $fieldName,
  1741. $mapping['inherited'],
  1742. );
  1743. }
  1745. if (isset($overrideMapping['joinColumns'])) {
  1746. $mapping['joinColumns'] = $overrideMapping['joinColumns'];
  1747. }
  1749. if (isset($overrideMapping['inversedBy'])) {
  1750. $mapping['inversedBy'] = $overrideMapping['inversedBy'];
  1751. }
  1753. if (isset($overrideMapping['joinTable'])) {
  1754. $mapping['joinTable'] = $overrideMapping['joinTable'];
  1755. }
  1757. if (isset($overrideMapping['fetch'])) {
  1758. $mapping['fetch'] = $overrideMapping['fetch'];
  1759. }
  1761. if (isset($overrideMapping['cascade'])) {
  1762. $mapping['cascade'] = $overrideMapping['cascade'];
  1763. }
  1765. switch ($mapping['type']) {
  1766. case self::ONE_TO_ONE:
  1767. case self::MANY_TO_ONE:
  1768. $mapping['joinColumnFieldNames'] = [];
  1769. $mapping['sourceToTargetKeyColumns'] = [];
  1770. break;
  1771. case self::MANY_TO_MANY:
  1772. $mapping['relationToSourceKeyColumns'] = [];
  1773. $mapping['relationToTargetKeyColumns'] = [];
  1774. break;
  1775. }
  1777. $this->associationMappings[$fieldName] = $this->_validateAndCompleteAssociationMapping($mapping);
  1778. }
  1780. /**
  1781. * Sets the override for a mapped field.
  1782. *
  1783. * @phpstan-param array<string, mixed> $overrideMapping
  1784. *
  1785. * @throws MappingException
  1786. */
  1787. public function setAttributeOverride(string $fieldName, array $overrideMapping): void
  1788. {
  1789. if (! isset($this->fieldMappings[$fieldName])) {
  1790. throw MappingException::invalidOverrideFieldName($this->name, $fieldName);
  1791. }
  1793. $mapping = $this->fieldMappings[$fieldName];
  1795. if (isset($mapping->inherited)) {
  1796. throw MappingException::illegalOverrideOfInheritedProperty($this->name, $fieldName, $mapping->inherited);
  1797. }
  1799. if (isset($mapping->id)) {
  1800. $overrideMapping['id'] = $mapping->id;
  1801. }
  1803. if (isset($mapping->declared)) {
  1804. $overrideMapping['declared'] = $mapping->declared;
  1805. }
  1807. if (! isset($overrideMapping['type'])) {
  1808. $overrideMapping['type'] = $mapping->type;
  1809. }
  1811. if (! isset($overrideMapping['fieldName'])) {
  1812. $overrideMapping['fieldName'] = $mapping->fieldName;
  1813. }
  1815. if ($overrideMapping['type'] !== $mapping->type) {
  1816. throw MappingException::invalidOverrideFieldType($this->name, $fieldName);
  1817. }
  1819. unset($this->fieldMappings[$fieldName]);
  1820. unset($this->fieldNames[$mapping->columnName]);
  1821. // @phpstan-ignore property.deprecated
  1822. unset($this->columnNames[$mapping->fieldName]);
  1824. $overrideMapping = $this->validateAndCompleteFieldMapping($overrideMapping);
  1826. $this->fieldMappings[$fieldName] = $overrideMapping;
  1827. }
  1829. /**
  1830. * Checks whether a mapped field is inherited from an entity superclass.
  1831. */
  1832. public function isInheritedField(string $fieldName): bool
  1833. {
  1834. return isset($this->fieldMappings[$fieldName]->inherited);
  1835. }
  1837. /**
  1838. * Checks if this entity is the root in any entity-inheritance-hierarchy.
  1839. */
  1840. public function isRootEntity(): bool
  1841. {
  1842. return $this->name === $this->rootEntityName;
  1843. }
  1845. /**
  1846. * Checks whether a mapped association field is inherited from a superclass.
  1847. */
  1848. public function isInheritedAssociation(string $fieldName): bool
  1849. {
  1850. return isset($this->associationMappings[$fieldName]->inherited);
  1851. }
  1853. public function isInheritedEmbeddedClass(string $fieldName): bool
  1854. {
  1855. return isset($this->embeddedClasses[$fieldName]->inherited);
  1856. }
  1858. /**
  1859. * Sets the name of the primary table the class is mapped to.
  1860. *
  1861. * @deprecated Use {@link setPrimaryTable}.
  1862. */
  1863. public function setTableName(string $tableName): void
  1864. {
  1865. $this->table['name'] = $tableName;
  1866. }
  1868. /**
  1869. * Sets the primary table definition. The provided array supports the
  1870. * following structure:
  1871. *
  1872. * name => <tableName> (optional, defaults to class name)
  1873. * indexes => array of indexes (optional)
  1874. * uniqueConstraints => array of constraints (optional)
  1875. *
  1876. * If a key is omitted, the current value is kept.
  1877. *
  1878. * @phpstan-param array<string, mixed> $table The table description.
  1879. */
  1880. public function setPrimaryTable(array $table): void
  1881. {
  1882. if (isset($table['name'])) {
  1883. // Split schema and table name from a table name like "myschema.mytable"
  1884. if (str_contains($table['name'], '.')) {
  1885. [$this->table['schema'], $table['name']] = explode('.', $table['name'], 2);
  1886. }
  1888. if ($table['name'][0] === '`') {
  1889. $table['name'] = trim($table['name'], '`');
  1890. $this->table['quoted'] = true;
  1891. }
  1893. $this->table['name'] = $table['name'];
  1894. }
  1896. if (isset($table['quoted'])) {
  1897. $this->table['quoted'] = $table['quoted'];
  1898. }
  1900. if (isset($table['schema'])) {
  1901. $this->table['schema'] = $table['schema'];
  1902. }
  1904. if (isset($table['indexes'])) {
  1905. $this->table['indexes'] = $table['indexes'];
  1906. }
  1908. if (isset($table['uniqueConstraints'])) {
  1909. $this->table['uniqueConstraints'] = $table['uniqueConstraints'];
  1910. }
  1912. if (isset($table['options'])) {
  1913. $this->table['options'] = $table['options'];
  1914. }
  1915. }
  1917. /**
  1918. * Checks whether the given type identifies an inheritance type.
  1919. */
  1920. private function isInheritanceType(int $type): bool
  1921. {
  1922. return $type === self::INHERITANCE_TYPE_NONE ||
  1923. $type === self::INHERITANCE_TYPE_SINGLE_TABLE ||
  1924. $type === self::INHERITANCE_TYPE_JOINED;
  1925. }
  1927. /**
  1928. * Adds a mapped field to the class.
  1929. *
  1930. * @phpstan-param array<string, mixed> $mapping The field mapping.
  1931. *
  1932. * @throws MappingException
  1933. */
  1934. public function mapField(array $mapping): void
  1935. {
  1936. $mapping = $this->validateAndCompleteFieldMapping($mapping);
  1937. $this->assertFieldNotMapped($mapping->fieldName);
  1939. if (isset($mapping->generated)) {
  1940. $this->requiresFetchAfterChange = true;
  1941. }
  1943. $this->fieldMappings[$mapping->fieldName] = $mapping;
  1944. }
  1946. /**
  1947. * INTERNAL:
  1948. * Adds an association mapping without completing/validating it.
  1949. * This is mainly used to add inherited association mappings to derived classes.
  1950. *
  1951. * @param ConcreteAssociationMapping $mapping
  1952. *
  1953. * @throws MappingException
  1954. */
  1955. public function addInheritedAssociationMapping(AssociationMapping $mapping/*, $owningClassName = null*/): void
  1956. {
  1957. if (isset($this->associationMappings[$mapping->fieldName])) {
  1958. throw MappingException::duplicateAssociationMapping($this->name, $mapping->fieldName);
  1959. }
  1961. $this->associationMappings[$mapping->fieldName] = $mapping;
  1962. }
  1964. /**
  1965. * INTERNAL:
  1966. * Adds a field mapping without completing/validating it.
  1967. * This is mainly used to add inherited field mappings to derived classes.
  1968. */
  1969. public function addInheritedFieldMapping(FieldMapping $fieldMapping): void
  1970. {
  1971. $this->fieldMappings[$fieldMapping->fieldName] = $fieldMapping;
  1972. // @phpstan-ignore property.deprecated
  1973. $this->columnNames[$fieldMapping->fieldName] = $fieldMapping->columnName;
  1974. $this->fieldNames[$fieldMapping->columnName] = $fieldMapping->fieldName;
  1976. if (isset($fieldMapping->generated)) {
  1977. $this->requiresFetchAfterChange = true;
  1978. }
  1979. }
  1981. /**
  1982. * Adds a one-to-one mapping.
  1983. *
  1984. * @param array<string, mixed> $mapping The mapping.
  1985. */
  1986. public function mapOneToOne(array $mapping): void
  1987. {
  1988. $mapping['type'] = self::ONE_TO_ONE;
  1990. $mapping = $this->_validateAndCompleteAssociationMapping($mapping);
  1992. $this->_storeAssociationMapping($mapping);
  1993. }
  1995. /**
  1996. * Adds a one-to-many mapping.
  1997. *
  1998. * @phpstan-param array<string, mixed> $mapping The mapping.
  1999. */
  2000. public function mapOneToMany(array $mapping): void
  2001. {
  2002. $mapping['type'] = self::ONE_TO_MANY;
  2004. $mapping = $this->_validateAndCompleteAssociationMapping($mapping);
  2006. $this->_storeAssociationMapping($mapping);
  2007. }
  2009. /**
  2010. * Adds a many-to-one mapping.
  2011. *
  2012. * @phpstan-param array<string, mixed> $mapping The mapping.
  2013. */
  2014. public function mapManyToOne(array $mapping): void
  2015. {
  2016. $mapping['type'] = self::MANY_TO_ONE;
  2018. $mapping = $this->_validateAndCompleteAssociationMapping($mapping);
  2020. $this->_storeAssociationMapping($mapping);
  2021. }
  2023. /**
  2024. * Adds a many-to-many mapping.
  2025. *
  2026. * @phpstan-param array<string, mixed> $mapping The mapping.
  2027. */
  2028. public function mapManyToMany(array $mapping): void
  2029. {
  2030. $mapping['type'] = self::MANY_TO_MANY;
  2032. $mapping = $this->_validateAndCompleteAssociationMapping($mapping);
  2034. $this->_storeAssociationMapping($mapping);
  2035. }
  2037. /**
  2038. * Stores the association mapping.
  2039. *
  2040. * @param ConcreteAssociationMapping $assocMapping
  2041. *
  2042. * @throws MappingException
  2043. */
  2044. protected function _storeAssociationMapping(AssociationMapping $assocMapping): void
  2045. {
  2046. $sourceFieldName = $assocMapping->fieldName;
  2048. $this->assertFieldNotMapped($sourceFieldName);
  2050. $this->associationMappings[$sourceFieldName] = $assocMapping;
  2051. }
  2053. /**
  2054. * Registers a custom repository class for the entity class.
  2055. *
  2056. * @param string|null $repositoryClassName The class name of the custom mapper.
  2057. * @phpstan-param class-string<EntityRepository>|null $repositoryClassName
  2058. */
  2059. public function setCustomRepositoryClass(string|null $repositoryClassName): void
  2060. {
  2061. if ($repositoryClassName === null) {
  2062. $this->customRepositoryClassName = null;
  2064. return;
  2065. }
  2067. $this->customRepositoryClassName = $this->fullyQualifiedClassName($repositoryClassName);
  2068. }
  2070. /**
  2071. * Dispatches the lifecycle event of the given entity to the registered
  2072. * lifecycle callbacks and lifecycle listeners.
  2073. *
  2074. * @deprecated Deprecated since version 2.4 in favor of \Doctrine\ORM\Event\ListenersInvoker
  2075. *
  2076. * @param string $lifecycleEvent The lifecycle event.
  2077. */
  2078. public function invokeLifecycleCallbacks(string $lifecycleEvent, object $entity): void
  2079. {
  2080. foreach ($this->lifecycleCallbacks[$lifecycleEvent] as $callback) {
  2081. $entity->$callback();
  2082. }
  2083. }
  2085. /**
  2086. * Whether the class has any attached lifecycle listeners or callbacks for a lifecycle event.
  2087. */
  2088. public function hasLifecycleCallbacks(string $lifecycleEvent): bool
  2089. {
  2090. return isset($this->lifecycleCallbacks[$lifecycleEvent]);
  2091. }
  2093. /**
  2094. * Gets the registered lifecycle callbacks for an event.
  2095. *
  2096. * @return string[]
  2097. * @phpstan-return list<string>
  2098. */
  2099. public function getLifecycleCallbacks(string $event): array
  2100. {
  2101. return $this->lifecycleCallbacks[$event] ?? [];
  2102. }
  2104. /**
  2105. * Adds a lifecycle callback for entities of this class.
  2106. */
  2107. public function addLifecycleCallback(string $callback, string $event): void
  2108. {
  2109. if ($this->isEmbeddedClass) {
  2110. throw MappingException::illegalLifecycleCallbackOnEmbeddedClass($callback, $this->name);
  2111. }
  2113. if (isset($this->lifecycleCallbacks[$event]) && in_array($callback, $this->lifecycleCallbacks[$event], true)) {
  2114. return;
  2115. }
  2117. $this->lifecycleCallbacks[$event][] = $callback;
  2118. }
  2120. /**
  2121. * Sets the lifecycle callbacks for entities of this class.
  2122. * Any previously registered callbacks are overwritten.
  2123. *
  2124. * @phpstan-param array<string, list<string>> $callbacks
  2125. */
  2126. public function setLifecycleCallbacks(array $callbacks): void
  2127. {
  2128. $this->lifecycleCallbacks = $callbacks;
  2129. }
  2131. /**
  2132. * Adds a entity listener for entities of this class.
  2133. *
  2134. * @param string $eventName The entity lifecycle event.
  2135. * @param string $class The listener class.
  2136. * @param string $method The listener callback method.
  2137. *
  2138. * @throws MappingException
  2139. */
  2140. public function addEntityListener(string $eventName, string $class, string $method): void
  2141. {
  2142. $class = $this->fullyQualifiedClassName($class);
  2144. $listener = [
  2145. 'class' => $class,
  2146. 'method' => $method,
  2147. ];
  2149. if (! class_exists($class)) {
  2150. throw MappingException::entityListenerClassNotFound($class, $this->name);
  2151. }
  2153. if (! method_exists($class, $method)) {
  2154. throw MappingException::entityListenerMethodNotFound($class, $method, $this->name);
  2155. }
  2157. if (isset($this->entityListeners[$eventName]) && in_array($listener, $this->entityListeners[$eventName], true)) {
  2158. throw MappingException::duplicateEntityListener($class, $method, $this->name);
  2159. }
  2161. $this->entityListeners[$eventName][] = $listener;
  2162. }
  2164. /**
  2165. * Sets the discriminator column definition.
  2166. *
  2167. * @see getDiscriminatorColumn()
  2168. *
  2169. * @param DiscriminatorColumnMapping|mixed[]|null $columnDef
  2170. * @phpstan-param DiscriminatorColumnMapping|array{
  2171. * name: string|null,
  2172. * fieldName?: string|null,
  2173. * type?: string|null,
  2174. * length?: int|null,
  2175. * columnDefinition?: string|null,
  2176. * enumType?: class-string<BackedEnum>|null,
  2177. * options?: array<string, mixed>|null
  2178. * }|null $columnDef
  2179. *
  2180. * @throws MappingException
  2181. */
  2182. public function setDiscriminatorColumn(DiscriminatorColumnMapping|array|null $columnDef): void
  2183. {
  2184. if ($columnDef instanceof DiscriminatorColumnMapping) {
  2185. $this->discriminatorColumn = $columnDef;
  2187. return;
  2188. }
  2190. if ($columnDef !== null) {
  2191. if (! isset($columnDef['name'])) {
  2192. throw MappingException::nameIsMandatoryForDiscriminatorColumns($this->name);
  2193. }
  2195. if (isset($this->fieldNames[$columnDef['name']])) {
  2196. throw MappingException::duplicateColumnName($this->name, $columnDef['name']);
  2197. }
  2199. $columnDef['fieldName'] ??= $columnDef['name'];
  2200. $columnDef['type'] ??= 'string';
  2201. $columnDef['options'] ??= [];
  2203. if (in_array($columnDef['type'], ['boolean', 'array', 'object', 'datetime', 'time', 'date'], true)) {
  2204. throw MappingException::invalidDiscriminatorColumnType($this->name, $columnDef['type']);
  2205. }
  2207. $this->discriminatorColumn = DiscriminatorColumnMapping::fromMappingArray($columnDef);
  2208. }
  2209. }
  2211. final public function getDiscriminatorColumn(): DiscriminatorColumnMapping
  2212. {
  2213. if ($this->discriminatorColumn === null) {
  2214. throw new LogicException('The discriminator column was not set.');
  2215. }
  2217. return $this->discriminatorColumn;
  2218. }
  2220. /**
  2221. * Sets the discriminator values used by this class.
  2222. * Used for JOINED and SINGLE_TABLE inheritance mapping strategies.
  2223. *
  2224. * @param array<int|string, string> $map
  2225. */
  2226. public function setDiscriminatorMap(array $map): void
  2227. {
  2228. if (count(array_flip($map)) !== count($map)) {
  2229. Deprecation::trigger(
  2230. 'doctrine/orm',
  2231. 'https://github.com/doctrine/orm/issues/3519',
  2232. <<<'DEPRECATION'
  2233. Mapping a class to multiple discriminator values is deprecated,
  2234. and the discriminator mapping of %s contains duplicate values
  2235. for the following discriminator values: %s.
  2236. DEPRECATION,
  2237. $this->name,
  2238. implode(', ', array_keys(array_filter(array_count_values($map), static function (int $value): bool {
  2239. return $value > 1;
  2240. }))),
  2241. );
  2242. }
  2244. foreach ($map as $value => $className) {
  2245. $this->addDiscriminatorMapClass($value, $className);
  2246. }
  2247. }
  2249. /**
  2250. * Adds one entry of the discriminator map with a new class and corresponding name.
  2251. *
  2252. * @throws MappingException
  2253. */
  2254. public function addDiscriminatorMapClass(int|string $name, string $className): void
  2255. {
  2256. $className = $this->fullyQualifiedClassName($className);
  2257. $className = ltrim($className, '\\');
  2259. $this->discriminatorMap[$name] = $className;
  2261. if ($this->name === $className) {
  2262. $this->discriminatorValue = $name;
  2264. return;
  2265. }
  2267. if (! (class_exists($className) || interface_exists($className))) {
  2268. throw MappingException::invalidClassInDiscriminatorMap($className, $this->name);
  2269. }
  2271. $this->addSubClass($className);
  2272. }
  2274. /** @param array<class-string> $classes */
  2275. public function addSubClasses(array $classes): void
  2276. {
  2277. foreach ($classes as $className) {
  2278. $this->addSubClass($className);
  2279. }
  2280. }
  2282. public function addSubClass(string $className): void
  2283. {
  2284. // By ignoring classes that are not subclasses of the current class, we simplify inheriting
  2285. // the subclass list from a parent class at the beginning of \Doctrine\ORM\Mapping\ClassMetadataFactory::doLoadMetadata.
  2287. if (is_subclass_of($className, $this->name) && ! in_array($className, $this->subClasses, true)) {
  2288. $this->subClasses[] = $className;
  2289. }
  2290. }
  2292. public function hasAssociation(string $fieldName): bool
  2293. {
  2294. return isset($this->associationMappings[$fieldName]);
  2295. }
  2297. public function isSingleValuedAssociation(string $fieldName): bool
  2298. {
  2299. return isset($this->associationMappings[$fieldName])
  2300. && ($this->associationMappings[$fieldName]->isToOne());
  2301. }
  2303. public function isCollectionValuedAssociation(string $fieldName): bool
  2304. {
  2305. return isset($this->associationMappings[$fieldName])
  2306. && ! $this->associationMappings[$fieldName]->isToOne();
  2307. }
  2309. /**
  2310. * Is this an association that only has a single join column?
  2311. */
  2312. public function isAssociationWithSingleJoinColumn(string $fieldName): bool
  2313. {
  2314. return isset($this->associationMappings[$fieldName])
  2315. && isset($this->associationMappings[$fieldName]->joinColumns[0])
  2316. && ! isset($this->associationMappings[$fieldName]->joinColumns[1]);
  2317. }
  2319. /**
  2320. * Returns the single association join column (if any).
  2321. *
  2322. * @throws MappingException
  2323. */
  2324. public function getSingleAssociationJoinColumnName(string $fieldName): string
  2325. {
  2326. if (! $this->isAssociationWithSingleJoinColumn($fieldName)) {
  2327. throw MappingException::noSingleAssociationJoinColumnFound($this->name, $fieldName);
  2328. }
  2330. $assoc = $this->associationMappings[$fieldName];
  2332. assert($assoc->isToOneOwningSide());
  2334. return $assoc->joinColumns[0]->name;
  2335. }
  2337. /**
  2338. * Returns the single association referenced join column name (if any).
  2339. *
  2340. * @throws MappingException
  2341. */
  2342. public function getSingleAssociationReferencedJoinColumnName(string $fieldName): string
  2343. {
  2344. if (! $this->isAssociationWithSingleJoinColumn($fieldName)) {
  2345. throw MappingException::noSingleAssociationJoinColumnFound($this->name, $fieldName);
  2346. }
  2348. $assoc = $this->associationMappings[$fieldName];
  2350. assert($assoc->isToOneOwningSide());
  2352. return $assoc->joinColumns[0]->referencedColumnName;
  2353. }
  2355. /**
  2356. * Used to retrieve a fieldname for either field or association from a given column.
  2357. *
  2358. * This method is used in foreign-key as primary-key contexts.
  2359. *
  2360. * @throws MappingException
  2361. */
  2362. public function getFieldForColumn(string $columnName): string
  2363. {
  2364. if (isset($this->fieldNames[$columnName])) {
  2365. return $this->fieldNames[$columnName];
  2366. }
  2368. foreach ($this->associationMappings as $assocName => $mapping) {
  2369. if (
  2370. $this->isAssociationWithSingleJoinColumn($assocName) &&
  2371. assert($this->associationMappings[$assocName]->isToOneOwningSide()) &&
  2372. $this->associationMappings[$assocName]->joinColumns[0]->name === $columnName
  2373. ) {
  2374. return $assocName;
  2375. }
  2376. }
  2378. throw MappingException::noFieldNameFoundForColumn($this->name, $columnName);
  2379. }
  2381. /**
  2382. * Sets the ID generator used to generate IDs for instances of this class.
  2383. */
  2384. public function setIdGenerator(AbstractIdGenerator $generator): void
  2385. {
  2386. $this->idGenerator = $generator;
  2387. }
  2389. /**
  2390. * Sets definition.
  2391. *
  2392. * @phpstan-param array<string, string|null> $definition
  2393. */
  2394. public function setCustomGeneratorDefinition(array $definition): void
  2395. {
  2396. $this->customGeneratorDefinition = $definition;
  2397. }
  2399. /**
  2400. * Sets the definition of the sequence ID generator for this class.
  2401. *
  2402. * The definition must have the following structure:
  2403. * <code>
  2404. * array(
  2405. * 'sequenceName' => 'name',
  2406. * 'allocationSize' => 20,
  2407. * 'initialValue' => 1
  2408. * 'quoted' => 1
  2409. * )
  2410. * </code>
  2411. *
  2412. * @phpstan-param array{sequenceName?: string, allocationSize?: int|string, initialValue?: int|string, quoted?: mixed} $definition
  2413. *
  2414. * @throws MappingException
  2415. */
  2416. public function setSequenceGeneratorDefinition(array $definition): void
  2417. {
  2418. if (! isset($definition['sequenceName']) || trim($definition['sequenceName']) === '') {
  2419. throw MappingException::missingSequenceName($this->name);
  2420. }
  2422. if ($definition['sequenceName'][0] === '`') {
  2423. $definition['sequenceName'] = trim($definition['sequenceName'], '`');
  2424. $definition['quoted'] = true;
  2425. }
  2427. if (! isset($definition['allocationSize']) || trim((string) $definition['allocationSize']) === '') {
  2428. $definition['allocationSize'] = '1';
  2429. }
  2431. if (! isset($definition['initialValue']) || trim((string) $definition['initialValue']) === '') {
  2432. $definition['initialValue'] = '1';
  2433. }
  2435. $definition['allocationSize'] = (string) $definition['allocationSize'];
  2436. $definition['initialValue'] = (string) $definition['initialValue'];
  2438. $this->sequenceGeneratorDefinition = $definition;
  2439. }
  2441. /**
  2442. * Sets the version field mapping used for versioning. Sets the default
  2443. * value to use depending on the column type.
  2444. *
  2445. * @phpstan-param array<string, mixed> $mapping The version field mapping array.
  2446. *
  2447. * @throws MappingException
  2448. */
  2449. public function setVersionMapping(array &$mapping): void
  2450. {
  2451. $this->isVersioned = true;
  2452. $this->versionField = $mapping['fieldName'];
  2453. $this->requiresFetchAfterChange = true;
  2455. if (! isset($mapping['default'])) {
  2456. if (in_array($mapping['type'], ['integer', 'bigint', 'smallint'], true)) {
  2457. $mapping['default'] = 1;
  2458. } elseif ($mapping['type'] === 'datetime') {
  2459. $mapping['default'] = 'CURRENT_TIMESTAMP';
  2460. } else {
  2461. throw MappingException::unsupportedOptimisticLockingType($this->name, $mapping['fieldName'], $mapping['type']);
  2462. }
  2463. }
  2464. }
  2466. /**
  2467. * Sets whether this class is to be versioned for optimistic locking.
  2468. */
  2469. public function setVersioned(bool $bool): void
  2470. {
  2471. $this->isVersioned = $bool;
  2473. if ($bool) {
  2474. $this->requiresFetchAfterChange = true;
  2475. }
  2476. }
  2478. /**
  2479. * Sets the name of the field that is to be used for versioning if this class is
  2480. * versioned for optimistic locking.
  2481. */
  2482. public function setVersionField(string|null $versionField): void
  2483. {
  2484. $this->versionField = $versionField;
  2485. }
  2487. /**
  2488. * Marks this class as read only, no change tracking is applied to it.
  2489. */
  2490. public function markReadOnly(): void
  2491. {
  2492. $this->isReadOnly = true;
  2493. }
  2495. /**
  2496. * {@inheritDoc}
  2497. */
  2498. public function getFieldNames(): array
  2499. {
  2500. return array_keys($this->fieldMappings);
  2501. }
  2503. /**
  2504. * {@inheritDoc}
  2505. */
  2506. public function getAssociationNames(): array
  2507. {
  2508. return array_keys($this->associationMappings);
  2509. }
  2511. /**
  2512. * {@inheritDoc}
  2513. *
  2514. * @phpstan-return class-string
  2515. *
  2516. * @throws InvalidArgumentException
  2517. */
  2518. public function getAssociationTargetClass(string $assocName): string
  2519. {
  2520. return $this->associationMappings[$assocName]->targetEntity
  2521. ?? throw new InvalidArgumentException("Association name expected, '" . $assocName . "' is not an association.");
  2522. }
  2524. public function getName(): string
  2525. {
  2526. return $this->name;
  2527. }
  2529. public function isAssociationInverseSide(string $assocName): bool
  2530. {
  2531. return isset($this->associationMappings[$assocName])
  2532. && ! $this->associationMappings[$assocName]->isOwningSide();
  2533. }
  2535. public function getAssociationMappedByTargetField(string $assocName): string
  2536. {
  2537. $assoc = $this->getAssociationMapping($assocName);
  2539. if (! $assoc instanceof InverseSideMapping) {
  2540. throw new LogicException(sprintf(
  2541. <<<'EXCEPTION'
  2542. Context: Calling %s() with "%s", which is the owning side of an association.
  2543. Problem: The owning side of an association has no "mappedBy" field.
  2544. Solution: Call %s::isAssociationInverseSide() to check first.
  2545. EXCEPTION,
  2546. __METHOD__,
  2547. $assocName,
  2548. self::class,
  2549. ));
  2550. }
  2552. return $assoc->mappedBy;
  2553. }
  2555. /**
  2556. * @param C $className
  2557. *
  2558. * @return string|null null if and only if the input value is null
  2559. * @phpstan-return (C is class-string ? class-string : (C is string ? string : null))
  2560. *
  2561. * @template C of string|null
  2562. */
  2563. public function fullyQualifiedClassName(string|null $className): string|null
  2564. {
  2565. if ($className === null) {
  2566. Deprecation::trigger(
  2567. 'doctrine/orm',
  2568. 'https://github.com/doctrine/orm/pull/11294',
  2569. 'Passing null to %s is deprecated and will not be supported in Doctrine ORM 4.0',
  2570. __METHOD__,
  2571. );
  2573. return null;
  2574. }
  2576. if (! str_contains($className, '\\') && $this->namespace) {
  2577. return $this->namespace . '\\' . $className;
  2578. }
  2580. return $className;
  2581. }
  2583. public function getMetadataValue(string $name): mixed
  2584. {
  2585. return $this->$name ?? null;
  2586. }
  2588. /**
  2589. * Map Embedded Class
  2590. *
  2591. * @phpstan-param array{
  2592. * fieldName: string,
  2593. * class?: class-string,
  2594. * declaredField?: string,
  2595. * columnPrefix?: string|false|null,
  2596. * originalField?: string
  2597. * } $mapping
  2598. *
  2599. * @throws MappingException
  2600. */
  2601. public function mapEmbedded(array $mapping): void
  2602. {
  2603. $this->assertFieldNotMapped($mapping['fieldName']);
  2605. if (! isset($mapping['class']) && $this->isTypedProperty($mapping['fieldName'])) {
  2606. $type = $this->reflClass->getProperty($mapping['fieldName'])->getType();
  2607. if ($type instanceof ReflectionNamedType) {
  2608. $mapping['class'] = $type->getName();
  2609. }
  2610. }
  2612. if (! (isset($mapping['class']) && $mapping['class'])) {
  2613. throw MappingException::missingEmbeddedClass($mapping['fieldName']);
  2614. }
  2616. $this->embeddedClasses[$mapping['fieldName']] = EmbeddedClassMapping::fromMappingArray([
  2617. 'class' => $this->fullyQualifiedClassName($mapping['class']),
  2618. 'columnPrefix' => $mapping['columnPrefix'] ?? null,
  2619. 'declaredField' => $mapping['declaredField'] ?? null,
  2620. 'originalField' => $mapping['originalField'] ?? null,
  2621. ]);
  2622. }
  2624. /**
  2625. * Inline the embeddable class
  2626. */
  2627. public function inlineEmbeddable(string $property, ClassMetadata $embeddable): void
  2628. {
  2629. foreach ($embeddable->fieldMappings as $originalFieldMapping) {
  2630. $fieldMapping = (array) $originalFieldMapping;
  2631. $fieldMapping['originalClass'] ??= $embeddable->name;
  2632. $fieldMapping['declaredField'] = isset($fieldMapping['declaredField'])
  2633. ? $property . '.' . $fieldMapping['declaredField']
  2634. : $property;
  2635. $fieldMapping['originalField'] ??= $fieldMapping['fieldName'];
  2636. $fieldMapping['fieldName'] = $property . '.' . $fieldMapping['fieldName'];
  2638. if (! empty($this->embeddedClasses[$property]->columnPrefix)) {
  2639. $fieldMapping['columnName'] = $this->embeddedClasses[$property]->columnPrefix . $fieldMapping['columnName'];
  2640. } elseif ($this->embeddedClasses[$property]->columnPrefix !== false) {
  2641. assert($this->reflClass !== null);
  2642. assert($embeddable->reflClass !== null);
  2643. $fieldMapping['columnName'] = $this->namingStrategy
  2644. ->embeddedFieldToColumnName(
  2645. $property,
  2646. $fieldMapping['columnName'],
  2647. $this->reflClass->name,
  2648. $embeddable->reflClass->name,
  2649. );
  2650. }
  2652. $this->mapField($fieldMapping);
  2653. }
  2654. }
  2656. /** @throws MappingException */
  2657. private function assertFieldNotMapped(string $fieldName): void
  2658. {
  2659. if (
  2660. isset($this->fieldMappings[$fieldName]) ||
  2661. isset($this->associationMappings[$fieldName]) ||
  2662. isset($this->embeddedClasses[$fieldName])
  2663. ) {
  2664. throw MappingException::duplicateFieldMapping($this->name, $fieldName);
  2665. }
  2666. }
  2668. /**
  2669. * Gets the sequence name based on class metadata.
  2670. *
  2671. * @todo Sequence names should be computed in DBAL depending on the platform
  2672. */
  2673. public function getSequenceName(AbstractPlatform $platform): string
  2674. {
  2675. $sequencePrefix = $this->getSequencePrefix($platform);
  2676. $columnName = $this->getSingleIdentifierColumnName();
  2678. return $sequencePrefix . '_' . $columnName . '_seq';
  2679. }
  2681. /**
  2682. * Gets the sequence name prefix based on class metadata.
  2683. *
  2684. * @todo Sequence names should be computed in DBAL depending on the platform
  2685. */
  2686. public function getSequencePrefix(AbstractPlatform $platform): string
  2687. {
  2688. $tableName = $this->getTableName();
  2689. $sequencePrefix = $tableName;
  2691. // Prepend the schema name to the table name if there is one
  2692. $schemaName = $this->getSchemaName();
  2693. if ($schemaName) {
  2694. $sequencePrefix = $schemaName . '.' . $tableName;
  2695. }
  2697. return $sequencePrefix;
  2698. }
  2699. }