[3.x] Make Types strongly typed (#2945)

Author: IonBazan

UPGRADE-3.0.md

@@ -23,6 +23,11 @@ generator to generate string UUIDs. For more efficient storage of UUIDs, use the
 `Doctrine\ODM\MongoDB\Types\BinaryUuidType` type in combination with the
 `Doctrine\ODM\MongoDB\Id\SymfonyUuidGenerator` generator.
 
+## Strong typing
+
+Native type hints have been introduced throughout the codebase. As a result, several
+methods signatures have changed, including but not limited to `Types` and `Mapping` namespaces.
+
 ## Metadata
 The `Doctrine\ODM\MongoDB\Mapping\ClassMetadata` class has been marked final and
 will no longer be extendable.
@@ -31,6 +36,8 @@ 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.
 
+The `Int64Type` no longer extends `IntType`.
+
 The `NOTIFY` change tracking policy has been removed, we suggest switching to
 `DEFERRED_EXPLICIT` instead. Consequentially `ClassMetadata::isChangeTrackingNotify` 
 and `ClassMetadata::CHANGETRACKING_NOTIFY` have been removed as well. `UnitOfWork`

benchmark/BaseBench.php

@@ -18,8 +18,8 @@
 
 abstract class BaseBench
 {
-    public const DATABASE_NAME           = 'doctrine_odm_performance';
-    private const DEFAULT_MONGODB_SERVER = 'mongodb://localhost:27017';
+    public const string DATABASE_NAME           = 'doctrine_odm_performance';
+    private const string DEFAULT_MONGODB_SERVER = 'mongodb://localhost:27017';
 
     protected static DocumentManager $documentManager;
 

src/Aggregation/Builder.php

@@ -33,23 +33,18 @@
  */
 class Builder
 {
-    /**
-     * The DocumentManager instance for this query
-     */
-    private DocumentManager $dm;
-
     /**
      * The ClassMetadata instance.
      */
-    private ClassMetadata $class;
+    private readonly ClassMetadata $class;
 
     /** @var class-string */
     private ?string $hydrationClass = null;
 
     /**
      * The Collection instance.
      */
-    private Collection $collection;
+    private readonly Collection $collection;
 
     /** @var Stage[] */
     private array $stages = [];
@@ -61,9 +56,8 @@ class Builder
      *
      * @param class-string $documentName
      */
-    public function __construct(DocumentManager $dm, string $documentName)
+    public function __construct(private readonly DocumentManager $dm, string $documentName)
     {
-        $this->dm         = $dm;
         $this->class      = $this->dm->getClassMetadata($documentName);
         $this->collection = $this->dm->getDocumentCollection($documentName);
     }
@@ -212,9 +206,8 @@ public function fill(): Stage\Fill
      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/geoNear/
      *
      * @param float|array<string, mixed>|Point $x
-     * @param float                            $y
      */
-    public function geoNear($x, $y = null): Stage\GeoNear
+    public function geoNear(float|array|Point $x, ?float $y = null): Stage\GeoNear
     {
         $stage = new Stage\GeoNear($this, $x, $y);
 
@@ -491,7 +484,7 @@ public function redact(): Stage\Redact
      * @param string|mixed[]|Expr|null $expression Optional. A replacement expression that
      * resolves to a document.
      */
-    public function replaceRoot($expression = null): Stage\ReplaceRoot
+    public function replaceRoot(string|array|Expr|null $expression = null): Stage\ReplaceRoot
     {
         $stage = new Stage\ReplaceRoot($this, $this->dm, $this->class, $expression);
 
@@ -511,7 +504,7 @@ public function replaceRoot($expression = null): Stage\ReplaceRoot
      * @param string|mixed[]|Expr|null $expression Optional. A replacement expression that
      * resolves to a document.
      */
-    public function replaceWith($expression = null): Stage\ReplaceWith
+    public function replaceWith(string|array|Expr|null $expression = null): Stage\ReplaceWith
     {
         $stage = new Stage\ReplaceWith($this, $this->dm, $this->class, $expression);
 
@@ -608,7 +601,7 @@ public function skip(int $skip): Stage\Skip
      * @param int|string|null                                        $order     Field order (if one field is specified)
      * @phpstan-param SortShape|string $fieldName Field name or array of field/order pairs
      */
-    public function sort($fieldName, $order = null): Stage\Sort
+    public function sort(array|string $fieldName, int|string|null $order = null): Stage\Sort
     {
         $fields = is_array($fieldName) ? $fieldName : [$fieldName => $order];
         // fixme: move to sort stage

src/Mapping/ClassMetadata.php

@@ -869,8 +869,7 @@ public function getReflectionClass(): ReflectionClass
         return $this->reflClass;
     }
 
-    /** @param string $fieldName */
-    public function isIdentifier($fieldName): bool
+    public function isIdentifier(string $fieldName): bool
     {
         return $this->identifier === $fieldName;
     }
@@ -1036,7 +1035,7 @@ public function setLifecycleCallbacks(array $callbacks): void
      *
      * @param array<string, mixed>|string $fields Database field name(s)
      */
-    public function registerAlsoLoadMethod(string $method, $fields): void
+    public function registerAlsoLoadMethod(string $method, array|string $fields): void
     {
         $this->alsoLoadMethods[$method] = is_array($fields) ? $fields : [$fields];
     }

src/Mapping/ClassMetadataFactory.php

@@ -221,7 +221,7 @@ protected function validateIdentifier(ClassMetadata $class): void
         }
     }
 
-    protected function newClassMetadataInstance($className): ClassMetadata
+    protected function newClassMetadataInstance(string $className): ClassMetadata
     {
         return new ClassMetadata($className);
     }

src/PersistentCollection/DefaultPersistentCollectionGenerator.php

@@ -110,7 +110,7 @@ public function loadClass(string $collectionClass, int $autoGenerate): string
     }
 
     /** @param string|false $fileName Filename to write collection class code or false to eval it. */
-    private function generateCollectionClass(string $for, string $targetFqcn, $fileName): void
+    private function generateCollectionClass(string $for, string $targetFqcn, string|false $fileName): void
     {
         $exploded  = explode('\\', $targetFqcn);
         $class     = array_pop($exploded);

src/Types/BinDataType.php

@@ -20,8 +20,7 @@ class BinDataType extends Type
      */
     protected int $binDataType = Binary::TYPE_GENERIC;
 
-    /** @return Binary|null */
-    public function convertToDatabaseValue($value)
+    public function convertToDatabaseValue(mixed $value): ?Binary
     {
         if ($value === null) {
             return null;
@@ -38,8 +37,7 @@ public function convertToDatabaseValue($value)
         return $value;
     }
 
-    /** @return mixed|string|null */
-    public function convertToPHPValue($value)
+    public function convertToPHPValue(mixed $value): mixed
     {
         return $value !== null ? ($value instanceof Binary ? $value->getData() : $value) : null;
     }

src/Types/BooleanType.php

@@ -9,14 +9,12 @@
  */
 class BooleanType extends Type
 {
-    /** @return bool|null */
-    public function convertToDatabaseValue($value)
+    public function convertToDatabaseValue(mixed $value): ?bool
     {
         return $value !== null ? (bool) $value : null;
     }
 
-    /** @return bool|null */
-    public function convertToPHPValue($value)
+    public function convertToPHPValue(mixed $value): ?bool
     {
         return $value !== null ? (bool) $value : null;
     }

src/Types/CollectionType.php

@@ -15,7 +15,7 @@
 class CollectionType extends Type
 {
     /** @return list<mixed>|null */
-    public function convertToDatabaseValue($value)
+    public function convertToDatabaseValue(mixed $value): ?array
     {
         if ($value !== null && ! is_array($value)) {
             throw MongoDBException::invalidValueForType('Collection', ['array', 'null'], $value);
@@ -25,7 +25,7 @@ public function convertToDatabaseValue($value)
     }
 
     /** @return list<mixed>|null */
-    public function convertToPHPValue($value)
+    public function convertToPHPValue(mixed $value): ?array
     {
         return $value !== null ? array_values($value) : null;
     }

src/Types/CustomIdType.php

@@ -9,12 +9,12 @@
  */
 class CustomIdType extends Type
 {
-    public function convertToDatabaseValue($value)
+    public function convertToDatabaseValue(mixed $value): mixed
     {
         return $value;
     }
 
-    public function convertToPHPValue($value)
+    public function convertToPHPValue(mixed $value): mixed
     {
         return $value;
     }