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

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