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

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\Types\Incrementable;
  17. use Doctrine\ODM\MongoDB\Types\Type;
  18. use Doctrine\ODM\MongoDB\Types\Versionable;
  19. use Doctrine\ODM\MongoDB\Utility\CollectionHelper;
  20. use Doctrine\Persistence\Mapping\ClassMetadata as BaseClassMetadata;
  21. use Doctrine\Persistence\Mapping\ReflectionService;
  22. use Doctrine\Persistence\Mapping\RuntimeReflectionService;
  23. use Doctrine\Persistence\Reflection\EnumReflectionProperty;
  24. use InvalidArgumentException;
  25. use LogicException;
  26. use ProxyManager\Proxy\GhostObjectInterface;
  27. use ReflectionClass;
  28. use ReflectionEnum;
  29. use ReflectionNamedType;
  30. use ReflectionProperty;
  32. use function array_filter;
  33. use function array_key_exists;
  34. use function array_keys;
  35. use function array_map;
  36. use function array_pop;
  37. use function assert;
  38. use function class_exists;
  39. use function constant;
  40. use function count;
  41. use function enum_exists;
  42. use function extension_loaded;
  43. use function get_class;
  44. use function in_array;
  45. use function interface_exists;
  46. use function is_array;
  47. use function is_string;
  48. use function is_subclass_of;
  49. use function ltrim;
  50. use function sprintf;
  51. use function strtolower;
  52. use function strtoupper;
  53. use function trigger_deprecation;
  55. use const PHP_VERSION_ID;
  57. /**
  58.  * A <tt>ClassMetadata</tt> instance holds all the object-document mapping metadata
  59.  * of a document and it's references.
  60.  *
  61.  * Once populated, ClassMetadata instances are usually cached in a serialized form.
  62.  *
  63.  * <b>IMPORTANT NOTE:</b>
  64.  *
  65.  * The fields of this class are only public for 2 reasons:
  66.  * 1) To allow fast READ access.
  67.  * 2) To drastically reduce the size of a serialized instance (private/protected members
  68.  *    get the whole class name, namespace inclusive, prepended to every property in
  69.  *    the serialized representation).
  70.  *
  71.  * @psalm-type FieldMappingConfig = array{
  72.  *      type?: string,
  73.  *      fieldName?: string,
  74.  *      name?: string,
  75.  *      strategy?: string,
  76.  *      association?: int,
  77.  *      id?: bool,
  78.  *      isOwningSide?: bool,
  79.  *      collectionClass?: class-string,
  80.  *      cascade?: list<string>|string,
  81.  *      embedded?: bool,
  82.  *      orphanRemoval?: bool,
  83.  *      options?: array<string, mixed>,
  84.  *      nullable?: bool,
  85.  *      reference?: bool,
  86.  *      storeAs?: string,
  87.  *      targetDocument?: class-string|null,
  88.  *      mappedBy?: string|null,
  89.  *      inversedBy?: string|null,
  90.  *      discriminatorField?: string,
  91.  *      defaultDiscriminatorValue?: string,
  92.  *      discriminatorMap?: array<string, class-string>,
  93.  *      repositoryMethod?: string|null,
  94.  *      sort?: array<string, string|int>,
  95.  *      limit?: int|null,
  96.  *      skip?: int|null,
  97.  *      version?: bool,
  98.  *      lock?: bool,
  99.  *      inherited?: string,
  100.  *      declared?: class-string,
  101.  *      prime?: list<string>,
  102.  *      sparse?: bool,
  103.  *      unique?: bool,
  104.  *      index?: bool,
  105.  *      index-name?: string,
  106.  *      criteria?: array<string, string>,
  107.  *      alsoLoadFields?: list<string>,
  108.  *      order?: int|string,
  109.  *      background?: bool,
  110.  *      enumType?: class-string<BackedEnum>,
  111.  * }
  112.  * @psalm-type FieldMapping = array{
  113.  *      type: string,
  114.  *      fieldName: string,
  115.  *      name: string,
  116.  *      isCascadeRemove: bool,
  117.  *      isCascadePersist: bool,
  118.  *      isCascadeRefresh: bool,
  119.  *      isCascadeMerge: bool,
  120.  *      isCascadeDetach: bool,
  121.  *      isOwningSide: bool,
  122.  *      isInverseSide: bool,
  123.  *      strategy?: string,
  124.  *      association?: int,
  125.  *      id?: bool,
  126.  *      collectionClass?: class-string,
  127.  *      cascade?: list<string>|string,
  128.  *      embedded?: bool,
  129.  *      orphanRemoval?: bool,
  130.  *      options?: array<string, mixed>,
  131.  *      nullable?: bool,
  132.  *      reference?: bool,
  133.  *      storeAs?: string,
  134.  *      targetDocument?: class-string|null,
  135.  *      mappedBy?: string|null,
  136.  *      inversedBy?: string|null,
  137.  *      discriminatorField?: string,
  138.  *      defaultDiscriminatorValue?: string,
  139.  *      discriminatorMap?: array<string, class-string>,
  140.  *      repositoryMethod?: string|null,
  141.  *      sort?: array<string, string|int>,
  142.  *      limit?: int|null,
  143.  *      skip?: int|null,
  144.  *      version?: bool,
  145.  *      lock?: bool,
  146.  *      notSaved?: bool,
  147.  *      inherited?: string,
  148.  *      declared?: class-string,
  149.  *      prime?: list<string>,
  150.  *      sparse?: bool,
  151.  *      unique?: bool,
  152.  *      index?: bool,
  153.  *      criteria?: array<string, string>,
  154.  *      alsoLoadFields?: list<string>,
  155.  *      enumType?: class-string<BackedEnum>,
  156.  * }
  157.  * @psalm-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, string>,
  199.  *      alsoLoadFields?: list<string>,
  200.  * }
  201.  * @psalm-type IndexKeys = array<string, mixed>
  202.  * @psalm-type IndexOptions = array{
  203.  *      background?: bool,
  204.  *      bits?: int,
  205.  *      default_language?: string,
  206.  *      expireAfterSeconds?: int,
  207.  *      language_override?: string,
  208.  *      min?: float,
  209.  *      max?: float,
  210.  *      name?: string,
  211.  *      partialFilterExpression?: mixed[],
  212.  *      sparse?: bool,
  213.  *      storageEngine?: mixed[],
  214.  *      textIndexVersion?: int,
  215.  *      unique?: bool,
  216.  *      weights?: array{string, int},
  217.  * }
  218.  * @psalm-type IndexMapping = array{
  219.  *      keys: IndexKeys,
  220.  *      options: IndexOptions
  221.  * }
  222.  * @psalm-type ShardKeys = array<string, mixed>
  223.  * @psalm-type ShardOptions = array<string, mixed>
  224.  * @psalm-type ShardKey = array{
  225.  *      keys?: ShardKeys,
  226.  *      options?: ShardOptions
  227.  * }
  228.  * @final
  229.  * @template-covariant T of object
  230.  * @template-implements BaseClassMetadata<T>
  231.  */
  232. /* final */ class ClassMetadata implements BaseClassMetadata
  233. {
  234.     /* The Id generator types. */
  235.     /**
  236.      * AUTO means Doctrine will automatically create a new \MongoDB\BSON\ObjectId instance for us.
  237.      */
  238.     public const GENERATOR_TYPE_AUTO = 1;
  240.     /**
  241.      * INCREMENT means a separate collection is used for maintaining and incrementing id generation.
  242.      * Offers full portability.
  243.      */
  244.     public const GENERATOR_TYPE_INCREMENT = 2;
  246.     /**
  247.      * UUID means Doctrine will generate a uuid for us.
  248.      */
  249.     public const GENERATOR_TYPE_UUID = 3;
  251.     /**
  252.      * ALNUM means Doctrine will generate Alpha-numeric string identifiers, using the INCREMENT
  253.      * generator to ensure identifier uniqueness
  254.      */
  255.     public const GENERATOR_TYPE_ALNUM = 4;
  257.     /**
  258.      * CUSTOM means Doctrine expect a class parameter. It will then try to initiate that class
  259.      * and pass other options to the generator. It will throw an Exception if the class
  260.      * does not exist or if an option was passed for that there is not setter in the new
  261.      * generator class.
  262.      *
  263.      * The class will have to implement IdGenerator.
  264.      */
  265.     public const GENERATOR_TYPE_CUSTOM = 5;
  267.     /**
  268.      * NONE means Doctrine will not generate any id for us and you are responsible for manually
  269.      * assigning an id.
  270.      */
  271.     public const GENERATOR_TYPE_NONE = 6;
  273.     /**
  274.      * Default discriminator field name.
  275.      *
  276.      * This is used for associations value for associations where a that do not define a "targetDocument" or
  277.      * "discriminatorField" option in their mapping.
  278.      */
  279.     public const DEFAULT_DISCRIMINATOR_FIELD = '_doctrine_class_name';
  281.     /**
  282.      * Association types
  283.      */
  284.     public const REFERENCE_ONE  = 1;
  285.     public const REFERENCE_MANY = 2;
  286.     public const EMBED_ONE      = 3;
  287.     public const EMBED_MANY     = 4;
  289.     /**
  290.      * Mapping types
  291.      */
  292.     public const MANY = 'many';
  293.     public const ONE  = 'one';
  295.     /**
  296.      * The types of storeAs references
  297.      */
  298.     public const REFERENCE_STORE_AS_ID             = 'id';
  299.     public const REFERENCE_STORE_AS_DB_REF         = 'dbRef';
  300.     public const REFERENCE_STORE_AS_DB_REF_WITH_DB = 'dbRefWithDb';
  301.     public const REFERENCE_STORE_AS_REF            = 'ref';
  303.     /**
  304.      * The collection schema validationAction values
  305.      *
  306.      * @see https://docs.mongodb.com/manual/core/schema-validation/#accept-or-reject-invalid-documents
  307.      */
  308.     public const SCHEMA_VALIDATION_ACTION_ERROR = 'error';
  309.     public const SCHEMA_VALIDATION_ACTION_WARN  = 'warn';
  311.     /**
  312.      * The collection schema validationLevel values
  313.      *
  314.      * @see https://docs.mongodb.com/manual/core/schema-validation/#existing-documents
  315.      */
  316.     public const SCHEMA_VALIDATION_LEVEL_OFF      = 'off';
  317.     public const SCHEMA_VALIDATION_LEVEL_STRICT   = 'strict';
  318.     public const SCHEMA_VALIDATION_LEVEL_MODERATE = 'moderate';
  320.     /* The inheritance mapping types */
  321.     /**
  322.      * NONE means the class does not participate in an inheritance hierarchy
  323.      * and therefore does not need an inheritance mapping type.
  324.      */
  325.     public const INHERITANCE_TYPE_NONE = 1;
  327.     /**
  328.      * SINGLE_COLLECTION means the class will be persisted according to the rules of
  329.      * <tt>Single Collection Inheritance</tt>.
  330.      */
  331.     public const INHERITANCE_TYPE_SINGLE_COLLECTION = 2;
  333.     /**
  334.      * COLLECTION_PER_CLASS means the class will be persisted according to the rules
  335.      * of <tt>Concrete Collection Inheritance</tt>.
  336.      */
  337.     public const INHERITANCE_TYPE_COLLECTION_PER_CLASS = 3;
  339.     /**
  340.      * DEFERRED_IMPLICIT means that changes of entities are calculated at commit-time
  341.      * by doing a property-by-property comparison with the original data. This will
  342.      * be done for all entities that are in MANAGED state at commit-time.
  343.      *
  344.      * This is the default change tracking policy.
  345.      */
  346.     public const CHANGETRACKING_DEFERRED_IMPLICIT = 1;
  348.     /**
  349.      * DEFERRED_EXPLICIT means that changes of entities are calculated at commit-time
  350.      * by doing a property-by-property comparison with the original data. This will
  351.      * be done only for entities that were explicitly saved (through persist() or a cascade).
  352.      */
  353.     public const CHANGETRACKING_DEFERRED_EXPLICIT = 2;
  355.     /**
  356.      * NOTIFY means that Doctrine relies on the entities sending out notifications
  357.      * when their properties change. Such entity classes must implement
  358.      * the <tt>NotifyPropertyChanged</tt> interface.
  359.      *
  360.      * @deprecated
  361.      */
  362.     public const CHANGETRACKING_NOTIFY = 3;
  364.     /**
  365.      * SET means that fields will be written to the database using a $set operator
  366.      */
  367.     public const STORAGE_STRATEGY_SET = 'set';
  369.     /**
  370.      * INCREMENT means that fields will be written to the database by calculating
  371.      * the difference and using the $inc operator
  372.      */
  373.     public const STORAGE_STRATEGY_INCREMENT = 'increment';
  375.     public const STORAGE_STRATEGY_PUSH_ALL         = 'pushAll';
  376.     public const STORAGE_STRATEGY_ADD_TO_SET       = 'addToSet';
  377.     public const STORAGE_STRATEGY_ATOMIC_SET       = 'atomicSet';
  378.     public const STORAGE_STRATEGY_ATOMIC_SET_ARRAY = 'atomicSetArray';
  379.     public const STORAGE_STRATEGY_SET_ARRAY        = 'setArray';
  381.     private const ALLOWED_GRIDFS_FIELDS = ['_id', 'chunkSize', 'filename', 'length', 'metadata', 'uploadDate'];
  383.     /**
  384.      * READ-ONLY: The name of the mongo database the document is mapped to.
  385.      *
  386.      * @var string|null
  387.      */
  388.     public $db;
  390.     /**
  391.      * READ-ONLY: The name of the mongo collection the document is mapped to.
  392.      *
  393.      * @var string
  394.      */
  395.     public $collection;
  397.     /**
  398.      * READ-ONLY: The name of the GridFS bucket the document is mapped to.
  399.      *
  400.      * @var string
  401.      */
  402.     public $bucketName = 'fs';
  404.     /**
  405.      * READ-ONLY: If the collection should be a fixed size.
  406.      *
  407.      * @var bool
  408.      */
  409.     public $collectionCapped = false;
  411.     /**
  412.      * READ-ONLY: If the collection is fixed size, its size in bytes.
  413.      *
  414.      * @var int|null
  415.      */
  416.     public $collectionSize;
  418.     /**
  419.      * READ-ONLY: If the collection is fixed size, the maximum number of elements to store in the collection.
  420.      *
  421.      * @var int|null
  422.      */
  423.     public $collectionMax;
  425.     /**
  426.      * READ-ONLY Describes how MongoDB clients route read operations to the members of a replica set.
  427.      *
  428.      * @var string|null
  429.      */
  430.     public $readPreference;
  432.     /**
  433.      * READ-ONLY Associated with readPreference Allows to specify criteria so that your application can target read
  434.      * operations to specific members, based on custom parameters.
  435.      *
  436.      * @var array<array<string, string>>
  437.      */
  438.     public $readPreferenceTags = [];
  440.     /**
  441.      * READ-ONLY: Describes the level of acknowledgement requested from MongoDB for write operations.
  442.      *
  443.      * @var string|int|null
  444.      */
  445.     public $writeConcern;
  447.     /**
  448.      * READ-ONLY: The field name of the document identifier.
  449.      *
  450.      * @var string|null
  451.      */
  452.     public $identifier;
  454.     /**
  455.      * READ-ONLY: The array of indexes for the document collection.
  456.      *
  457.      * @var array<array<string, mixed>>
  458.      * @psalm-var array<IndexMapping>
  459.      */
  460.     public $indexes = [];
  462.     /**
  463.      * READ-ONLY: Keys and options describing shard key. Only for sharded collections.
  464.      *
  465.      * @var array<string, array>
  466.      * @psalm-var ShardKey
  467.      */
  468.     public $shardKey = [];
  470.     /**
  471.      * Allows users to specify a validation schema for the collection.
  472.      *
  473.      * @var array|object|null
  474.      * @psalm-var array<string, mixed>|object|null
  475.      */
  476.     private $validator;
  478.     /**
  479.      * Determines whether to error on invalid documents or just warn about the violations but allow invalid documents to be inserted.
  480.      *
  481.      * @var string
  482.      */
  483.     private $validationAction = self::SCHEMA_VALIDATION_ACTION_ERROR;
  485.     /**
  486.      * Determines how strictly MongoDB applies the validation rules to existing documents during an update.
  487.      */
  488.     private string $validationLevel = self::SCHEMA_VALIDATION_LEVEL_STRICT;
  490.     /**
  491.      * READ-ONLY: The name of the document class.
  492.      *
  493.      * @var string
  494.      * @psalm-var class-string<T>
  495.      */
  496.     public $name;
  498.     /**
  499.      * READ-ONLY: The name of the document class that is at the root of the mapped document inheritance
  500.      * hierarchy. If the document is not part of a mapped inheritance hierarchy this is the same
  501.      * as {@link $documentName}.
  502.      *
  503.      * @var string
  504.      * @psalm-var class-string
  505.      */
  506.     public $rootDocumentName;
  508.     /**
  509.      * The name of the custom repository class used for the document class.
  510.      * (Optional).
  511.      *
  512.      * @var string|null
  513.      * @psalm-var class-string|null
  514.      */
  515.     public $customRepositoryClassName;
  517.     /**
  518.      * READ-ONLY: The names of the parent classes (ancestors).
  519.      *
  520.      * @var array
  521.      * @psalm-var list<class-string>
  522.      */
  523.     public $parentClasses = [];
  525.     /**
  526.      * READ-ONLY: The names of all subclasses (descendants).
  527.      *
  528.      * @var array
  529.      * @psalm-var list<class-string>
  530.      */
  531.     public $subClasses = [];
  533.     /**
  534.      * The ReflectionProperty instances of the mapped class.
  535.      *
  536.      * @var ReflectionProperty[]
  537.      */
  538.     public $reflFields = [];
  540.     /**
  541.      * READ-ONLY: The inheritance mapping type used by the class.
  542.      *
  543.      * @var int
  544.      */
  545.     public $inheritanceType = self::INHERITANCE_TYPE_NONE;
  547.     /**
  548.      * READ-ONLY: The Id generator type used by the class.
  549.      *
  550.      * @var int
  551.      */
  552.     public $generatorType = self::GENERATOR_TYPE_AUTO;
  554.     /**
  555.      * READ-ONLY: The Id generator options.
  556.      *
  557.      * @var array<string, mixed>
  558.      */
  559.     public $generatorOptions = [];
  561.     /**
  562.      * READ-ONLY: The ID generator used for generating IDs for this class.
  563.      *
  564.      * @var IdGenerator|null
  565.      */
  566.     public $idGenerator;
  568.     /**
  569.      * READ-ONLY: The field mappings of the class.
  570.      * Keys are field names and values are mapping definitions.
  571.      *
  572.      * The mapping definition array has the following values:
  573.      *
  574.      * - <b>fieldName</b> (string)
  575.      * The name of the field in the Document.
  576.      *
  577.      * - <b>id</b> (boolean, optional)
  578.      * Marks the field as the primary key of the document. Multiple fields of an
  579.      * document can have the id attribute, forming a composite key.
  580.      *
  581.      * @var array<string, mixed>
  582.      * @psalm-var array<string, FieldMapping>
  583.      */
  584.     public $fieldMappings = [];
  586.     /**
  587.      * READ-ONLY: The association mappings of the class.
  588.      * Keys are field names and values are mapping definitions.
  589.      *
  590.      * @var array<string, mixed>
  591.      * @psalm-var array<string, AssociationFieldMapping>
  592.      */
  593.     public $associationMappings = [];
  595.     /**
  596.      * READ-ONLY: Array of fields to also load with a given method.
  597.      *
  598.      * @var array<string, mixed[]>
  599.      */
  600.     public $alsoLoadMethods = [];
  602.     /**
  603.      * READ-ONLY: The registered lifecycle callbacks for documents of this class.
  604.      *
  605.      * @var array<string, list<string>>
  606.      */
  607.     public $lifecycleCallbacks = [];
  609.     /**
  610.      * READ-ONLY: The discriminator value of this class.
  611.      *
  612.      * <b>This does only apply to the JOINED and SINGLE_COLLECTION inheritance mapping strategies
  613.      * where a discriminator field is used.</b>
  614.      *
  615.      * @see discriminatorField
  616.      *
  617.      * @var string|null
  618.      * @psalm-var class-string|null
  619.      */
  620.     public $discriminatorValue;
  622.     /**
  623.      * READ-ONLY: The discriminator map of all mapped classes in the hierarchy.
  624.      *
  625.      * <b>This does only apply to the SINGLE_COLLECTION inheritance mapping strategy
  626.      * where a discriminator field is used.</b>
  627.      *
  628.      * @see discriminatorField
  629.      *
  630.      * @psalm-var array<string, class-string>
  631.      */
  632.     public $discriminatorMap = [];
  634.     /**
  635.      * READ-ONLY: The definition of the discriminator field used in SINGLE_COLLECTION
  636.      * inheritance mapping.
  637.      *
  638.      * @var string|null
  639.      */
  640.     public $discriminatorField;
  642.     /**
  643.      * READ-ONLY: The default value for discriminatorField in case it's not set in the document
  644.      *
  645.      * @see discriminatorField
  646.      *
  647.      * @var string|null
  648.      */
  649.     public $defaultDiscriminatorValue;
  651.     /**
  652.      * READ-ONLY: Whether this class describes the mapping of a mapped superclass.
  653.      *
  654.      * @var bool
  655.      */
  656.     public $isMappedSuperclass = false;
  658.     /**
  659.      * READ-ONLY: Whether this class describes the mapping of a embedded document.
  660.      *
  661.      * @var bool
  662.      */
  663.     public $isEmbeddedDocument = false;
  665.     /**
  666.      * READ-ONLY: Whether this class describes the mapping of an aggregation result document.
  667.      *
  668.      * @var bool
  669.      */
  670.     public $isQueryResultDocument = false;
  672.     /**
  673.      * READ-ONLY: Whether this class describes the mapping of a database view.
  674.      */
  675.     private bool $isView = false;
  677.     /**
  678.      * READ-ONLY: Whether this class describes the mapping of a gridFS file
  679.      *
  680.      * @var bool
  681.      */
  682.     public $isFile = false;
  684.     /**
  685.      * READ-ONLY: The default chunk size in bytes for the file
  686.      *
  687.      * @var int|null
  688.      */
  689.     public $chunkSizeBytes;
  691.     /**
  692.      * READ-ONLY: The policy used for change-tracking on entities of this class.
  693.      *
  694.      * @var int
  695.      */
  696.     public $changeTrackingPolicy = self::CHANGETRACKING_DEFERRED_IMPLICIT;
  698.     /**
  699.      * READ-ONLY: A flag for whether or not instances of this class are to be versioned
  700.      * with optimistic locking.
  701.      *
  702.      * @var bool $isVersioned
  703.      */
  704.     public $isVersioned = false;
  706.     /**
  707.      * READ-ONLY: The name of the field which is used for versioning in optimistic locking (if any).
  708.      *
  709.      * @var string|null $versionField
  710.      */
  711.     public $versionField;
  713.     /**
  714.      * READ-ONLY: A flag for whether or not instances of this class are to allow pessimistic
  715.      * locking.
  716.      *
  717.      * @var bool $isLockable
  718.      */
  719.     public $isLockable = false;
  721.     /**
  722.      * READ-ONLY: The name of the field which is used for locking a document.
  723.      *
  724.      * @var mixed $lockField
  725.      */
  726.     public $lockField;
  728.     /**
  729.      * The ReflectionClass instance of the mapped class.
  730.      *
  731.      * @var ReflectionClass
  732.      * @psalm-var ReflectionClass<T>
  733.      */
  734.     public $reflClass;
  736.     /**
  737.      * READ_ONLY: A flag for whether or not this document is read-only.
  738.      *
  739.      * @var bool
  740.      */
  741.     public $isReadOnly;
  743.     private InstantiatorInterface $instantiator;
  745.     private ReflectionService $reflectionService;
  747.     /**
  748.      * @var string|null
  749.      * @psalm-var class-string|null
  750.      */
  751.     private $rootClass;
  753.     /**
  754.      * Initializes a new ClassMetadata instance that will hold the object-document mapping
  755.      * metadata of the class with the given name.
  756.      *
  757.      * @psalm-param class-string<T> $documentName
  758.      */
  759.     public function __construct(string $documentName)
  760.     {
  761.         $this->name              = $documentName;
  762.         $this->rootDocumentName  = $documentName;
  763.         $this->reflectionService = new RuntimeReflectionService();
  764.         $this->reflClass         = new ReflectionClass($documentName);
  765.         $this->setCollection($this->reflClass->getShortName());
  766.         $this->instantiator = new Instantiator();
  767.     }
  769.     /**
  770.      * Helper method to get reference id of ref* type references
  771.      *
  772.      * @internal
  773.      *
  774.      * @param mixed $reference
  775.      *
  776.      * @return mixed
  777.      */
  778.     public static function getReferenceId($reference, string $storeAs)
  779.     {
  780.         return $storeAs === self::REFERENCE_STORE_AS_ID ? $reference : $reference[self::getReferencePrefix($storeAs) . 'id'];
  781.     }
  783.     /**
  784.      * Returns the reference prefix used for a reference
  785.      */
  786.     private static function getReferencePrefix(string $storeAs): string
  787.     {
  788.         if (! in_array($storeAs, [self::REFERENCE_STORE_AS_REF, self::REFERENCE_STORE_AS_DB_REF, self::REFERENCE_STORE_AS_DB_REF_WITH_DB])) {
  789.             throw new LogicException('Can only get a reference prefix for DBRef and reference arrays');
  790.         }
  792.         return $storeAs === self::REFERENCE_STORE_AS_REF ? '' : '$';
  793.     }
  795.     /**
  796.      * Returns a fully qualified field name for a given reference
  797.      *
  798.      * @internal
  799.      *
  800.      * @param string $pathPrefix The field path prefix
  801.      */
  802.     public static function getReferenceFieldName(string $storeAs, string $pathPrefix = ''): string
  803.     {
  804.         if ($storeAs === self::REFERENCE_STORE_AS_ID) {
  805.             return $pathPrefix;
  806.         }
  808.         return ($pathPrefix ? $pathPrefix . '.' : '') . static::getReferencePrefix($storeAs) . 'id';
  809.     }
  811.     public function getReflectionClass(): ReflectionClass
  812.     {
  813.         return $this->reflClass;
  814.     }
  816.     /** @param string $fieldName */
  817.     public function isIdentifier($fieldName): bool
  818.     {
  819.         return $this->identifier === $fieldName;
  820.     }
  822.     /**
  823.      * Sets the mapped identifier field of this class.
  824.      *
  825.      * @internal
  826.      */
  827.     public function setIdentifier(?string $identifier): void
  828.     {
  829.         $this->identifier = $identifier;
  830.     }
  832.     /**
  833.      * Since MongoDB only allows exactly one identifier field
  834.      * this will always return an array with only one value
  835.      *
  836.      * @return array<string|null>
  837.      */
  838.     public function getIdentifier(): array
  839.     {
  840.         return [$this->identifier];
  841.     }
  843.     /**
  844.      * Since MongoDB only allows exactly one identifier field
  845.      * this will always return an array with only one value
  846.      *
  847.      * @return array<string|null>
  848.      */
  849.     public function getIdentifierFieldNames(): array
  850.     {
  851.         return [$this->identifier];
  852.     }
  854.     /** @param string $fieldName */
  855.     public function hasField($fieldName): bool
  856.     {
  857.         return isset($this->fieldMappings[$fieldName]);
  858.     }
  860.     /**
  861.      * Sets the inheritance type used by the class and it's subclasses.
  862.      */
  863.     public function setInheritanceType(int $type): void
  864.     {
  865.         $this->inheritanceType = $type;
  866.     }
  868.     /**
  869.      * Checks whether a mapped field is inherited from an entity superclass.
  870.      */
  871.     public function isInheritedField(string $fieldName): bool
  872.     {
  873.         return isset($this->fieldMappings[$fieldName]['inherited']);
  874.     }
  876.     /**
  877.      * Registers a custom repository class for the document class.
  878.      *
  879.      * @psalm-param class-string|null $repositoryClassName
  880.      */
  881.     public function setCustomRepositoryClass(?string $repositoryClassName): void
  882.     {
  883.         if ($this->isEmbeddedDocument || $this->isQueryResultDocument) {
  884.             return;
  885.         }
  887.         $this->customRepositoryClassName = $repositoryClassName;
  888.     }
  890.     /**
  891.      * Dispatches the lifecycle event of the given document by invoking all
  892.      * registered callbacks.
  893.      *
  894.      * @param mixed[]|null $arguments
  895.      *
  896.      * @throws InvalidArgumentException If document class is not this class or
  897.      *                                   a Proxy of this class.
  898.      */
  899.     public function invokeLifecycleCallbacks(string $event, object $document, ?array $arguments = null): void
  900.     {
  901.         if ($this->isView()) {
  902.             return;
  903.         }
  905.         if (! $document instanceof $this->name) {
  906.             throw new InvalidArgumentException(sprintf('Expected document class "%s"; found: "%s"', $this->name, get_class($document)));
  907.         }
  909.         if (empty($this->lifecycleCallbacks[$event])) {
  910.             return;
  911.         }
  913.         foreach ($this->lifecycleCallbacks[$event] as $callback) {
  914.             if ($arguments !== null) {
  915.                 $document->$callback(...$arguments);
  916.             } else {
  917.                 $document->$callback();
  918.             }
  919.         }
  920.     }
  922.     /**
  923.      * Checks whether the class has callbacks registered for a lifecycle event.
  924.      */
  925.     public function hasLifecycleCallbacks(string $event): bool
  926.     {
  927.         return ! empty($this->lifecycleCallbacks[$event]);
  928.     }
  930.     /**
  931.      * Gets the registered lifecycle callbacks for an event.
  932.      *
  933.      * @return list<string>
  934.      */
  935.     public function getLifecycleCallbacks(string $event): array
  936.     {
  937.         return $this->lifecycleCallbacks[$event] ?? [];
  938.     }
  940.     /**
  941.      * Adds a lifecycle callback for documents of this class.
  942.      *
  943.      * If the callback is already registered, this is a NOOP.
  944.      */
  945.     public function addLifecycleCallback(string $callback, string $event): void
  946.     {
  947.         if (isset($this->lifecycleCallbacks[$event]) && in_array($callback, $this->lifecycleCallbacks[$event])) {
  948.             return;
  949.         }
  951.         $this->lifecycleCallbacks[$event][] = $callback;
  952.     }
  954.     /**
  955.      * Sets the lifecycle callbacks for documents of this class.
  956.      *
  957.      * Any previously registered callbacks are overwritten.
  958.      *
  959.      * @param array<string, list<string>> $callbacks
  960.      */
  961.     public function setLifecycleCallbacks(array $callbacks): void
  962.     {
  963.         $this->lifecycleCallbacks = $callbacks;
  964.     }
  966.     /**
  967.      * Registers a method for loading document data before field hydration.
  968.      *
  969.      * Note: A method may be registered multiple times for different fields.
  970.      * it will be invoked only once for the first field found.
  971.      *
  972.      * @param array<string, mixed>|string $fields Database field name(s)
  973.      */
  974.     public function registerAlsoLoadMethod(string $method, $fields): void
  975.     {
  976.         $this->alsoLoadMethods[$method] = is_array($fields) ? $fields : [$fields];
  977.     }
  979.     /**
  980.      * Sets the AlsoLoad methods for documents of this class.
  981.      *
  982.      * Any previously registered methods are overwritten.
  983.      *
  984.      * @param array<string, mixed[]> $methods
  985.      */
  986.     public function setAlsoLoadMethods(array $methods): void
  987.     {
  988.         $this->alsoLoadMethods = $methods;
  989.     }
  991.     /**
  992.      * Sets the discriminator field.
  993.      *
  994.      * The field name is the the unmapped database field. Discriminator values
  995.      * are only used to discern the hydration class and are not mapped to class
  996.      * properties.
  997.      *
  998.      * @param array<string, mixed>|string|null $discriminatorField
  999.      * @psalm-param array{name?: string, fieldName?: string}|string|null $discriminatorField
  1000.      *
  1001.      * @throws MappingException If the discriminator field conflicts with the
  1002.      *                          "name" attribute of a mapped field.
  1003.      */
  1004.     public function setDiscriminatorField($discriminatorField): void
  1005.     {
  1006.         if ($this->isFile) {
  1007.             throw MappingException::discriminatorNotAllowedForGridFS($this->name);
  1008.         }
  1010.         if ($discriminatorField === null) {
  1011.             $this->discriminatorField = null;
  1013.             return;
  1014.         }
  1016.         // @todo: deprecate, document and remove this:
  1017.         // Handle array argument with name/fieldName keys for BC
  1018.         if (is_array($discriminatorField)) {
  1019.             if (isset($discriminatorField['name'])) {
  1020.                 $discriminatorField = $discriminatorField['name'];
  1021.             } elseif (isset($discriminatorField['fieldName'])) {
  1022.                 $discriminatorField = $discriminatorField['fieldName'];
  1023.             }
  1024.         }
  1026.         foreach ($this->fieldMappings as $fieldMapping) {
  1027.             if ($discriminatorField === $fieldMapping['name']) {
  1028.                 throw MappingException::discriminatorFieldConflict($this->name, $discriminatorField);
  1029.             }
  1030.         }
  1032.         $this->discriminatorField = $discriminatorField;
  1033.     }
  1035.     /**
  1036.      * Sets the discriminator values used by this class.
  1037.      * Used for JOINED and SINGLE_TABLE inheritance mapping strategies.
  1038.      *
  1039.      * @param array<string, class-string> $map
  1040.      *
  1041.      * @throws MappingException
  1042.      */
  1043.     public function setDiscriminatorMap(array $map): void
  1044.     {
  1045.         if ($this->isFile) {
  1046.             throw MappingException::discriminatorNotAllowedForGridFS($this->name);
  1047.         }
  1049.         $this->subClasses         = [];
  1050.         $this->discriminatorMap   = [];
  1051.         $this->discriminatorValue = null;
  1053.         foreach ($map as $value => $className) {
  1054.             $this->discriminatorMap[$value] = $className;
  1055.             if ($this->name === $className) {
  1056.                 $this->discriminatorValue = $value;
  1057.             } else {
  1058.                 if (! class_exists($className)) {
  1059.                     throw MappingException::invalidClassInDiscriminatorMap($className, $this->name);
  1060.                 }
  1062.                 if (is_subclass_of($className, $this->name)) {
  1063.                     $this->subClasses[] = $className;
  1064.                 }
  1065.             }
  1066.         }
  1067.     }
  1069.     /**
  1070.      * Sets the default discriminator value to be used for this class
  1071.      * Used for SINGLE_TABLE inheritance mapping strategies if the document has no discriminator value
  1072.      *
  1073.      * @throws MappingException
  1074.      */
  1075.     public function setDefaultDiscriminatorValue(?string $defaultDiscriminatorValue): void
  1076.     {
  1077.         if ($this->isFile) {
  1078.             throw MappingException::discriminatorNotAllowedForGridFS($this->name);
  1079.         }
  1081.         if ($defaultDiscriminatorValue === null) {
  1082.             $this->defaultDiscriminatorValue = null;
  1084.             return;
  1085.         }
  1087.         if (! array_key_exists($defaultDiscriminatorValue, $this->discriminatorMap)) {
  1088.             throw MappingException::invalidDiscriminatorValue($defaultDiscriminatorValue, $this->name);
  1089.         }
  1091.         $this->defaultDiscriminatorValue = $defaultDiscriminatorValue;
  1092.     }
  1094.     /**
  1095.      * Sets the discriminator value for this class.
  1096.      * Used for JOINED/SINGLE_TABLE inheritance and multiple document types in a single
  1097.      * collection.
  1098.      *
  1099.      * @throws MappingException
  1100.      */
  1101.     public function setDiscriminatorValue(string $value): void
  1102.     {
  1103.         if ($this->isFile) {
  1104.             throw MappingException::discriminatorNotAllowedForGridFS($this->name);
  1105.         }
  1107.         $this->discriminatorMap[$value] = $this->name;
  1108.         $this->discriminatorValue       = $value;
  1109.     }
  1111.     /**
  1112.      * Add a index for this Document.
  1113.      *
  1114.      * @param array<string, int|string> $keys
  1115.      * @psalm-param IndexKeys $keys
  1116.      * @psalm-param IndexOptions $options
  1117.      */
  1118.     public function addIndex(array $keys, array $options = []): void
  1119.     {
  1120.         $this->indexes[] = [
  1121.             'keys' => array_map(static function ($value) {
  1122.                 if ($value === 1 || $value === -1) {
  1123.                     return $value;
  1124.                 }
  1126.                 if (is_string($value)) {
  1127.                     $lower = strtolower($value);
  1128.                     if ($lower === 'asc') {
  1129.                         return 1;
  1130.                     }
  1132.                     if ($lower === 'desc') {
  1133.                         return -1;
  1134.                     }
  1135.                 }
  1137.                 return $value;
  1138.             }, $keys),
  1139.             'options' => $options,
  1140.         ];
  1141.     }
  1143.     /**
  1144.      * Returns the array of indexes for this Document.
  1145.      *
  1146.      * @psalm-return array<IndexMapping>
  1147.      */
  1148.     public function getIndexes(): array
  1149.     {
  1150.         return $this->indexes;
  1151.     }
  1153.     /**
  1154.      * Checks whether this document has indexes or not.
  1155.      */
  1156.     public function hasIndexes(): bool
  1157.     {
  1158.         return $this->indexes !== [];
  1159.     }
  1161.     /**
  1162.      * Set shard key for this Document.
  1163.      *
  1164.      * @param array<string, string|int> $keys
  1165.      * @param array<string, mixed>      $options
  1166.      * @psalm-param ShardKeys $keys
  1167.      * @psalm-param ShardOptions      $options
  1168.      *
  1169.      * @throws MappingException
  1170.      */
  1171.     public function setShardKey(array $keys, array $options = []): void
  1172.     {
  1173.         if ($this->inheritanceType === self::INHERITANCE_TYPE_SINGLE_COLLECTION && $this->shardKey !== []) {
  1174.             throw MappingException::shardKeyInSingleCollInheritanceSubclass($this->getName());
  1175.         }
  1177.         if ($this->isEmbeddedDocument) {
  1178.             throw MappingException::embeddedDocumentCantHaveShardKey($this->getName());
  1179.         }
  1181.         foreach (array_keys($keys) as $field) {
  1182.             if (! isset($this->fieldMappings[$field])) {
  1183.                 continue;
  1184.             }
  1186.             if (in_array($this->fieldMappings[$field]['type'], [self::MANY, Type::COLLECTION])) {
  1187.                 throw MappingException::noMultiKeyShardKeys($this->getName(), $field);
  1188.             }
  1190.             if ($this->fieldMappings[$field]['strategy'] !== self::STORAGE_STRATEGY_SET) {
  1191.                 throw MappingException::onlySetStrategyAllowedInShardKey($this->getName(), $field);
  1192.             }
  1193.         }
  1195.         $this->shardKey = [
  1196.             'keys' => array_map(static function ($value) {
  1197.                 if ($value === 1 || $value === -1) {
  1198.                     return $value;
  1199.                 }
  1201.                 if (is_string($value)) {
  1202.                     $lower = strtolower($value);
  1203.                     if ($lower === 'asc') {
  1204.                         return 1;
  1205.                     }
  1207.                     if ($lower === 'desc') {
  1208.                         return -1;
  1209.                     }
  1210.                 }
  1212.                 return $value;
  1213.             }, $keys),
  1214.             'options' => $options,
  1215.         ];
  1216.     }
  1218.     /** @psalm-return ShardKey */
  1219.     public function getShardKey(): array
  1220.     {
  1221.         return $this->shardKey;
  1222.     }
  1224.     /**
  1225.      * Checks whether this document has shard key or not.
  1226.      */
  1227.     public function isSharded(): bool
  1228.     {
  1229.         return $this->shardKey !== [];
  1230.     }
  1232.     /**
  1233.      * @return array|object|null
  1234.      * @psalm-return array<string, mixed>|object|null
  1235.      */
  1236.     public function getValidator()
  1237.     {
  1238.         return $this->validator;
  1239.     }
  1241.     /**
  1242.      * @param array|object|null $validator
  1243.      * @psalm-param array<string, mixed>|object|null $validator
  1244.      */
  1245.     public function setValidator($validator): void
  1246.     {
  1247.         $this->validator = $validator;
  1248.     }
  1250.     public function getValidationAction(): string
  1251.     {
  1252.         return $this->validationAction;
  1253.     }
  1255.     public function setValidationAction(string $validationAction): void
  1256.     {
  1257.         $this->validationAction = $validationAction;
  1258.     }
  1260.     public function getValidationLevel(): string
  1261.     {
  1262.         return $this->validationLevel;
  1263.     }
  1265.     public function setValidationLevel(string $validationLevel): void
  1266.     {
  1267.         $this->validationLevel = $validationLevel;
  1268.     }
  1270.     /**
  1271.      * Sets the read preference used by this class.
  1272.      *
  1273.      * @param array<array<string, string>> $tags
  1274.      */
  1275.     public function setReadPreference(?string $readPreference, array $tags): void
  1276.     {
  1277.         $this->readPreference     = $readPreference;
  1278.         $this->readPreferenceTags = $tags;
  1279.     }
  1281.     /**
  1282.      * Sets the write concern used by this class.
  1283.      *
  1284.      * @param string|int|null $writeConcern
  1285.      */
  1286.     public function setWriteConcern($writeConcern): void
  1287.     {
  1288.         $this->writeConcern = $writeConcern;
  1289.     }
  1291.     /** @return int|string|null */
  1292.     public function getWriteConcern()
  1293.     {
  1294.         return $this->writeConcern;
  1295.     }
  1297.     /**
  1298.      * Whether there is a write concern configured for this class.
  1299.      */
  1300.     public function hasWriteConcern(): bool
  1301.     {
  1302.         return $this->writeConcern !== null;
  1303.     }
  1305.     /**
  1306.      * Sets the change tracking policy used by this class.
  1307.      */
  1308.     public function setChangeTrackingPolicy(int $policy): void
  1309.     {
  1310.         $this->changeTrackingPolicy = $policy;
  1311.     }
  1313.     /**
  1314.      * Whether the change tracking policy of this class is "deferred explicit".
  1315.      */
  1316.     public function isChangeTrackingDeferredExplicit(): bool
  1317.     {
  1318.         return $this->changeTrackingPolicy === self::CHANGETRACKING_DEFERRED_EXPLICIT;
  1319.     }
  1321.     /**
  1322.      * Whether the change tracking policy of this class is "deferred implicit".
  1323.      */
  1324.     public function isChangeTrackingDeferredImplicit(): bool
  1325.     {
  1326.         return $this->changeTrackingPolicy === self::CHANGETRACKING_DEFERRED_IMPLICIT;
  1327.     }
  1329.     /**
  1330.      * Whether the change tracking policy of this class is "notify".
  1331.      *
  1332.      * @deprecated This method was deprecated in doctrine/mongodb-odm 2.4. Please use DEFERRED_EXPLICIT tracking
  1333.      * policy and isChangeTrackingDeferredImplicit method to detect it.
  1334.      */
  1335.     public function isChangeTrackingNotify(): bool
  1336.     {
  1337.         return $this->changeTrackingPolicy === self::CHANGETRACKING_NOTIFY;
  1338.     }
  1340.     /**
  1341.      * Gets the ReflectionProperties of the mapped class.
  1342.      *
  1343.      * @return ReflectionProperty[]
  1344.      */
  1345.     public function getReflectionProperties(): array
  1346.     {
  1347.         return $this->reflFields;
  1348.     }
  1350.     /**
  1351.      * Gets a ReflectionProperty for a specific field of the mapped class.
  1352.      */
  1353.     public function getReflectionProperty(string $name): ReflectionProperty
  1354.     {
  1355.         return $this->reflFields[$name];
  1356.     }
  1358.     /** @psalm-return class-string<T> */
  1359.     public function getName(): string
  1360.     {
  1361.         return $this->name;
  1362.     }
  1364.     /**
  1365.      * Returns the database this Document is mapped to.
  1366.      */
  1367.     public function getDatabase(): ?string
  1368.     {
  1369.         return $this->db;
  1370.     }
  1372.     /**
  1373.      * Set the database this Document is mapped to.
  1374.      */
  1375.     public function setDatabase(?string $db): void
  1376.     {
  1377.         $this->db = $db;
  1378.     }
  1380.     /**
  1381.      * Get the collection this Document is mapped to.
  1382.      */
  1383.     public function getCollection(): string
  1384.     {
  1385.         return $this->collection;
  1386.     }
  1388.     /**
  1389.      * Sets the collection this Document is mapped to.
  1390.      *
  1391.      * @param array|string $name
  1392.      * @psalm-param array{name: string, capped?: bool, size?: int, max?: int}|string $name
  1393.      *
  1394.      * @throws InvalidArgumentException
  1395.      */
  1396.     public function setCollection($name): void
  1397.     {
  1398.         if (is_array($name)) {
  1399.             if (! isset($name['name'])) {
  1400.                 throw new InvalidArgumentException('A name key is required when passing an array to setCollection()');
  1401.             }
  1403.             $this->collectionCapped = $name['capped'] ?? false;
  1404.             $this->collectionSize   = $name['size'] ?? 0;
  1405.             $this->collectionMax    = $name['max'] ?? 0;
  1406.             $this->collection       = $name['name'];
  1407.         } else {
  1408.             $this->collection = $name;
  1409.         }
  1410.     }
  1412.     public function getBucketName(): ?string
  1413.     {
  1414.         return $this->bucketName;
  1415.     }
  1417.     public function setBucketName(string $bucketName): void
  1418.     {
  1419.         $this->bucketName = $bucketName;
  1420.         $this->setCollection($bucketName . '.files');
  1421.     }
  1423.     public function getChunkSizeBytes(): ?int
  1424.     {
  1425.         return $this->chunkSizeBytes;
  1426.     }
  1428.     public function setChunkSizeBytes(int $chunkSizeBytes): void
  1429.     {
  1430.         $this->chunkSizeBytes = $chunkSizeBytes;
  1431.     }
  1433.     /**
  1434.      * Get whether or not the documents collection is capped.
  1435.      */
  1436.     public function getCollectionCapped(): bool
  1437.     {
  1438.         return $this->collectionCapped;
  1439.     }
  1441.     /**
  1442.      * Set whether or not the documents collection is capped.
  1443.      */
  1444.     public function setCollectionCapped(bool $bool): void
  1445.     {
  1446.         $this->collectionCapped = $bool;
  1447.     }
  1449.     /**
  1450.      * Get the collection size
  1451.      */
  1452.     public function getCollectionSize(): ?int
  1453.     {
  1454.         return $this->collectionSize;
  1455.     }
  1457.     /**
  1458.      * Set the collection size.
  1459.      */
  1460.     public function setCollectionSize(int $size): void
  1461.     {
  1462.         $this->collectionSize = $size;
  1463.     }
  1465.     /**
  1466.      * Get the collection max.
  1467.      */
  1468.     public function getCollectionMax(): ?int
  1469.     {
  1470.         return $this->collectionMax;
  1471.     }
  1473.     /**
  1474.      * Set the collection max.
  1475.      */
  1476.     public function setCollectionMax(int $max): void
  1477.     {
  1478.         $this->collectionMax = $max;
  1479.     }
  1481.     /**
  1482.      * Returns TRUE if this Document is mapped to a collection FALSE otherwise.
  1483.      */
  1484.     public function isMappedToCollection(): bool
  1485.     {
  1486.         return $this->collection !== '' && $this->collection !== null;
  1487.     }
  1489.     /**
  1490.      * Validates the storage strategy of a mapping for consistency
  1491.      *
  1492.      * @psalm-param FieldMappingConfig $mapping
  1493.      *
  1494.      * @throws MappingException
  1495.      */
  1496.     private function applyStorageStrategy(array &$mapping): void
  1497.     {
  1498.         if (! isset($mapping['type']) || isset($mapping['id'])) {
  1499.             return;
  1500.         }
  1502.         switch (true) {
  1503.             case $mapping['type'] === self::MANY:
  1504.                 $defaultStrategy   = CollectionHelper::DEFAULT_STRATEGY;
  1505.                 $allowedStrategies = [
  1506.                     self::STORAGE_STRATEGY_PUSH_ALL,
  1507.                     self::STORAGE_STRATEGY_ADD_TO_SET,
  1508.                     self::STORAGE_STRATEGY_SET,
  1509.                     self::STORAGE_STRATEGY_SET_ARRAY,
  1510.                     self::STORAGE_STRATEGY_ATOMIC_SET,
  1511.                     self::STORAGE_STRATEGY_ATOMIC_SET_ARRAY,
  1512.                 ];
  1513.                 break;
  1515.             case $mapping['type'] === self::ONE:
  1516.                 $defaultStrategy   = self::STORAGE_STRATEGY_SET;
  1517.                 $allowedStrategies = [self::STORAGE_STRATEGY_SET];
  1518.                 break;
  1520.             default:
  1521.                 $defaultStrategy   = self::STORAGE_STRATEGY_SET;
  1522.                 $allowedStrategies = [self::STORAGE_STRATEGY_SET];
  1523.                 $type              = Type::getType($mapping['type']);
  1524.                 if ($type instanceof Incrementable) {
  1525.                     $allowedStrategies[] = self::STORAGE_STRATEGY_INCREMENT;
  1526.                 }
  1527.         }
  1529.         if (! isset($mapping['strategy'])) {
  1530.             $mapping['strategy'] = $defaultStrategy;
  1531.         }
  1533.         if (! in_array($mapping['strategy'], $allowedStrategies)) {
  1534.             throw MappingException::invalidStorageStrategy($this->name, $mapping['fieldName'], $mapping['type'], $mapping['strategy']);
  1535.         }
  1537.         if (
  1538.             isset($mapping['reference']) && $mapping['type'] === self::MANY && $mapping['isOwningSide']
  1539.             && ! empty($mapping['sort']) && ! CollectionHelper::usesSet($mapping['strategy'])
  1540.         ) {
  1541.             throw MappingException::referenceManySortMustNotBeUsedWithNonSetCollectionStrategy($this->name, $mapping['fieldName'], $mapping['strategy']);
  1542.         }
  1543.     }
  1545.     /**
  1546.      * Map a single embedded document.
  1547.      *
  1548.      * @psalm-param FieldMappingConfig $mapping
  1549.      */
  1550.     public function mapOneEmbedded(array $mapping): void
  1551.     {
  1552.         $mapping['embedded'] = true;
  1553.         $mapping['type']     = self::ONE;
  1555.         $this->mapField($mapping);
  1556.     }
  1558.     /**
  1559.      * Map a collection of embedded documents.
  1560.      *
  1561.      * @psalm-param FieldMappingConfig $mapping
  1562.      */
  1563.     public function mapManyEmbedded(array $mapping): void
  1564.     {
  1565.         $mapping['embedded'] = true;
  1566.         $mapping['type']     = self::MANY;
  1568.         $this->mapField($mapping);
  1569.     }
  1571.     /**
  1572.      * Map a single document reference.
  1573.      *
  1574.      * @psalm-param FieldMappingConfig $mapping
  1575.      */
  1576.     public function mapOneReference(array $mapping): void
  1577.     {
  1578.         $mapping['reference'] = true;
  1579.         $mapping['type']      = self::ONE;
  1581.         $this->mapField($mapping);
  1582.     }
  1584.     /**
  1585.      * Map a collection of document references.
  1586.      *
  1587.      * @psalm-param FieldMappingConfig $mapping
  1588.      */
  1589.     public function mapManyReference(array $mapping): void
  1590.     {
  1591.         $mapping['reference'] = true;
  1592.         $mapping['type']      = self::MANY;
  1594.         $this->mapField($mapping);
  1595.     }
  1597.     /**
  1598.      * Adds a field mapping without completing/validating it.
  1599.      * This is mainly used to add inherited field mappings to derived classes.
  1600.      *
  1601.      * @internal
  1602.      *
  1603.      * @psalm-param FieldMapping $fieldMapping
  1604.      */
  1605.     public function addInheritedFieldMapping(array $fieldMapping): void
  1606.     {
  1607.         $this->fieldMappings[$fieldMapping['fieldName']] = $fieldMapping;
  1609.         if (! isset($fieldMapping['association'])) {
  1610.             return;
  1611.         }
  1613.         $this->associationMappings[$fieldMapping['fieldName']] = $fieldMapping;
  1614.     }
  1616.     /**
  1617.      * Adds an association mapping without completing/validating it.
  1618.      * This is mainly used to add inherited association mappings to derived classes.
  1619.      *
  1620.      * @internal
  1621.      *
  1622.      * @psalm-param AssociationFieldMapping $mapping
  1623.      *
  1624.      * @throws MappingException
  1625.      */
  1626.     public function addInheritedAssociationMapping(array $mapping): void
  1627.     {
  1628.         $this->associationMappings[$mapping['fieldName']] = $mapping;
  1629.     }
  1631.     /**
  1632.      * Checks whether the class has a mapped association with the given field name.
  1633.      */
  1634.     public function hasReference(string $fieldName): bool
  1635.     {
  1636.         return isset($this->fieldMappings[$fieldName]['reference']);
  1637.     }
  1639.     /**
  1640.      * Checks whether the class has a mapped embed with the given field name.
  1641.      */
  1642.     public function hasEmbed(string $fieldName): bool
  1643.     {
  1644.         return isset($this->fieldMappings[$fieldName]['embedded']);
  1645.     }
  1647.     /**
  1648.      * Checks whether the class has a mapped association (embed or reference) with the given field name.
  1649.      *
  1650.      * @param string $fieldName
  1651.      */
  1652.     public function hasAssociation($fieldName): bool
  1653.     {
  1654.         return $this->hasReference($fieldName) || $this->hasEmbed($fieldName);
  1655.     }
  1657.     /**
  1658.      * Checks whether the class has a mapped reference or embed for the specified field and
  1659.      * is a single valued association.
  1660.      *
  1661.      * @param string $fieldName
  1662.      */
  1663.     public function isSingleValuedAssociation($fieldName): bool
  1664.     {
  1665.         return $this->isSingleValuedReference($fieldName) || $this->isSingleValuedEmbed($fieldName);
  1666.     }
  1668.     /**
  1669.      * Checks whether the class has a mapped reference or embed for the specified field and
  1670.      * is a collection valued association.
  1671.      *
  1672.      * @param string $fieldName
  1673.      */
  1674.     public function isCollectionValuedAssociation($fieldName): bool
  1675.     {
  1676.         return $this->isCollectionValuedReference($fieldName) || $this->isCollectionValuedEmbed($fieldName);
  1677.     }
  1679.     /**
  1680.      * Checks whether the class has a mapped association for the specified field
  1681.      * and if yes, checks whether it is a single-valued association (to-one).
  1682.      */
  1683.     public function isSingleValuedReference(string $fieldName): bool
  1684.     {
  1685.         return isset($this->fieldMappings[$fieldName]['association']) &&
  1686.             $this->fieldMappings[$fieldName]['association'] === self::REFERENCE_ONE;
  1687.     }
  1689.     /**
  1690.      * Checks whether the class has a mapped association for the specified field
  1691.      * and if yes, checks whether it is a collection-valued association (to-many).
  1692.      */
  1693.     public function isCollectionValuedReference(string $fieldName): bool
  1694.     {
  1695.         return isset($this->fieldMappings[$fieldName]['association']) &&
  1696.             $this->fieldMappings[$fieldName]['association'] === self::REFERENCE_MANY;
  1697.     }
  1699.     /**
  1700.      * Checks whether the class has a mapped embedded document for the specified field
  1701.      * and if yes, checks whether it is a single-valued association (to-one).
  1702.      */
  1703.     public function isSingleValuedEmbed(string $fieldName): bool
  1704.     {
  1705.         return isset($this->fieldMappings[$fieldName]['association']) &&
  1706.             $this->fieldMappings[$fieldName]['association'] === self::EMBED_ONE;
  1707.     }
  1709.     /**
  1710.      * Checks whether the class has a mapped embedded document for the specified field
  1711.      * and if yes, checks whether it is a collection-valued association (to-many).
  1712.      */
  1713.     public function isCollectionValuedEmbed(string $fieldName): bool
  1714.     {
  1715.         return isset($this->fieldMappings[$fieldName]['association']) &&
  1716.             $this->fieldMappings[$fieldName]['association'] === self::EMBED_MANY;
  1717.     }
  1719.     /**
  1720.      * Sets the ID generator used to generate IDs for instances of this class.
  1721.      */
  1722.     public function setIdGenerator(IdGenerator $generator): void
  1723.     {
  1724.         $this->idGenerator = $generator;
  1725.     }
  1727.     /**
  1728.      * Casts the identifier to its portable PHP type.
  1729.      *
  1730.      * @param mixed $id
  1731.      *
  1732.      * @return mixed $id
  1733.      */
  1734.     public function getPHPIdentifierValue($id)
  1735.     {
  1736.         $idType = $this->fieldMappings[$this->identifier]['type'];
  1738.         return Type::getType($idType)->convertToPHPValue($id);
  1739.     }
  1741.     /**
  1742.      * Casts the identifier to its database type.
  1743.      *
  1744.      * @param mixed $id
  1745.      *
  1746.      * @return mixed $id
  1747.      */
  1748.     public function getDatabaseIdentifierValue($id)
  1749.     {
  1750.         $idType = $this->fieldMappings[$this->identifier]['type'];
  1752.         return Type::getType($idType)->convertToDatabaseValue($id);
  1753.     }
  1755.     /**
  1756.      * Sets the document identifier of a document.
  1757.      *
  1758.      * The value will be converted to a PHP type before being set.
  1759.      *
  1760.      * @param mixed $id
  1761.      */
  1762.     public function setIdentifierValue(object $document, $id): void
  1763.     {
  1764.         $id = $this->getPHPIdentifierValue($id);
  1765.         $this->reflFields[$this->identifier]->setValue($document, $id);
  1766.     }
  1768.     /**
  1769.      * Gets the document identifier as a PHP type.
  1770.      *
  1771.      * @return mixed $id
  1772.      */
  1773.     public function getIdentifierValue(object $document)
  1774.     {
  1775.         return $this->reflFields[$this->identifier]->getValue($document);
  1776.     }
  1778.     /**
  1779.      * Since MongoDB only allows exactly one identifier field this is a proxy
  1780.      * to {@see getIdentifierValue()} and returns an array with the identifier
  1781.      * field as a key.
  1782.      *
  1783.      * @param object $object
  1784.      */
  1785.     public function getIdentifierValues($object): array
  1786.     {
  1787.         return [$this->identifier => $this->getIdentifierValue($object)];
  1788.     }
  1790.     /**
  1791.      * Get the document identifier object as a database type.
  1792.      *
  1793.      * @return mixed $id
  1794.      */
  1795.     public function getIdentifierObject(object $document)
  1796.     {
  1797.         return $this->getDatabaseIdentifierValue($this->getIdentifierValue($document));
  1798.     }
  1800.     /**
  1801.      * Sets the specified field to the specified value on the given document.
  1802.      *
  1803.      * @param mixed $value
  1804.      */
  1805.     public function setFieldValue(object $document, string $field, $value): void
  1806.     {
  1807.         if ($document instanceof GhostObjectInterface && ! $document->isProxyInitialized()) {
  1808.             //property changes to an uninitialized proxy will not be tracked or persisted,
  1809.             //so the proxy needs to be loaded first.
  1810.             $document->initializeProxy();
  1811.         }
  1813.         $this->reflFields[$field]->setValue($document, $value);
  1814.     }
  1816.     /**
  1817.      * Gets the specified field's value off the given document.
  1818.      *
  1819.      * @return mixed
  1820.      */
  1821.     public function getFieldValue(object $document, string $field)
  1822.     {
  1823.         if ($document instanceof GhostObjectInterface && $field !== $this->identifier && ! $document->isProxyInitialized()) {
  1824.             $document->initializeProxy();
  1825.         }
  1827.         return $this->reflFields[$field]->getValue($document);
  1828.     }
  1830.     /**
  1831.      * Gets the mapping of a field.
  1832.      *
  1833.      * @psalm-return FieldMapping
  1834.      *
  1835.      * @throws MappingException If the $fieldName is not found in the fieldMappings array.
  1836.      */
  1837.     public function getFieldMapping(string $fieldName): array
  1838.     {
  1839.         if (! isset($this->fieldMappings[$fieldName])) {
  1840.             throw MappingException::mappingNotFound($this->name, $fieldName);
  1841.         }
  1843.         return $this->fieldMappings[$fieldName];
  1844.     }
  1846.     /**
  1847.      * Gets mappings of fields holding embedded document(s).
  1848.      *
  1849.      * @psalm-return array<string, FieldMapping>
  1850.      */
  1851.     public function getEmbeddedFieldsMappings(): array
  1852.     {
  1853.         return array_filter(
  1854.             $this->associationMappings,
  1855.             static fn ($assoc) => ! empty($assoc['embedded'])
  1856.         );
  1857.     }
  1859.     /**
  1860.      * Gets the field mapping by its DB name.
  1861.      * E.g. it returns identifier's mapping when called with _id.
  1862.      *
  1863.      * @psalm-return FieldMapping
  1864.      *
  1865.      * @throws MappingException
  1866.      */
  1867.     public function getFieldMappingByDbFieldName(string $dbFieldName): array
  1868.     {
  1869.         foreach ($this->fieldMappings as $mapping) {
  1870.             if ($mapping['name'] === $dbFieldName) {
  1871.                 return $mapping;
  1872.             }
  1873.         }
  1875.         throw MappingException::mappingNotFoundByDbName($this->name, $dbFieldName);
  1876.     }
  1878.     /**
  1879.      * Check if the field is not null.
  1880.      */
  1881.     public function isNullable(string $fieldName): bool
  1882.     {
  1883.         $mapping = $this->getFieldMapping($fieldName);
  1885.         return isset($mapping['nullable']) && $mapping['nullable'] === true;
  1886.     }
  1888.     /**
  1889.      * Checks whether the document has a discriminator field and value configured.
  1890.      */
  1891.     public function hasDiscriminator(): bool
  1892.     {
  1893.         return isset($this->discriminatorField, $this->discriminatorValue);
  1894.     }
  1896.     /**
  1897.      * Sets the type of Id generator to use for the mapped class.
  1898.      */
  1899.     public function setIdGeneratorType(int $generatorType): void
  1900.     {
  1901.         $this->generatorType = $generatorType;
  1902.     }
  1904.     /**
  1905.      * Sets the Id generator options.
  1906.      *
  1907.      * @param array<string, mixed> $generatorOptions
  1908.      */
  1909.     public function setIdGeneratorOptions(array $generatorOptions): void
  1910.     {
  1911.         $this->generatorOptions = $generatorOptions;
  1912.     }
  1914.     public function isInheritanceTypeNone(): bool
  1915.     {
  1916.         return $this->inheritanceType === self::INHERITANCE_TYPE_NONE;
  1917.     }
  1919.     /**
  1920.      * Checks whether the mapped class uses the SINGLE_COLLECTION inheritance mapping strategy.
  1921.      */
  1922.     public function isInheritanceTypeSingleCollection(): bool
  1923.     {
  1924.         return $this->inheritanceType === self::INHERITANCE_TYPE_SINGLE_COLLECTION;
  1925.     }
  1927.     /**
  1928.      * Checks whether the mapped class uses the COLLECTION_PER_CLASS inheritance mapping strategy.
  1929.      */
  1930.     public function isInheritanceTypeCollectionPerClass(): bool
  1931.     {
  1932.         return $this->inheritanceType === self::INHERITANCE_TYPE_COLLECTION_PER_CLASS;
  1933.     }
  1935.     /**
  1936.      * Sets the mapped subclasses of this class.
  1937.      *
  1938.      * @param string[] $subclasses The names of all mapped subclasses.
  1939.      * @psalm-param class-string[] $subclasses
  1940.      */
  1941.     public function setSubclasses(array $subclasses): void
  1942.     {
  1943.         foreach ($subclasses as $subclass) {
  1944.             $this->subClasses[] = $subclass;
  1945.         }
  1946.     }
  1948.     /**
  1949.      * Sets the parent class names.
  1950.      * Assumes that the class names in the passed array are in the order:
  1951.      * directParent -> directParentParent -> directParentParentParent ... -> root.
  1952.      *
  1953.      * @param string[] $classNames
  1954.      * @psalm-param list<class-string> $classNames
  1955.      */
  1956.     public function setParentClasses(array $classNames): void
  1957.     {
  1958.         $this->parentClasses = $classNames;
  1960.         if (count($classNames) <= 0) {
  1961.             return;
  1962.         }
  1964.         $this->rootDocumentName = (string) array_pop($classNames);
  1965.     }
  1967.     /**
  1968.      * Checks whether the class will generate a new \MongoDB\BSON\ObjectId instance for us.
  1969.      */
  1970.     public function isIdGeneratorAuto(): bool
  1971.     {
  1972.         return $this->generatorType === self::GENERATOR_TYPE_AUTO;
  1973.     }
  1975.     /**
  1976.      * Checks whether the class will use a collection to generate incremented identifiers.
  1977.      */
  1978.     public function isIdGeneratorIncrement(): bool
  1979.     {
  1980.         return $this->generatorType === self::GENERATOR_TYPE_INCREMENT;
  1981.     }
  1983.     /**
  1984.      * Checks whether the class will generate a uuid id.
  1985.      */
  1986.     public function isIdGeneratorUuid(): bool
  1987.     {
  1988.         return $this->generatorType === self::GENERATOR_TYPE_UUID;
  1989.     }
  1991.     /**
  1992.      * Checks whether the class uses no id generator.
  1993.      */
  1994.     public function isIdGeneratorNone(): bool
  1995.     {
  1996.         return $this->generatorType === self::GENERATOR_TYPE_NONE;
  1997.     }
  1999.     /**
  2000.      * Sets the version field mapping used for versioning. Sets the default
  2001.      * value to use depending on the column type.
  2002.      *
  2003.      * @psalm-param FieldMapping $mapping
  2004.      *
  2005.      * @throws LockException
  2006.      */
  2007.     public function setVersionMapping(array &$mapping): void
  2008.     {
  2009.         if (! Type::getType($mapping['type']) instanceof Versionable) {
  2010.             throw LockException::invalidVersionFieldType($mapping['type']);
  2011.         }
  2013.         $this->isVersioned  = true;
  2014.         $this->versionField = $mapping['fieldName'];
  2015.     }
  2017.     /**
  2018.      * Sets whether this class is to be versioned for optimistic locking.
  2019.      */
  2020.     public function setVersioned(bool $bool): void
  2021.     {
  2022.         $this->isVersioned = $bool;
  2023.     }
  2025.     /**
  2026.      * Sets the name of the field that is to be used for versioning if this class is
  2027.      * versioned for optimistic locking.
  2028.      */
  2029.     public function setVersionField(?string $versionField): void
  2030.     {
  2031.         $this->versionField = $versionField;
  2032.     }
  2034.     /**
  2035.      * Sets the version field mapping used for versioning. Sets the default
  2036.      * value to use depending on the column type.
  2037.      *
  2038.      * @psalm-param FieldMapping $mapping
  2039.      *
  2040.      * @throws LockException
  2041.      */
  2042.     public function setLockMapping(array &$mapping): void
  2043.     {
  2044.         if ($mapping['type'] !== 'int') {
  2045.             throw LockException::invalidLockFieldType($mapping['type']);
  2046.         }
  2048.         $this->isLockable = true;
  2049.         $this->lockField  = $mapping['fieldName'];
  2050.     }
  2052.     /**
  2053.      * Sets whether this class is to allow pessimistic locking.
  2054.      */
  2055.     public function setLockable(bool $bool): void
  2056.     {
  2057.         $this->isLockable = $bool;
  2058.     }
  2060.     /**
  2061.      * Sets the name of the field that is to be used for storing whether a document
  2062.      * is currently locked or not.
  2063.      */
  2064.     public function setLockField(string $lockField): void
  2065.     {
  2066.         $this->lockField = $lockField;
  2067.     }
  2069.     /**
  2070.      * Marks this class as read only, no change tracking is applied to it.
  2071.      */
  2072.     public function markReadOnly(): void
  2073.     {
  2074.         $this->isReadOnly = true;
  2075.     }
  2077.     public function getRootClass(): ?string
  2078.     {
  2079.         return $this->rootClass;
  2080.     }
  2082.     public function isView(): bool
  2083.     {
  2084.         return $this->isView;
  2085.     }
  2087.     /** @psalm-param class-string $rootClass */
  2088.     public function markViewOf(string $rootClass): void
  2089.     {
  2090.         $this->isView    = true;
  2091.         $this->rootClass = $rootClass;
  2092.     }
  2094.     public function getFieldNames(): array
  2095.     {
  2096.         return array_keys($this->fieldMappings);
  2097.     }
  2099.     public function getAssociationNames(): array
  2100.     {
  2101.         return array_keys($this->associationMappings);
  2102.     }
  2104.     /** @param string $fieldName */
  2105.     public function getTypeOfField($fieldName): ?string
  2106.     {
  2107.         return isset($this->fieldMappings[$fieldName]) ?
  2108.             $this->fieldMappings[$fieldName]['type'] : null;
  2109.     }
  2111.     /**
  2112.      * @param string $assocName
  2113.      *
  2114.      * @psalm-return class-string|null
  2115.      */
  2116.     public function getAssociationTargetClass($assocName): ?string
  2117.     {
  2118.         if (! isset($this->associationMappings[$assocName])) {
  2119.             throw new InvalidArgumentException("Association name expected, '" . $assocName . "' is not an association.");
  2120.         }
  2122.         return $this->associationMappings[$assocName]['targetDocument'] ?? null;
  2123.     }
  2125.     /**
  2126.      * Retrieve the collectionClass associated with an association
  2127.      *
  2128.      * @psalm-return class-string
  2129.      */
  2130.     public function getAssociationCollectionClass(string $assocName): string
  2131.     {
  2132.         if (! isset($this->associationMappings[$assocName])) {
  2133.             throw new InvalidArgumentException("Association name expected, '" . $assocName . "' is not an association.");
  2134.         }
  2136.         if (! array_key_exists('collectionClass', $this->associationMappings[$assocName])) {
  2137.             throw new InvalidArgumentException("collectionClass can only be applied to 'embedMany' and 'referenceMany' associations.");
  2138.         }
  2140.         return $this->associationMappings[$assocName]['collectionClass'];
  2141.     }
  2143.     /** @param string $assocName */
  2144.     public function isAssociationInverseSide($assocName): bool
  2145.     {
  2146.         throw new BadMethodCallException(__METHOD__ . '() is not implemented yet.');
  2147.     }
  2149.     /** @param string $assocName */
  2150.     public function getAssociationMappedByTargetField($assocName)
  2151.     {
  2152.         throw new BadMethodCallException(__METHOD__ . '() is not implemented yet.');
  2153.     }
  2155.     /**
  2156.      * Map a field.
  2157.      *
  2158.      * @psalm-param FieldMappingConfig $mapping
  2159.      *
  2160.      * @psalm-return FieldMapping
  2161.      *
  2162.      * @throws MappingException
  2163.      */
  2164.     public function mapField(array $mapping): array
  2165.     {
  2166.         if (! isset($mapping['fieldName']) && isset($mapping['name'])) {
  2167.             $mapping['fieldName'] = $mapping['name'];
  2168.         }
  2170.         if ($this->isTypedProperty($mapping['fieldName'])) {
  2171.             $mapping = $this->validateAndCompleteTypedFieldMapping($mapping);
  2173.             if (isset($mapping['type']) && $mapping['type'] === self::MANY) {
  2174.                 $mapping = $this->validateAndCompleteTypedManyAssociationMapping($mapping);
  2175.             }
  2176.         }
  2178.         if (! isset($mapping['fieldName']) || ! is_string($mapping['fieldName'])) {
  2179.             throw MappingException::missingFieldName($this->name);
  2180.         }
  2182.         if (! isset($mapping['name'])) {
  2183.             $mapping['name'] = $mapping['fieldName'];
  2184.         }
  2186.         if ($this->identifier === $mapping['name'] && empty($mapping['id'])) {
  2187.             throw MappingException::mustNotChangeIdentifierFieldsType($this->name, (string) $mapping['name']);
  2188.         }
  2190.         if ($this->discriminatorField !== null && $this->discriminatorField === $mapping['name']) {
  2191.             throw MappingException::discriminatorFieldConflict($this->name, $this->discriminatorField);
  2192.         }
  2194.         if (isset($mapping['collectionClass'])) {
  2195.             $mapping['collectionClass'] = ltrim($mapping['collectionClass'], '\\');
  2196.         }
  2198.         if (! empty($mapping['collectionClass'])) {
  2199.             $rColl = new ReflectionClass($mapping['collectionClass']);
  2200.             if (! $rColl->implementsInterface(Collection::class)) {
  2201.                 throw MappingException::collectionClassDoesNotImplementCommonInterface($this->name, $mapping['fieldName'], $mapping['collectionClass']);
  2202.             }
  2203.         }
  2205.         if (isset($mapping['cascade']) && isset($mapping['embedded'])) {
  2206.             throw MappingException::cascadeOnEmbeddedNotAllowed($this->name, $mapping['fieldName']);
  2207.         }
  2209.         $cascades = isset($mapping['cascade']) ? array_map('strtolower', (array) $mapping['cascade']) : [];
  2211.         if (in_array('all', $cascades) || isset($mapping['embedded'])) {
  2212.             $cascades = ['remove', 'persist', 'refresh', 'merge', 'detach'];
  2213.         }
  2215.         if (isset($mapping['embedded'])) {
  2216.             unset($mapping['cascade']);
  2217.         } elseif (isset($mapping['cascade'])) {
  2218.             $mapping['cascade'] = $cascades;
  2219.         }
  2221.         $mapping['isCascadeRemove']  = in_array('remove', $cascades);
  2222.         $mapping['isCascadePersist'] = in_array('persist', $cascades);
  2223.         $mapping['isCascadeRefresh'] = in_array('refresh', $cascades);
  2224.         $mapping['isCascadeMerge']   = in_array('merge', $cascades);
  2225.         $mapping['isCascadeDetach']  = in_array('detach', $cascades);
  2227.         if (isset($mapping['id']) && $mapping['id'] === true) {
  2228.             $mapping['name']  = '_id';
  2229.             $this->identifier = $mapping['fieldName'];
  2230.             if (isset($mapping['strategy'])) {
  2231.                 $this->generatorType = constant(self::class . '::GENERATOR_TYPE_' . strtoupper($mapping['strategy']));
  2232.             }
  2234.             $this->generatorOptions = $mapping['options'] ?? [];
  2235.             switch ($this->generatorType) {
  2236.                 case self::GENERATOR_TYPE_AUTO:
  2237.                     $mapping['type'] = 'id';
  2238.                     break;
  2239.                 default:
  2240.                     if (! empty($this->generatorOptions['type'])) {
  2241.                         $mapping['type'] = (string) $this->generatorOptions['type'];
  2242.                     } elseif (empty($mapping['type'])) {
  2243.                         $mapping['type'] = $this->generatorType === self::GENERATOR_TYPE_INCREMENT ? Type::INT : Type::CUSTOMID;
  2244.                     }
  2245.             }
  2247.             unset($this->generatorOptions['type']);
  2248.         }
  2250.         if (! isset($mapping['type'])) {
  2251.             // Default to string
  2252.             $mapping['type'] = Type::STRING;
  2253.         }
  2255.         if (! isset($mapping['nullable'])) {
  2256.             $mapping['nullable'] = false;
  2257.         }
  2259.         if (
  2260.             isset($mapping['reference'])
  2261.             && isset($mapping['storeAs'])
  2262.             && $mapping['storeAs'] === self::REFERENCE_STORE_AS_ID
  2263.             && ! isset($mapping['targetDocument'])
  2264.         ) {
  2265.             throw MappingException::simpleReferenceRequiresTargetDocument($this->name, $mapping['fieldName']);
  2266.         }
  2268.         if (
  2269.             isset($mapping['reference']) && empty($mapping['targetDocument']) && empty($mapping['discriminatorMap']) &&
  2270.                 (isset($mapping['mappedBy']) || isset($mapping['inversedBy']))
  2271.         ) {
  2272.             throw MappingException::owningAndInverseReferencesRequireTargetDocument($this->name, $mapping['fieldName']);
  2273.         }
  2275.         if ($this->isEmbeddedDocument && $mapping['type'] === self::MANY && isset($mapping['strategy']) && CollectionHelper::isAtomic($mapping['strategy'])) {
  2276.             throw MappingException::atomicCollectionStrategyNotAllowed($mapping['strategy'], $this->name, $mapping['fieldName']);
  2277.         }
  2279.         if (isset($mapping['repositoryMethod']) && ! (empty($mapping['skip']) && empty($mapping['limit']) && empty($mapping['sort']))) {
  2280.             throw MappingException::repositoryMethodCanNotBeCombinedWithSkipLimitAndSort($this->name, $mapping['fieldName']);
  2281.         }
  2283.         if (isset($mapping['targetDocument']) && isset($mapping['discriminatorMap'])) {
  2284.             trigger_deprecation(
  2285.                 'doctrine/mongodb-odm',
  2286.                 '2.2',
  2287.                 'Mapping both "targetDocument" and "discriminatorMap" on field "%s" in class "%s" is deprecated. Only one of them can be used at a time',
  2288.                 $mapping['fieldName'],
  2289.                 $this->name,
  2290.             );
  2291.         }
  2293.         if (isset($mapping['reference']) && $mapping['type'] === self::ONE) {
  2294.             $mapping['association'] = self::REFERENCE_ONE;
  2295.         }
  2297.         if (isset($mapping['reference']) && $mapping['type'] === self::MANY) {
  2298.             $mapping['association'] = self::REFERENCE_MANY;
  2299.         }
  2301.         if (isset($mapping['embedded']) && $mapping['type'] === self::ONE) {
  2302.             $mapping['association'] = self::EMBED_ONE;
  2303.         }
  2305.         if (isset($mapping['embedded']) && $mapping['type'] === self::MANY) {
  2306.             $mapping['association'] = self::EMBED_MANY;
  2307.         }
  2309.         if (isset($mapping['association']) && ! isset($mapping['targetDocument']) && ! isset($mapping['discriminatorField'])) {
  2310.             $mapping['discriminatorField'] = self::DEFAULT_DISCRIMINATOR_FIELD;
  2311.         }
  2313.         if (isset($mapping['targetDocument']) && ! class_exists($mapping['targetDocument']) && ! interface_exists($mapping['targetDocument'])) {
  2314.             throw MappingException::invalidTargetDocument(
  2315.                 $mapping['targetDocument'],
  2316.                 $this->name,
  2317.                 $mapping['fieldName'],
  2318.             );
  2319.         }
  2321.         if (isset($mapping['discriminatorMap'])) {
  2322.             foreach ($mapping['discriminatorMap'] as $value => $class) {
  2323.                 if (! class_exists($class) && ! interface_exists($class)) {
  2324.                     throw MappingException::invalidClassInReferenceDiscriminatorMap($class, $this->name, $mapping['fieldName']);
  2325.                 }
  2326.             }
  2327.         }
  2329.         if (isset($mapping['version'])) {
  2330.             $mapping['notSaved'] = true;
  2331.             $this->setVersionMapping($mapping);
  2332.         }
  2334.         if (isset($mapping['lock'])) {
  2335.             $mapping['notSaved'] = true;
  2336.             $this->setLockMapping($mapping);
  2337.         }
  2339.         $mapping['isOwningSide']  = true;
  2340.         $mapping['isInverseSide'] = false;
  2341.         if (isset($mapping['reference'])) {
  2342.             if (isset($mapping['inversedBy']) && $mapping['inversedBy']) {
  2343.                 $mapping['isOwningSide']  = true;
  2344.                 $mapping['isInverseSide'] = false;
  2345.             }
  2347.             if (isset($mapping['mappedBy']) && $mapping['mappedBy']) {
  2348.                 $mapping['isInverseSide'] = true;
  2349.                 $mapping['isOwningSide']  = false;
  2350.             }
  2352.             if (isset($mapping['repositoryMethod'])) {
  2353.                 $mapping['isInverseSide'] = true;
  2354.                 $mapping['isOwningSide']  = false;
  2355.             }
  2357.             if (! isset($mapping['orphanRemoval'])) {
  2358.                 $mapping['orphanRemoval'] = false;
  2359.             }
  2360.         }
  2362.         if (! empty($mapping['prime']) && ($mapping['association'] !== self::REFERENCE_MANY || ! $mapping['isInverseSide'])) {
  2363.             throw MappingException::referencePrimersOnlySupportedForInverseReferenceMany($this->name, $mapping['fieldName']);
  2364.         }
  2366.         if ($this->isFile && ! $this->isAllowedGridFSField($mapping['name'])) {
  2367.             throw MappingException::fieldNotAllowedForGridFS($this->name, $mapping['fieldName']);
  2368.         }
  2370.         $this->applyStorageStrategy($mapping);
  2371.         $this->checkDuplicateMapping($mapping);
  2372.         $this->typeRequirementsAreMet($mapping);
  2374.         $deprecatedTypes = [
  2375.             Type::BOOLEAN => Type::BOOL,
  2376.             Type::INTEGER => Type::INT,
  2377.             Type::INTID => Type::INT,
  2378.         ];
  2379.         if (isset($deprecatedTypes[$mapping['type']])) {
  2380.             trigger_deprecation(
  2381.                 'doctrine/mongodb-odm',
  2382.                 '2.1',
  2383.                 'The "%s" mapping type is deprecated. Use "%s" instead.',
  2384.                 $mapping['type'],
  2385.                 $deprecatedTypes[$mapping['type']],
  2386.             );
  2387.         }
  2389.         $this->fieldMappings[$mapping['fieldName']] = $mapping;
  2390.         if (isset($mapping['association'])) {
  2391.             $this->associationMappings[$mapping['fieldName']] = $mapping;
  2392.         }
  2394.         $reflProp = $this->reflectionService->getAccessibleProperty($this->name, $mapping['fieldName']);
  2395.         assert($reflProp instanceof ReflectionProperty);
  2397.         if (isset($mapping['enumType'])) {
  2398.             if (PHP_VERSION_ID < 80100) {
  2399.                 throw MappingException::enumsRequirePhp81($this->name, $mapping['fieldName']);
  2400.             }
  2402.             if (! enum_exists($mapping['enumType'])) {
  2403.                 throw MappingException::nonEnumTypeMapped($this->name, $mapping['fieldName'], $mapping['enumType']);
  2404.             }
  2406.             $reflectionEnum = new ReflectionEnum($mapping['enumType']);
  2407.             if (! $reflectionEnum->isBacked()) {
  2408.                 throw MappingException::nonBackedEnumMapped($this->name, $mapping['fieldName'], $mapping['enumType']);
  2409.             }
  2411.             $reflProp = new EnumReflectionProperty($reflProp, $mapping['enumType']);
  2412.         }
  2414.         $this->reflFields[$mapping['fieldName']] = $reflProp;
  2416.         return $mapping;
  2417.     }
  2419.     /**
  2420.      * Determines which fields get serialized.
  2421.      *
  2422.      * It is only serialized what is necessary for best unserialization performance.
  2423.      * That means any metadata properties that are not set or empty or simply have
  2424.      * their default value are NOT serialized.
  2425.      *
  2426.      * Parts that are also NOT serialized because they can not be properly unserialized:
  2427.      *      - reflClass (ReflectionClass)
  2428.      *      - reflFields (ReflectionProperty array)
  2429.      *
  2430.      * @return array The names of all the fields that should be serialized.
  2431.      */
  2432.     public function __sleep()
  2433.     {
  2434.         // This metadata is always serialized/cached.
  2435.         $serialized = [
  2436.             'fieldMappings',
  2437.             'associationMappings',
  2438.             'identifier',
  2439.             'name',
  2440.             'db',
  2441.             'collection',
  2442.             'readPreference',
  2443.             'readPreferenceTags',
  2444.             'writeConcern',
  2445.             'rootDocumentName',
  2446.             'generatorType',
  2447.             'generatorOptions',
  2448.             'idGenerator',
  2449.             'indexes',
  2450.             'shardKey',
  2451.         ];
  2453.         // The rest of the metadata is only serialized if necessary.
  2454.         if ($this->changeTrackingPolicy !== self::CHANGETRACKING_DEFERRED_IMPLICIT) {
  2455.             $serialized[] = 'changeTrackingPolicy';
  2456.         }
  2458.         if ($this->customRepositoryClassName) {
  2459.             $serialized[] = 'customRepositoryClassName';
  2460.         }
  2462.         if ($this->inheritanceType !== self::INHERITANCE_TYPE_NONE || $this->discriminatorField !== null) {
  2463.             $serialized[] = 'inheritanceType';
  2464.             $serialized[] = 'discriminatorField';
  2465.             $serialized[] = 'discriminatorValue';
  2466.             $serialized[] = 'discriminatorMap';
  2467.             $serialized[] = 'defaultDiscriminatorValue';
  2468.             $serialized[] = 'parentClasses';
  2469.             $serialized[] = 'subClasses';
  2470.         }
  2472.         if ($this->isMappedSuperclass) {
  2473.             $serialized[] = 'isMappedSuperclass';
  2474.         }
  2476.         if ($this->isEmbeddedDocument) {
  2477.             $serialized[] = 'isEmbeddedDocument';
  2478.         }
  2480.         if ($this->isQueryResultDocument) {
  2481.             $serialized[] = 'isQueryResultDocument';
  2482.         }
  2484.         if ($this->isView()) {
  2485.             $serialized[] = 'isView';
  2486.             $serialized[] = 'rootClass';
  2487.         }
  2489.         if ($this->isFile) {
  2490.             $serialized[] = 'isFile';
  2491.             $serialized[] = 'bucketName';
  2492.             $serialized[] = 'chunkSizeBytes';
  2493.         }
  2495.         if ($this->isVersioned) {
  2496.             $serialized[] = 'isVersioned';
  2497.             $serialized[] = 'versionField';
  2498.         }
  2500.         if ($this->isLockable) {
  2501.             $serialized[] = 'isLockable';
  2502.             $serialized[] = 'lockField';
  2503.         }
  2505.         if ($this->lifecycleCallbacks) {
  2506.             $serialized[] = 'lifecycleCallbacks';
  2507.         }
  2509.         if ($this->collectionCapped) {
  2510.             $serialized[] = 'collectionCapped';
  2511.             $serialized[] = 'collectionSize';
  2512.             $serialized[] = 'collectionMax';
  2513.         }
  2515.         if ($this->isReadOnly) {
  2516.             $serialized[] = 'isReadOnly';
  2517.         }
  2519.         if ($this->validator !== null) {
  2520.             $serialized[] = 'validator';
  2521.             $serialized[] = 'validationAction';
  2522.             $serialized[] = 'validationLevel';
  2523.         }
  2525.         return $serialized;
  2526.     }
  2528.     /**
  2529.      * Restores some state that can not be serialized/unserialized.
  2530.      */
  2531.     public function __wakeup()
  2532.     {
  2533.         // Restore ReflectionClass and properties
  2534.         $this->reflectionService = new RuntimeReflectionService();
  2535.         $this->reflClass         = new ReflectionClass($this->name);
  2536.         $this->instantiator      = new Instantiator();
  2538.         foreach ($this->fieldMappings as $field => $mapping) {
  2539.             $prop = $this->reflectionService->getAccessibleProperty($mapping['declared'] ?? $this->name, $field);
  2540.             assert($prop instanceof ReflectionProperty);
  2542.             if (isset($mapping['enumType'])) {
  2543.                 $prop = new EnumReflectionProperty($prop, $mapping['enumType']);
  2544.             }
  2546.             $this->reflFields[$field] = $prop;
  2547.         }
  2548.     }
  2550.     /**
  2551.      * Creates a new instance of the mapped class, without invoking the constructor.
  2552.      *
  2553.      * @psalm-return T
  2554.      */
  2555.     public function newInstance(): object
  2556.     {
  2557.         /** @psalm-var T */
  2558.         return $this->instantiator->instantiate($this->name);
  2559.     }
  2561.     private function isAllowedGridFSField(string $name): bool
  2562.     {
  2563.         return in_array($name, self::ALLOWED_GRIDFS_FIELDS, true);
  2564.     }
  2566.     /** @psalm-param FieldMapping $mapping */
  2567.     private function typeRequirementsAreMet(array $mapping): void
  2568.     {
  2569.         if ($mapping['type'] === Type::DECIMAL128 && ! extension_loaded('bcmath')) {
  2570.             throw MappingException::typeRequirementsNotFulfilled($this->name, $mapping['fieldName'], Type::DECIMAL128, 'ext-bcmath is missing');
  2571.         }
  2572.     }
  2574.     /** @psalm-param FieldMapping $mapping */
  2575.     private function checkDuplicateMapping(array $mapping): void
  2576.     {
  2577.         if ($mapping['notSaved'] ?? false) {
  2578.             return;
  2579.         }
  2581.         foreach ($this->fieldMappings as $fieldName => $otherMapping) {
  2582.             // Ignore fields with the same name - we can safely override their mapping
  2583.             if ($mapping['fieldName'] === $fieldName) {
  2584.                 continue;
  2585.             }
  2587.             // Ignore fields with a different name in the database
  2588.             if ($mapping['name'] !== $otherMapping['name']) {
  2589.                 continue;
  2590.             }
  2592.             // If the other field is not saved, ignore it as well
  2593.             if ($otherMapping['notSaved'] ?? false) {
  2594.                 continue;
  2595.             }
  2597.             throw MappingException::duplicateDatabaseFieldName($this->getName(), $mapping['fieldName'], $mapping['name'], $fieldName);
  2598.         }
  2599.     }
  2601.     private function isTypedProperty(string $name): bool
  2602.     {
  2603.         return $this->reflClass->hasProperty($name)
  2604.             && $this->reflClass->getProperty($name)->hasType();
  2605.     }
  2607.     /**
  2608.      * Validates & completes the given field mapping based on typed property.
  2609.      *
  2610.      * @psalm-param FieldMappingConfig $mapping
  2611.      *
  2612.      * @return FieldMappingConfig
  2613.      */
  2614.     private function validateAndCompleteTypedFieldMapping(array $mapping): array
  2615.     {
  2616.         $type = $this->reflClass->getProperty($mapping['fieldName'])->getType();
  2618.         if (! $type instanceof ReflectionNamedType || isset($mapping['type'])) {
  2619.             return $mapping;
  2620.         }
  2622.         if (PHP_VERSION_ID >= 80100 && ! $type->isBuiltin() && enum_exists($type->getName())) {
  2623.             $mapping['enumType'] = $type->getName();
  2625.             $reflection = new ReflectionEnum($type->getName());
  2626.             $type       = $reflection->getBackingType();
  2628.             if ($type === null) {
  2629.                 throw MappingException::nonBackedEnumMapped($this->name, $mapping['fieldName'], $mapping['enumType']);
  2630.             }
  2632.             assert($type instanceof ReflectionNamedType);
  2633.         }
  2635.         switch ($type->getName()) {
  2636.             case DateTime::class:
  2637.                 $mapping['type'] = Type::DATE;
  2638.                 break;
  2639.             case DateTimeImmutable::class:
  2640.                 $mapping['type'] = Type::DATE_IMMUTABLE;
  2641.                 break;
  2642.             case 'array':
  2643.                 $mapping['type'] = Type::HASH;
  2644.                 break;
  2645.             case 'bool':
  2646.                 $mapping['type'] = Type::BOOL;
  2647.                 break;
  2648.             case 'float':
  2649.                 $mapping['type'] = Type::FLOAT;
  2650.                 break;
  2651.             case 'int':
  2652.                 $mapping['type'] = Type::INT;
  2653.                 break;
  2654.             case 'string':
  2655.                 $mapping['type'] = Type::STRING;
  2656.                 break;
  2657.         }
  2659.         return $mapping;
  2660.     }
  2662.     /**
  2663.      * Validates & completes the basic mapping information based on typed property.
  2664.      *
  2665.      * @psalm-param FieldMappingConfig $mapping
  2666.      *
  2667.      * @return FieldMappingConfig
  2668.      */
  2669.     private function validateAndCompleteTypedManyAssociationMapping(array $mapping): array
  2670.     {
  2671.         $type = $this->reflClass->getProperty($mapping['fieldName'])->getType();
  2673.         if (! $type instanceof ReflectionNamedType) {
  2674.             return $mapping;
  2675.         }
  2677.         if (! isset($mapping['collectionClass']) && class_exists($type->getName())) {
  2678.             $mapping['collectionClass'] = $type->getName();
  2679.         }
  2681.         return $mapping;
  2682.     }
  2683. }