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

Open in your IDE?
  1. <?php
  3. declare(strict_types=1);
  5. namespace Doctrine\ODM\MongoDB\Mapping;
  7. use BackedEnum;
  8. use BadMethodCallException;
  9. use DateTime;
  10. use DateTimeImmutable;
  11. use Doctrine\Common\Collections\Collection;
  12. use Doctrine\Instantiator\Instantiator;
  13. use Doctrine\Instantiator\InstantiatorInterface;
  14. use Doctrine\ODM\MongoDB\Id\IdGenerator;
  15. use Doctrine\ODM\MongoDB\LockException;
  16. use Doctrine\ODM\MongoDB\Types\Incrementable;
  17. use Doctrine\ODM\MongoDB\Types\Type;
  18. use Doctrine\ODM\MongoDB\Types\Versionable;
  19. use Doctrine\ODM\MongoDB\Utility\CollectionHelper;
  20. use Doctrine\Persistence\Mapping\ClassMetadata as BaseClassMetadata;
  21. use Doctrine\Persistence\Mapping\ReflectionService;
  22. use Doctrine\Persistence\Mapping\RuntimeReflectionService;
  23. use Doctrine\Persistence\Reflection\EnumReflectionProperty;
  24. use InvalidArgumentException;
  25. use LogicException;
  26. use ProxyManager\Proxy\GhostObjectInterface;
  27. use ReflectionClass;
  28. use ReflectionEnum;
  29. use ReflectionNamedType;
  30. use ReflectionProperty;
  32. use function array_filter;
  33. use function array_key_exists;
  34. use function array_keys;
  35. use function array_map;
  36. use function array_pop;
  37. use function assert;
  38. use function class_exists;
  39. use function constant;
  40. use function count;
  41. use function enum_exists;
  42. use function extension_loaded;
  43. use function in_array;
  44. use function interface_exists;
  45. use function is_array;
  46. use function is_string;
  47. use function is_subclass_of;
  48. use function ltrim;
  49. use function sprintf;
  50. use function strtolower;
  51. use function strtoupper;
  52. use function trigger_deprecation;
  54. /**
  55.  * A <tt>ClassMetadata</tt> instance holds all the object-document mapping metadata
  56.  * of a document and it's references.
  57.  *
  58.  * Once populated, ClassMetadata instances are usually cached in a serialized form.
  59.  *
  60.  * <b>IMPORTANT NOTE:</b>
  61.  *
  62.  * The fields of this class are only public for 2 reasons:
  63.  * 1) To allow fast READ access.
  64.  * 2) To drastically reduce the size of a serialized instance (private/protected members
  65.  *    get the whole class name, namespace inclusive, prepended to every property in
  66.  *    the serialized representation).
  67.  *
  68.  * @psalm-type FieldMappingConfig = array{
  69.  *      type?: string,
  70.  *      fieldName?: string,
  71.  *      name?: string,
  72.  *      strategy?: string,
  73.  *      association?: int,
  74.  *      id?: bool,
  75.  *      isOwningSide?: bool,
  76.  *      collectionClass?: class-string,
  77.  *      cascade?: list<string>|string,
  78.  *      embedded?: bool,
  79.  *      orphanRemoval?: bool,
  80.  *      options?: array<string, mixed>,
  81.  *      nullable?: bool,
  82.  *      reference?: bool,
  83.  *      storeAs?: string,
  84.  *      targetDocument?: class-string|null,
  85.  *      mappedBy?: string|null,
  86.  *      inversedBy?: string|null,
  87.  *      discriminatorField?: string,
  88.  *      defaultDiscriminatorValue?: string,
  89.  *      discriminatorMap?: array<string, class-string>,
  90.  *      repositoryMethod?: string|null,
  91.  *      sort?: array<string, string|int>,
  92.  *      limit?: int|null,
  93.  *      skip?: int|null,
  94.  *      version?: bool,
  95.  *      lock?: bool,
  96.  *      inherited?: string,
  97.  *      declared?: class-string,
  98.  *      prime?: list<string>,
  99.  *      sparse?: bool,
  100.  *      unique?: bool,
  101.  *      index?: bool,
  102.  *      index-name?: string,
  103.  *      criteria?: array<string, mixed>,
  104.  *      alsoLoadFields?: list<string>,
  105.  *      order?: int|string,
  106.  *      background?: bool,
  107.  *      enumType?: class-string<BackedEnum>,
  108.  * }
  109.  * @psalm-type FieldMapping = array{
  110.  *      type: string,
  111.  *      fieldName: string,
  112.  *      name: string,
  113.  *      isCascadeRemove: bool,
  114.  *      isCascadePersist: bool,
  115.  *      isCascadeRefresh: bool,
  116.  *      isCascadeMerge: bool,
  117.  *      isCascadeDetach: bool,
  118.  *      isOwningSide: bool,
  119.  *      isInverseSide: bool,
  120.  *      strategy?: string,
  121.  *      association?: int,
  122.  *      id?: bool,
  123.  *      collectionClass?: class-string,
  124.  *      cascade?: list<string>|string,
  125.  *      embedded?: bool,
  126.  *      orphanRemoval?: bool,
  127.  *      options?: array<string, mixed>,
  128.  *      nullable?: bool,
  129.  *      reference?: bool,
  130.  *      storeAs?: string,
  131.  *      targetDocument?: class-string|null,
  132.  *      mappedBy?: string|null,
  133.  *      inversedBy?: string|null,
  134.  *      discriminatorField?: string,
  135.  *      defaultDiscriminatorValue?: string,
  136.  *      discriminatorMap?: array<string, class-string>,
  137.  *      repositoryMethod?: string|null,
  138.  *      sort?: array<string, string|int>,
  139.  *      limit?: int|null,
  140.  *      skip?: int|null,
  141.  *      version?: bool,
  142.  *      lock?: bool,
  143.  *      notSaved?: bool,
  144.  *      inherited?: string,
  145.  *      declared?: class-string,
  146.  *      prime?: list<string>,
  147.  *      sparse?: bool,
  148.  *      unique?: bool,
  149.  *      index?: bool,
  150.  *      criteria?: array<string, mixed>,
  151.  *      alsoLoadFields?: list<string>,
  152.  *      enumType?: class-string<BackedEnum>,
  153.  *      storeEmptyArray?: bool,
  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, mixed>,
  197.  *      alsoLoadFields?: list<string>,
  198.  *      storeEmptyArray?: bool,
  199.  * }
  200.  * @psalm-type IndexKeys = array<string, mixed>
  201.  * @psalm-type IndexOptions = array{
  202.  *      background?: bool,
  203.  *      bits?: int,
  204.  *      default_language?: string,
  205.  *      expireAfterSeconds?: int,
  206.  *      language_override?: string,
  207.  *      min?: float,
  208.  *      max?: float,
  209.  *      name?: string,
  210.  *      partialFilterExpression?: mixed[],
  211.  *      sparse?: bool,
  212.  *      storageEngine?: mixed[],
  213.  *      textIndexVersion?: int,
  214.  *      unique?: bool,
  215.  *      weights?: array{string, int},
  216.  * }
  217.  * @psalm-type IndexMapping = array{
  218.  *      keys: IndexKeys,
  219.  *      options: IndexOptions
  220.  * }
  221.  * @psalm-type ShardKeys = array<string, mixed>
  222.  * @psalm-type ShardOptions = array<string, mixed>
  223.  * @psalm-type ShardKey = array{
  224.  *      keys?: ShardKeys,
  225.  *      options?: ShardOptions
  226.  * }
  227.  * @final
  228.  * @template-covariant T of object
  229.  * @template-implements BaseClassMetadata<T>
  230.  */
  231. /* final */ class ClassMetadata implements BaseClassMetadata
  232. {
  233.     /* The Id generator types. */
  234.     /**
  235.      * AUTO means Doctrine will automatically create a new \MongoDB\BSON\ObjectId instance for us.
  236.      */
  237.     public const GENERATOR_TYPE_AUTO = 1;
  239.     /**
  240.      * INCREMENT means a separate collection is used for maintaining and incrementing id generation.
  241.      * Offers full portability.
  242.      */
  243.     public const GENERATOR_TYPE_INCREMENT = 2;
  245.     /**
  246.      * UUID means Doctrine will generate a uuid for us.
  247.      */
  248.     public const GENERATOR_TYPE_UUID = 3;
  250.     /**
  251.      * ALNUM means Doctrine will generate Alpha-numeric string identifiers, using the INCREMENT
  252.      * generator to ensure identifier uniqueness
  253.      */
  254.     public const GENERATOR_TYPE_ALNUM = 4;
  256.     /**
  257.      * CUSTOM means Doctrine expect a class parameter. It will then try to initiate that class
  258.      * and pass other options to the generator. It will throw an Exception if the class
  259.      * does not exist or if an option was passed for that there is not setter in the new
  260.      * generator class.
  261.      *
  262.      * The class will have to implement IdGenerator.
  263.      */
  264.     public const GENERATOR_TYPE_CUSTOM = 5;
  266.     /**
  267.      * NONE means Doctrine will not generate any id for us and you are responsible for manually
  268.      * assigning an id.
  269.      */
  270.     public const GENERATOR_TYPE_NONE = 6;
  272.     /**
  273.      * Default discriminator field name.
  274.      *
  275.      * This is used for associations value for associations where a that do not define a "targetDocument" or
  276.      * "discriminatorField" option in their mapping.
  277.      */
  278.     public const DEFAULT_DISCRIMINATOR_FIELD = '_doctrine_class_name';
  280.     /**
  281.      * Association types
  282.      */
  283.     public const REFERENCE_ONE  = 1;
  284.     public const REFERENCE_MANY = 2;
  285.     public const EMBED_ONE      = 3;
  286.     public const EMBED_MANY     = 4;
  288.     /**
  289.      * Mapping types
  290.      */
  291.     public const MANY = 'many';
  292.     public const ONE  = 'one';
  294.     /**
  295.      * The types of storeAs references
  296.      */
  297.     public const REFERENCE_STORE_AS_ID             = 'id';
  298.     public const REFERENCE_STORE_AS_DB_REF         = 'dbRef';
  299.     public const REFERENCE_STORE_AS_DB_REF_WITH_DB = 'dbRefWithDb';
  300.     public const REFERENCE_STORE_AS_REF            = 'ref';
  302.     /**
  303.      * The collection schema validationAction values
  304.      *
  305.      * @see https://docs.mongodb.com/manual/core/schema-validation/#accept-or-reject-invalid-documents
  306.      */
  307.     public const SCHEMA_VALIDATION_ACTION_ERROR = 'error';
  308.     public const SCHEMA_VALIDATION_ACTION_WARN  = 'warn';
  310.     /**
  311.      * The collection schema validationLevel values
  312.      *
  313.      * @see https://docs.mongodb.com/manual/core/schema-validation/#existing-documents
  314.      */
  315.     public const SCHEMA_VALIDATION_LEVEL_OFF      = 'off';
  316.     public const SCHEMA_VALIDATION_LEVEL_STRICT   = 'strict';
  317.     public const SCHEMA_VALIDATION_LEVEL_MODERATE = 'moderate';
  319.     /* The inheritance mapping types */
  320.     /**
  321.      * NONE means the class does not participate in an inheritance hierarchy
  322.      * and therefore does not need an inheritance mapping type.
  323.      */
  324.     public const INHERITANCE_TYPE_NONE = 1;
  326.     /**
  327.      * SINGLE_COLLECTION means the class will be persisted according to the rules of
  328.      * <tt>Single Collection Inheritance</tt>.
  329.      */
  330.     public const INHERITANCE_TYPE_SINGLE_COLLECTION = 2;
  332.     /**
  333.      * COLLECTION_PER_CLASS means the class will be persisted according to the rules
  334.      * of <tt>Concrete Collection Inheritance</tt>.
  335.      */
  336.     public const INHERITANCE_TYPE_COLLECTION_PER_CLASS = 3;
  338.     /**
  339.      * DEFERRED_IMPLICIT means that changes of entities are calculated at commit-time
  340.      * by doing a property-by-property comparison with the original data. This will
  341.      * be done for all entities that are in MANAGED state at commit-time.
  342.      *
  343.      * This is the default change tracking policy.
  344.      */
  345.     public const CHANGETRACKING_DEFERRED_IMPLICIT = 1;
  347.     /**
  348.      * DEFERRED_EXPLICIT means that changes of entities are calculated at commit-time
  349.      * by doing a property-by-property comparison with the original data. This will
  350.      * be done only for entities that were explicitly saved (through persist() or a cascade).
  351.      */
  352.     public const CHANGETRACKING_DEFERRED_EXPLICIT = 2;
  354.     /**
  355.      * NOTIFY means that Doctrine relies on the entities sending out notifications
  356.      * when their properties change. Such entity classes must implement
  357.      * the <tt>NotifyPropertyChanged</tt> interface.
  358.      *
  359.      * @deprecated
  360.      */
  361.     public const CHANGETRACKING_NOTIFY = 3;
  363.     /**
  364.      * SET means that fields will be written to the database using a $set operator
  365.      */
  366.     public const STORAGE_STRATEGY_SET = 'set';
  368.     /**
  369.      * INCREMENT means that fields will be written to the database by calculating
  370.      * the difference and using the $inc operator
  371.      */
  372.     public const STORAGE_STRATEGY_INCREMENT = 'increment';
  374.     public const STORAGE_STRATEGY_PUSH_ALL         = 'pushAll';
  375.     public const STORAGE_STRATEGY_ADD_TO_SET       = 'addToSet';
  376.     public const STORAGE_STRATEGY_ATOMIC_SET       = 'atomicSet';
  377.     public const STORAGE_STRATEGY_ATOMIC_SET_ARRAY = 'atomicSetArray';
  378.     public const STORAGE_STRATEGY_SET_ARRAY        = 'setArray';
  380.     private const ALLOWED_GRIDFS_FIELDS = ['_id', 'chunkSize', 'filename', 'length', 'metadata', 'uploadDate'];
  382.     /**
  383.      * READ-ONLY: The name of the mongo database the document is mapped to.
  384.      *
  385.      * @var string|null
  386.      */
  387.     public $db;
  389.     /**
  390.      * READ-ONLY: The name of the mongo collection the document is mapped to.
  391.      *
  392.      * @var string
  393.      */
  394.     public $collection;
  396.     /**
  397.      * READ-ONLY: The name of the GridFS bucket the document is mapped to.
  398.      *
  399.      * @var string
  400.      */
  401.     public $bucketName = 'fs';
  403.     /**
  404.      * READ-ONLY: If the collection should be a fixed size.
  405.      *
  406.      * @var bool
  407.      */
  408.     public $collectionCapped = false;
  410.     /**
  411.      * READ-ONLY: If the collection is fixed size, its size in bytes.
  412.      *
  413.      * @var int|null
  414.      */
  415.     public $collectionSize;
  417.     /**
  418.      * READ-ONLY: If the collection is fixed size, the maximum number of elements to store in the collection.
  419.      *
  420.      * @var int|null
  421.      */
  422.     public $collectionMax;
  424.     /**
  425.      * READ-ONLY Describes how MongoDB clients route read operations to the members of a replica set.
  426.      *
  427.      * @var string|null
  428.      */
  429.     public $readPreference;
  431.     /**
  432.      * READ-ONLY Associated with readPreference Allows to specify criteria so that your application can target read
  433.      * operations to specific members, based on custom parameters.
  434.      *
  435.      * @var array<array<string, string>>
  436.      */
  437.     public $readPreferenceTags = [];
  439.     /**
  440.      * READ-ONLY: Describes the level of acknowledgement requested from MongoDB for write operations.
  441.      *
  442.      * @var string|int|null
  443.      */
  444.     public $writeConcern;
  446.     /**
  447.      * READ-ONLY: The field name of the document identifier.
  448.      *
  449.      * @var string|null
  450.      */
  451.     public $identifier;
  453.     /**
  454.      * READ-ONLY: The array of indexes for the document collection.
  455.      *
  456.      * @var array<array<string, mixed>>
  457.      * @psalm-var array<IndexMapping>
  458.      */
  459.     public $indexes = [];
  461.     /**
  462.      * READ-ONLY: Keys and options describing shard key. Only for sharded collections.
  463.      *
  464.      * @var array<string, array>
  465.      * @psalm-var ShardKey
  466.      */
  467.     public $shardKey = [];
  469.     /**
  470.      * Allows users to specify a validation schema for the collection.
  471.      *
  472.      * @var array|object|null
  473.      * @psalm-var array<string, mixed>|object|null
  474.      */
  475.     private $validator;
  477.     /**
  478.      * Determines whether to error on invalid documents or just warn about the violations but allow invalid documents to be inserted.
  479.      *
  480.      * @var string
  481.      */
  482.     private $validationAction = self::SCHEMA_VALIDATION_ACTION_ERROR;
  484.     /**
  485.      * Determines how strictly MongoDB applies the validation rules to existing documents during an update.
  486.      */
  487.     private string $validationLevel = self::SCHEMA_VALIDATION_LEVEL_STRICT;
  489.     /**
  490.      * READ-ONLY: The name of the document class.
  491.      *
  492.      * @var string
  493.      * @psalm-var class-string<T>
  494.      */
  495.     public $name;
  497.     /**
  498.      * READ-ONLY: The name of the document class that is at the root of the mapped document inheritance
  499.      * hierarchy. If the document is not part of a mapped inheritance hierarchy this is the same
  500.      * as {@link $documentName}.
  501.      *
  502.      * @var string
  503.      * @psalm-var class-string
  504.      */
  505.     public $rootDocumentName;
  507.     /**
  508.      * The name of the custom repository class used for the document class.
  509.      * (Optional).
  510.      *
  511.      * @var string|null
  512.      * @psalm-var class-string|null
  513.      */
  514.     public $customRepositoryClassName;
  516.     /**
  517.      * READ-ONLY: The names of the parent classes (ancestors).
  518.      *
  519.      * @var array
  520.      * @psalm-var list<class-string>
  521.      */
  522.     public $parentClasses = [];
  524.     /**
  525.      * READ-ONLY: The names of all subclasses (descendants).
  526.      *
  527.      * @var array
  528.      * @psalm-var list<class-string>
  529.      */
  530.     public $subClasses = [];
  532.     /**
  533.      * The ReflectionProperty instances of the mapped class.
  534.      *
  535.      * @var ReflectionProperty[]
  536.      */
  537.     public $reflFields = [];
  539.     /**
  540.      * READ-ONLY: The inheritance mapping type used by the class.
  541.      *
  542.      * @var int
  543.      */
  544.     public $inheritanceType = self::INHERITANCE_TYPE_NONE;
  546.     /**
  547.      * READ-ONLY: The Id generator type used by the class.
  548.      *
  549.      * @var int
  550.      */
  551.     public $generatorType = self::GENERATOR_TYPE_AUTO;
  553.     /**
  554.      * READ-ONLY: The Id generator options.
  555.      *
  556.      * @var array<string, mixed>
  557.      */
  558.     public $generatorOptions = [];
  560.     /**
  561.      * READ-ONLY: The ID generator used for generating IDs for this class.
  562.      *
  563.      * @var IdGenerator|null
  564.      */
  565.     public $idGenerator;
  567.     /**
  568.      * READ-ONLY: The field mappings of the class.
  569.      * Keys are field names and values are mapping definitions.
  570.      *
  571.      * The mapping definition array has the following values:
  572.      *
  573.      * - <b>fieldName</b> (string)
  574.      * The name of the field in the Document.
  575.      *
  576.      * - <b>id</b> (boolean, optional)
  577.      * Marks the field as the primary key of the document. Multiple fields of an
  578.      * document can have the id attribute, forming a composite key.
  579.      *
  580.      * @var array<string, mixed>
  581.      * @psalm-var array<string, FieldMapping>
  582.      */
  583.     public $fieldMappings = [];
  585.     /**
  586.      * READ-ONLY: The association mappings of the class.
  587.      * Keys are field names and values are mapping definitions.
  588.      *
  589.      * @var array<string, mixed>
  590.      * @psalm-var array<string, AssociationFieldMapping>
  591.      */
  592.     public $associationMappings = [];
  594.     /**
  595.      * READ-ONLY: Array of fields to also load with a given method.
  596.      *
  597.      * @var array<string, mixed[]>
  598.      */
  599.     public $alsoLoadMethods = [];
  601.     /**
  602.      * READ-ONLY: The registered lifecycle callbacks for documents of this class.
  603.      *
  604.      * @var array<string, list<string>>
  605.      */
  606.     public $lifecycleCallbacks = [];
  608.     /**
  609.      * READ-ONLY: The discriminator value of this class.
  610.      *
  611.      * <b>This does only apply to the JOINED and SINGLE_COLLECTION inheritance mapping strategies
  612.      * where a discriminator field is used.</b>
  613.      *
  614.      * @see discriminatorField
  615.      *
  616.      * @var string|null
  617.      * @psalm-var class-string|null
  618.      */
  619.     public $discriminatorValue;
  621.     /**
  622.      * READ-ONLY: The discriminator map of all mapped classes in the hierarchy.
  623.      *
  624.      * <b>This does only apply to the SINGLE_COLLECTION inheritance mapping strategy
  625.      * where a discriminator field is used.</b>
  626.      *
  627.      * @see discriminatorField
  628.      *
  629.      * @psalm-var array<string, class-string>
  630.      */
  631.     public $discriminatorMap = [];
  633.     /**
  634.      * READ-ONLY: The definition of the discriminator field used in SINGLE_COLLECTION
  635.      * inheritance mapping.
  636.      *
  637.      * @var string|null
  638.      */
  639.     public $discriminatorField;
  641.     /**
  642.      * READ-ONLY: The default value for discriminatorField in case it's not set in the document
  643.      *
  644.      * @see discriminatorField
  645.      *
  646.      * @var string|null
  647.      */
  648.     public $defaultDiscriminatorValue;
  650.     /**
  651.      * READ-ONLY: Whether this class describes the mapping of a mapped superclass.
  652.      *
  653.      * @var bool
  654.      */
  655.     public $isMappedSuperclass = false;
  657.     /**
  658.      * READ-ONLY: Whether this class describes the mapping of a embedded document.
  659.      *
  660.      * @var bool
  661.      */
  662.     public $isEmbeddedDocument = false;
  664.     /**
  665.      * READ-ONLY: Whether this class describes the mapping of an aggregation result document.
  666.      *
  667.      * @var bool
  668.      */
  669.     public $isQueryResultDocument = false;
  671.     /**
  672.      * READ-ONLY: Whether this class describes the mapping of a database view.
  673.      */
  674.     private bool $isView = false;
  676.     /**
  677.      * READ-ONLY: Whether this class describes the mapping of a gridFS file
  678.      *
  679.      * @var bool
  680.      */
  681.     public $isFile = false;
  683.     /**
  684.      * READ-ONLY: The default chunk size in bytes for the file
  685.      *
  686.      * @var int|null
  687.      */
  688.     public $chunkSizeBytes;
  690.     /**
  691.      * READ-ONLY: The policy used for change-tracking on entities of this class.
  692.      *
  693.      * @var int
  694.      */
  695.     public $changeTrackingPolicy = self::CHANGETRACKING_DEFERRED_IMPLICIT;
  697.     /**
  698.      * READ-ONLY: A flag for whether or not instances of this class are to be versioned
  699.      * with optimistic locking.
  700.      *
  701.      * @var bool $isVersioned
  702.      */
  703.     public $isVersioned = false;
  705.     /**
  706.      * READ-ONLY: The name of the field which is used for versioning in optimistic locking (if any).
  707.      *
  708.      * @var string|null $versionField
  709.      */
  710.     public $versionField;
  712.     /**
  713.      * READ-ONLY: A flag for whether or not instances of this class are to allow pessimistic
  714.      * locking.
  715.      *
  716.      * @var bool $isLockable
  717.      */
  718.     public $isLockable = false;
  720.     /**
  721.      * READ-ONLY: The name of the field which is used for locking a document.
  722.      *
  723.      * @var mixed $lockField
  724.      */
  725.     public $lockField;
  727.     /**
  728.      * The ReflectionClass instance of the mapped class.
  729.      *
  730.      * @var ReflectionClass
  731.      * @psalm-var ReflectionClass<T>
  732.      */
  733.     public $reflClass;
  735.     /**
  736.      * READ_ONLY: A flag for whether or not this document is read-only.
  737.      *
  738.      * @var bool
  739.      */
  740.     public $isReadOnly;
  742.     private InstantiatorInterface $instantiator;
  744.     private ReflectionService $reflectionService;
  746.     /**
  747.      * @var string|null
  748.      * @psalm-var class-string|null
  749.      */
  750.     private $rootClass;
  752.     /**
  753.      * Initializes a new ClassMetadata instance that will hold the object-document mapping
  754.      * metadata of the class with the given name.
  755.      *
  756.      * @psalm-param class-string<T> $documentName
  757.      */
  758.     public function __construct(string $documentName)
  759.     {
  760.         $this->name              = $documentName;
  761.         $this->rootDocumentName  = $documentName;
  762.         $this->reflectionService = new RuntimeReflectionService();
  763.         $this->reflClass         = new ReflectionClass($documentName);
  764.         $this->setCollection($this->reflClass->getShortName());
  765.         $this->instantiator = new Instantiator();
  766.     }
  768.     /**
  769.      * Helper method to get reference id of ref* type references
  770.      *
  771.      * @internal
  772.      *
  773.      * @param mixed $reference
  774.      *
  775.      * @return mixed
  776.      */
  777.     public static function getReferenceId($reference, string $storeAs)
  778.     {
  779.         return $storeAs === self::REFERENCE_STORE_AS_ID ? $reference : $reference[self::getReferencePrefix($storeAs) . 'id'];
  780.     }
  782.     /**
  783.      * Returns the reference prefix used for a reference
  784.      */
  785.     private static function getReferencePrefix(string $storeAs): string
  786.     {
  787.         if (! in_array($storeAs, [self::REFERENCE_STORE_AS_REF, self::REFERENCE_STORE_AS_DB_REF, self::REFERENCE_STORE_AS_DB_REF_WITH_DB])) {
  788.             throw new LogicException('Can only get a reference prefix for DBRef and reference arrays');
  789.         }
  791.         return $storeAs === self::REFERENCE_STORE_AS_REF ? '' : '$';
  792.     }
  794.     /**
  795.      * Returns a fully qualified field name for a given reference
  796.      *
  797.      * @internal
  798.      *
  799.      * @param string $pathPrefix The field path prefix
  800.      */
  801.     public static function getReferenceFieldName(string $storeAs, string $pathPrefix = ''): string
  802.     {
  803.         if ($storeAs === self::REFERENCE_STORE_AS_ID) {
  804.             return $pathPrefix;
  805.         }
  807.         return ($pathPrefix ? $pathPrefix . '.' : '') . static::getReferencePrefix($storeAs) . 'id';
  808.     }
  810.     public function getReflectionClass(): ReflectionClass
  811.     {
  812.         return $this->reflClass;
  813.     }
  815.     /** @param string $fieldName */
  816.     public function isIdentifier($fieldName): bool
  817.     {
  818.         return $this->identifier === $fieldName;
  819.     }
  821.     /**
  822.      * Sets the mapped identifier field of this class.
  823.      *
  824.      * @internal
  825.      */
  826.     public function setIdentifier(?string $identifier): void
  827.     {
  828.         $this->identifier = $identifier;
  829.     }
  831.     /**
  832.      * Since MongoDB only allows exactly one identifier field
  833.      * this will always return an array with only one value
  834.      *
  835.      * @return array<string|null>
  836.      */
  837.     public function getIdentifier(): array
  838.     {
  839.         return [$this->identifier];
  840.     }
  842.     /**
  843.      * Since MongoDB only allows exactly one identifier field
  844.      * this will always return an array with only one value
  845.      *
  846.      * @return array<string|null>
  847.      */
  848.     public function getIdentifierFieldNames(): array
  849.     {
  850.         return [$this->identifier];
  851.     }
  853.     /** @param string $fieldName */
  854.     public function hasField($fieldName): bool
  855.     {
  856.         return isset($this->fieldMappings[$fieldName]);
  857.     }
  859.     /**
  860.      * Sets the inheritance type used by the class and it's subclasses.
  861.      */
  862.     public function setInheritanceType(int $type): void
  863.     {
  864.         $this->inheritanceType = $type;
  865.     }
  867.     /**
  868.      * Checks whether a mapped field is inherited from an entity superclass.
  869.      */
  870.     public function isInheritedField(string $fieldName): bool
  871.     {
  872.         return isset($this->fieldMappings[$fieldName]['inherited']);
  873.     }
  875.     /**
  876.      * Registers a custom repository class for the document class.
  877.      *
  878.      * @psalm-param class-string|null $repositoryClassName
  879.      */
  880.     public function setCustomRepositoryClass(?string $repositoryClassName): void
  881.     {
  882.         if ($this->isEmbeddedDocument || $this->isQueryResultDocument) {
  883.             return;
  884.         }
  886.         $this->customRepositoryClassName = $repositoryClassName;
  887.     }
  889.     /**
  890.      * Dispatches the lifecycle event of the given document by invoking all
  891.      * registered callbacks.
  892.      *
  893.      * @param mixed[]|null $arguments
  894.      *
  895.      * @throws InvalidArgumentException If document class is not this class or
  896.      *                                   a Proxy of this class.
  897.      */
  898.     public function invokeLifecycleCallbacks(string $event, object $document, ?array $arguments = null): void
  899.     {
  900.         if ($this->isView()) {
  901.             return;
  902.         }
  904.         if (! $document instanceof $this->name) {
  905.             throw new InvalidArgumentException(sprintf('Expected document class "%s"; found: "%s"', $this->name, $document::class));
  906.         }
  908.         if (empty($this->lifecycleCallbacks[$event])) {
  909.             return;
  910.         }
  912.         foreach ($this->lifecycleCallbacks[$event] as $callback) {
  913.             if ($arguments !== null) {
  914.                 $document->$callback(...$arguments);
  915.             } else {
  916.                 $document->$callback();
  917.             }
  918.         }
  919.     }
  921.     /**
  922.      * Checks whether the class has callbacks registered for a lifecycle event.
  923.      */
  924.     public function hasLifecycleCallbacks(string $event): bool
  925.     {
  926.         return ! empty($this->lifecycleCallbacks[$event]);
  927.     }
  929.     /**
  930.      * Gets the registered lifecycle callbacks for an event.
  931.      *
  932.      * @return list<string>
  933.      */
  934.     public function getLifecycleCallbacks(string $event): array
  935.     {
  936.         return $this->lifecycleCallbacks[$event] ?? [];
  937.     }
  939.     /**
  940.      * Adds a lifecycle callback for documents of this class.
  941.      *
  942.      * If the callback is already registered, this is a NOOP.
  943.      */
  944.     public function addLifecycleCallback(string $callback, string $event): void
  945.     {
  946.         if (isset($this->lifecycleCallbacks[$event]) && in_array($callback, $this->lifecycleCallbacks[$event])) {
  947.             return;
  948.         }
  950.         $this->lifecycleCallbacks[$event][] = $callback;
  951.     }
  953.     /**
  954.      * Sets the lifecycle callbacks for documents of this class.
  955.      *
  956.      * Any previously registered callbacks are overwritten.
  957.      *
  958.      * @param array<string, list<string>> $callbacks
  959.      */
  960.     public function setLifecycleCallbacks(array $callbacks): void
  961.     {
  962.         $this->lifecycleCallbacks = $callbacks;
  963.     }
  965.     /**
  966.      * Registers a method for loading document data before field hydration.
  967.      *
  968.      * Note: A method may be registered multiple times for different fields.
  969.      * it will be invoked only once for the first field found.
  970.      *
  971.      * @param array<string, mixed>|string $fields Database field name(s)
  972.      */
  973.     public function registerAlsoLoadMethod(string $method, $fields): void
  974.     {
  975.         $this->alsoLoadMethods[$method] = is_array($fields) ? $fields : [$fields];
  976.     }
  978.     /**
  979.      * Sets the AlsoLoad methods for documents of this class.
  980.      *
  981.      * Any previously registered methods are overwritten.
  982.      *
  983.      * @param array<string, mixed[]> $methods
  984.      */
  985.     public function setAlsoLoadMethods(array $methods): void
  986.     {
  987.         $this->alsoLoadMethods = $methods;
  988.     }
  990.     /**
  991.      * Sets the discriminator field.
  992.      *
  993.      * The field name is the the unmapped database field. Discriminator values
  994.      * are only used to discern the hydration class and are not mapped to class
  995.      * properties.
  996.      *
  997.      * @param array<string, mixed>|string|null $discriminatorField
  998.      * @psalm-param array{name?: string, fieldName?: string}|string|null $discriminatorField
  999.      *
  1000.      * @throws MappingException If the discriminator field conflicts with the
  1001.      *                          "name" attribute of a mapped field.
  1002.      */
  1003.     public function setDiscriminatorField($discriminatorField): void
  1004.     {
  1005.         if ($this->isFile) {
  1006.             throw MappingException::discriminatorNotAllowedForGridFS($this->name);
  1007.         }
  1009.         if ($discriminatorField === null) {
  1010.             $this->discriminatorField = null;
  1012.             return;
  1013.         }
  1015.         // @todo: deprecate, document and remove this:
  1016.         // Handle array argument with name/fieldName keys for BC
  1017.         if (is_array($discriminatorField)) {
  1018.             if (isset($discriminatorField['name'])) {
  1019.                 $discriminatorField = $discriminatorField['name'];
  1020.             } elseif (isset($discriminatorField['fieldName'])) {
  1021.                 $discriminatorField = $discriminatorField['fieldName'];
  1022.             }
  1023.         }
  1025.         foreach ($this->fieldMappings as $fieldMapping) {
  1026.             if ($discriminatorField === $fieldMapping['name']) {
  1027.                 throw MappingException::discriminatorFieldConflict($this->name, $discriminatorField);
  1028.             }
  1029.         }
  1031.         $this->discriminatorField = $discriminatorField;
  1032.     }
  1034.     /**
  1035.      * Sets the discriminator values used by this class.
  1036.      * Used for JOINED and SINGLE_TABLE inheritance mapping strategies.
  1037.      *
  1038.      * @param array<string, class-string> $map
  1039.      *
  1040.      * @throws MappingException
  1041.      */
  1042.     public function setDiscriminatorMap(array $map): void
  1043.     {
  1044.         if ($this->isFile) {
  1045.             throw MappingException::discriminatorNotAllowedForGridFS($this->name);
  1046.         }
  1048.         $this->subClasses         = [];
  1049.         $this->discriminatorMap   = [];
  1050.         $this->discriminatorValue = null;
  1052.         foreach ($map as $value => $className) {
  1053.             $this->discriminatorMap[$value] = $className;
  1054.             if ($this->name === $className) {
  1055.                 $this->discriminatorValue = $value;
  1056.             } else {
  1057.                 if (! class_exists($className)) {
  1058.                     throw MappingException::invalidClassInDiscriminatorMap($className, $this->name);
  1059.                 }
  1061.                 if (is_subclass_of($className, $this->name)) {
  1062.                     $this->subClasses[] = $className;
  1063.                 }
  1064.             }
  1065.         }
  1066.     }
  1068.     /**
  1069.      * Sets the default discriminator value to be used for this class
  1070.      * Used for SINGLE_TABLE inheritance mapping strategies if the document has no discriminator value
  1071.      *
  1072.      * @throws MappingException
  1073.      */
  1074.     public function setDefaultDiscriminatorValue(?string $defaultDiscriminatorValue): void
  1075.     {
  1076.         if ($this->isFile) {
  1077.             throw MappingException::discriminatorNotAllowedForGridFS($this->name);
  1078.         }
  1080.         if ($defaultDiscriminatorValue === null) {
  1081.             $this->defaultDiscriminatorValue = null;
  1083.             return;
  1084.         }
  1086.         if (! array_key_exists($defaultDiscriminatorValue, $this->discriminatorMap)) {
  1087.             throw MappingException::invalidDiscriminatorValue($defaultDiscriminatorValue, $this->name);
  1088.         }
  1090.         $this->defaultDiscriminatorValue = $defaultDiscriminatorValue;
  1091.     }
  1093.     /**
  1094.      * Sets the discriminator value for this class.
  1095.      * Used for JOINED/SINGLE_TABLE inheritance and multiple document types in a single
  1096.      * collection.
  1097.      *
  1098.      * @throws MappingException
  1099.      */
  1100.     public function setDiscriminatorValue(string $value): void
  1101.     {
  1102.         if ($this->isFile) {
  1103.             throw MappingException::discriminatorNotAllowedForGridFS($this->name);
  1104.         }
  1106.         $this->discriminatorMap[$value] = $this->name;
  1107.         $this->discriminatorValue       = $value;
  1108.     }
  1110.     /**
  1111.      * Add a index for this Document.
  1112.      *
  1113.      * @param array<string, int|string> $keys
  1114.      * @psalm-param IndexKeys $keys
  1115.      * @psalm-param IndexOptions $options
  1116.      */
  1117.     public function addIndex(array $keys, array $options = []): void
  1118.     {
  1119.         $this->indexes[] = [
  1120.             'keys' => array_map(static function ($value) {
  1121.                 if ($value === 1 || $value === -1) {
  1122.                     return $value;
  1123.                 }
  1125.                 if (is_string($value)) {
  1126.                     $lower = strtolower($value);
  1127.                     if ($lower === 'asc') {
  1128.                         return 1;
  1129.                     }
  1131.                     if ($lower === 'desc') {
  1132.                         return -1;
  1133.                     }
  1134.                 }
  1136.                 return $value;
  1137.             }, $keys),
  1138.             'options' => $options,
  1139.         ];
  1140.     }
  1142.     /**
  1143.      * Returns the array of indexes for this Document.
  1144.      *
  1145.      * @psalm-return array<IndexMapping>
  1146.      */
  1147.     public function getIndexes(): array
  1148.     {
  1149.         return $this->indexes;
  1150.     }
  1152.     /**
  1153.      * Checks whether this document has indexes or not.
  1154.      */
  1155.     public function hasIndexes(): bool
  1156.     {
  1157.         return $this->indexes !== [];
  1158.     }
  1160.     /**
  1161.      * Set shard key for this Document.
  1162.      *
  1163.      * @param array<string, string|int> $keys
  1164.      * @param array<string, mixed>      $options
  1165.      * @psalm-param ShardKeys $keys
  1166.      * @psalm-param ShardOptions      $options
  1167.      *
  1168.      * @throws MappingException
  1169.      */
  1170.     public function setShardKey(array $keys, array $options = []): void
  1171.     {
  1172.         if ($this->inheritanceType === self::INHERITANCE_TYPE_SINGLE_COLLECTION && $this->shardKey !== []) {
  1173.             throw MappingException::shardKeyInSingleCollInheritanceSubclass($this->getName());
  1174.         }
  1176.         if ($this->isEmbeddedDocument) {
  1177.             throw MappingException::embeddedDocumentCantHaveShardKey($this->getName());
  1178.         }
  1180.         foreach (array_keys($keys) as $field) {
  1181.             if (! isset($this->fieldMappings[$field])) {
  1182.                 continue;
  1183.             }
  1185.             if (in_array($this->fieldMappings[$field]['type'], [self::MANY, Type::COLLECTION])) {
  1186.                 throw MappingException::noMultiKeyShardKeys($this->getName(), $field);
  1187.             }
  1189.             if ($this->fieldMappings[$field]['strategy'] !== self::STORAGE_STRATEGY_SET) {
  1190.                 throw MappingException::onlySetStrategyAllowedInShardKey($this->getName(), $field);
  1191.             }
  1192.         }
  1194.         $this->shardKey = [
  1195.             'keys' => array_map(static function ($value) {
  1196.                 if ($value === 1 || $value === -1) {
  1197.                     return $value;
  1198.                 }
  1200.                 if (is_string($value)) {
  1201.                     $lower = strtolower($value);
  1202.                     if ($lower === 'asc') {
  1203.                         return 1;
  1204.                     }
  1206.                     if ($lower === 'desc') {
  1207.                         return -1;
  1208.                     }
  1209.                 }
  1211.                 return $value;
  1212.             }, $keys),
  1213.             'options' => $options,
  1214.         ];
  1215.     }
  1217.     /** @psalm-return ShardKey */
  1218.     public function getShardKey(): array
  1219.     {
  1220.         return $this->shardKey;
  1221.     }
  1223.     /**
  1224.      * Checks whether this document has shard key or not.
  1225.      */
  1226.     public function isSharded(): bool
  1227.     {
  1228.         return $this->shardKey !== [];
  1229.     }
  1231.     /**
  1232.      * @return array|object|null
  1233.      * @psalm-return array<string, mixed>|object|null
  1234.      */
  1235.     public function getValidator()
  1236.     {
  1237.         return $this->validator;
  1238.     }
  1240.     /**
  1241.      * @param array|object|null $validator
  1242.      * @psalm-param array<string, mixed>|object|null $validator
  1243.      */
  1244.     public function setValidator($validator): void
  1245.     {
  1246.         $this->validator = $validator;
  1247.     }
  1249.     public function getValidationAction(): string
  1250.     {
  1251.         return $this->validationAction;
  1252.     }
  1254.     public function setValidationAction(string $validationAction): void
  1255.     {
  1256.         $this->validationAction = $validationAction;
  1257.     }
  1259.     public function getValidationLevel(): string
  1260.     {
  1261.         return $this->validationLevel;
  1262.     }
  1264.     public function setValidationLevel(string $validationLevel): void
  1265.     {
  1266.         $this->validationLevel = $validationLevel;
  1267.     }
  1269.     /**
  1270.      * Sets the read preference used by this class.
  1271.      *
  1272.      * @param array<array<string, string>> $tags
  1273.      */
  1274.     public function setReadPreference(?string $readPreference, array $tags): void
  1275.     {
  1276.         $this->readPreference     = $readPreference;
  1277.         $this->readPreferenceTags = $tags;
  1278.     }
  1280.     /**
  1281.      * Sets the write concern used by this class.
  1282.      *
  1283.      * @param string|int|null $writeConcern
  1284.      */
  1285.     public function setWriteConcern($writeConcern): void
  1286.     {
  1287.         $this->writeConcern = $writeConcern;
  1288.     }
  1290.     /** @return int|string|null */
  1291.     public function getWriteConcern()
  1292.     {
  1293.         return $this->writeConcern;
  1294.     }
  1296.     /**
  1297.      * Whether there is a write concern configured for this class.
  1298.      */
  1299.     public function hasWriteConcern(): bool
  1300.     {
  1301.         return $this->writeConcern !== null;
  1302.     }
  1304.     /**
  1305.      * Sets the change tracking policy used by this class.
  1306.      */
  1307.     public function setChangeTrackingPolicy(int $policy): void
  1308.     {
  1309.         $this->changeTrackingPolicy = $policy;
  1310.     }
  1312.     /**
  1313.      * Whether the change tracking policy of this class is "deferred explicit".
  1314.      */
  1315.     public function isChangeTrackingDeferredExplicit(): bool
  1316.     {
  1317.         return $this->changeTrackingPolicy === self::CHANGETRACKING_DEFERRED_EXPLICIT;
  1318.     }
  1320.     /**
  1321.      * Whether the change tracking policy of this class is "deferred implicit".
  1322.      */
  1323.     public function isChangeTrackingDeferredImplicit(): bool
  1324.     {
  1325.         return $this->changeTrackingPolicy === self::CHANGETRACKING_DEFERRED_IMPLICIT;
  1326.     }
  1328.     /**
  1329.      * Whether the change tracking policy of this class is "notify".
  1330.      *
  1331.      * @deprecated This method was deprecated in doctrine/mongodb-odm 2.4. Please use DEFERRED_EXPLICIT tracking
  1332.      * policy and isChangeTrackingDeferredImplicit method to detect it.
  1333.      */
  1334.     public function isChangeTrackingNotify(): bool
  1335.     {
  1336.         return $this->changeTrackingPolicy === self::CHANGETRACKING_NOTIFY;
  1337.     }
  1339.     /**
  1340.      * Gets the ReflectionProperties of the mapped class.
  1341.      *
  1342.      * @return ReflectionProperty[]
  1343.      */
  1344.     public function getReflectionProperties(): array
  1345.     {
  1346.         return $this->reflFields;
  1347.     }
  1349.     /**
  1350.      * Gets a ReflectionProperty for a specific field of the mapped class.
  1351.      */
  1352.     public function getReflectionProperty(string $name): ReflectionProperty
  1353.     {
  1354.         return $this->reflFields[$name];
  1355.     }
  1357.     /** @psalm-return class-string<T> */
  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 fn ($assoc) => ! empty($assoc['embedded'])
  1855.         );
  1856.     }
  1858.     /**
  1859.      * Gets the field mapping by its DB name.
  1860.      * E.g. it returns identifier's mapping when called with _id.
  1861.      *
  1862.      * @psalm-return FieldMapping
  1863.      *
  1864.      * @throws MappingException
  1865.      */
  1866.     public function getFieldMappingByDbFieldName(string $dbFieldName): array
  1867.     {
  1868.         foreach ($this->fieldMappings as $mapping) {
  1869.             if ($mapping['name'] === $dbFieldName) {
  1870.                 return $mapping;
  1871.             }
  1872.         }
  1874.         throw MappingException::mappingNotFoundByDbName($this->name, $dbFieldName);
  1875.     }
  1877.     /**
  1878.      * Check if the field is not null.
  1879.      */
  1880.     public function isNullable(string $fieldName): bool
  1881.     {
  1882.         $mapping = $this->getFieldMapping($fieldName);
  1884.         return isset($mapping['nullable']) && $mapping['nullable'] === true;
  1885.     }
  1887.     /**
  1888.      * Checks whether the document has a discriminator field and value configured.
  1889.      */
  1890.     public function hasDiscriminator(): bool
  1891.     {
  1892.         return isset($this->discriminatorField, $this->discriminatorValue);
  1893.     }
  1895.     /**
  1896.      * Sets the type of Id generator to use for the mapped class.
  1897.      */
  1898.     public function setIdGeneratorType(int $generatorType): void
  1899.     {
  1900.         $this->generatorType = $generatorType;
  1901.     }
  1903.     /**
  1904.      * Sets the Id generator options.
  1905.      *
  1906.      * @param array<string, mixed> $generatorOptions
  1907.      */
  1908.     public function setIdGeneratorOptions(array $generatorOptions): void
  1909.     {
  1910.         $this->generatorOptions = $generatorOptions;
  1911.     }
  1913.     public function isInheritanceTypeNone(): bool
  1914.     {
  1915.         return $this->inheritanceType === self::INHERITANCE_TYPE_NONE;
  1916.     }
  1918.     /**
  1919.      * Checks whether the mapped class uses the SINGLE_COLLECTION inheritance mapping strategy.
  1920.      */
  1921.     public function isInheritanceTypeSingleCollection(): bool
  1922.     {
  1923.         return $this->inheritanceType === self::INHERITANCE_TYPE_SINGLE_COLLECTION;
  1924.     }
  1926.     /**
  1927.      * Checks whether the mapped class uses the COLLECTION_PER_CLASS inheritance mapping strategy.
  1928.      */
  1929.     public function isInheritanceTypeCollectionPerClass(): bool
  1930.     {
  1931.         return $this->inheritanceType === self::INHERITANCE_TYPE_COLLECTION_PER_CLASS;
  1932.     }
  1934.     /**
  1935.      * Sets the mapped subclasses of this class.
  1936.      *
  1937.      * @param string[] $subclasses The names of all mapped subclasses.
  1938.      * @psalm-param class-string[] $subclasses
  1939.      */
  1940.     public function setSubclasses(array $subclasses): void
  1941.     {
  1942.         foreach ($subclasses as $subclass) {
  1943.             $this->subClasses[] = $subclass;
  1944.         }
  1945.     }
  1947.     /**
  1948.      * Sets the parent class names.
  1949.      * Assumes that the class names in the passed array are in the order:
  1950.      * directParent -> directParentParent -> directParentParentParent ... -> root.
  1951.      *
  1952.      * @param string[] $classNames
  1953.      * @psalm-param list<class-string> $classNames
  1954.      */
  1955.     public function setParentClasses(array $classNames): void
  1956.     {
  1957.         $this->parentClasses = $classNames;
  1959.         if (count($classNames) <= 0) {
  1960.             return;
  1961.         }
  1963.         $this->rootDocumentName = (string) array_pop($classNames);
  1964.     }
  1966.     /**
  1967.      * Checks whether the class will generate a new \MongoDB\BSON\ObjectId instance for us.
  1968.      */
  1969.     public function isIdGeneratorAuto(): bool
  1970.     {
  1971.         return $this->generatorType === self::GENERATOR_TYPE_AUTO;
  1972.     }
  1974.     /**
  1975.      * Checks whether the class will use a collection to generate incremented identifiers.
  1976.      */
  1977.     public function isIdGeneratorIncrement(): bool
  1978.     {
  1979.         return $this->generatorType === self::GENERATOR_TYPE_INCREMENT;
  1980.     }
  1982.     /**
  1983.      * Checks whether the class will generate a uuid id.
  1984.      */
  1985.     public function isIdGeneratorUuid(): bool
  1986.     {
  1987.         return $this->generatorType === self::GENERATOR_TYPE_UUID;
  1988.     }
  1990.     /**
  1991.      * Checks whether the class uses no id generator.
  1992.      */
  1993.     public function isIdGeneratorNone(): bool
  1994.     {
  1995.         return $this->generatorType === self::GENERATOR_TYPE_NONE;
  1996.     }
  1998.     /**
  1999.      * Sets the version field mapping used for versioning. Sets the default
  2000.      * value to use depending on the column type.
  2001.      *
  2002.      * @psalm-param FieldMapping $mapping
  2003.      *
  2004.      * @throws LockException
  2005.      */
  2006.     public function setVersionMapping(array &$mapping): void
  2007.     {
  2008.         if (! Type::getType($mapping['type']) instanceof Versionable) {
  2009.             throw LockException::invalidVersionFieldType($mapping['type']);
  2010.         }
  2012.         $this->isVersioned  = true;
  2013.         $this->versionField = $mapping['fieldName'];
  2014.     }
  2016.     /**
  2017.      * Sets whether this class is to be versioned for optimistic locking.
  2018.      */
  2019.     public function setVersioned(bool $bool): void
  2020.     {
  2021.         $this->isVersioned = $bool;
  2022.     }
  2024.     /**
  2025.      * Sets the name of the field that is to be used for versioning if this class is
  2026.      * versioned for optimistic locking.
  2027.      */
  2028.     public function setVersionField(?string $versionField): void
  2029.     {
  2030.         $this->versionField = $versionField;
  2031.     }
  2033.     /**
  2034.      * Sets the version field mapping used for versioning. Sets the default
  2035.      * value to use depending on the column type.
  2036.      *
  2037.      * @psalm-param FieldMapping $mapping
  2038.      *
  2039.      * @throws LockException
  2040.      */
  2041.     public function setLockMapping(array &$mapping): void
  2042.     {
  2043.         if ($mapping['type'] !== 'int') {
  2044.             throw LockException::invalidLockFieldType($mapping['type']);
  2045.         }
  2047.         $this->isLockable = true;
  2048.         $this->lockField  = $mapping['fieldName'];
  2049.     }
  2051.     /**
  2052.      * Sets whether this class is to allow pessimistic locking.
  2053.      */
  2054.     public function setLockable(bool $bool): void
  2055.     {
  2056.         $this->isLockable = $bool;
  2057.     }
  2059.     /**
  2060.      * Sets the name of the field that is to be used for storing whether a document
  2061.      * is currently locked or not.
  2062.      */
  2063.     public function setLockField(string $lockField): void
  2064.     {
  2065.         $this->lockField = $lockField;
  2066.     }
  2068.     /**
  2069.      * Marks this class as read only, no change tracking is applied to it.
  2070.      */
  2071.     public function markReadOnly(): void
  2072.     {
  2073.         $this->isReadOnly = true;
  2074.     }
  2076.     public function getRootClass(): ?string
  2077.     {
  2078.         return $this->rootClass;
  2079.     }
  2081.     public function isView(): bool
  2082.     {
  2083.         return $this->isView;
  2084.     }
  2086.     /** @psalm-param class-string $rootClass */
  2087.     public function markViewOf(string $rootClass): void
  2088.     {
  2089.         $this->isView    = true;
  2090.         $this->rootClass = $rootClass;
  2091.     }
  2093.     public function getFieldNames(): array
  2094.     {
  2095.         return array_keys($this->fieldMappings);
  2096.     }
  2098.     public function getAssociationNames(): array
  2099.     {
  2100.         return array_keys($this->associationMappings);
  2101.     }
  2103.     /** @param string $fieldName */
  2104.     public function getTypeOfField($fieldName): ?string
  2105.     {
  2106.         return isset($this->fieldMappings[$fieldName]) ?
  2107.             $this->fieldMappings[$fieldName]['type'] : null;
  2108.     }
  2110.     /**
  2111.      * @param string $assocName
  2112.      *
  2113.      * @psalm-return class-string|null
  2114.      */
  2115.     public function getAssociationTargetClass($assocName): ?string
  2116.     {
  2117.         if (! isset($this->associationMappings[$assocName])) {
  2118.             throw new InvalidArgumentException("Association name expected, '" . $assocName . "' is not an association.");
  2119.         }
  2121.         return $this->associationMappings[$assocName]['targetDocument'] ?? null;
  2122.     }
  2124.     /**
  2125.      * Retrieve the collectionClass associated with an association
  2126.      *
  2127.      * @psalm-return class-string
  2128.      */
  2129.     public function getAssociationCollectionClass(string $assocName): string
  2130.     {
  2131.         if (! isset($this->associationMappings[$assocName])) {
  2132.             throw new InvalidArgumentException("Association name expected, '" . $assocName . "' is not an association.");
  2133.         }
  2135.         if (! array_key_exists('collectionClass', $this->associationMappings[$assocName])) {
  2136.             throw new InvalidArgumentException("collectionClass can only be applied to 'embedMany' and 'referenceMany' associations.");
  2137.         }
  2139.         return $this->associationMappings[$assocName]['collectionClass'];
  2140.     }
  2142.     /** @param string $assocName */
  2143.     public function isAssociationInverseSide($assocName): bool
  2144.     {
  2145.         throw new BadMethodCallException(__METHOD__ . '() is not implemented yet.');
  2146.     }
  2148.     /** @param string $assocName */
  2149.     public function getAssociationMappedByTargetField($assocName)
  2150.     {
  2151.         throw new BadMethodCallException(__METHOD__ . '() is not implemented yet.');
  2152.     }
  2154.     /**
  2155.      * Map a field.
  2156.      *
  2157.      * @psalm-param FieldMappingConfig $mapping
  2158.      *
  2159.      * @psalm-return FieldMapping
  2160.      *
  2161.      * @throws MappingException
  2162.      */
  2163.     public function mapField(array $mapping): array
  2164.     {
  2165.         if (! isset($mapping['fieldName']) && isset($mapping['name'])) {
  2166.             $mapping['fieldName'] = $mapping['name'];
  2167.         }
  2169.         if ($this->isTypedProperty($mapping['fieldName'])) {
  2170.             $mapping = $this->validateAndCompleteTypedFieldMapping($mapping);
  2172.             if (isset($mapping['type']) && $mapping['type'] === self::MANY) {
  2173.                 $mapping = $this->validateAndCompleteTypedManyAssociationMapping($mapping);
  2174.             }
  2175.         }
  2177.         if (! isset($mapping['fieldName']) || ! is_string($mapping['fieldName'])) {
  2178.             throw MappingException::missingFieldName($this->name);
  2179.         }
  2181.         if (! isset($mapping['name'])) {
  2182.             $mapping['name'] = $mapping['fieldName'];
  2183.         }
  2185.         if ($this->identifier === $mapping['name'] && empty($mapping['id'])) {
  2186.             throw MappingException::mustNotChangeIdentifierFieldsType($this->name, (string) $mapping['name']);
  2187.         }
  2189.         if ($this->discriminatorField !== null && $this->discriminatorField === $mapping['name']) {
  2190.             throw MappingException::discriminatorFieldConflict($this->name, $this->discriminatorField);
  2191.         }
  2193.         if (isset($mapping['collectionClass'])) {
  2194.             $mapping['collectionClass'] = ltrim($mapping['collectionClass'], '\\');
  2195.         }
  2197.         if (! empty($mapping['collectionClass'])) {
  2198.             $rColl = new ReflectionClass($mapping['collectionClass']);
  2199.             if (! $rColl->implementsInterface(Collection::class)) {
  2200.                 throw MappingException::collectionClassDoesNotImplementCommonInterface($this->name, $mapping['fieldName'], $mapping['collectionClass']);
  2201.             }
  2202.         }
  2204.         if (isset($mapping['cascade']) && isset($mapping['embedded'])) {
  2205.             throw MappingException::cascadeOnEmbeddedNotAllowed($this->name, $mapping['fieldName']);
  2206.         }
  2208.         $cascades = isset($mapping['cascade']) ? array_map('strtolower', (array) $mapping['cascade']) : [];
  2210.         if (in_array('all', $cascades) || isset($mapping['embedded'])) {
  2211.             $cascades = ['remove', 'persist', 'refresh', 'merge', 'detach'];
  2212.         }
  2214.         if (isset($mapping['embedded'])) {
  2215.             unset($mapping['cascade']);
  2216.         } elseif (isset($mapping['cascade'])) {
  2217.             $mapping['cascade'] = $cascades;
  2218.         }
  2220.         $mapping['isCascadeRemove']  = in_array('remove', $cascades);
  2221.         $mapping['isCascadePersist'] = in_array('persist', $cascades);
  2222.         $mapping['isCascadeRefresh'] = in_array('refresh', $cascades);
  2223.         $mapping['isCascadeMerge']   = in_array('merge', $cascades);
  2224.         $mapping['isCascadeDetach']  = in_array('detach', $cascades);
  2226.         if (isset($mapping['id']) && $mapping['id'] === true) {
  2227.             $mapping['name']  = '_id';
  2228.             $this->identifier = $mapping['fieldName'];
  2229.             if (isset($mapping['strategy'])) {
  2230.                 $this->generatorType = constant(self::class . '::GENERATOR_TYPE_' . strtoupper($mapping['strategy']));
  2231.             }
  2233.             $this->generatorOptions = $mapping['options'] ?? [];
  2234.             switch ($this->generatorType) {
  2235.                 case self::GENERATOR_TYPE_AUTO:
  2236.                     $mapping['type'] = 'id';
  2237.                     break;
  2238.                 default:
  2239.                     if (! empty($this->generatorOptions['type'])) {
  2240.                         $mapping['type'] = (string) $this->generatorOptions['type'];
  2241.                     } elseif (empty($mapping['type'])) {
  2242.                         $mapping['type'] = $this->generatorType === self::GENERATOR_TYPE_INCREMENT ? Type::INT : Type::CUSTOMID;
  2243.                     }
  2244.             }
  2246.             unset($this->generatorOptions['type']);
  2247.         }
  2249.         if (! isset($mapping['type'])) {
  2250.             // Default to string
  2251.             $mapping['type'] = Type::STRING;
  2252.         }
  2254.         if (! isset($mapping['nullable'])) {
  2255.             $mapping['nullable'] = false;
  2256.         }
  2258.         if (
  2259.             isset($mapping['reference'])
  2260.             && isset($mapping['storeAs'])
  2261.             && $mapping['storeAs'] === self::REFERENCE_STORE_AS_ID
  2262.             && ! isset($mapping['targetDocument'])
  2263.         ) {
  2264.             throw MappingException::simpleReferenceRequiresTargetDocument($this->name, $mapping['fieldName']);
  2265.         }
  2267.         if (
  2268.             isset($mapping['reference']) && empty($mapping['targetDocument']) && empty($mapping['discriminatorMap']) &&
  2269.                 (isset($mapping['mappedBy']) || isset($mapping['inversedBy']))
  2270.         ) {
  2271.             throw MappingException::owningAndInverseReferencesRequireTargetDocument($this->name, $mapping['fieldName']);
  2272.         }
  2274.         if ($this->isEmbeddedDocument && $mapping['type'] === self::MANY && isset($mapping['strategy']) && CollectionHelper::isAtomic($mapping['strategy'])) {
  2275.             throw MappingException::atomicCollectionStrategyNotAllowed($mapping['strategy'], $this->name, $mapping['fieldName']);
  2276.         }
  2278.         if (isset($mapping['repositoryMethod']) && ! (empty($mapping['skip']) && empty($mapping['limit']) && empty($mapping['sort']))) {
  2279.             throw MappingException::repositoryMethodCanNotBeCombinedWithSkipLimitAndSort($this->name, $mapping['fieldName']);
  2280.         }
  2282.         if (isset($mapping['targetDocument']) && isset($mapping['discriminatorMap'])) {
  2283.             trigger_deprecation(
  2284.                 'doctrine/mongodb-odm',
  2285.                 '2.2',
  2286.                 'Mapping both "targetDocument" and "discriminatorMap" on field "%s" in class "%s" is deprecated. Only one of them can be used at a time',
  2287.                 $mapping['fieldName'],
  2288.                 $this->name,
  2289.             );
  2290.         }
  2292.         if (isset($mapping['reference']) && $mapping['type'] === self::ONE) {
  2293.             $mapping['association'] = self::REFERENCE_ONE;
  2294.         }
  2296.         if (isset($mapping['reference']) && $mapping['type'] === self::MANY) {
  2297.             $mapping['association'] = self::REFERENCE_MANY;
  2298.         }
  2300.         if (isset($mapping['embedded']) && $mapping['type'] === self::ONE) {
  2301.             $mapping['association'] = self::EMBED_ONE;
  2302.         }
  2304.         if (isset($mapping['embedded']) && $mapping['type'] === self::MANY) {
  2305.             $mapping['association'] = self::EMBED_MANY;
  2306.         }
  2308.         if (isset($mapping['association']) && ! isset($mapping['targetDocument']) && ! isset($mapping['discriminatorField'])) {
  2309.             $mapping['discriminatorField'] = self::DEFAULT_DISCRIMINATOR_FIELD;
  2310.         }
  2312.         if (isset($mapping['targetDocument']) && ! class_exists($mapping['targetDocument']) && ! interface_exists($mapping['targetDocument'])) {
  2313.             throw MappingException::invalidTargetDocument(
  2314.                 $mapping['targetDocument'],
  2315.                 $this->name,
  2316.                 $mapping['fieldName'],
  2317.             );
  2318.         }
  2320.         if (isset($mapping['discriminatorMap'])) {
  2321.             foreach ($mapping['discriminatorMap'] as $value => $class) {
  2322.                 if (! class_exists($class) && ! interface_exists($class)) {
  2323.                     throw MappingException::invalidClassInReferenceDiscriminatorMap($class, $this->name, $mapping['fieldName']);
  2324.                 }
  2325.             }
  2326.         }
  2328.         if (isset($mapping['version'])) {
  2329.             $mapping['notSaved'] = true;
  2330.             $this->setVersionMapping($mapping);
  2331.         }
  2333.         if (isset($mapping['lock'])) {
  2334.             $mapping['notSaved'] = true;
  2335.             $this->setLockMapping($mapping);
  2336.         }
  2338.         $mapping['isOwningSide']  = true;
  2339.         $mapping['isInverseSide'] = false;
  2340.         if (isset($mapping['reference'])) {
  2341.             if (isset($mapping['inversedBy']) && $mapping['inversedBy']) {
  2342.                 $mapping['isOwningSide']  = true;
  2343.                 $mapping['isInverseSide'] = false;
  2344.             }
  2346.             if (isset($mapping['mappedBy']) && $mapping['mappedBy']) {
  2347.                 $mapping['isInverseSide'] = true;
  2348.                 $mapping['isOwningSide']  = false;
  2349.             }
  2351.             if (isset($mapping['repositoryMethod'])) {
  2352.                 $mapping['isInverseSide'] = true;
  2353.                 $mapping['isOwningSide']  = false;
  2354.             }
  2356.             if (! isset($mapping['orphanRemoval'])) {
  2357.                 $mapping['orphanRemoval'] = false;
  2358.             }
  2359.         }
  2361.         if (! empty($mapping['prime']) && ($mapping['association'] !== self::REFERENCE_MANY || ! $mapping['isInverseSide'])) {
  2362.             throw MappingException::referencePrimersOnlySupportedForInverseReferenceMany($this->name, $mapping['fieldName']);
  2363.         }
  2365.         if ($this->isFile && ! $this->isAllowedGridFSField($mapping['name'])) {
  2366.             throw MappingException::fieldNotAllowedForGridFS($this->name, $mapping['fieldName']);
  2367.         }
  2369.         $this->applyStorageStrategy($mapping);
  2370.         $this->checkDuplicateMapping($mapping);
  2371.         $this->typeRequirementsAreMet($mapping);
  2373.         $deprecatedTypes = [
  2374.             Type::BOOLEAN => Type::BOOL,
  2375.             Type::INTEGER => Type::INT,
  2376.             Type::INTID => Type::INT,
  2377.         ];
  2378.         if (isset($deprecatedTypes[$mapping['type']])) {
  2379.             trigger_deprecation(
  2380.                 'doctrine/mongodb-odm',
  2381.                 '2.1',
  2382.                 'The "%s" mapping type is deprecated. Use "%s" instead.',
  2383.                 $mapping['type'],
  2384.                 $deprecatedTypes[$mapping['type']],
  2385.             );
  2386.         }
  2388.         $this->fieldMappings[$mapping['fieldName']] = $mapping;
  2389.         if (isset($mapping['association'])) {
  2390.             $this->associationMappings[$mapping['fieldName']] = $mapping;
  2391.         }
  2393.         $reflProp = $this->reflectionService->getAccessibleProperty($this->name, $mapping['fieldName']);
  2394.         assert($reflProp instanceof ReflectionProperty);
  2396.         if (isset($mapping['enumType'])) {
  2397.             if (! enum_exists($mapping['enumType'])) {
  2398.                 throw MappingException::nonEnumTypeMapped($this->name, $mapping['fieldName'], $mapping['enumType']);
  2399.             }
  2401.             $reflectionEnum = new ReflectionEnum($mapping['enumType']);
  2402.             if (! $reflectionEnum->isBacked()) {
  2403.                 throw MappingException::nonBackedEnumMapped($this->name, $mapping['fieldName'], $mapping['enumType']);
  2404.             }
  2406.             $reflProp = new EnumReflectionProperty($reflProp, $mapping['enumType']);
  2407.         }
  2409.         $this->reflFields[$mapping['fieldName']] = $reflProp;
  2411.         return $mapping;
  2412.     }
  2414.     /**
  2415.      * Determines which fields get serialized.
  2416.      *
  2417.      * It is only serialized what is necessary for best unserialization performance.
  2418.      * That means any metadata properties that are not set or empty or simply have
  2419.      * their default value are NOT serialized.
  2420.      *
  2421.      * Parts that are also NOT serialized because they can not be properly unserialized:
  2422.      *      - reflClass (ReflectionClass)
  2423.      *      - reflFields (ReflectionProperty array)
  2424.      *
  2425.      * @return array The names of all the fields that should be serialized.
  2426.      */
  2427.     public function __sleep()
  2428.     {
  2429.         // This metadata is always serialized/cached.
  2430.         $serialized = [
  2431.             'fieldMappings',
  2432.             'associationMappings',
  2433.             'identifier',
  2434.             'name',
  2435.             'db',
  2436.             'collection',
  2437.             'readPreference',
  2438.             'readPreferenceTags',
  2439.             'writeConcern',
  2440.             'rootDocumentName',
  2441.             'generatorType',
  2442.             'generatorOptions',
  2443.             'idGenerator',
  2444.             'indexes',
  2445.             'shardKey',
  2446.         ];
  2448.         // The rest of the metadata is only serialized if necessary.
  2449.         if ($this->changeTrackingPolicy !== self::CHANGETRACKING_DEFERRED_IMPLICIT) {
  2450.             $serialized[] = 'changeTrackingPolicy';
  2451.         }
  2453.         if ($this->customRepositoryClassName) {
  2454.             $serialized[] = 'customRepositoryClassName';
  2455.         }
  2457.         if ($this->inheritanceType !== self::INHERITANCE_TYPE_NONE || $this->discriminatorField !== null) {
  2458.             $serialized[] = 'inheritanceType';
  2459.             $serialized[] = 'discriminatorField';
  2460.             $serialized[] = 'discriminatorValue';
  2461.             $serialized[] = 'discriminatorMap';
  2462.             $serialized[] = 'defaultDiscriminatorValue';
  2463.             $serialized[] = 'parentClasses';
  2464.             $serialized[] = 'subClasses';
  2465.         }
  2467.         if ($this->isMappedSuperclass) {
  2468.             $serialized[] = 'isMappedSuperclass';
  2469.         }
  2471.         if ($this->isEmbeddedDocument) {
  2472.             $serialized[] = 'isEmbeddedDocument';
  2473.         }
  2475.         if ($this->isQueryResultDocument) {
  2476.             $serialized[] = 'isQueryResultDocument';
  2477.         }
  2479.         if ($this->isView()) {
  2480.             $serialized[] = 'isView';
  2481.             $serialized[] = 'rootClass';
  2482.         }
  2484.         if ($this->isFile) {
  2485.             $serialized[] = 'isFile';
  2486.             $serialized[] = 'bucketName';
  2487.             $serialized[] = 'chunkSizeBytes';
  2488.         }
  2490.         if ($this->isVersioned) {
  2491.             $serialized[] = 'isVersioned';
  2492.             $serialized[] = 'versionField';
  2493.         }
  2495.         if ($this->isLockable) {
  2496.             $serialized[] = 'isLockable';
  2497.             $serialized[] = 'lockField';
  2498.         }
  2500.         if ($this->lifecycleCallbacks) {
  2501.             $serialized[] = 'lifecycleCallbacks';
  2502.         }
  2504.         if ($this->collectionCapped) {
  2505.             $serialized[] = 'collectionCapped';
  2506.             $serialized[] = 'collectionSize';
  2507.             $serialized[] = 'collectionMax';
  2508.         }
  2510.         if ($this->isReadOnly) {
  2511.             $serialized[] = 'isReadOnly';
  2512.         }
  2514.         if ($this->validator !== null) {
  2515.             $serialized[] = 'validator';
  2516.             $serialized[] = 'validationAction';
  2517.             $serialized[] = 'validationLevel';
  2518.         }
  2520.         return $serialized;
  2521.     }
  2523.     /**
  2524.      * Restores some state that can not be serialized/unserialized.
  2525.      */
  2526.     public function __wakeup()
  2527.     {
  2528.         // Restore ReflectionClass and properties
  2529.         $this->reflectionService = new RuntimeReflectionService();
  2530.         $this->reflClass         = new ReflectionClass($this->name);
  2531.         $this->instantiator      = new Instantiator();
  2533.         foreach ($this->fieldMappings as $field => $mapping) {
  2534.             $prop = $this->reflectionService->getAccessibleProperty($mapping['declared'] ?? $this->name, $field);
  2535.             assert($prop instanceof ReflectionProperty);
  2537.             if (isset($mapping['enumType'])) {
  2538.                 $prop = new EnumReflectionProperty($prop, $mapping['enumType']);
  2539.             }
  2541.             $this->reflFields[$field] = $prop;
  2542.         }
  2543.     }
  2545.     /**
  2546.      * Creates a new instance of the mapped class, without invoking the constructor.
  2547.      *
  2548.      * @psalm-return T
  2549.      */
  2550.     public function newInstance(): object
  2551.     {
  2552.         /** @psalm-var T */
  2553.         return $this->instantiator->instantiate($this->name);
  2554.     }
  2556.     private function isAllowedGridFSField(string $name): bool
  2557.     {
  2558.         return in_array($name, self::ALLOWED_GRIDFS_FIELDS, true);
  2559.     }
  2561.     /** @psalm-param FieldMapping $mapping */
  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.     /** @psalm-param FieldMapping $mapping */
  2570.     private function checkDuplicateMapping(array $mapping): void
  2571.     {
  2572.         if ($mapping['notSaved'] ?? false) {
  2573.             return;
  2574.         }
  2576.         foreach ($this->fieldMappings as $fieldName => $otherMapping) {
  2577.             // Ignore fields with the same name - we can safely override their mapping
  2578.             if ($mapping['fieldName'] === $fieldName) {
  2579.                 continue;
  2580.             }
  2582.             // Ignore fields with a different name in the database
  2583.             if ($mapping['name'] !== $otherMapping['name']) {
  2584.                 continue;
  2585.             }
  2587.             // If the other field is not saved, ignore it as well
  2588.             if ($otherMapping['notSaved'] ?? false) {
  2589.                 continue;
  2590.             }
  2592.             throw MappingException::duplicateDatabaseFieldName($this->getName(), $mapping['fieldName'], $mapping['name'], $fieldName);
  2593.         }
  2594.     }
  2596.     private function isTypedProperty(string $name): bool
  2597.     {
  2598.         return $this->reflClass->hasProperty($name)
  2599.             && $this->reflClass->getProperty($name)->hasType();
  2600.     }
  2602.     /**
  2603.      * Validates & completes the given field mapping based on typed property.
  2604.      *
  2605.      * @psalm-param FieldMappingConfig $mapping
  2606.      *
  2607.      * @return FieldMappingConfig
  2608.      */
  2609.     private function validateAndCompleteTypedFieldMapping(array $mapping): array
  2610.     {
  2611.         $type = $this->reflClass->getProperty($mapping['fieldName'])->getType();
  2613.         if (! $type instanceof ReflectionNamedType || isset($mapping['type'])) {
  2614.             return $mapping;
  2615.         }
  2617.         if (! $type->isBuiltin() && enum_exists($type->getName())) {
  2618.             $reflection = new ReflectionEnum($type->getName());
  2620.             if (! $reflection->isBacked()) {
  2621.                 throw MappingException::nonBackedEnumMapped($this->name, $mapping['fieldName'], $reflection->getName());
  2622.             }
  2624.             $type = $reflection->getBackingType();
  2625.             assert($type instanceof ReflectionNamedType);
  2626.             $mapping['enumType'] = $reflection->getName();
  2627.         }
  2629.         switch ($type->getName()) {
  2630.             case DateTime::class:
  2631.                 $mapping['type'] = Type::DATE;
  2632.                 break;
  2633.             case DateTimeImmutable::class:
  2634.                 $mapping['type'] = Type::DATE_IMMUTABLE;
  2635.                 break;
  2636.             case 'array':
  2637.                 $mapping['type'] = Type::HASH;
  2638.                 break;
  2639.             case 'bool':
  2640.                 $mapping['type'] = Type::BOOL;
  2641.                 break;
  2642.             case 'float':
  2643.                 $mapping['type'] = Type::FLOAT;
  2644.                 break;
  2645.             case 'int':
  2646.                 $mapping['type'] = Type::INT;
  2647.                 break;
  2648.             case 'string':
  2649.                 $mapping['type'] = Type::STRING;
  2650.                 break;
  2651.         }
  2653.         return $mapping;
  2654.     }
  2656.     /**
  2657.      * Validates & completes the basic mapping information based on typed property.
  2658.      *
  2659.      * @psalm-param FieldMappingConfig $mapping
  2660.      *
  2661.      * @return FieldMappingConfig
  2662.      */
  2663.     private function validateAndCompleteTypedManyAssociationMapping(array $mapping): array
  2664.     {
  2665.         $type = $this->reflClass->getProperty($mapping['fieldName'])->getType();
  2667.         if (! $type instanceof ReflectionNamedType) {
  2668.             return $mapping;
  2669.         }
  2671.         if (! isset($mapping['collectionClass']) && class_exists($type->getName())) {
  2672.             $mapping['collectionClass'] = $type->getName();
  2673.         }
  2675.         return $mapping;
  2676.     }
  2677. }