Deprecate overriding the __sleep method of ClassMetadata or PersistentCollection (#2965)

* Deprecate overring the __sleep method of ClassMetadata or PersistentCollection

* Test extending the ClassMetadata class

* Discard phpstan issues with soft-final

Author: GromNaN

phpstan-baseline.neon

@@ -415,8 +415,20 @@ parameters:
 			path: src/Mapping/ClassMetadata.php
 
 		-
-			message: '#^Property Doctrine\\ODM\\MongoDB\\Mapping\\ClassMetadata\:\:\$rootClass \(class\-string\|null\) is never assigned null so it can be removed from the property type\.$#'
-			identifier: property.unusedType
+			message: '#^Result of && is always false\.$#'
+			identifier: booleanAnd.alwaysFalse
+			count: 1
+			path: src/Mapping/ClassMetadata.php
+
+		-
+			message: '#^Strict comparison using \!\=\= between ''Doctrine\\\\ODM\\\\MongoDB\\\\Mapping\\\\ClassMetadata'' and ''Doctrine\\\\ODM\\\\MongoDB\\\\Mapping\\\\ClassMetadata'' will always evaluate to false\.$#'
+			identifier: notIdentical.alwaysFalse
+			count: 1
+			path: src/Mapping/ClassMetadata.php
+
+		-
+			message: '#^Strict comparison using \!\=\= between mixed and \*NEVER\* will always evaluate to true\.$#'
+			identifier: notIdentical.alwaysTrue
 			count: 1
 			path: src/Mapping/ClassMetadata.php
 
@@ -1068,6 +1080,12 @@ parameters:
 			count: 1
 			path: tests/Tests/Functional/TargetDocumentTest.php
 
+		-
+			message: '#^Class Doctrine\\ODM\\MongoDB\\Tests\\Mapping\\ExtendedClassMetadata extends @final class Doctrine\\ODM\\MongoDB\\Mapping\\ClassMetadata\.$#'
+			identifier: class.extendsFinalByPhpDoc
+			count: 1
+			path: tests/Tests/Mapping/ClassMetadataTest.php
+
 		-
 			message: '#^Method Doctrine\\ODM\\MongoDB\\Tests\\Mapping\\ClassMetadataTest\:\:testEmptyVectorSearchIndexDefinition\(\) has parameter \$definition with no value type specified in iterable type array\.$#'
 			identifier: missingType.iterableValue

src/Mapping/ClassMetadata.php

@@ -34,6 +34,7 @@
 use ProxyManager\Proxy\GhostObjectInterface;
 use ReflectionClass;
 use ReflectionEnum;
+use ReflectionMethod;
 use ReflectionNamedType;
 use ReflectionProperty;
 use Symfony\Component\Uid\UuidV1;
@@ -923,7 +924,7 @@ public static function getReferenceFieldName(string $storeAs, string $pathPrefix
             return $pathPrefix;
         }
 
-        return ($pathPrefix ? $pathPrefix . '.' : '') . static::getReferencePrefix($storeAs) . 'id';
+        return ($pathPrefix ? $pathPrefix . '.' : '') . self::getReferencePrefix($storeAs) . 'id';
     }
 
     public function getReflectionClass(): ReflectionClass
@@ -2645,7 +2646,31 @@ public function mapField(array $mapping): array
      *      - reflFields (ReflectionProperty array)
      *      - propertyAccessors (ReflectionProperty array)
      *
-     * @return array The names of all the fields that should be serialized.
+     * @return array<string, mixed> The serialized data.
+     */
+    public function __serialize(): array
+    {
+        if (static::class !== self::class && (new ReflectionMethod($this, '__sleep'))->getDeclaringClass() !== self::class) {
+            trigger_deprecation(
+                'doctrine/mongodb-odm',
+                '2.16',
+                'The method __sleep() is deprecated. Implement and use %s() instead.',
+                __METHOD__,
+            );
+        }
+
+        $data = [];
+        foreach ($this->__sleep() as $field) {
+            $data[$field] = $this->$field;
+        }
+
+        return $data;
+    }
+
+    /**
+     * @deprecated
+     *
+     * @return list<string> The names of all the fields that should be serialized.
      */
     public function __sleep()
     {
@@ -2665,8 +2690,10 @@ public function __sleep()
             'generatorOptions',
             'idGenerator',
             'indexes',
+            'searchIndexes',
             'shardKey',
             'timeSeriesOptions',
+            'isEncrypted',
         ];
 
         // The rest of the metadata is only serialized if necessary.
@@ -2700,7 +2727,7 @@ public function __sleep()
             $serialized[] = 'isQueryResultDocument';
         }
 
-        if ($this->isView()) {
+        if ($this->isView) {
             $serialized[] = 'isView';
             $serialized[] = 'rootClass';
         }
@@ -2745,8 +2772,20 @@ public function __sleep()
     }
 
     /**
-     * Restores some state that cannot be serialized/unserialized.
+     * Restores the serialized values and some state that cannot be serialized/unserialized.
+     *
+     * @param array<string, mixed> $data The serialized data.
      */
