Merge release 2.14.0 into 3.0.x

.doctrine-project.json

@@ -6,16 +6,21 @@
     "docsSlug": "doctrine-mongodb-odm",
     "versions": [
         {
-            "name": "2.14",
-            "branchName": "2.14.x",
+            "name": "2.15",
+            "branchName": "2.15.x",
             "slug": "latest",
             "upcoming": true
         },
+        {
+            "name": "2.14",
+            "branchName": "2.14.x",
+            "slug": "2.14",
+            "current": true
+        },
         {
             "name": "2.13",
-            "branchName": "2.13.x",
             "slug": "2.13",
-            "current": true
+            "maintained": false
         },
         {
             "name": "2.12",

.github/workflows/atlas-ci.yml

@@ -96,4 +96,5 @@ jobs:
         run: "vendor/bin/phpunit --group atlas"
         env:
           DOCTRINE_MONGODB_SERVER: "mongodb://127.0.0.1:27017/?directConnection=true"
-          USE_LAZY_GHOST_OBJECTS: ${{ matrix.proxy == 'lazy-ghost' && '1' || '0' }}
+          USE_LAZY_GHOST_OBJECT: ${{ matrix.proxy == 'lazy-ghost' && '1' || '0' }}
+          USE_NATIVE_LAZY_OBJECT: ${{ matrix.proxy == 'native' && '1' || '0' }}

.github/workflows/coding-standards.yml

@@ -11,4 +11,4 @@ on:
 jobs:
   coding-standards:
     name: "Coding Standards"
-    uses: "doctrine/.github/.github/workflows/coding-standards.yml@12.0.0"
+    uses: "doctrine/.github/.github/workflows/coding-standards.yml@12.1.0"

.github/workflows/continuous-integration.yml

@@ -77,6 +77,13 @@ jobs:
             dependencies: "highest"
             symfony-version: "stable"
             proxy: "proxy-manager"
+          # Test with Native Lazy Objects
+          - php-version: "8.4"
+            mongodb-version: "8.0"
+            driver-version: "stable"
+            dependencies: "highest"
+            symfony-version: "stable"
+            proxy: "native"
           # Test with extension 1.21
           - topology: "server"
             php-version: "8.2"
@@ -159,8 +166,9 @@ jobs:
           topology: ${{ matrix.topology }}
 
       - name: "Run PHPUnit"
-        run: "vendor/bin/phpunit --exclude-group=atlas"
+        run: "vendor/bin/phpunit --exclude-group=atlas ${{ matrix.dependencies == 'lowest' && '--do-not-fail-on-deprecation --do-not-fail-on-warning --do-not-fail-on-notice' || '' }}"
         env:
           DOCTRINE_MONGODB_SERVER: ${{ steps.setup-mongodb.outputs.cluster-uri }}
-          USE_LAZY_GHOST_OBJECTS: ${{ matrix.proxy == 'lazy-ghost' && '1' || '0' }}"
+          USE_LAZY_GHOST_OBJECT: ${{ matrix.proxy == 'lazy-ghost' && '1' || '0' }}
+          USE_NATIVE_LAZY_OBJECT: ${{ matrix.proxy == 'native' && '1' || '0' }}
           CRYPT_SHARED_LIB_PATH: ${{ steps.setup-mongodb.outputs.crypt-shared-lib-path }}

.github/workflows/documentation.yml

@@ -17,4 +17,4 @@ on:
 jobs:
   documentation:
     name: "Generate documentation"
-    uses: "doctrine/.github/.github/workflows/documentation.yml@12.0.0"
+    uses: "doctrine/.github/.github/workflows/documentation.yml@12.1.0"

.github/workflows/performance.yml

@@ -56,7 +56,7 @@ jobs:
         uses: "ramsey/composer-install@v3"
 
       - name: "Upload composer.lock as build artifact"
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v5
         with:
           name: composer.lock
           path: composer.lock

.github/workflows/release-on-milestone-closed.yml

@@ -8,7 +8,7 @@ on:
 jobs:
   release:
     name: "Git tag, release & create merge-up PR"
-    uses: "doctrine/.github/.github/workflows/release-on-milestone-closed.yml@12.0.0"
+    uses: "doctrine/.github/.github/workflows/release-on-milestone-closed.yml@12.1.0"
     with:
       use-next-minor-as-default-branch: true
     secrets:

.github/workflows/static-analysis.yml

@@ -51,7 +51,7 @@ jobs:
         uses: "ramsey/composer-install@v3"
 
       - name: "Upload composer.lock as build artifact"
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v5
         with:
           name: "composer-lock-static-analysis-phpstan"
           path: composer.lock

.github/workflows/website-schema.yml

@@ -18,4 +18,4 @@ on:
 jobs:
   json-validate:
     name: "Validate JSON schema"
-    uses: "doctrine/.github/.github/workflows/website-schema.yml@12.0.0"
+    uses: "doctrine/.github/.github/workflows/website-schema.yml@12.1.0"

composer.json

@@ -63,16 +63,17 @@
         "ext-bcmath": "Decimal128 type support"
     },
     "autoload": {
-        "psr-4": { "Doctrine\\ODM\\MongoDB\\": "lib/Doctrine/ODM/MongoDB" }
+        "psr-4": { "Doctrine\\ODM\\MongoDB\\": "src" }
     },
     "autoload-dev": {
         "psr-4": {
             "Doctrine\\ODM\\MongoDB\\Benchmark\\": "benchmark",
-            "Doctrine\\ODM\\MongoDB\\Tests\\": "tests/Doctrine/ODM/MongoDB/Tests",
+            "Doctrine\\ODM\\MongoDB\\Tests\\": "tests/Tests",
             "Documentation\\": "tests/Documentation",
             "Documents\\": "tests/Documents",
+            "Documents84\\": "tests/Documents84",
             "Stubs\\": "tests/Stubs",
-            "TestDocuments\\" :"tests/Doctrine/ODM/MongoDB/Tests/Mapping/Driver/fixtures"
+            "TestDocuments\\" :"tests/Tests/Mapping/Driver/fixtures"
         }
     },
     "config": {

docs/en/reference/custom-mapping-types.rst

@@ -9,6 +9,9 @@ In order to create a new mapping type you need to subclass
 ``Doctrine\ODM\MongoDB\Types\Type`` and implement/override
 the methods.
 
+Date Example: Mapping DateTimeImmutable with Timezone
+-----------------------------------------------------
+
 The following example defines a custom type that stores ``DateTimeInterface``
 instances as an embedded document containing a BSON date and accompanying
 timezone string. Those same embedded documents are then be translated back into
@@ -32,6 +35,7 @@ a ``DateTimeImmutable`` when the data is read from the database.
         // This trait provides default closureToPHP used during data hydration
         use ClosureToPHP;
 
+        /** @param array{utc: UTCDateTime, tz: string} $value */
         public function convertToPHPValue($value): DateTimeImmutable
         {
             if (!isset($value['utc'], $value['tz'])) {
@@ -46,6 +50,7 @@ a ``DateTimeImmutable`` when the data is read from the database.
             return DateTimeImmutable::createFromMutable($dateTime);
         }
 
+        /** @return array{utc: UTCDateTime, tz: string} */
         public function convertToDatabaseValue($value): array
         {
             if (!$value instanceof DateTimeImmutable) {
@@ -115,5 +120,85 @@ specify a unique name for the mapping type and map that to the corresponding
 
         <field field-name="field" type="date_with_timezone" />
 
+Custom Type Example: Mapping a Money Value Object
+-------------------------------------------------
+
+You can create a custom mapping type for your own value objects or classes. For
+example, to map a ``Money`` value object using the `moneyphp/money library`_, you can
+implement a type that converts between this class and a BSON embedded document format.
+
+This approach works for any custom class by adapting the conversion logic to your needs.
+
+Example Implementation (using ``Money\Money``)::
+
+.. code-block:: php
+
+    <?php
+
+    namespace App\MongoDB\Types;
+
+    use Doctrine\ODM\MongoDB\Types\ClosureToPHP;
+    use Doctrine\ODM\MongoDB\Types\Type;
+    use InvalidArgumentException;
+    use Money\Money;
+    use Money\Currency;
+
+    final class MoneyType extends Type
+    {
+        // This trait provides a default closureToPHP used during data hydration
+        use ClosureToPHP;
+
+        public function convertToPHPValue(mixed $value): ?Money
+        {
+            if (null === $value) {
+                return null;
+            }
+
+            if (is_array($value) && isset($value['amount'], $value['currency'])) {
+                return new Money($value['amount'], new Currency($value['currency']));
+            }
+
+            throw new InvalidArgumentException(sprintf('Could not convert database value from "%s" to %s', get_debug_type($value), Money::class));
+        }
+
+        public function convertToDatabaseValue(mixed $value): ?array
+        {
+            if (null === $value) {
+                return null;
+            }
+
+            if ($value instanceof Money) {
+                return [
+                    'amount' => $value->getAmount(),
+                    'currency' => $value->getCurrency()->getCode(),
+                ];
+            }
+
+            throw new InvalidArgumentException(sprintf('Could not convert database value from "%s" to array', get_debug_type($value)));
+        }
+    }
+
+Register the type in your bootstrap code::
+
+.. code-block:: php
+
+    Type::addType(Money::class, App\MongoDB\Types\MoneyType::class);
+
+By using the |FQCN| of the value object class as the type name, the type is
+automatically used when encountering a property of that class. This means you
+can omit the ``type`` option when defining the field mapping::
+
+.. code-block:: php
+
+    #[Field]
+    public ?\Money\Money $price;
+
+.. note::
+
+    This implementation of ``MoneyType`` is kept simple for illustration purposes
+    and does not handle all edge cases, but it should give you a good starting
+    point for implementing your own custom types.
+
+.. _`moneyphp/money library`: https://github.com/moneyphp/money
 .. |FQCN| raw:: html
   <abbr title="Fully-Qualified Class Name">FQCN</abbr>

phpcs.xml.dist

@@ -12,7 +12,7 @@
     <config name="php_version" value="80100"/>
 
     <file>benchmark</file>
-    <file>lib</file>
+    <file>src</file>
     <file>tests</file>
     <file>tools</file>
 
@@ -50,46 +50,46 @@
     </rule>
 
     <rule ref="PSR1.Classes.ClassDeclaration.MissingNamespace">
-        <exclude-pattern>tests/Doctrine/ODM/MongoDB/Tests/Mapping/Documents/GlobalNamespaceDocument.php</exclude-pattern>
+        <exclude-pattern>tests/Tests/Mapping/Documents/GlobalNamespaceDocument.php</exclude-pattern>
     </rule>
 
     <rule ref="Squiz.Classes.ValidClassName.NotPascalCase">
-        <exclude-pattern>tests/Doctrine/ODM/MongoDB/Tests/Mapping/Documents/GlobalNamespaceDocument.php</exclude-pattern>
+        <exclude-pattern>tests/Tests/Mapping/Documents/GlobalNamespaceDocument.php</exclude-pattern>
     </rule>
 
     <rule ref="Squiz.NamingConventions.ValidVariableName.NotCamelCaps">
-        <exclude-pattern>tests/Doctrine/ODM/MongoDB/Tests/Functional/FunctionalTest.php</exclude-pattern>
+        <exclude-pattern>tests/Tests/Functional/FunctionalTest.php</exclude-pattern>
     </rule>
 
     <rule ref="Generic.NamingConventions.UpperCaseConstantName.ClassConstantNotUpperCase">
-        <exclude-pattern>lib/Doctrine/ODM/MongoDB/Events.php</exclude-pattern>
+        <exclude-pattern>src/Events.php</exclude-pattern>
     </rule>
 
     <rule ref="PSR1.Classes.ClassDeclaration.MultipleClasses">
-        <exclude-pattern>lib/Doctrine/ODM/MongoDB/Mapping/Driver/CompatibilityAnnotationDriver.php</exclude-pattern>
-        <exclude-pattern>lib/Doctrine/ODM/MongoDB/Tools/Console/Command/CommandCompatibility.php</exclude-pattern>
-        <exclude-pattern>lib/Doctrine/ODM/MongoDB/Tools/Console/Helper/DocumentManagerHelper.php</exclude-pattern>
-        <exclude-pattern>*/tests/*</exclude-pattern>
+        <exclude-pattern>src/Mapping/Driver/CompatibilityAnnotationDriver.php</exclude-pattern>
+        <exclude-pattern>src/Tools/Console/Command/CommandCompatibility.php</exclude-pattern>
+        <exclude-pattern>src/Tools/Console/Helper/DocumentManagerHelper.php</exclude-pattern>
+        <exclude-pattern>tests/*</exclude-pattern>
     </rule>
 
     <rule ref="Squiz.Classes.ClassFileName.NoMatch">
-        <exclude-pattern>lib/Doctrine/ODM/MongoDB/Tools/Console/Helper/DocumentManagerHelper.php</exclude-pattern>
-        <exclude-pattern>*/tests/*</exclude-pattern>
+        <exclude-pattern>src/Tools/Console/Helper/DocumentManagerHelper.php</exclude-pattern>
+        <exclude-pattern>tests/*</exclude-pattern>
     </rule>
 
     <!-- If forces to add "@inheritDoc" because the analysis is per file -->
     <rule ref="SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingAnyTypeHint">
-        <exclude-pattern>*/lib/*</exclude-pattern>
-        <exclude-pattern>tests/Doctrine/ODM/MongoDB/Tests/Functional/DocumentPersisterTest.php</exclude-pattern>
-        <exclude-pattern>tests/Doctrine/ODM/MongoDB/Tests/Functional/CustomTypeTest.php</exclude-pattern>
+        <exclude-pattern>src/*</exclude-pattern>
+        <exclude-pattern>tests/Tests/Functional/DocumentPersisterTest.php</exclude-pattern>
+        <exclude-pattern>tests/Tests/Functional/CustomTypeTest.php</exclude-pattern>
     </rule>
 
     <rule ref="SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingNativeTypeHint">
         <!-- We do want to test generating collections without return types -->
-        <exclude-pattern>*/tests/Doctrine/ODM/MongoDB/Tests/PersistentCollection/Coll*</exclude-pattern>
+        <exclude-pattern>tests/Tests/PersistentCollection/Coll*</exclude-pattern>
     </rule>
     <!-- It fails when using Nowdoc in method call -->
     <rule ref="SlevomatCodingStandard.Functions.RequireTrailingCommaInCall.MissingTrailingComma">
-        <exclude-pattern>lib/Doctrine/ODM/MongoDB/Tools/Console/Command/*</exclude-pattern>
+        <exclude-pattern>src/Tools/Console/Command/*</exclude-pattern>
     </rule>
 </ruleset>