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

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