+    public function __unserialize(array $data): void
+    {
+        foreach ($data as $field => $value) {
+            $this->$field = $value;
+        }
+
+        $this->__wakeup();
+    }
+
+    /** @deprecated */
     public function __wakeup(): void
     {
         // Restore ReflectionClass and properties

src/PersistentCollection/PersistentCollectionTrait.php

@@ -509,6 +509,23 @@ public function slice($offset, $length = null)
      * Called by PHP when this collection is serialized. Ensures that the
      * internal state of the collection can be reproduced after serialization
      *
+     * @return array<string, mixed>
+     */
+    public function __serialize(): array
+    {
+        return [
+            'coll' => $this->coll,
+            'initialized' => $this->initialized,
+            'mongoData' => $this->mongoData,
+            'snapshot' => $this->snapshot,
+            'isDirty' => $this->isDirty,
+            'hints' => $this->hints,
+        ];
+    }
+
+    /**
+     * @deprecated Implement and use __serialize() instead.
+     *
      * @return string[]
      */
     public function __sleep()

tests/Tests/CaptureDeprecationMessages.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ODM\MongoDB\Tests;
+
+use function call_user_func;
+use function restore_error_handler;
+use function set_error_handler;
+
+use const E_USER_DEPRECATED;
+
+trait CaptureDeprecationMessages
+{
+    /**
+     * This method can be replaced with expectUserDeprecationMessage() in PHPUnit 11+.
+     * https://docs.phpunit.de/en/11.1/error-handling.html#expecting-deprecations-e-user-deprecated
+     *
+     * @param list<string> $errors
+     *
+     * @param-out list<string> $errors
+     */
+    private function captureDeprecationMessages(callable $callable, ?array &$errors): mixed
+    {
+        $errors = [];
+
+        set_error_handler(static function (int $errno, string $errstr) use (&$errors): bool {
+            $errors[] = $errstr;
+
+            return false;
+        }, E_USER_DEPRECATED);
+
+        try {
+            return call_user_func($callable);
+        } finally {
+            restore_error_handler();
+        }
+    }
+}

tests/Tests/Mapping/ClassMetadataTest.php

@@ -14,6 +14,7 @@
 use Doctrine\ODM\MongoDB\Mapping\TimeSeries\Granularity;
 use Doctrine\ODM\MongoDB\Repository\DocumentRepository;
 use Doctrine\ODM\MongoDB\Tests\BaseTestCase;
+use Doctrine\ODM\MongoDB\Tests\CaptureDeprecationMessages;
 use Doctrine\ODM\MongoDB\Tests\ClassMetadataTestUtil;
 use Doctrine\ODM\MongoDB\Types\Type;
 use Doctrine\ODM\MongoDB\Utility\CollectionHelper;
@@ -51,6 +52,8 @@
 
 class ClassMetadataTest extends BaseTestCase
 {
+    use CaptureDeprecationMessages;
+
     public function testClassMetadataInstanceSerialization(): void
     {
         $cm = new ClassMetadata(CmsUser::class);
@@ -84,6 +87,8 @@ public function testClassMetadataInstanceSerialization(): void
         $cm->setValidator(Document::fromJSON($validatorJson)->toPHP());
         $cm->setValidationAction(ClassMetadata::SCHEMA_VALIDATION_ACTION_WARN);
         $cm->setValidationLevel(ClassMetadata::SCHEMA_VALIDATION_LEVEL_OFF);
+        $cm->isEncrypted = true;
+        $cm->addSearchIndex(['mappings' => ['fields' => ['title' => ['type' => 'string']]]], 'custom_name');
         self::assertIsArray($cm->getFieldMapping('phonenumbers'));
         self::assertCount(1, $cm->fieldMappings);
         self::assertCount(1, $cm->associationMappings);
@@ -117,6 +122,25 @@ public function testClassMetadataInstanceSerialization(): void
         self::assertEquals(Document::fromJSON($validatorJson)->toPHP(), $cm->getValidator());
         self::assertEquals(ClassMetadata::SCHEMA_VALIDATION_ACTION_WARN, $cm->getValidationAction());
         self::assertEquals(ClassMetadata::SCHEMA_VALIDATION_LEVEL_OFF, $cm->getValidationLevel());
+        self::assertTrue($cm->isEncrypted);
+        self::assertSame([['definition' => ['mappings' => ['fields' => ['title' => ['type' => 'string']]]], 'name' => 'custom_name', 'type' => 'search']], $cm->getSearchIndexes());
+    }
+
+    public function testExtendingClassMetadata(): void
+    {
+        $cm = new ExtendedClassMetadata(CmsUser::class);
+        $cm->setCollection('custom_collection');
+        $cm->customProperty = 'some_value';
+
+        $serialized = $this->captureDeprecationMessages(static fn () => serialize($cm), $deprecations);
+        $cm         = unserialize($serialized);
+
+        self::assertInstanceOf(ExtendedClassMetadata::class, $cm);
+        self::assertSame(CmsUser::class, $cm->name);
+        self::assertSame('custom_collection', $cm->getCollection());
+        self::assertSame('some_value', $cm->customProperty);
+
+        self::assertSame(['Since doctrine/mongodb-odm 2.16: The method __sleep() is deprecated. Implement and use Doctrine\ODM\MongoDB\Mapping\ClassMetadata::__serialize() instead.'], $deprecations);
     }
 
     public function testOwningSideAndInverseSide(): void
@@ -1136,3 +1160,14 @@ class TimeSeriesTestDocument
     #[ODM\Field]
     public string $metadata;
 }
+
+class ExtendedClassMetadata extends ClassMetadata
+{
+    public string $customProperty;
+
+    /** @return list<string> */
+    public function __sleep(): array
+    {
+        return array_merge(parent::__sleep(), ['customProperty']);
+    }
+}