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

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