vendor/doctrine/mongodb-odm/lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadata.php line 2479

Open in your IDE?
  1. <?php
  3. declare(strict_types=1);
  5. namespace Doctrine\ODM\MongoDB\Mapping;
  7. use BackedEnum;
  8. use BadMethodCallException;
  9. use DateTime;
  10. use DateTimeImmutable;
  11. use Doctrine\Common\Collections\Collection;
  12. use Doctrine\Instantiator\Instantiator;
  13. use Doctrine\Instantiator\InstantiatorInterface;
  14. use Doctrine\ODM\MongoDB\Id\IdGenerator;
  15. use Doctrine\ODM\MongoDB\LockException;
  16. use Doctrine\ODM\MongoDB\Mapping\Annotations\TimeSeries;
  17. use Doctrine\ODM\MongoDB\Proxy\InternalProxy;
  18. use Doctrine\ODM\MongoDB\Types\Incrementable;
  19. use Doctrine\ODM\MongoDB\Types\Type;
  20. use Doctrine\ODM\MongoDB\Types\Versionable;
  21. use Doctrine\ODM\MongoDB\Utility\CollectionHelper;
  22. use Doctrine\Persistence\Mapping\ClassMetadata as BaseClassMetadata;
  23. use Doctrine\Persistence\Mapping\ReflectionService;
  24. use Doctrine\Persistence\Mapping\RuntimeReflectionService;
  25. use Doctrine\Persistence\Reflection\EnumReflectionProperty;
  26. use InvalidArgumentException;
  27. use LogicException;
  28. use ProxyManager\Proxy\GhostObjectInterface;
  29. use ReflectionClass;
  30. use ReflectionEnum;
  31. use ReflectionNamedType;
  32. use ReflectionProperty;
  34. use function array_filter;
  35. use function array_key_exists;
  36. use function array_keys;
  37. use function array_map;
  38. use function array_pop;
  39. use function assert;
  40. use function class_exists;
  41. use function constant;
  42. use function count;
  43. use function enum_exists;
  44. use function extension_loaded;
  45. use function in_array;
  46. use function interface_exists;
  47. use function is_array;
  48. use function is_string;
  49. use function is_subclass_of;
  50. use function ltrim;
  51. use function sprintf;
  52. use function strtolower;
  53. use function strtoupper;
  54. use function trigger_deprecation;
  56. /**
  57. * A <tt>ClassMetadata</tt> instance holds all the object-document mapping metadata
  58. * of a document and it's references.
  59. *
  60. * Once populated, ClassMetadata instances are usually cached in a serialized form.
  61. *
  62. * <b>IMPORTANT NOTE:</b>
  63. *
  64. * The fields of this class are only public for 2 reasons:
  65. * 1) To allow fast READ access.
  66. * 2) To drastically reduce the size of a serialized instance (private/protected members
  67. * get the whole class name, namespace inclusive, prepended to every property in
  68. * the serialized representation).
  69. *
  70. * @phpstan-type FieldMappingConfig array{
  71. * type?: string,
  72. * fieldName?: string,
  73. * name?: string,
  74. * strategy?: string,
  75. * association?: int,
  76. * id?: bool,
  77. * isOwningSide?: bool,
  78. * collectionClass?: class-string,
  79. * cascade?: list<string>|string,
  80. * embedded?: bool,
  81. * orphanRemoval?: bool,
  82. * options?: array<string, mixed>,
  83. * nullable?: bool,
  84. * reference?: bool,
  85. * storeAs?: string,
  86. * targetDocument?: class-string|null,
  87. * mappedBy?: string|null,
  88. * inversedBy?: string|null,
  89. * discriminatorField?: string,
  90. * defaultDiscriminatorValue?: string,
  91. * discriminatorMap?: array<string, class-string>,
  92. * repositoryMethod?: string|null,
  93. * sort?: array<string, string|int>,
  94. * limit?: int|null,
  95. * skip?: int|null,
  96. * version?: bool,
  97. * lock?: bool,
  98. * inherited?: string,
  99. * declared?: class-string,
  100. * prime?: list<string>,
  101. * sparse?: bool,
  102. * unique?: bool,
  103. * index?: bool,
  104. * index-name?: string,
  105. * criteria?: array<string, mixed>,
  106. * alsoLoadFields?: list<string>,
  107. * order?: int|string,
  108. * background?: bool,
  109. * enumType?: class-string<BackedEnum>,
  110. * }
  111. * @phpstan-type FieldMapping array{
  112. * type: string,
  113. * fieldName: string,
  114. * name: string,
  115. * isCascadeRemove: bool,
  116. * isCascadePersist: bool,
  117. * isCascadeRefresh: bool,
  118. * isCascadeMerge: bool,
  119. * isCascadeDetach: bool,
  120. * isOwningSide: bool,
  121. * isInverseSide: bool,
  122. * strategy?: string,
  123. * association?: int,
  124. * id?: bool,
  125. * collectionClass?: class-string,
  126. * cascade?: list<string>|string,
  127. * embedded?: bool,
  128. * orphanRemoval?: bool,
  129. * options?: array<string, mixed>,
  130. * nullable?: bool,
  131. * reference?: bool,
  132. * storeAs?: string,
  133. * targetDocument?: class-string|null,
  134. * mappedBy?: string|null,
  135. * inversedBy?: string|null,
  136. * discriminatorField?: string,
  137. * defaultDiscriminatorValue?: string,
  138. * discriminatorMap?: array<string, class-string>,
  139. * repositoryMethod?: string|null,
  140. * sort?: array<string, string|int>,
  141. * limit?: int|null,
  142. * skip?: int|null,
  143. * version?: bool,
  144. * lock?: bool,
  145. * notSaved?: bool,
  146. * inherited?: string,
  147. * declared?: class-string,
  148. * prime?: list<string>,
  149. * sparse?: bool,
  150. * unique?: bool,
  151. * index?: bool,
  152. * criteria?: array<string, mixed>,
  153. * alsoLoadFields?: list<string>,
  154. * enumType?: class-string<BackedEnum>,
  155. * storeEmptyArray?: bool,
  156. * }
  157. * @phpstan-type AssociationFieldMapping array{
  158. * type?: string,
  159. * fieldName: string,
  160. * name: string,
  161. * isCascadeRemove: bool,
  162. * isCascadePersist: bool,
  163. * isCascadeRefresh: bool,
  164. * isCascadeMerge: bool,
  165. * isCascadeDetach: bool,
  166. * isOwningSide: bool,
  167. * isInverseSide: bool,
  168. * targetDocument: class-string|null,
  169. * association: int,
  170. * strategy?: string,
  171. * id?: bool,
  172. * collectionClass?: class-string,
  173. * cascade?: list<string>|string,
  174. * embedded?: bool,
  175. * orphanRemoval?: bool,
  176. * options?: array<string, mixed>,
  177. * nullable?: bool,
  178. * reference?: bool,
  179. * storeAs?: string,
  180. * mappedBy?: string|null,
  181. * inversedBy?: string|null,
  182. * discriminatorField?: string,
  183. * defaultDiscriminatorValue?: string,
  184. * discriminatorMap?: array<string, class-string>,
  185. * repositoryMethod?: string|null,
  186. * sort?: array<string, string|int>,
  187. * limit?: int|null,
  188. * skip?: int|null,
  189. * version?: bool,
  190. * lock?: bool,
  191. * notSaved?: bool,
  192. * inherited?: string,
  193. * declared?: class-string,
  194. * prime?: list<string>,
  195. * sparse?: bool,
  196. * unique?: bool,
  197. * index?: bool,
  198. * criteria?: array<string, mixed>,
  199. * alsoLoadFields?: list<string>,
  200. * storeEmptyArray?: bool,
  201. * }
  202. * @phpstan-type IndexKeys array<string, mixed>
  203. * @phpstan-type IndexOptions array{
  204. * background?: bool,
  205. * bits?: int,
  206. * default_language?: string,
  207. * expireAfterSeconds?: int,
  208. * language_override?: string,
  209. * min?: float,
  210. * max?: float,
  211. * name?: string,
  212. * partialFilterExpression?: mixed[],
  213. * sparse?: bool,
  214. * storageEngine?: mixed[],
  215. * textIndexVersion?: int,
  216. * unique?: bool,
  217. * weights?: array{string, int},
  218. * }
  219. * @phpstan-type IndexMapping array{
  220. * keys: IndexKeys,
  221. * options: IndexOptions
  222. * }
  223. * @phpstan-type SearchIndexStoredSourceInclude array{include: list<string>}
  224. * @phpstan-type SearchIndexStoredSourceExclude array{exclude: list<string>}
  225. * @phpstan-type SearchIndexStoredSource bool|SearchIndexStoredSourceInclude|SearchIndexStoredSourceExclude
  226. * @phpstan-type SearchIndexSynonym array{
  227. * analyzer: string,
  228. * name: string,
  229. * source: array{
  230. * collection: string,
  231. * },
  232. * }
  233. * @phpstan-type SearchIndexDefinition array{
  234. * mappings: array{
  235. * dynamic?: bool,
  236. * fields?: array,
  237. * },
  238. * analyzer?: string,
  239. * searchAnalyzer?: string,
  240. * analyzers?: array,
  241. * storedSource?: SearchIndexStoredSource,
  242. * synonyms?: list<SearchIndexSynonym>,
  243. * }
  244. * @phpstan-type SearchIndexMapping array{
  245. * name: string,
  246. * definition: SearchIndexDefinition
  247. * }
  248. * @phpstan-type ShardKeys array<string, mixed>
  249. * @phpstan-type ShardOptions array<string, mixed>
  250. * @phpstan-type ShardKey array{
  251. * keys?: ShardKeys,
  252. * options?: ShardOptions
  253. * }
  254. * @final
  255. * @template-covariant T of object
  256. * @template-implements BaseClassMetadata<T>
  257. */
  258. /* final */ class ClassMetadata implements BaseClassMetadata
  259. {
  260. /* The Id generator types. */
  261. /**
  262. * AUTO means Doctrine will automatically create a new \MongoDB\BSON\ObjectId instance for us.
  263. */
  264. public const GENERATOR_TYPE_AUTO = 1;
  266. /**
  267. * INCREMENT means a separate collection is used for maintaining and incrementing id generation.
  268. * Offers full portability.
  269. */
  270. public const GENERATOR_TYPE_INCREMENT = 2;
  272. /**
  273. * UUID means Doctrine will generate a uuid for us.
  274. */
  275. public const GENERATOR_TYPE_UUID = 3;
  277. /**
  278. * ALNUM means Doctrine will generate Alpha-numeric string identifiers, using the INCREMENT
  279. * generator to ensure identifier uniqueness
  280. */
  281. public const GENERATOR_TYPE_ALNUM = 4;
  283. /**
  284. * CUSTOM means Doctrine expect a class parameter. It will then try to initiate that class
  285. * and pass other options to the generator. It will throw an Exception if the class
  286. * does not exist or if an option was passed for that there is not setter in the new
  287. * generator class.
  288. *
  289. * The class will have to implement IdGenerator.
  290. */
  291. public const GENERATOR_TYPE_CUSTOM = 5;
  293. /**
  294. * NONE means Doctrine will not generate any id for us and you are responsible for manually
  295. * assigning an id.
  296. */
  297. public const GENERATOR_TYPE_NONE = 6;
  299. /**
  300. * Default discriminator field name.
  301. *
  302. * This is used for associations value for associations where a that do not define a "targetDocument" or
  303. * "discriminatorField" option in their mapping.
  304. */
  305. public const DEFAULT_DISCRIMINATOR_FIELD = '_doctrine_class_name';
  307. /**
  308. * Association types
  309. */
  310. public const REFERENCE_ONE = 1;
  311. public const REFERENCE_MANY = 2;
  312. public const EMBED_ONE = 3;
  313. public const EMBED_MANY = 4;
  315. /**
  316. * Mapping types
  317. */
  318. public const MANY = 'many';
  319. public const ONE = 'one';
  321. /**
  322. * The types of storeAs references
  323. */
  324. public const REFERENCE_STORE_AS_ID = 'id';
  325. public const REFERENCE_STORE_AS_DB_REF = 'dbRef';
  326. public const REFERENCE_STORE_AS_DB_REF_WITH_DB = 'dbRefWithDb';
  327. public const REFERENCE_STORE_AS_REF = 'ref';
  329. /**
  330. * Rejects any insert or update that violates the validation criteria.
  331. *
  332. * Value for collection schema validationAction.
  333. *
  334. * @see https://www.mongodb.com/docs/manual/core/schema-validation/handle-invalid-documents/#option-1--reject-invalid-documents
  335. */
  336. public const SCHEMA_VALIDATION_ACTION_ERROR = 'error';
  338. /**
  339. * MongoDB allows the operation to proceed, but records the violation in the MongoDB log.
  340. *
  341. * Value for collection schema validationAction.
  342. *
  343. * @see https://www.mongodb.com/docs/manual/core/schema-validation/handle-invalid-documents/#option-2--allow-invalid-documents--but-record-them-in-the-log
  344. */
  345. public const SCHEMA_VALIDATION_ACTION_WARN = 'warn';
  347. /**
  348. * Disable schema validation for the collection.
  349. *
  350. * Value of validationLevel.
  351. *
  352. * @see https://www.mongodb.com/docs/manual/core/schema-validation/specify-validation-level/
  353. */
  354. public const SCHEMA_VALIDATION_LEVEL_OFF = 'off';
  356. /**
  357. * MongoDB applies the same validation rules to all document inserts and updates.
  358. *
  359. * Value of validationLevel.
  360. *
  361. * @see https://www.mongodb.com/docs/manual/core/schema-validation/specify-validation-level/#steps--use-strict-validation
  362. */
  363. public const SCHEMA_VALIDATION_LEVEL_STRICT = 'strict';
  365. /**
  366. * MongoDB applies the same validation rules to document inserts and updates
  367. * to existing valid documents that match the validation rules. Updates to
  368. * existing documents in the collection that don't match the validation rules
  369. * aren't checked for validity.
  370. *
  371. * Value of validationLevel.
  372. *
  373. * @see https://www.mongodb.com/docs/manual/core/schema-validation/specify-validation-level/#steps--use-moderate-validation
  374. */
  375. public const SCHEMA_VALIDATION_LEVEL_MODERATE = 'moderate';
  377. /* The inheritance mapping types */
  378. /**
  379. * NONE means the class does not participate in an inheritance hierarchy
  380. * and therefore does not need an inheritance mapping type.
  381. */
  382. public const INHERITANCE_TYPE_NONE = 1;
  384. /**
  385. * SINGLE_COLLECTION means the class will be persisted according to the rules of
  386. * <tt>Single Collection Inheritance</tt>.
  387. */
  388. public const INHERITANCE_TYPE_SINGLE_COLLECTION = 2;
  390. /**
  391. * COLLECTION_PER_CLASS means the class will be persisted according to the rules
  392. * of <tt>Concrete Collection Inheritance</tt>.
  393. */
  394. public const INHERITANCE_TYPE_COLLECTION_PER_CLASS = 3;
  396. /**
  397. * DEFERRED_IMPLICIT means that changes of entities are calculated at commit-time
  398. * by doing a property-by-property comparison with the original data. This will
  399. * be done for all entities that are in MANAGED state at commit-time.
  400. *
  401. * This is the default change tracking policy.
  402. */
  403. public const CHANGETRACKING_DEFERRED_IMPLICIT = 1;
  405. /**
  406. * DEFERRED_EXPLICIT means that changes of entities are calculated at commit-time
  407. * by doing a property-by-property comparison with the original data. This will
  408. * be done only for entities that were explicitly saved (through persist() or a cascade).
  409. */
  410. public const CHANGETRACKING_DEFERRED_EXPLICIT = 2;
  412. /**
  413. * NOTIFY means that Doctrine relies on the entities sending out notifications
  414. * when their properties change. Such entity classes must implement
  415. * the <tt>NotifyPropertyChanged</tt> interface.
  416. *
  417. * @deprecated
  418. */
  419. public const CHANGETRACKING_NOTIFY = 3;
  421. /**
  422. * SET means that fields will be written to the database using a $set operator
  423. */
  424. public const STORAGE_STRATEGY_SET = 'set';
  426. /**
  427. * INCREMENT means that fields will be written to the database by calculating
  428. * the difference and using the $inc operator
  429. */
  430. public const STORAGE_STRATEGY_INCREMENT = 'increment';
  432. public const STORAGE_STRATEGY_PUSH_ALL = 'pushAll';
  433. public const STORAGE_STRATEGY_ADD_TO_SET = 'addToSet';
  434. public const STORAGE_STRATEGY_ATOMIC_SET = 'atomicSet';
  435. public const STORAGE_STRATEGY_ATOMIC_SET_ARRAY = 'atomicSetArray';
  436. public const STORAGE_STRATEGY_SET_ARRAY = 'setArray';
  438. /**
  439. * Default search index name.
  440. *
  441. * @see https://www.mongodb.com/docs/manual/reference/command/createSearchIndexes/
  442. */
  443. public const DEFAULT_SEARCH_INDEX_NAME = 'default';
  445. private const ALLOWED_GRIDFS_FIELDS = ['_id', 'chunkSize', 'filename', 'length', 'metadata', 'uploadDate'];
  447. /**
  448. * READ-ONLY: The name of the mongo database the document is mapped to.
  449. *
  450. * @var string|null
  451. */
  452. public $db;
  454. /**
  455. * READ-ONLY: The name of the mongo collection the document is mapped to.
  456. *
  457. * @var string
  458. */
  459. public $collection;
  461. /**
  462. * READ-ONLY: The name of the GridFS bucket the document is mapped to.
  463. *
  464. * @var string
  465. */
  466. public $bucketName = 'fs';
  468. /**
  469. * READ-ONLY: If the collection should be a fixed size.
  470. *
  471. * @var bool
  472. */
  473. public $collectionCapped = false;
  475. /**
  476. * READ-ONLY: If the collection is fixed size, its size in bytes.
  477. *
  478. * @var int|null
  479. */
  480. public $collectionSize;
  482. /**
  483. * READ-ONLY: If the collection is fixed size, the maximum number of elements to store in the collection.
  484. *
  485. * @var int|null
  486. */
  487. public $collectionMax;
  489. /**
  490. * READ-ONLY Describes how MongoDB clients route read operations to the members of a replica set.
  491. *
  492. * @var string|null
  493. */
  494. public $readPreference;
  496. /**
  497. * READ-ONLY Associated with readPreference Allows to specify criteria so that your application can target read
  498. * operations to specific members, based on custom parameters.
  499. *
  500. * @var array<array<string, string>>
  501. */
  502. public $readPreferenceTags = [];
  504. /**
  505. * READ-ONLY: Describes the level of acknowledgement requested from MongoDB for write operations.
  506. *
  507. * @var string|int|null
  508. */
  509. public $writeConcern;
  511. /**
  512. * READ-ONLY: The field name of the document identifier.
  513. *
  514. * @var string|null
  515. */
  516. public $identifier;
  518. /**
  519. * READ-ONLY: The array of indexes for the document collection.
  520. *
  521. * @var array<array<string, mixed>>
  522. * @phpstan-var array<IndexMapping>
  523. */
  524. public $indexes = [];
  526. /**
  527. * READ-ONLY: The array of search indexes for the document collection.
  528. *
  529. * @var list<SearchIndexMapping>
  530. */
  531. public $searchIndexes = [];
  533. /**
  534. * READ-ONLY: Keys and options describing shard key. Only for sharded collections.
  535. *
  536. * @var array<string, array>
  537. * @phpstan-var ShardKey
  538. */
  539. public $shardKey = [];
  541. /**
  542. * Allows users to specify a validation schema for the collection.
  543. *
  544. * @phpstan-var array<string, mixed>|object|null
  545. */
  546. private array|object|null $validator = null;
  548. /**
  549. * Determines whether to error on invalid documents or just warn about the violations but allow invalid documents to be inserted.
  550. */
  551. private string $validationAction = self::SCHEMA_VALIDATION_ACTION_ERROR;
  553. /**
  554. * Determines how strictly MongoDB applies the validation rules to existing documents during an update.
  555. */
  556. private string $validationLevel = self::SCHEMA_VALIDATION_LEVEL_STRICT;
  558. /**
  559. * READ-ONLY: The name of the document class.
  560. *
  561. * @var class-string<T>
  562. */
  563. public $name;
  565. /**
  566. * READ-ONLY: The name of the document class that is at the root of the mapped document inheritance
  567. * hierarchy. If the document is not part of a mapped inheritance hierarchy this is the same
  568. * as {@link $documentName}.
  569. *
  570. * @var class-string
  571. */
  572. public $rootDocumentName;
  574. /**
  575. * The name of the custom repository class used for the document class.
  576. * (Optional).
  577. *
  578. * @var class-string|null
  579. */
  580. public $customRepositoryClassName;
  582. /**
  583. * READ-ONLY: The names of the parent classes (ancestors).
  584. *
  585. * @var list<class-string>
  586. */
  587. public $parentClasses = [];
  589. /**
  590. * READ-ONLY: The names of all subclasses (descendants).
  591. *
  592. * @var list<class-string>
  593. */
  594. public $subClasses = [];
  596. /**
  597. * The ReflectionProperty instances of the mapped class.
  598. *
  599. * @var ReflectionProperty[]
  600. */
  601. public $reflFields = [];
  603. /**
  604. * READ-ONLY: The inheritance mapping type used by the class.
  605. *
  606. * @var int
  607. */
  608. public $inheritanceType = self::INHERITANCE_TYPE_NONE;
  610. /**
  611. * READ-ONLY: The Id generator type used by the class.
  612. *
  613. * @var int
  614. */
  615. public $generatorType = self::GENERATOR_TYPE_AUTO;
  617. /**
  618. * READ-ONLY: The Id generator options.
  619. *
  620. * @var array<string, mixed>
  621. */
  622. public $generatorOptions = [];
  624. /**
  625. * READ-ONLY: The ID generator used for generating IDs for this class.
  626. *
  627. * @var IdGenerator|null
  628. */
  629. public $idGenerator;
  631. /**
  632. * READ-ONLY: The field mappings of the class.
  633. * Keys are field names and values are mapping definitions.
  634. *
  635. * The mapping definition array has the following values:
  636. *
  637. * - <b>fieldName</b> (string)
  638. * The name of the field in the Document.
  639. *
  640. * - <b>id</b> (boolean, optional)
  641. * Marks the field as the primary key of the document. Multiple fields of an
  642. * document can have the id attribute, forming a composite key.
  643. *
  644. * @var array<string, mixed>
  645. * @phpstan-var array<string, FieldMapping>
  646. */
  647. public $fieldMappings = [];
  649. /**
  650. * READ-ONLY: The association mappings of the class.
  651. * Keys are field names and values are mapping definitions.
  652. *
  653. * @var array<string, mixed>
  654. * @phpstan-var array<string, AssociationFieldMapping>
  655. */
  656. public $associationMappings = [];
  658. /**
  659. * READ-ONLY: Array of fields to also load with a given method.
  660. *
  661. * @var array<string, mixed[]>
  662. */
  663. public $alsoLoadMethods = [];
  665. /**
  666. * READ-ONLY: The registered lifecycle callbacks for documents of this class.
  667. *
  668. * @var array<string, list<string>>
  669. */
  670. public $lifecycleCallbacks = [];
  672. /**
  673. * READ-ONLY: The discriminator value of this class.
  674. *
  675. * <b>This does only apply to the JOINED and SINGLE_COLLECTION inheritance mapping strategies
  676. * where a discriminator field is used.</b>
  677. *
  678. * @see discriminatorField
  679. *
  680. * @var class-string|null
  681. */
  682. public $discriminatorValue;
  684. /**
  685. * READ-ONLY: The discriminator map of all mapped classes in the hierarchy.
  686. *
  687. * <b>This does only apply to the SINGLE_COLLECTION inheritance mapping strategy
  688. * where a discriminator field is used.</b>
  689. *
  690. * @see discriminatorField
  691. *
  692. * @var array<string, class-string>
  693. */
  694. public $discriminatorMap = [];
  696. /**
  697. * READ-ONLY: The definition of the discriminator field used in SINGLE_COLLECTION
  698. * inheritance mapping.
  699. *
  700. * @var string|null
  701. */
  702. public $discriminatorField;
  704. /**
  705. * READ-ONLY: The default value for discriminatorField in case it's not set in the document
  706. *
  707. * @see discriminatorField
  708. *
  709. * @var string|null
  710. */
  711. public $defaultDiscriminatorValue;
  713. /**
  714. * READ-ONLY: Whether this class describes the mapping of a mapped superclass.
  715. *
  716. * @var bool
  717. */
  718. public $isMappedSuperclass = false;
  720. /**
  721. * READ-ONLY: Whether this class describes the mapping of a embedded document.
  722. *
  723. * @var bool
  724. */
  725. public $isEmbeddedDocument = false;
  727. /**
  728. * READ-ONLY: Whether this class describes the mapping of an aggregation result document.
  729. *
  730. * @var bool
  731. */
  732. public $isQueryResultDocument = false;
  734. /**
  735. * READ-ONLY: Whether this class describes the mapping of a database view.
  736. */
  737. private bool $isView = false;
  739. /**
  740. * READ-ONLY: Whether this class describes the mapping of a gridFS file
  741. *
  742. * @var bool
  743. */
  744. public $isFile = false;
  746. /**
  747. * READ-ONLY: The default chunk size in bytes for the file
  748. *
  749. * @var int|null
  750. */
  751. public $chunkSizeBytes;
  753. /**
  754. * READ-ONLY: The policy used for change-tracking on entities of this class.
  755. *
  756. * @var int
  757. */
  758. public $changeTrackingPolicy = self::CHANGETRACKING_DEFERRED_IMPLICIT;
  760. /**
  761. * READ-ONLY: A flag for whether or not instances of this class are to be versioned
  762. * with optimistic locking.
  763. *
  764. * @var bool $isVersioned
  765. */
  766. public $isVersioned = false;
  768. /**
  769. * READ-ONLY: The name of the field which is used for versioning in optimistic locking (if any).
  770. *
  771. * @var string|null $versionField
  772. */
  773. public $versionField;
  775. /**
  776. * READ-ONLY: A flag for whether or not instances of this class are to allow pessimistic
  777. * locking.
  778. *
  779. * @var bool $isLockable
  780. */
  781. public $isLockable = false;
  783. /**
  784. * READ-ONLY: The name of the field which is used for locking a document.
  785. *
  786. * @var mixed $lockField
  787. */
  788. public $lockField;
  790. /**
  791. * The ReflectionClass instance of the mapped class.
  792. *
  793. * @var ReflectionClass<T>
  794. */
  795. public $reflClass;
  797. /**
  798. * READ_ONLY: A flag for whether or not this document is read-only.
  799. *
  800. * @var bool
  801. */
  802. public $isReadOnly;
  804. /** READ ONLY: stores metadata about the time series collection */
  805. public ?TimeSeries $timeSeriesOptions = null;
  807. private InstantiatorInterface $instantiator;
  809. private ReflectionService $reflectionService;
  811. /** @var class-string|null */
  812. private ?string $rootClass;
  814. /**
  815. * Initializes a new ClassMetadata instance that will hold the object-document mapping
  816. * metadata of the class with the given name.
  817. *
  818. * @param class-string<T> $documentName
  819. */
  820. public function __construct(string $documentName)
  821. {
  822. $this->name = $documentName;
  823. $this->rootDocumentName = $documentName;
  824. $this->reflectionService = new RuntimeReflectionService();
  825. $this->reflClass = new ReflectionClass($documentName);
  826. $this->setCollection($this->reflClass->getShortName());
  827. $this->instantiator = new Instantiator();
  828. }
  830. /**
  831. * Helper method to get reference id of ref* type references
  832. *
  833. * @internal
  834. *
  835. * @param mixed $reference
  836. *
  837. * @return mixed
  838. */
  839. public static function getReferenceId($reference, string $storeAs)
  840. {
  841. return $storeAs === self::REFERENCE_STORE_AS_ID ? $reference : $reference[self::getReferencePrefix($storeAs) . 'id'];
  842. }
  844. /**
  845. * Returns the reference prefix used for a reference
  846. */
  847. private static function getReferencePrefix(string $storeAs): string
  848. {
  849. if (! in_array($storeAs, [self::REFERENCE_STORE_AS_REF, self::REFERENCE_STORE_AS_DB_REF, self::REFERENCE_STORE_AS_DB_REF_WITH_DB])) {
  850. throw new LogicException('Can only get a reference prefix for DBRef and reference arrays');
  851. }
  853. return $storeAs === self::REFERENCE_STORE_AS_REF ? '' : '$';
  854. }
  856. /**
  857. * Returns a fully qualified field name for a given reference
  858. *
  859. * @internal
  860. *
  861. * @param string $pathPrefix The field path prefix
  862. */
  863. public static function getReferenceFieldName(string $storeAs, string $pathPrefix = ''): string
  864. {
  865. if ($storeAs === self::REFERENCE_STORE_AS_ID) {
  866. return $pathPrefix;
  867. }
  869. return ($pathPrefix ? $pathPrefix . '.' : '') . static::getReferencePrefix($storeAs) . 'id';
  870. }
  872. public function getReflectionClass(): ReflectionClass
  873. {
  874. return $this->reflClass;
  875. }
  877. /** @param string $fieldName */
  878. public function isIdentifier($fieldName): bool
  879. {
  880. return $this->identifier === $fieldName;
  881. }
  883. /**
  884. * Sets the mapped identifier field of this class.
  885. *
  886. * @internal
  887. */
  888. public function setIdentifier(?string $identifier): void
  889. {
  890. $this->identifier = $identifier;
  891. }
  893. /**
  894. * Since MongoDB only allows exactly one identifier field
  895. * this will always return an array with only one value
  896. *
  897. * @return array<string|null>
  898. */
  899. public function getIdentifier(): array
  900. {
  901. return [$this->identifier];
  902. }
  904. /**
  905. * Since MongoDB only allows exactly one identifier field
  906. * this will always return an array with only one value
  907. *
  908. * @return array<string|null>
  909. */
  910. public function getIdentifierFieldNames(): array
  911. {
  912. return [$this->identifier];
  913. }
  915. /** @param string $fieldName */
  916. public function hasField($fieldName): bool
  917. {
  918. return isset($this->fieldMappings[$fieldName]);
  919. }
  921. /**
  922. * Sets the inheritance type used by the class and it's subclasses.
  923. */
  924. public function setInheritanceType(int $type): void
  925. {
  926. $this->inheritanceType = $type;
  927. }
  929. /**
  930. * Checks whether a mapped field is inherited from an entity superclass.
  931. */
  932. public function isInheritedField(string $fieldName): bool
  933. {
  934. return isset($this->fieldMappings[$fieldName]['inherited']);
  935. }
  937. /**
  938. * Registers a custom repository class for the document class.
  939. *
  940. * @param class-string|null $repositoryClassName
  941. */
  942. public function setCustomRepositoryClass(?string $repositoryClassName): void
  943. {
  944. if ($this->isEmbeddedDocument || $this->isQueryResultDocument) {
  945. return;
  946. }
  948. $this->customRepositoryClassName = $repositoryClassName;
  949. }
  951. /**
  952. * Dispatches the lifecycle event of the given document by invoking all
  953. * registered callbacks.
  954. *
  955. * @param mixed[]|null $arguments
  956. *
  957. * @throws InvalidArgumentException If document class is not this class or
  958. * a Proxy of this class.
  959. */
  960. public function invokeLifecycleCallbacks(string $event, object $document, ?array $arguments = null): void
  961. {
  962. if ($this->isView()) {
  963. return;
  964. }
  966. if (! $document instanceof $this->name) {
  967. throw new InvalidArgumentException(sprintf('Expected document class "%s"; found: "%s"', $this->name, $document::class));
  968. }
  970. if (empty($this->lifecycleCallbacks[$event])) {
  971. return;
  972. }
  974. foreach ($this->lifecycleCallbacks[$event] as $callback) {
  975. if ($arguments !== null) {
  976. $document->$callback(...$arguments);
  977. } else {
  978. $document->$callback();
  979. }
  980. }
  981. }
  983. /**
  984. * Checks whether the class has callbacks registered for a lifecycle event.
  985. */
  986. public function hasLifecycleCallbacks(string $event): bool
  987. {
  988. return ! empty($this->lifecycleCallbacks[$event]);
  989. }
  991. /**
  992. * Gets the registered lifecycle callbacks for an event.
  993. *
  994. * @return list<string>
  995. */
  996. public function getLifecycleCallbacks(string $event): array
  997. {
  998. return $this->lifecycleCallbacks[$event] ?? [];
  999. }
  1001. /**
  1002. * Adds a lifecycle callback for documents of this class.
  1003. *
  1004. * If the callback is already registered, this is a NOOP.
  1005. */
  1006. public function addLifecycleCallback(string $callback, string $event): void
  1007. {
  1008. if (isset($this->lifecycleCallbacks[$event]) && in_array($callback, $this->lifecycleCallbacks[$event])) {
  1009. return;
  1010. }
  1012. $this->lifecycleCallbacks[$event][] = $callback;
  1013. }
  1015. /**
  1016. * Sets the lifecycle callbacks for documents of this class.
  1017. *
  1018. * Any previously registered callbacks are overwritten.
  1019. *
  1020. * @param array<string, list<string>> $callbacks
  1021. */
  1022. public function setLifecycleCallbacks(array $callbacks): void
  1023. {
  1024. $this->lifecycleCallbacks = $callbacks;
  1025. }
  1027. /**
  1028. * Registers a method for loading document data before field hydration.
  1029. *
  1030. * Note: A method may be registered multiple times for different fields.
  1031. * it will be invoked only once for the first field found.
  1032. *
  1033. * @param array<string, mixed>|string $fields Database field name(s)
  1034. */
  1035. public function registerAlsoLoadMethod(string $method, $fields): void
  1036. {
  1037. $this->alsoLoadMethods[$method] = is_array($fields) ? $fields : [$fields];
  1038. }
  1040. /**
  1041. * Sets the AlsoLoad methods for documents of this class.
  1042. *
  1043. * Any previously registered methods are overwritten.
  1044. *
  1045. * @param array<string, mixed[]> $methods
  1046. */
  1047. public function setAlsoLoadMethods(array $methods): void
  1048. {
  1049. $this->alsoLoadMethods = $methods;
  1050. }
  1052. /**
  1053. * Sets the discriminator field.
  1054. *
  1055. * The field name is the the unmapped database field. Discriminator values
  1056. * are only used to discern the hydration class and are not mapped to class
  1057. * properties.
  1058. *
  1059. * @param array{name?: string, fieldName?: string}|string|null $discriminatorField
  1060. *
  1061. * @throws MappingException If the discriminator field conflicts with the
  1062. * "name" attribute of a mapped field.
  1063. */
  1064. public function setDiscriminatorField($discriminatorField): void
  1065. {
  1066. if ($this->isFile) {
  1067. throw MappingException::discriminatorNotAllowedForGridFS($this->name);
  1068. }
  1070. if ($discriminatorField === null) {
  1071. $this->discriminatorField = null;
  1073. return;
  1074. }
  1076. // @todo: deprecate, document and remove this:
  1077. // Handle array argument with name/fieldName keys for BC
  1078. if (is_array($discriminatorField)) {
  1079. if (isset($discriminatorField['name'])) {
  1080. $discriminatorField = $discriminatorField['name'];
  1081. } elseif (isset($discriminatorField['fieldName'])) {
  1082. $discriminatorField = $discriminatorField['fieldName'];
  1083. }
  1084. }
  1086. foreach ($this->fieldMappings as $fieldMapping) {
  1087. if ($discriminatorField === $fieldMapping['name']) {
  1088. throw MappingException::discriminatorFieldConflict($this->name, $discriminatorField);
  1089. }
  1090. }
  1092. $this->discriminatorField = $discriminatorField;
  1093. }
  1095. /**
  1096. * Sets the discriminator values used by this class.
  1097. * Used for JOINED and SINGLE_TABLE inheritance mapping strategies.
  1098. *
  1099. * @param array<string, class-string> $map
  1100. *
  1101. * @throws MappingException
  1102. */
  1103. public function setDiscriminatorMap(array $map): void
  1104. {
  1105. if ($this->isFile) {
  1106. throw MappingException::discriminatorNotAllowedForGridFS($this->name);
  1107. }
  1109. $this->subClasses = [];
  1110. $this->discriminatorMap = [];
  1111. $this->discriminatorValue = null;
  1113. foreach ($map as $value => $className) {
  1114. $this->discriminatorMap[$value] = $className;
  1115. if ($this->name === $className) {
  1116. $this->discriminatorValue = $value;
  1117. } else {
  1118. if (! class_exists($className)) {
  1119. throw MappingException::invalidClassInDiscriminatorMap($className, $this->name);
  1120. }
  1122. if (is_subclass_of($className, $this->name)) {
  1123. $this->subClasses[] = $className;
  1124. }
  1125. }
  1126. }
  1127. }
  1129. /**
  1130. * Sets the default discriminator value to be used for this class
  1131. * Used for SINGLE_TABLE inheritance mapping strategies if the document has no discriminator value
  1132. *
  1133. * @throws MappingException
  1134. */
  1135. public function setDefaultDiscriminatorValue(?string $defaultDiscriminatorValue): void
  1136. {
  1137. if ($this->isFile) {
  1138. throw MappingException::discriminatorNotAllowedForGridFS($this->name);
  1139. }
  1141. if ($defaultDiscriminatorValue === null) {
  1142. $this->defaultDiscriminatorValue = null;
  1144. return;
  1145. }
  1147. if (! array_key_exists($defaultDiscriminatorValue, $this->discriminatorMap)) {
  1148. throw MappingException::invalidDiscriminatorValue($defaultDiscriminatorValue, $this->name);
  1149. }
  1151. $this->defaultDiscriminatorValue = $defaultDiscriminatorValue;
  1152. }
  1154. /**
  1155. * Sets the discriminator value for this class.
  1156. * Used for JOINED/SINGLE_TABLE inheritance and multiple document types in a single
  1157. * collection.
  1158. *
  1159. * @throws MappingException
  1160. */
  1161. public function setDiscriminatorValue(string $value): void
  1162. {
  1163. if ($this->isFile) {
  1164. throw MappingException::discriminatorNotAllowedForGridFS($this->name);
  1165. }
  1167. $this->discriminatorMap[$value] = $this->name;
  1168. $this->discriminatorValue = $value;
  1169. }
  1171. /**
  1172. * Add a index for this Document.
  1173. *
  1174. * @param array<string, int|string> $keys
  1175. * @phpstan-param IndexKeys $keys
  1176. * @phpstan-param IndexOptions $options
  1177. */
  1178. public function addIndex(array $keys, array $options = []): void
  1179. {
  1180. $this->indexes[] = [
  1181. 'keys' => array_map(static function ($value) {
  1182. if ($value === 1 || $value === -1) {
  1183. return $value;
  1184. }
  1186. if (is_string($value)) {
  1187. $lower = strtolower($value);
  1188. if ($lower === 'asc') {
  1189. return 1;
  1190. }
  1192. if ($lower === 'desc') {
  1193. return -1;
  1194. }
  1195. }
  1197. return $value;
  1198. }, $keys),
  1199. 'options' => $options,
  1200. ];
  1201. }
  1203. /**
  1204. * Returns the array of indexes for this Document.
  1205. *
  1206. * @phpstan-return array<IndexMapping>
  1207. */
  1208. public function getIndexes(): array
  1209. {
  1210. return $this->indexes;
  1211. }
  1213. /**
  1214. * Checks whether this document has indexes or not.
  1215. */
  1216. public function hasIndexes(): bool
  1217. {
  1218. return $this->indexes !== [];
  1219. }
  1221. /**
  1222. * Add a search index for this Document.
  1223. *
  1224. * @phpstan-param SearchIndexDefinition $definition
  1225. */
  1226. public function addSearchIndex(array $definition, ?string $name = null): void
  1227. {
  1228. $name ??= self::DEFAULT_SEARCH_INDEX_NAME;
  1230. if (empty($definition['mappings']['dynamic']) && empty($definition['mappings']['fields'])) {
  1231. throw MappingException::emptySearchIndexDefinition($this->name, $name);
  1232. }
  1234. $this->searchIndexes[] = [
  1235. 'definition' => $definition,
  1236. 'name' => $name,
  1237. ];
  1238. }
  1240. /**
  1241. * Returns the array of search indexes for this Document.
  1242. *
  1243. * @phpstan-return list<SearchIndexMapping>
  1244. */
  1245. public function getSearchIndexes(): array
  1246. {
  1247. return $this->searchIndexes;
  1248. }
  1250. /**
  1251. * Checks whether this document has search indexes or not.
  1252. */
  1253. public function hasSearchIndexes(): bool
  1254. {
  1255. return $this->searchIndexes !== [];
  1256. }
  1258. /**
  1259. * Set shard key for this Document.
  1260. *
  1261. * @param array<string, string|int> $keys
  1262. * @param array<string, mixed> $options
  1263. * @phpstan-param ShardKeys $keys
  1264. * @phpstan-param ShardOptions $options
  1265. *
  1266. * @throws MappingException
  1267. */
  1268. public function setShardKey(array $keys, array $options = []): void
  1269. {
  1270. if ($this->inheritanceType === self::INHERITANCE_TYPE_SINGLE_COLLECTION && $this->shardKey !== []) {
  1271. throw MappingException::shardKeyInSingleCollInheritanceSubclass($this->getName());
  1272. }
  1274. if ($this->isEmbeddedDocument) {
  1275. throw MappingException::embeddedDocumentCantHaveShardKey($this->getName());
  1276. }
  1278. foreach (array_keys($keys) as $field) {
  1279. if (! isset($this->fieldMappings[$field])) {
  1280. continue;
  1281. }
  1283. if (in_array($this->fieldMappings[$field]['type'], [self::MANY, Type::COLLECTION])) {
  1284. throw MappingException::noMultiKeyShardKeys($this->getName(), $field);
  1285. }
  1287. if ($this->fieldMappings[$field]['strategy'] !== self::STORAGE_STRATEGY_SET) {
  1288. throw MappingException::onlySetStrategyAllowedInShardKey($this->getName(), $field);
  1289. }
  1290. }
  1292. $this->shardKey = [
  1293. 'keys' => array_map(static function ($value) {
  1294. if ($value === 1 || $value === -1) {
  1295. return $value;
  1296. }
  1298. if (is_string($value)) {
  1299. $lower = strtolower($value);
  1300. if ($lower === 'asc') {
  1301. return 1;
  1302. }
  1304. if ($lower === 'desc') {
  1305. return -1;
  1306. }
  1307. }
  1309. return $value;
  1310. }, $keys),
  1311. 'options' => $options,
  1312. ];
  1313. }
  1315. /** @phpstan-return ShardKey */
  1316. public function getShardKey(): array
  1317. {
  1318. return $this->shardKey;
  1319. }
  1321. /**
  1322. * Checks whether this document has shard key or not.
  1323. */
  1324. public function isSharded(): bool
  1325. {
  1326. return $this->shardKey !== [];
  1327. }
  1329. /** @return array<string, mixed>|object|null */
  1330. public function getValidator()
  1331. {
  1332. return $this->validator;
  1333. }
  1335. /** @param array<string, mixed>|object|null $validator */
  1336. public function setValidator($validator): void
  1337. {
  1338. $this->validator = $validator;
  1339. }
  1341. public function getValidationAction(): string
  1342. {
  1343. return $this->validationAction;
  1344. }
  1346. public function setValidationAction(string $validationAction): void
  1347. {
  1348. $this->validationAction = $validationAction;
  1349. }
  1351. public function getValidationLevel(): string
  1352. {
  1353. return $this->validationLevel;
  1354. }
  1356. public function setValidationLevel(string $validationLevel): void
  1357. {
  1358. $this->validationLevel = $validationLevel;
  1359. }
  1361. /**
  1362. * Sets the read preference used by this class.
  1363. *
  1364. * @param array<array<string, string>> $tags
  1365. */
  1366. public function setReadPreference(?string $readPreference, array $tags): void
  1367. {
  1368. $this->readPreference = $readPreference;
  1369. $this->readPreferenceTags = $tags;
  1370. }
  1372. /**
  1373. * Sets the write concern used by this class.
  1374. *
  1375. * @param string|int|null $writeConcern
  1376. */
  1377. public function setWriteConcern($writeConcern): void
  1378. {
  1379. $this->writeConcern = $writeConcern;
  1380. }
  1382. /** @return int|string|null */
  1383. public function getWriteConcern()
  1384. {
  1385. return $this->writeConcern;
  1386. }
  1388. /**
  1389. * Whether there is a write concern configured for this class.
  1390. */
  1391. public function hasWriteConcern(): bool
  1392. {
  1393. return $this->writeConcern !== null;
  1394. }
  1396. /**
  1397. * Sets the change tracking policy used by this class.
  1398. */
  1399. public function setChangeTrackingPolicy(int $policy): void
  1400. {
  1401. $this->changeTrackingPolicy = $policy;
  1402. }
  1404. /**
  1405. * Whether the change tracking policy of this class is "deferred explicit".
  1406. */
  1407. public function isChangeTrackingDeferredExplicit(): bool
  1408. {
  1409. return $this->changeTrackingPolicy === self::CHANGETRACKING_DEFERRED_EXPLICIT;
  1410. }
  1412. /**
  1413. * Whether the change tracking policy of this class is "deferred implicit".
  1414. */
  1415. public function isChangeTrackingDeferredImplicit(): bool
  1416. {
  1417. return $this->changeTrackingPolicy === self::CHANGETRACKING_DEFERRED_IMPLICIT;
  1418. }
  1420. /**
  1421. * Whether the change tracking policy of this class is "notify".
  1422. *
  1423. * @deprecated This method was deprecated in doctrine/mongodb-odm 2.4. Please use DEFERRED_EXPLICIT tracking
  1424. * policy and isChangeTrackingDeferredImplicit method to detect it.
  1425. */
  1426. public function isChangeTrackingNotify(): bool
  1427. {
  1428. return $this->changeTrackingPolicy === self::CHANGETRACKING_NOTIFY;
  1429. }
  1431. /**
  1432. * Gets the ReflectionProperties of the mapped class.
  1433. *
  1434. * @return ReflectionProperty[]
  1435. */
  1436. public function getReflectionProperties(): array
  1437. {
  1438. return $this->reflFields;
  1439. }
  1441. /**
  1442. * Gets a ReflectionProperty for a specific field of the mapped class.
  1443. */
  1444. public function getReflectionProperty(string $name): ReflectionProperty
  1445. {
  1446. return $this->reflFields[$name];
  1447. }
  1449. /** @return class-string<T> */
  1450. public function getName(): string
  1451. {
  1452. return $this->name;
  1453. }
  1455. /**
  1456. * Returns the database this Document is mapped to.
  1457. */
  1458. public function getDatabase(): ?string
  1459. {
  1460. return $this->db;
  1461. }
  1463. /**
  1464. * Set the database this Document is mapped to.
  1465. */
  1466. public function setDatabase(?string $db): void
  1467. {
  1468. $this->db = $db;
  1469. }
  1471. /**
  1472. * Get the collection this Document is mapped to.
  1473. */
  1474. public function getCollection(): string
  1475. {
  1476. return $this->collection;
  1477. }
  1479. /**
  1480. * Sets the collection this Document is mapped to.
  1481. *
  1482. * @param array{name: string, capped?: bool, size?: int, max?: int}|string $name
  1483. *
  1484. * @throws InvalidArgumentException
  1485. */
  1486. public function setCollection($name): void
  1487. {
  1488. if (is_array($name)) {
  1489. if (! isset($name['name'])) {
  1490. throw new InvalidArgumentException('A name key is required when passing an array to setCollection()');
  1491. }
  1493. $this->collectionCapped = $name['capped'] ?? false;
  1494. $this->collectionSize = $name['size'] ?? 0;
  1495. $this->collectionMax = $name['max'] ?? 0;
  1496. $this->collection = $name['name'];
  1497. } else {
  1498. $this->collection = $name;
  1499. }
  1500. }
  1502. public function getBucketName(): ?string
  1503. {
  1504. return $this->bucketName;
  1505. }
  1507. public function setBucketName(string $bucketName): void
  1508. {
  1509. $this->bucketName = $bucketName;
  1510. $this->setCollection($bucketName . '.files');
  1511. }
  1513. public function getChunkSizeBytes(): ?int
  1514. {
  1515. return $this->chunkSizeBytes;
  1516. }
  1518. public function setChunkSizeBytes(int $chunkSizeBytes): void
  1519. {
  1520. $this->chunkSizeBytes = $chunkSizeBytes;
  1521. }
  1523. /**
  1524. * Get whether or not the documents collection is capped.
  1525. */
  1526. public function getCollectionCapped(): bool
  1527. {
  1528. return $this->collectionCapped;
  1529. }
  1531. /**
  1532. * Set whether or not the documents collection is capped.
  1533. */
  1534. public function setCollectionCapped(bool $bool): void
  1535. {
  1536. $this->collectionCapped = $bool;
  1537. }
  1539. /**
  1540. * Get the collection size
  1541. */
  1542. public function getCollectionSize(): ?int
  1543. {
  1544. return $this->collectionSize;
  1545. }
  1547. /**
  1548. * Set the collection size.
  1549. */
  1550. public function setCollectionSize(int $size): void
  1551. {
  1552. $this->collectionSize = $size;
  1553. }
  1555. /**
  1556. * Get the collection max.
  1557. */
  1558. public function getCollectionMax(): ?int
  1559. {
  1560. return $this->collectionMax;
  1561. }
  1563. /**
  1564. * Set the collection max.
  1565. */
  1566. public function setCollectionMax(int $max): void
  1567. {
  1568. $this->collectionMax = $max;
  1569. }
  1571. /**
  1572. * Returns TRUE if this Document is mapped to a collection FALSE otherwise.
  1573. */
  1574. public function isMappedToCollection(): bool
  1575. {
  1576. return $this->collection !== '' && $this->collection !== null;
  1577. }
  1579. /**
  1580. * Validates the storage strategy of a mapping for consistency
  1581. *
  1582. * @phpstan-param FieldMappingConfig $mapping
  1583. *
  1584. * @throws MappingException
  1585. */
  1586. private function applyStorageStrategy(array &$mapping): void
  1587. {
  1588. if (! isset($mapping['type']) || isset($mapping['id'])) {
  1589. return;
  1590. }
  1592. switch (true) {
  1593. case $mapping['type'] === self::MANY:
  1594. $defaultStrategy = CollectionHelper::DEFAULT_STRATEGY;
  1595. $allowedStrategies = [
  1596. self::STORAGE_STRATEGY_PUSH_ALL,
  1597. self::STORAGE_STRATEGY_ADD_TO_SET,
  1598. self::STORAGE_STRATEGY_SET,
  1599. self::STORAGE_STRATEGY_SET_ARRAY,
  1600. self::STORAGE_STRATEGY_ATOMIC_SET,
  1601. self::STORAGE_STRATEGY_ATOMIC_SET_ARRAY,
  1602. ];
  1603. break;
  1605. case $mapping['type'] === self::ONE:
  1606. $defaultStrategy = self::STORAGE_STRATEGY_SET;
  1607. $allowedStrategies = [self::STORAGE_STRATEGY_SET];
  1608. break;
  1610. default:
  1611. $defaultStrategy = self::STORAGE_STRATEGY_SET;
  1612. $allowedStrategies = [self::STORAGE_STRATEGY_SET];
  1613. $type = Type::getType($mapping['type']);
  1614. if ($type instanceof Incrementable) {
  1615. $allowedStrategies[] = self::STORAGE_STRATEGY_INCREMENT;
  1616. }
  1617. }
  1619. if (! isset($mapping['strategy'])) {
  1620. $mapping['strategy'] = $defaultStrategy;
  1621. }
  1623. if (! in_array($mapping['strategy'], $allowedStrategies)) {
  1624. throw MappingException::invalidStorageStrategy($this->name, $mapping['fieldName'], $mapping['type'], $mapping['strategy']);
  1625. }
  1627. if (
  1628. isset($mapping['reference']) && $mapping['type'] === self::MANY && $mapping['isOwningSide']
  1629. && ! empty($mapping['sort']) && ! CollectionHelper::usesSet($mapping['strategy'])
  1630. ) {
  1631. throw MappingException::referenceManySortMustNotBeUsedWithNonSetCollectionStrategy($this->name, $mapping['fieldName'], $mapping['strategy']);
  1632. }
  1633. }
  1635. /**
  1636. * Map a single embedded document.
  1637. *
  1638. * @phpstan-param FieldMappingConfig $mapping
  1639. */
  1640. public function mapOneEmbedded(array $mapping): void
  1641. {
  1642. $mapping['embedded'] = true;
  1643. $mapping['type'] = self::ONE;
  1645. $this->mapField($mapping);
  1646. }
  1648. /**
  1649. * Map a collection of embedded documents.
  1650. *
  1651. * @phpstan-param FieldMappingConfig $mapping
  1652. */
  1653. public function mapManyEmbedded(array $mapping): void
  1654. {
  1655. $mapping['embedded'] = true;
  1656. $mapping['type'] = self::MANY;
  1658. $this->mapField($mapping);
  1659. }
  1661. /**
  1662. * Map a single document reference.
  1663. *
  1664. * @phpstan-param FieldMappingConfig $mapping
  1665. */
  1666. public function mapOneReference(array $mapping): void
  1667. {
  1668. $mapping['reference'] = true;
  1669. $mapping['type'] = self::ONE;
  1671. $this->mapField($mapping);
  1672. }
  1674. /**
  1675. * Map a collection of document references.
  1676. *
  1677. * @phpstan-param FieldMappingConfig $mapping
  1678. */
  1679. public function mapManyReference(array $mapping): void
  1680. {
  1681. $mapping['reference'] = true;
  1682. $mapping['type'] = self::MANY;
  1684. $this->mapField($mapping);
  1685. }
  1687. /**
  1688. * Adds a field mapping without completing/validating it.
  1689. * This is mainly used to add inherited field mappings to derived classes.
  1690. *
  1691. * @internal
  1692. *
  1693. * @phpstan-param FieldMapping $fieldMapping
  1694. */
  1695. public function addInheritedFieldMapping(array $fieldMapping): void
  1696. {
  1697. $this->fieldMappings[$fieldMapping['fieldName']] = $fieldMapping;
  1699. if (! isset($fieldMapping['association'])) {
  1700. return;
  1701. }
  1703. $this->associationMappings[$fieldMapping['fieldName']] = $fieldMapping;
  1704. }
  1706. /**
  1707. * Adds an association mapping without completing/validating it.
  1708. * This is mainly used to add inherited association mappings to derived classes.
  1709. *
  1710. * @internal
  1711. *
  1712. * @phpstan-param AssociationFieldMapping $mapping
  1713. *
  1714. * @throws MappingException
  1715. */
  1716. public function addInheritedAssociationMapping(array $mapping): void
  1717. {
  1718. $this->associationMappings[$mapping['fieldName']] = $mapping;
  1719. }
  1721. /**
  1722. * Checks whether the class has a mapped association with the given field name.
  1723. */
  1724. public function hasReference(string $fieldName): bool
  1725. {
  1726. return isset($this->fieldMappings[$fieldName]['reference']);
  1727. }
  1729. /**
  1730. * Checks whether the class has a mapped embed with the given field name.
  1731. */
  1732. public function hasEmbed(string $fieldName): bool
  1733. {
  1734. return isset($this->fieldMappings[$fieldName]['embedded']);
  1735. }
  1737. /**
  1738. * Checks whether the class has a mapped association (embed or reference) with the given field name.
  1739. *
  1740. * @param string $fieldName
  1741. */
  1742. public function hasAssociation($fieldName): bool
  1743. {
  1744. return $this->hasReference($fieldName) || $this->hasEmbed($fieldName);
  1745. }
  1747. /**
  1748. * Checks whether the class has a mapped reference or embed for the specified field and
  1749. * is a single valued association.
  1750. *
  1751. * @param string $fieldName
  1752. */
  1753. public function isSingleValuedAssociation($fieldName): bool
  1754. {
  1755. return $this->isSingleValuedReference($fieldName) || $this->isSingleValuedEmbed($fieldName);
  1756. }
  1758. /**
  1759. * Checks whether the class has a mapped reference or embed for the specified field and
  1760. * is a collection valued association.
  1761. *
  1762. * @param string $fieldName
  1763. */
  1764. public function isCollectionValuedAssociation($fieldName): bool
  1765. {
  1766. return $this->isCollectionValuedReference($fieldName) || $this->isCollectionValuedEmbed($fieldName);
  1767. }
  1769. /**
  1770. * Checks whether the class has a mapped association for the specified field
  1771. * and if yes, checks whether it is a single-valued association (to-one).
  1772. */
  1773. public function isSingleValuedReference(string $fieldName): bool
  1774. {
  1775. return isset($this->fieldMappings[$fieldName]['association']) &&
  1776. $this->fieldMappings[$fieldName]['association'] === self::REFERENCE_ONE;
  1777. }
  1779. /**
  1780. * Checks whether the class has a mapped association for the specified field
  1781. * and if yes, checks whether it is a collection-valued association (to-many).
  1782. */
  1783. public function isCollectionValuedReference(string $fieldName): bool
  1784. {
  1785. return isset($this->fieldMappings[$fieldName]['association']) &&
  1786. $this->fieldMappings[$fieldName]['association'] === self::REFERENCE_MANY;
  1787. }
  1789. /**
  1790. * Checks whether the class has a mapped embedded document for the specified field
  1791. * and if yes, checks whether it is a single-valued association (to-one).
  1792. */
  1793. public function isSingleValuedEmbed(string $fieldName): bool
  1794. {
  1795. return isset($this->fieldMappings[$fieldName]['association']) &&
  1796. $this->fieldMappings[$fieldName]['association'] === self::EMBED_ONE;
  1797. }
  1799. /**
  1800. * Checks whether the class has a mapped embedded document for the specified field
  1801. * and if yes, checks whether it is a collection-valued association (to-many).
  1802. */
  1803. public function isCollectionValuedEmbed(string $fieldName): bool
  1804. {
  1805. return isset($this->fieldMappings[$fieldName]['association']) &&
  1806. $this->fieldMappings[$fieldName]['association'] === self::EMBED_MANY;
  1807. }
  1809. /**
  1810. * Sets the ID generator used to generate IDs for instances of this class.
  1811. */
  1812. public function setIdGenerator(IdGenerator $generator): void
  1813. {
  1814. $this->idGenerator = $generator;
  1815. }
  1817. /**
  1818. * Casts the identifier to its portable PHP type.
  1819. *
  1820. * @param mixed $id
  1821. *
  1822. * @return mixed $id
  1823. */
  1824. public function getPHPIdentifierValue($id)
  1825. {
  1826. $idType = $this->fieldMappings[$this->identifier]['type'];
  1828. return Type::getType($idType)->convertToPHPValue($id);
  1829. }
  1831. /**
  1832. * Casts the identifier to its database type.
  1833. *
  1834. * @param mixed $id
  1835. *
  1836. * @return mixed $id
  1837. */
  1838. public function getDatabaseIdentifierValue($id)
  1839. {
  1840. $idType = $this->fieldMappings[$this->identifier]['type'];
  1842. return Type::getType($idType)->convertToDatabaseValue($id);
  1843. }
  1845. /**
  1846. * Sets the document identifier of a document.
  1847. *
  1848. * The value will be converted to a PHP type before being set.
  1849. *
  1850. * @param mixed $id
  1851. */
  1852. public function setIdentifierValue(object $document, $id): void
  1853. {
  1854. $id = $this->getPHPIdentifierValue($id);
  1855. $this->reflFields[$this->identifier]->setValue($document, $id);
  1856. }
  1858. /**
  1859. * Gets the document identifier as a PHP type.
  1860. *
  1861. * @return mixed $id
  1862. */
  1863. public function getIdentifierValue(object $document)
  1864. {
  1865. return $this->reflFields[$this->identifier]->getValue($document);
  1866. }
  1868. /**
  1869. * Since MongoDB only allows exactly one identifier field this is a proxy
  1870. * to {@see getIdentifierValue()} and returns an array with the identifier
  1871. * field as a key.
  1872. *
  1873. * @param object $object
  1874. */
  1875. public function getIdentifierValues($object): array
  1876. {
  1877. return [$this->identifier => $this->getIdentifierValue($object)];
  1878. }
  1880. /**
  1881. * Get the document identifier object as a database type.
  1882. *
  1883. * @return mixed $id
  1884. */
  1885. public function getIdentifierObject(object $document)
  1886. {
  1887. return $this->getDatabaseIdentifierValue($this->getIdentifierValue($document));
  1888. }
  1890. /**
  1891. * Sets the specified field to the specified value on the given document.
  1892. *
  1893. * @param mixed $value
  1894. */
  1895. public function setFieldValue(object $document, string $field, $value): void
  1896. {
  1897. if ($document instanceof InternalProxy && ! $document->__isInitialized()) {
  1898. //property changes to an uninitialized proxy will not be tracked or persisted,
  1899. //so the proxy needs to be loaded first.
  1900. $document->__load();
  1901. } elseif ($document instanceof GhostObjectInterface && ! $document->isProxyInitialized()) {
  1902. $document->initializeProxy();
  1903. }
  1905. $this->reflFields[$field]->setValue($document, $value);
  1906. }
  1908. /**
  1909. * Gets the specified field's value off the given document.
  1910. *
  1911. * @return mixed
  1912. */
  1913. public function getFieldValue(object $document, string $field)
  1914. {
  1915. if ($document instanceof InternalProxy && $field !== $this->identifier && ! $document->__isInitialized()) {
  1916. $document->__load();
  1917. } elseif ($document instanceof GhostObjectInterface && $field !== $this->identifier && ! $document->isProxyInitialized()) {
  1918. $document->initializeProxy();
  1919. }
  1921. return $this->reflFields[$field]->getValue($document);
  1922. }
  1924. /**
  1925. * Gets the mapping of a field.
  1926. *
  1927. * @phpstan-return FieldMapping
  1928. *
  1929. * @throws MappingException If the $fieldName is not found in the fieldMappings array.
  1930. */
  1931. public function getFieldMapping(string $fieldName): array
  1932. {
  1933. if (! isset($this->fieldMappings[$fieldName])) {
  1934. throw MappingException::mappingNotFound($this->name, $fieldName);
  1935. }
  1937. return $this->fieldMappings[$fieldName];
  1938. }
  1940. /**
  1941. * Gets mappings of fields holding embedded document(s).
  1942. *
  1943. * @return array<string, AssociationFieldMapping>
  1944. */
  1945. public function getEmbeddedFieldsMappings(): array
  1946. {
  1947. return array_filter(
  1948. $this->associationMappings,
  1949. static fn ($assoc) => ! empty($assoc['embedded']),
  1950. );
  1951. }
  1953. /**
  1954. * Gets the field mapping by its DB name.
  1955. * E.g. it returns identifier's mapping when called with _id.
  1956. *
  1957. * @phpstan-return FieldMapping
  1958. *
  1959. * @throws MappingException
  1960. */
  1961. public function getFieldMappingByDbFieldName(string $dbFieldName): array
  1962. {
  1963. foreach ($this->fieldMappings as $mapping) {
  1964. if ($mapping['name'] === $dbFieldName) {
  1965. return $mapping;
  1966. }
  1967. }
  1969. throw MappingException::mappingNotFoundByDbName($this->name, $dbFieldName);
  1970. }
  1972. /**
  1973. * Check if the field is not null.
  1974. */
  1975. public function isNullable(string $fieldName): bool
  1976. {
  1977. $mapping = $this->getFieldMapping($fieldName);
  1979. return isset($mapping['nullable']) && $mapping['nullable'] === true;
  1980. }
  1982. /**
  1983. * Checks whether the document has a discriminator field and value configured.
  1984. */
  1985. public function hasDiscriminator(): bool
  1986. {
  1987. return isset($this->discriminatorField, $this->discriminatorValue);
  1988. }
  1990. /**
  1991. * Sets the type of Id generator to use for the mapped class.
  1992. */
  1993. public function setIdGeneratorType(int $generatorType): void
  1994. {
  1995. $this->generatorType = $generatorType;
  1996. }
  1998. /**
  1999. * Sets the Id generator options.
  2000. *
  2001. * @param array<string, mixed> $generatorOptions
  2002. */
  2003. public function setIdGeneratorOptions(array $generatorOptions): void
  2004. {
  2005. $this->generatorOptions = $generatorOptions;
  2006. }
  2008. public function isInheritanceTypeNone(): bool
  2009. {
  2010. return $this->inheritanceType === self::INHERITANCE_TYPE_NONE;
  2011. }
  2013. /**
  2014. * Checks whether the mapped class uses the SINGLE_COLLECTION inheritance mapping strategy.
  2015. */
  2016. public function isInheritanceTypeSingleCollection(): bool
  2017. {
  2018. return $this->inheritanceType === self::INHERITANCE_TYPE_SINGLE_COLLECTION;
  2019. }
  2021. /**
  2022. * Checks whether the mapped class uses the COLLECTION_PER_CLASS inheritance mapping strategy.
  2023. */
  2024. public function isInheritanceTypeCollectionPerClass(): bool
  2025. {
  2026. return $this->inheritanceType === self::INHERITANCE_TYPE_COLLECTION_PER_CLASS;
  2027. }
  2029. /**
  2030. * Sets the mapped subclasses of this class.
  2031. *
  2032. * @param class-string[] $subclasses The names of all mapped subclasses.
  2033. */
  2034. public function setSubclasses(array $subclasses): void
  2035. {
  2036. foreach ($subclasses as $subclass) {
  2037. $this->subClasses[] = $subclass;
  2038. }
  2039. }
  2041. /**
  2042. * Sets the parent class names.
  2043. * Assumes that the class names in the passed array are in the order:
  2044. * directParent -> directParentParent -> directParentParentParent ... -> root.
  2045. *
  2046. * @param list<class-string> $classNames
  2047. */
  2048. public function setParentClasses(array $classNames): void
  2049. {
  2050. $this->parentClasses = $classNames;
  2052. if (count($classNames) <= 0) {
  2053. return;
  2054. }
  2056. $this->rootDocumentName = (string) array_pop($classNames);
  2057. }
  2059. /**
  2060. * Checks whether the class will generate a new \MongoDB\BSON\ObjectId instance for us.
  2061. */
  2062. public function isIdGeneratorAuto(): bool
  2063. {
  2064. return $this->generatorType === self::GENERATOR_TYPE_AUTO;
  2065. }
  2067. /**
  2068. * Checks whether the class will use a collection to generate incremented identifiers.
  2069. */
  2070. public function isIdGeneratorIncrement(): bool
  2071. {
  2072. return $this->generatorType === self::GENERATOR_TYPE_INCREMENT;
  2073. }
  2075. /**
  2076. * Checks whether the class will generate a uuid id.
  2077. */
  2078. public function isIdGeneratorUuid(): bool
  2079. {
  2080. return $this->generatorType === self::GENERATOR_TYPE_UUID;
  2081. }
  2083. /**
  2084. * Checks whether the class uses no id generator.
  2085. */
  2086. public function isIdGeneratorNone(): bool
  2087. {
  2088. return $this->generatorType === self::GENERATOR_TYPE_NONE;
  2089. }
  2091. /**
  2092. * Sets the version field mapping used for versioning. Sets the default
  2093. * value to use depending on the column type.
  2094. *
  2095. * @phpstan-param FieldMapping $mapping
  2096. *
  2097. * @throws LockException
  2098. */
  2099. public function setVersionMapping(array &$mapping): void
  2100. {
  2101. if (! Type::getType($mapping['type']) instanceof Versionable) {
  2102. throw LockException::invalidVersionFieldType($mapping['type']);
  2103. }
  2105. $this->isVersioned = true;
  2106. $this->versionField = $mapping['fieldName'];
  2107. }
  2109. /**
  2110. * Sets whether this class is to be versioned for optimistic locking.
  2111. */
  2112. public function setVersioned(bool $bool): void
  2113. {
  2114. $this->isVersioned = $bool;
  2115. }
  2117. /**
  2118. * Sets the name of the field that is to be used for versioning if this class is
  2119. * versioned for optimistic locking.
  2120. */
  2121. public function setVersionField(?string $versionField): void
  2122. {
  2123. $this->versionField = $versionField;
  2124. }
  2126. /**
  2127. * Sets the version field mapping used for versioning. Sets the default
  2128. * value to use depending on the column type.
  2129. *
  2130. * @phpstan-param FieldMapping $mapping
  2131. *
  2132. * @throws LockException
  2133. */
  2134. public function setLockMapping(array &$mapping): void
  2135. {
  2136. if ($mapping['type'] !== 'int') {
  2137. throw LockException::invalidLockFieldType($mapping['type']);
  2138. }
  2140. $this->isLockable = true;
  2141. $this->lockField = $mapping['fieldName'];
  2142. }
  2144. /**
  2145. * Sets whether this class is to allow pessimistic locking.
  2146. */
  2147. public function setLockable(bool $bool): void
  2148. {
  2149. $this->isLockable = $bool;
  2150. }
  2152. /**
  2153. * Sets the name of the field that is to be used for storing whether a document
  2154. * is currently locked or not.
  2155. */
  2156. public function setLockField(string $lockField): void
  2157. {
  2158. $this->lockField = $lockField;
  2159. }
  2161. /**
  2162. * Marks this class as read only, no change tracking is applied to it.
  2163. */
  2164. public function markReadOnly(): void
  2165. {
  2166. $this->isReadOnly = true;
  2167. }
  2169. public function getRootClass(): ?string
  2170. {
  2171. return $this->rootClass;
  2172. }
  2174. public function isView(): bool
  2175. {
  2176. return $this->isView;
  2177. }
  2179. /** @param class-string $rootClass */
  2180. public function markViewOf(string $rootClass): void
  2181. {
  2182. $this->isView = true;
  2183. $this->rootClass = $rootClass;
  2184. }
  2186. public function markAsTimeSeries(TimeSeries $options): void
  2187. {
  2188. $this->validateTimeSeriesOptions($options);
  2190. $this->timeSeriesOptions = $options;
  2191. }
  2193. public function getFieldNames(): array
  2194. {
  2195. return array_keys($this->fieldMappings);
  2196. }
  2198. public function getAssociationNames(): array
  2199. {
  2200. return array_keys($this->associationMappings);
  2201. }
  2203. /** @param string $fieldName */
  2204. public function getTypeOfField($fieldName): ?string
  2205. {
  2206. return isset($this->fieldMappings[$fieldName]) ?
  2207. $this->fieldMappings[$fieldName]['type'] : null;
  2208. }
  2210. /**
  2211. * @param string $assocName
  2212. *
  2213. * @return class-string|null
  2214. */
  2215. public function getAssociationTargetClass($assocName): ?string
  2216. {
  2217. if (! isset($this->associationMappings[$assocName])) {
  2218. throw new InvalidArgumentException("Association name expected, '" . $assocName . "' is not an association.");
  2219. }
  2221. return $this->associationMappings[$assocName]['targetDocument'] ?? null;
  2222. }
  2224. /**
  2225. * Retrieve the collectionClass associated with an association
  2226. *
  2227. * @return class-string
  2228. */
  2229. public function getAssociationCollectionClass(string $assocName): string
  2230. {
  2231. if (! isset($this->associationMappings[$assocName])) {
  2232. throw new InvalidArgumentException("Association name expected, '" . $assocName . "' is not an association.");
  2233. }
  2235. if (! array_key_exists('collectionClass', $this->associationMappings[$assocName])) {
  2236. throw new InvalidArgumentException("collectionClass can only be applied to 'embedMany' and 'referenceMany' associations.");
  2237. }
  2239. return $this->associationMappings[$assocName]['collectionClass'];
  2240. }
  2242. /** @param string $assocName */
  2243. public function isAssociationInverseSide($assocName): bool
  2244. {
  2245. throw new BadMethodCallException(__METHOD__ . '() is not implemented yet.');
  2246. }
  2248. /** @param string $assocName */
  2249. public function getAssociationMappedByTargetField($assocName): string
  2250. {
  2251. throw new BadMethodCallException(__METHOD__ . '() is not implemented yet.');
  2252. }
  2254. /**
  2255. * Map a field.
  2256. *
  2257. * @phpstan-param FieldMappingConfig $mapping
  2258. *
  2259. * @phpstan-return FieldMapping
  2260. *
  2261. * @throws MappingException
  2262. */
  2263. public function mapField(array $mapping): array
  2264. {
  2265. if (! isset($mapping['fieldName']) && isset($mapping['name'])) {
  2266. $mapping['fieldName'] = $mapping['name'];
  2267. }
  2269. if ($this->isTypedProperty($mapping['fieldName'])) {
  2270. $mapping = $this->validateAndCompleteTypedFieldMapping($mapping);
  2272. if (isset($mapping['type']) && $mapping['type'] === self::MANY) {
  2273. $mapping = $this->validateAndCompleteTypedManyAssociationMapping($mapping);
  2274. }
  2275. }
  2277. if (! isset($mapping['fieldName']) || ! is_string($mapping['fieldName'])) {
  2278. throw MappingException::missingFieldName($this->name);
  2279. }
  2281. if (! isset($mapping['name'])) {
  2282. $mapping['name'] = $mapping['fieldName'];
  2283. }
  2285. if ($this->identifier === $mapping['name'] && empty($mapping['id'])) {
  2286. throw MappingException::mustNotChangeIdentifierFieldsType($this->name, (string) $mapping['name']);
  2287. }
  2289. if ($this->discriminatorField !== null && $this->discriminatorField === $mapping['name']) {
  2290. throw MappingException::discriminatorFieldConflict($this->name, $this->discriminatorField);
  2291. }
  2293. if (isset($mapping['collectionClass'])) {
  2294. $mapping['collectionClass'] = ltrim($mapping['collectionClass'], '\\');
  2295. }
  2297. if (! empty($mapping['collectionClass'])) {
  2298. $rColl = new ReflectionClass($mapping['collectionClass']);
  2299. if (! $rColl->implementsInterface(Collection::class)) {
  2300. throw MappingException::collectionClassDoesNotImplementCommonInterface($this->name, $mapping['fieldName'], $mapping['collectionClass']);
  2301. }
  2302. }
  2304. if (isset($mapping['cascade']) && isset($mapping['embedded'])) {
  2305. throw MappingException::cascadeOnEmbeddedNotAllowed($this->name, $mapping['fieldName']);
  2306. }
  2308. $cascades = isset($mapping['cascade']) ? array_map('strtolower', (array) $mapping['cascade']) : [];
  2310. if (in_array('all', $cascades) || isset($mapping['embedded'])) {
  2311. $cascades = ['remove', 'persist', 'refresh', 'merge', 'detach'];
  2312. }
  2314. if (isset($mapping['embedded'])) {
  2315. unset($mapping['cascade']);
  2316. } elseif (isset($mapping['cascade'])) {
  2317. $mapping['cascade'] = $cascades;
  2318. }
  2320. $mapping['isCascadeRemove'] = in_array('remove', $cascades);
  2321. $mapping['isCascadePersist'] = in_array('persist', $cascades);
  2322. $mapping['isCascadeRefresh'] = in_array('refresh', $cascades);
  2323. $mapping['isCascadeMerge'] = in_array('merge', $cascades);
  2324. $mapping['isCascadeDetach'] = in_array('detach', $cascades);
  2326. if (isset($mapping['id']) && $mapping['id'] === true) {
  2327. $mapping['name'] = '_id';
  2328. $this->identifier = $mapping['fieldName'];
  2329. if (isset($mapping['strategy'])) {
  2330. $this->generatorType = constant(self::class . '::GENERATOR_TYPE_' . strtoupper($mapping['strategy']));
  2331. }
  2333. $this->generatorOptions = $mapping['options'] ?? [];
  2334. switch ($this->generatorType) {
  2335. case self::GENERATOR_TYPE_AUTO:
  2336. $mapping['type'] = 'id';
  2337. break;
  2338. default:
  2339. if (! empty($this->generatorOptions['type'])) {
  2340. $mapping['type'] = (string) $this->generatorOptions['type'];
  2341. } elseif (empty($mapping['type'])) {
  2342. $mapping['type'] = $this->generatorType === self::GENERATOR_TYPE_INCREMENT ? Type::INT : Type::CUSTOMID;
  2343. }
  2344. }
  2346. unset($this->generatorOptions['type']);
  2347. }
  2349. if (! isset($mapping['type'])) {
  2350. // Default to string
  2351. $mapping['type'] = Type::STRING;
  2352. }
  2354. if (! isset($mapping['nullable'])) {
  2355. $mapping['nullable'] = false;
  2356. }
  2358. if (
  2359. isset($mapping['reference'])
  2360. && isset($mapping['storeAs'])
  2361. && $mapping['storeAs'] === self::REFERENCE_STORE_AS_ID
  2362. && ! isset($mapping['targetDocument'])
  2363. ) {
  2364. throw MappingException::simpleReferenceRequiresTargetDocument($this->name, $mapping['fieldName']);
  2365. }
  2367. if (
  2368. isset($mapping['reference']) && empty($mapping['targetDocument']) && empty($mapping['discriminatorMap']) &&
  2369. (isset($mapping['mappedBy']) || isset($mapping['inversedBy']))
  2370. ) {
  2371. throw MappingException::owningAndInverseReferencesRequireTargetDocument($this->name, $mapping['fieldName']);
  2372. }
  2374. if ($this->isEmbeddedDocument && $mapping['type'] === self::MANY && isset($mapping['strategy']) && CollectionHelper::isAtomic($mapping['strategy'])) {
  2375. throw MappingException::atomicCollectionStrategyNotAllowed($mapping['strategy'], $this->name, $mapping['fieldName']);
  2376. }
  2378. if (isset($mapping['repositoryMethod']) && ! (empty($mapping['skip']) && empty($mapping['limit']) && empty($mapping['sort']))) {
  2379. throw MappingException::repositoryMethodCanNotBeCombinedWithSkipLimitAndSort($this->name, $mapping['fieldName']);
  2380. }
  2382. if (isset($mapping['targetDocument']) && isset($mapping['discriminatorMap'])) {
  2383. trigger_deprecation(
  2384. 'doctrine/mongodb-odm',
  2385. '2.2',
  2386. 'Mapping both "targetDocument" and "discriminatorMap" on field "%s" in class "%s" is deprecated. Only one of them can be used at a time',
  2387. $mapping['fieldName'],
  2388. $this->name,
  2389. );
  2390. }
  2392. if (isset($mapping['reference']) && $mapping['type'] === self::ONE) {
  2393. $mapping['association'] = self::REFERENCE_ONE;
  2394. }
  2396. if (isset($mapping['reference']) && $mapping['type'] === self::MANY) {
  2397. $mapping['association'] = self::REFERENCE_MANY;
  2398. }
  2400. if (isset($mapping['embedded']) && $mapping['type'] === self::ONE) {
  2401. $mapping['association'] = self::EMBED_ONE;
  2402. }
  2404. if (isset($mapping['embedded']) && $mapping['type'] === self::MANY) {
  2405. $mapping['association'] = self::EMBED_MANY;
  2406. }
  2408. if (isset($mapping['association']) && ! isset($mapping['targetDocument']) && ! isset($mapping['discriminatorField'])) {
  2409. $mapping['discriminatorField'] = self::DEFAULT_DISCRIMINATOR_FIELD;
  2410. }
  2412. if (isset($mapping['targetDocument']) && ! class_exists($mapping['targetDocument']) && ! interface_exists($mapping['targetDocument'])) {
  2413. throw MappingException::invalidTargetDocument(
  2414. $mapping['targetDocument'],
  2415. $this->name,
  2416. $mapping['fieldName'],
  2417. );
  2418. }
  2420. if (isset($mapping['discriminatorMap'])) {
  2421. foreach ($mapping['discriminatorMap'] as $value => $class) {
  2422. if (! class_exists($class) && ! interface_exists($class)) {
  2423. throw MappingException::invalidClassInReferenceDiscriminatorMap($class, $this->name, $mapping['fieldName']);
  2424. }
  2425. }
  2426. }
  2428. if (isset($mapping['version'])) {
  2429. $mapping['notSaved'] = true;
  2430. $this->setVersionMapping($mapping);
  2431. }
  2433. if (isset($mapping['lock'])) {
  2434. $mapping['notSaved'] = true;
  2435. $this->setLockMapping($mapping);
  2436. }
  2438. $mapping['isOwningSide'] = true;
  2439. $mapping['isInverseSide'] = false;
  2440. if (isset($mapping['reference'])) {
  2441. if (isset($mapping['inversedBy']) && $mapping['inversedBy']) {
  2442. $mapping['isOwningSide'] = true;
  2443. $mapping['isInverseSide'] = false;
  2444. }
  2446. if (isset($mapping['mappedBy']) && $mapping['mappedBy']) {
  2447. $mapping['isInverseSide'] = true;
  2448. $mapping['isOwningSide'] = false;
  2449. }
  2451. if (isset($mapping['repositoryMethod'])) {
  2452. $mapping['isInverseSide'] = true;
  2453. $mapping['isOwningSide'] = false;
  2454. }
  2456. if (! isset($mapping['orphanRemoval'])) {
  2457. $mapping['orphanRemoval'] = false;
  2458. }
  2459. }
  2461. if (! empty($mapping['prime']) && ($mapping['association'] !== self::REFERENCE_MANY || ! $mapping['isInverseSide'])) {
  2462. throw MappingException::referencePrimersOnlySupportedForInverseReferenceMany($this->name, $mapping['fieldName']);
  2463. }
  2465. if ($this->isFile && ! $this->isAllowedGridFSField($mapping['name'])) {
  2466. throw MappingException::fieldNotAllowedForGridFS($this->name, $mapping['fieldName']);
  2467. }
  2469. $this->applyStorageStrategy($mapping);
  2470. $this->checkDuplicateMapping($mapping);
  2471. $this->typeRequirementsAreMet($mapping);
  2473. $deprecatedTypes = [
  2474. Type::BOOLEAN => Type::BOOL,
  2475. Type::INTEGER => Type::INT,
  2476. Type::INTID => Type::INT,
  2477. ];
  2478. if (isset($deprecatedTypes[$mapping['type']])) {
  2479. trigger_deprecation(
  2480. 'doctrine/mongodb-odm',
  2481. '2.1',
  2482. 'The "%s" mapping type is deprecated. Use "%s" instead.',
  2483. $mapping['type'],
  2484. $deprecatedTypes[$mapping['type']],
  2485. );
  2486. }
  2488. $this->fieldMappings[$mapping['fieldName']] = $mapping;
  2489. if (isset($mapping['association'])) {
  2490. $this->associationMappings[$mapping['fieldName']] = $mapping;
  2491. }
  2493. $reflProp = $this->reflectionService->getAccessibleProperty($this->name, $mapping['fieldName']);
  2494. assert($reflProp instanceof ReflectionProperty);
  2496. if (isset($mapping['enumType'])) {
  2497. if (! enum_exists($mapping['enumType'])) {
  2498. throw MappingException::nonEnumTypeMapped($this->name, $mapping['fieldName'], $mapping['enumType']);
  2499. }
  2501. $reflectionEnum = new ReflectionEnum($mapping['enumType']);
  2502. if (! $reflectionEnum->isBacked()) {
  2503. throw MappingException::nonBackedEnumMapped($this->name, $mapping['fieldName'], $mapping['enumType']);
  2504. }
  2506. $reflProp = new EnumReflectionProperty($reflProp, $mapping['enumType']);
  2507. }
  2509. $this->reflFields[$mapping['fieldName']] = $reflProp;
  2511. return $mapping;
  2512. }
  2514. /**
  2515. * Determines which fields get serialized.
  2516. *
  2517. * It is only serialized what is necessary for best unserialization performance.
  2518. * That means any metadata properties that are not set or empty or simply have
  2519. * their default value are NOT serialized.
  2520. *
  2521. * Parts that are also NOT serialized because they can not be properly unserialized:
  2522. * - reflClass (ReflectionClass)
  2523. * - reflFields (ReflectionProperty array)
  2524. *
  2525. * @return array The names of all the fields that should be serialized.
  2526. */
  2527. public function __sleep()
  2528. {
  2529. // This metadata is always serialized/cached.
  2530. $serialized = [
  2531. 'fieldMappings',
  2532. 'associationMappings',
  2533. 'identifier',
  2534. 'name',
  2535. 'db',
  2536. 'collection',
  2537. 'readPreference',
  2538. 'readPreferenceTags',
  2539. 'writeConcern',
  2540. 'rootDocumentName',
  2541. 'generatorType',
  2542. 'generatorOptions',
  2543. 'idGenerator',
  2544. 'indexes',
  2545. 'shardKey',
  2546. 'timeSeriesOptions',
  2547. ];
  2549. // The rest of the metadata is only serialized if necessary.
  2550. if ($this->changeTrackingPolicy !== self::CHANGETRACKING_DEFERRED_IMPLICIT) {
  2551. $serialized[] = 'changeTrackingPolicy';
  2552. }
  2554. if ($this->customRepositoryClassName) {
  2555. $serialized[] = 'customRepositoryClassName';
  2556. }
  2558. if ($this->inheritanceType !== self::INHERITANCE_TYPE_NONE || $this->discriminatorField !== null) {
  2559. $serialized[] = 'inheritanceType';
  2560. $serialized[] = 'discriminatorField';
  2561. $serialized[] = 'discriminatorValue';
  2562. $serialized[] = 'discriminatorMap';
  2563. $serialized[] = 'defaultDiscriminatorValue';
  2564. $serialized[] = 'parentClasses';
  2565. $serialized[] = 'subClasses';
  2566. }
  2568. if ($this->isMappedSuperclass) {
  2569. $serialized[] = 'isMappedSuperclass';
  2570. }
  2572. if ($this->isEmbeddedDocument) {
  2573. $serialized[] = 'isEmbeddedDocument';
  2574. }
  2576. if ($this->isQueryResultDocument) {
  2577. $serialized[] = 'isQueryResultDocument';
  2578. }
  2580. if ($this->isView()) {
  2581. $serialized[] = 'isView';
  2582. $serialized[] = 'rootClass';
  2583. }
  2585. if ($this->isFile) {
  2586. $serialized[] = 'isFile';
  2587. $serialized[] = 'bucketName';
  2588. $serialized[] = 'chunkSizeBytes';
  2589. }
  2591. if ($this->isVersioned) {
  2592. $serialized[] = 'isVersioned';
  2593. $serialized[] = 'versionField';
  2594. }
  2596. if ($this->isLockable) {
  2597. $serialized[] = 'isLockable';
  2598. $serialized[] = 'lockField';
  2599. }
  2601. if ($this->lifecycleCallbacks) {
  2602. $serialized[] = 'lifecycleCallbacks';
  2603. }
  2605. if ($this->collectionCapped) {
  2606. $serialized[] = 'collectionCapped';
  2607. $serialized[] = 'collectionSize';
  2608. $serialized[] = 'collectionMax';
  2609. }
  2611. if ($this->isReadOnly) {
  2612. $serialized[] = 'isReadOnly';
  2613. }
  2615. if ($this->validator !== null) {
  2616. $serialized[] = 'validator';
  2617. $serialized[] = 'validationAction';
  2618. $serialized[] = 'validationLevel';
  2619. }
  2621. return $serialized;
  2622. }
  2624. /**
  2625. * Restores some state that can not be serialized/unserialized.
  2626. */
  2627. public function __wakeup()
  2628. {
  2629. // Restore ReflectionClass and properties
  2630. $this->reflectionService = new RuntimeReflectionService();
  2631. $this->reflClass = new ReflectionClass($this->name);
  2632. $this->instantiator = new Instantiator();
  2634. foreach ($this->fieldMappings as $field => $mapping) {
  2635. $prop = $this->reflectionService->getAccessibleProperty($mapping['declared'] ?? $this->name, $field);
  2636. assert($prop instanceof ReflectionProperty);
  2638. if (isset($mapping['enumType'])) {
  2639. $prop = new EnumReflectionProperty($prop, $mapping['enumType']);
  2640. }
  2642. $this->reflFields[$field] = $prop;
  2643. }
  2644. }
  2646. /**
  2647. * Creates a new instance of the mapped class, without invoking the constructor.
  2648. *
  2649. * @phpstan-return T
  2650. */
  2651. public function newInstance(): object
  2652. {
  2653. /** @phpstan-var T */
  2654. return $this->instantiator->instantiate($this->name);
  2655. }
  2657. private function isAllowedGridFSField(string $name): bool
  2658. {
  2659. return in_array($name, self::ALLOWED_GRIDFS_FIELDS, true);
  2660. }
  2662. /** @phpstan-param FieldMapping $mapping */
  2663. private function typeRequirementsAreMet(array $mapping): void
  2664. {
  2665. if ($mapping['type'] === Type::DECIMAL128 && ! extension_loaded('bcmath')) {
  2666. throw MappingException::typeRequirementsNotFulfilled($this->name, $mapping['fieldName'], Type::DECIMAL128, 'ext-bcmath is missing');
  2667. }
  2668. }
  2670. /** @phpstan-param FieldMapping $mapping */
  2671. private function checkDuplicateMapping(array $mapping): void
  2672. {
  2673. if ($mapping['notSaved'] ?? false) {
  2674. return;
  2675. }
  2677. foreach ($this->fieldMappings as $fieldName => $otherMapping) {
  2678. // Ignore fields with the same name - we can safely override their mapping
  2679. if ($mapping['fieldName'] === $fieldName) {
  2680. continue;
  2681. }
  2683. // Ignore fields with a different name in the database
  2684. if ($mapping['name'] !== $otherMapping['name']) {
  2685. continue;
  2686. }
  2688. // If the other field is not saved, ignore it as well
  2689. if ($otherMapping['notSaved'] ?? false) {
  2690. continue;
  2691. }
  2693. throw MappingException::duplicateDatabaseFieldName($this->getName(), $mapping['fieldName'], $mapping['name'], $fieldName);
  2694. }
  2695. }
  2697. private function isTypedProperty(string $name): bool
  2698. {
  2699. return $this->reflClass->hasProperty($name)
  2700. && $this->reflClass->getProperty($name)->hasType();
  2701. }
  2703. /**
  2704. * Validates & completes the given field mapping based on typed property.
  2705. *
  2706. * @phpstan-param FieldMappingConfig $mapping
  2707. *
  2708. * @return FieldMappingConfig
  2709. */
  2710. private function validateAndCompleteTypedFieldMapping(array $mapping): array
  2711. {
  2712. $type = $this->reflClass->getProperty($mapping['fieldName'])->getType();
  2714. if (! $type instanceof ReflectionNamedType || isset($mapping['type'])) {
  2715. return $mapping;
  2716. }
  2718. if (! $type->isBuiltin() && enum_exists($type->getName())) {
  2719. $reflection = new ReflectionEnum($type->getName());
  2721. if (! $reflection->isBacked()) {
  2722. throw MappingException::nonBackedEnumMapped($this->name, $mapping['fieldName'], $reflection->getName());
  2723. }
  2725. $type = $reflection->getBackingType();
  2726. assert($type instanceof ReflectionNamedType);
  2727. $mapping['enumType'] = $reflection->getName();
  2728. }
  2730. switch ($type->getName()) {
  2731. case DateTime::class:
  2732. $mapping['type'] = Type::DATE;
  2733. break;
  2734. case DateTimeImmutable::class:
  2735. $mapping['type'] = Type::DATE_IMMUTABLE;
  2736. break;
  2737. case 'array':
  2738. $mapping['type'] = Type::HASH;
  2739. break;
  2740. case 'bool':
  2741. $mapping['type'] = Type::BOOL;
  2742. break;
  2743. case 'float':
  2744. $mapping['type'] = Type::FLOAT;
  2745. break;
  2746. case 'int':
  2747. $mapping['type'] = Type::INT;
  2748. break;
  2749. case 'string':
  2750. $mapping['type'] = Type::STRING;
  2751. break;
  2752. }
  2754. return $mapping;
  2755. }
  2757. /**
  2758. * Validates & completes the basic mapping information based on typed property.
  2759. *
  2760. * @phpstan-param FieldMappingConfig $mapping
  2761. *
  2762. * @return FieldMappingConfig
  2763. */
  2764. private function validateAndCompleteTypedManyAssociationMapping(array $mapping): array
  2765. {
  2766. $type = $this->reflClass->getProperty($mapping['fieldName'])->getType();
  2768. if (! $type instanceof ReflectionNamedType) {
  2769. return $mapping;
  2770. }
  2772. if (! isset($mapping['collectionClass']) && class_exists($type->getName())) {
  2773. $mapping['collectionClass'] = $type->getName();
  2774. }
  2776. return $mapping;
  2777. }
  2779. private function validateTimeSeriesOptions(TimeSeries $options): void
  2780. {
  2781. if (! $this->hasField($options->timeField)) {
  2782. throw MappingException::timeSeriesFieldNotFound($this->name, $options->timeField, 'time');
  2783. }
  2785. if ($options->metaField !== null && ! $this->hasField($options->metaField)) {
  2786. throw MappingException::timeSeriesFieldNotFound($this->name, $options->metaField, 'metadata');
  2787. }
  2788. }
  2789. }