Merge remote-tracking branch 'origin/2.3.x' into support-expr-in-queries

# Conflicts:
#	composer.json
#	lib/Doctrine/ODM/MongoDB/Persisters/PersistenceBuilder.php
#	lib/Doctrine/ODM/MongoDB/Query/Expr.php
#	phpstan-baseline.neon
#	tests/Doctrine/ODM/MongoDB/Tests/Mapping/ClassMetadataTest.php

Author: Vincent Le Henaff

.doctrine-project.json

@@ -26,7 +26,6 @@
             "name": "2.1",
             "branchName": "2.1.x",
             "slug": "2.1",
-            "current": true,
             "maintained": false,
             "aliases": [
                 "2.1.x"
@@ -45,6 +44,7 @@
             "name": "1.3",
             "branchName": "1.3.x",
             "slug": "1.3",
+            "maintained": false,
             "aliases": [
                 "1.3.x"
             ]

UPGRADE-2.2.md

@@ -22,3 +22,11 @@ Using `@Index` annotation(s) on a class level is a preferred way for defining
 indexes for documents. Using `@Index` in the `@Indexes` annotation or an `indexes`
 property of other annotations was deprecated and will be removed in ODM 3.0.
 
+## DocumentManager configuration
+
+Using doctrine/cache to cache metadata is deprecated in favor of using PSR-6.
+The `getMetadataCacheImpl` and `setMetadataCacheImpl` methods in
+`Doctrine\ODM\MongoDB\Configuration` have been deprecated. Please use
+`getMetadataCache`and `setMetadataCache` with a PSR-6 implementation instead.
+Note that even after switching to PSR-6, `getMetadataCacheImpl` will return a
+cache instance that wraps the PSR-6 cache.

UPGRADE-2.3.md

@@ -0,0 +1,14 @@
+# UPGRADE FROM 2.2 to 2.3
+
+## Proxy Class Name Resolution
+
+The `Doctrine\ODM\MongoDB\Proxy\Resolver\ClassNameResolver` interface has been
+deprecated in favor of the `Doctrine\Persistence\Mapping\ProxyClassNameResolver`
+interface.
+
+The `getClassNameResolver` method in `DocumentManager` is deprecated and should
+not be used. To retrieve the mapped class name for any object or class string,
+fetch metadata for the class and read the class using `$metadata->getName()`.
+The metadata layer is aware of these proxy namespace changes and how to resolve
+them, so users should always go through the metadata layer to retrieve mapped
+class names.

UPGRADE-3.0.md

@@ -21,3 +21,16 @@ will no longer be extendable.
 The `boolean`, `integer`, and `int_id` mapping types have been removed. Use the
 `bool`, `int`, and `int` types, respectively. These types behave exactly the
 same.
+
+## Proxy Class Name Resolution
+
+The `Doctrine\ODM\MongoDB\Proxy\Resolver\ClassNameResolver` interface has been
+dropped in favor of the `Doctrine\Persistence\Mapping\ProxyClassNameResolver`
+interface.
+
+The `getClassNameResolver` method in `DocumentManager` has been removed. To
+retrieve the mapped class name for any object or class string,  fetch metadata
+for the class and read the class using `$metadata->getName()`. The metadata
+layer is aware of these proxy namespace changes and how to resolve them, so
+users should always go through the metadata layer to retrieve mapped class
+names.

benchmark/BaseBench.php

@@ -4,13 +4,13 @@
 
 namespace Doctrine\ODM\MongoDB\Benchmark;
 
-use Doctrine\Common\Cache\ArrayCache;
 use Doctrine\ODM\MongoDB\Configuration;
 use Doctrine\ODM\MongoDB\DocumentManager;
 use Doctrine\ODM\MongoDB\Mapping\Driver\AnnotationDriver;
 use MongoDB\Client;
 use MongoDB\Model\DatabaseInfo;
 use PhpBench\Benchmark\Metadata\Annotations\BeforeMethods;
+use Symfony\Component\Cache\Adapter\ArrayAdapter;
 
 use function array_map;
 use function getenv;
@@ -48,7 +48,7 @@ public function initDocumentManager()
         $config->setPersistentCollectionNamespace('PersistentCollections');
         $config->setDefaultDB(self::DATABASE_NAME);
         $config->setMetadataDriverImpl(self::createMetadataDriverImpl());
-        $config->setMetadataCacheImpl(new ArrayCache());
+        $config->setMetadataCache(new ArrayAdapter());
 
         $client = new Client(
             getenv('DOCTRINE_MONGODB_SERVER') ?: self::DEFAULT_MONGODB_SERVER,

composer.json

@@ -25,27 +25,30 @@
         "php": "^7.2 || ^8.0",
         "ext-mongodb": "^1.5",
         "doctrine/annotations": "^1.6",
-        "doctrine/cache": "^1.7",
+        "doctrine/cache": "^1.11 || ^2.0",
         "doctrine/collections": "^1.5",
         "doctrine/event-manager": "^1.0",
         "doctrine/instantiator": "^1.1",
-        "doctrine/persistence": "^1.3.5|^2.0",
+        "doctrine/persistence": "^2.2",
         "friendsofphp/proxy-manager-lts": "^1.0",
-        "jean85/pretty-package-versions": "^1.3.0",
+        "jean85/pretty-package-versions": "^1.3.0 || ^2.0.1",
         "mongodb/mongodb": "^1.2.0",
-        "symfony/console": "^3.4|^4.1|^5.0",
+        "psr/cache": "^1.0 || ^2.0 || ^3.0",
+        "symfony/console": "^3.4 || ^4.1 || ^5.0",
         "symfony/deprecation-contracts": "^2.2",
-        "symfony/var-dumper": "^3.4|^4.1|^5.0"
+        "symfony/var-dumper": "^3.4 || ^4.1 || ^5.0"
     },
     "require-dev": {
         "ext-bcmath": "*",
-        "doctrine/coding-standard": "^8.2",
+        "doctrine/coding-standard": "^9.0",
         "jmikola/geojson": "^1.0",
         "phpbench/phpbench": "^1.0.0",
-        "phpstan/phpstan": "^0.12.32",
+        "phpstan/phpstan": "^0.12.89",
+        "phpstan/phpstan-phpunit": "^0.12.19",
         "phpunit/phpunit": "^8.5 || ^9",
         "squizlabs/php_codesniffer": "^3.5",
-        "vimeo/psalm": "^4.2.1"
+        "symfony/cache": "^4.4 || ^5.0",
+        "vimeo/psalm": "^4.8.1"
     },
     "suggest": {
         "ext-bcmath": "Decimal128 type support"

docs/en/cookbook/validation-of-documents.rst

@@ -1,6 +1,9 @@
 Validation of Documents
 =======================
 
+Validation of Documents - Application Side
+------------------------------------------
+
 .. sectionauthor:: Benjamin Eberlei <[email protected]>
 
 Doctrine does not ship with any internal validators, the reason
@@ -127,4 +130,124 @@ instances. This was already discussed in the previous blog post on
 the Versionable extension, which requires another type of event
 called "onFlush".
 
-Further readings: :doc:`Lifecycle Events <../reference/events>`
+Further readings: :doc:`Lifecycle Events <../reference/events>`
+
+Validation of Documents - Database Side
+---------------------------------------
+
+.. sectionauthor:: Alexandre Abrioux <[email protected]>
+
+.. note::
+
+    This feature has been introduced in version 2.3.0
+
+MongoDB ≥ 3.6 offers the capability to validate documents during
+insertions and updates through a schema associated to the collection
+(cf. `MongoDB documentation <https://docs.mongodb.com/manual/core/schema-validation/>`_).
+
+Doctrine MongoDB ODM now provides a way to take advantage of this functionality
+thanks to the new :doc:`@Validation <../reference/annotations-reference#validation>`
+annotation and its properties (also available with XML mapping):
+
+-
+  ``validator`` - The schema that will be used to validate documents.
+  It is a string representing a BSON document under the
+  `Extended JSON specification <https://github.com/mongodb/specifications/blob/master/source/extended-json.rst>`_.
+-
+  ``action`` - The behavior followed by MongoDB to handle documents that
+  violate the validation rules.
+-
+  ``level`` - The threshold used by MongoDB to filter operations that
+  will get validated.
+
+Once defined, those options will be added to the collection after running
+the ``odm:schema:create`` or ``odm:schema:update`` command.
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+
+        namespace Documents;
+
+        use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
+        use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
+
+        /**
+         * @ODM\Document
+         * @ODM\Validation(
+         *     validator=SchemaValidated::VALIDATOR,
+         *     action=ClassMetadata::SCHEMA_VALIDATION_ACTION_WARN,
+         *     level=ClassMetadata::SCHEMA_VALIDATION_LEVEL_MODERATE,
+         * )
+         */
+        class SchemaValidated
+        {
+            public const VALIDATOR = <<<'EOT'
+        {
+            "$jsonSchema": {
+                "required": ["name"],
+                "properties": {
+                    "name": {
+                        "bsonType": "string",
+                        "description": "must be a string and is required"
+                    }
+                }
+            },
+            "$or": [
+                { "phone": { "$type": "string" } },
+                { "email": { "$regex": { "$regularExpression" : { "pattern": "@mongodb\\.com$", "options": "" } } } },
+                { "status": { "$in": [ "Unknown", "Incomplete" ] } }
+            ]
+        }
+        EOT;
+
+            /** @ODM\Id */
+            private $id;
+
+            /** @ODM\Field(type="string") */
+            private $name;
+
+            /** @ODM\Field(type="string") */
+            private $phone;
+
+            /** @ODM\Field(type="string") */
+            private $email;
+
+            /** @ODM\Field(type="string") */
+            private $status;
+        }
+
+    .. code-block:: xml
+
+        <?xml version="1.0" encoding="UTF-8"?>
+        <doctrine-mongo-mapping xmlns="http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping"
+                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                          xsi:schemaLocation="http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping
+                          http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping.xsd">
+
+            <document name="SchemaValidated">
+                <schema-validation action="warn" level="moderate">
+                    {
+                        "$jsonSchema": {
+                            "required": ["name"],
+                            "properties": {
+                                "name": {
+                                    "bsonType": "string",
+                                    "description": "must be a string and is required"
+                                }
+                            }
+                        },
+                        "$or": [
+                            { "phone": { "$type": "string" } },
+                            { "email": { "$regex": { "$regularExpression" : { "pattern": "@mongodb\\.com$", "options": "" } } } },
+                            { "status": { "$in": [ "Unknown", "Incomplete" ] } }
+                        ]
+                    }
+                </schema-validation>
+            </document>
+        </doctrine-mongo-mapping>
+
+Please refer to the :doc:`@Validation <../reference/annotations-reference#document>` annotation reference
+for more details on how to use this feature.

docs/en/reference/annotations-reference.rst

@@ -139,7 +139,7 @@ and it does not contain the class name of the persisted document, a
 @Document
 ---------
 
-Required annotation to mark a PHP class as a document, whose peristence will be
+Required annotation to mark a PHP class as a document, whose persistence will be
 managed by ODM.
 
 Optional attributes:
@@ -1092,6 +1092,100 @@ Alias of `@Index`_, with the ``unique`` option set by default.
 
 .. _annotations_reference_version:
 
+@Validation
+-----------
+
+This annotation may be used at the class level to specify the validation schema
+for the related collection.
+
+-
+   ``validator`` - Specifies a schema that will be used by
+   MongoDB to validate data inserted or updated in the collection.
+   Please refer to the following
+   `MongoDB documentation (Schema Validation ¶) <https://docs.mongodb.com/manual/core/schema-validation/>`_
+   for more details. The value should be a string representing a BSON document under the
+   `Extended JSON specification <https://github.com/mongodb/specifications/blob/master/source/extended-json.rst>`_.
+   The recommended way to fill up this property is to create a class constant
+   (eg. ``::VALIDATOR``) using the
+   `HEREDOC/NOWDOC syntax <https://www.php.net/manual/en/language.types.string.php#language.types.string.syntax.nowdoc>`_
+   for clarity and to reference it as the annotation value.
+   Please note that if you decide to insert the schema directly in the annotation without
+   using a class constant then double quotes ``"`` have to be escaped by doubling them ``""``.
+   This method also requires that you don't prefix multiline strings by the Docblock asterisk symbol ``*``.
+-
+   ``action`` - Determines how MongoDB handles documents that violate
+   the validation rules. Please refer to the related
+   `MongoDB documentation (Accept or Reject Invalid Documents ¶) <https://docs.mongodb.com/manual/core/schema-validation/#accept-or-reject-invalid-documents>`_
+   for more details. The allowed values are the following:
+
+       - ``error``
+       - ``warn``
+
+   If it is not defined then the default behavior (``error``) will be used.
+   Those values are also declared as constants for convenience:
+
+      - ``\Doctrine\ODM\MongoDB\Mapping\ClassMetadata::SCHEMA_VALIDATION_ACTION_ERROR``
+      - ``\Doctrine\ODM\MongoDB\Mapping\ClassMetadata::SCHEMA_VALIDATION_ACTION_WARN``
+
+   Import the ``ClassMetadata`` namespace to use those constants in your annotation.
+-
+   ``level`` - Determines which operations MongoDB applies the
+   validation rules. Please refer to the related
+   `MongoDB documentation (Existing Documents ¶) <https://docs.mongodb.com/manual/core/schema-validation/#existing-documents>`_
+   for more details. The allowed values are the following:
+
+      - ``off``
+      - ``strict``
+      - ``moderate``
+
+   If it is not defined then the default behavior (``strict``) will be used.
+   Those values are also declared as constants for convenience:
+
+      - ``\Doctrine\ODM\MongoDB\Mapping\ClassMetadata::SCHEMA_VALIDATION_LEVEL_OFF``
+      - ``\Doctrine\ODM\MongoDB\Mapping\ClassMetadata::SCHEMA_VALIDATION_LEVEL_STRICT``
+      - ``\Doctrine\ODM\MongoDB\Mapping\ClassMetadata::SCHEMA_VALIDATION_LEVEL_MODERATE``
+
+   Import the ``ClassMetadata`` namespace to use those constants in your annotation.
+
+.. code-block:: php
+
+    <?php
+
+    use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
+    // ... other imports
+
+    /**
+     * @Document
+     * @Validation(
+     *     validator=SchemaValidated::VALIDATOR,
+     *     action=ClassMetadata::SCHEMA_VALIDATION_ACTION_WARN,
+     *     level=ClassMetadata::SCHEMA_VALIDATION_LEVEL_MODERATE,
+     * )
+     */
+    class SchemaValidated
+    {
+        public const VALIDATOR = <<<'EOT'
+    {
+        "$jsonSchema": {
+            "required": ["name"],
+            "properties": {
+                "name": {
+                    "bsonType": "string",
+                    "description": "must be a string and is required"
+                }
+            }
+        },
+        "$or": [
+            { "phone": { "$type": "string" } },
+            { "email": { "$regex": { "$regularExpression" : { "pattern": "@mongodb\\.com$", "options": "" } } } },
+            { "status": { "$in": [ "Unknown", "Incomplete" ] } }
+        ]
+    }
+    EOT;
+
+        // rest of the class code...
+    }
+
 @Version
 --------