[3.x] Make Types strongly typed

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

@@ -867,8 +867,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;
     }
@@ -1034,7 +1033,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

@@ -220,7 +220,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;
     }

src/Types/DateImmutableType.php

@@ -6,15 +6,13 @@
 
 use DateTime;
 use DateTimeImmutable;
-use DateTimeInterface;
 use RuntimeException;
 
 use function sprintf;
 
 class DateImmutableType extends DateType
 {
-    /** @return DateTimeImmutable */
-    public static function getDateTime($value): DateTimeInterface
+    public static function getDateTime(mixed $value): DateTimeImmutable
     {
         $datetime = parent::getDateTime($value);
 
@@ -33,12 +31,7 @@ public static function getDateTime($value): DateTimeInterface
         ));
     }
 
-    /**
-     * @param mixed $current
-     *
-     * @return DateTimeInterface
-     */
-    public function getNextVersion($current)
+    public function getNextVersion(mixed $current): DateTimeImmutable
     {
         return new DateTimeImmutable();
     }

src/Types/DateType.php

@@ -36,7 +36,7 @@ class DateType extends Type implements Versionable
      *
      * @throws InvalidArgumentException If $value is invalid.
      */
-    public static function getDateTime($value): DateTimeInterface
+    public static function getDateTime(mixed $value): DateTimeInterface
     {
         $datetime  = false;
         $exception = null;
@@ -70,8 +70,7 @@ public static function getDateTime($value): DateTimeInterface
         return $datetime;
     }
 
-    /** @return DateTime|false */
-    private static function craftDateTime(int $seconds, int $microseconds = 0)
+    private static function craftDateTime(int $seconds, int $microseconds = 0): DateTime|false
     {
         $datetime = new DateTime();
         $datetime->setTimestamp($seconds);
@@ -82,8 +81,7 @@ private static function craftDateTime(int $seconds, int $microseconds = 0)
         return $datetime;
     }
 
-    /** @return UTCDateTime|null */
-    public function convertToDatabaseValue($value)
+    public function convertToDatabaseValue(mixed $value): ?UTCDateTime
     {
         if ($value === null || $value instanceof UTCDateTime) {
             return $value;
@@ -94,8 +92,7 @@ public function convertToDatabaseValue($value)
         return new UTCDateTime($datetime);
     }
 
-    /** @return DateTimeInterface|null */
-    public function convertToPHPValue($value)
+    public function convertToPHPValue(mixed $value): ?DateTimeInterface
     {
         if ($value === null) {
             return null;
@@ -114,12 +111,7 @@ public function closureToPHP(): string
         return 'if ($value === null) { $return = null; } else { $return = \\' . static::class . '::getDateTime($value); }';
     }
 
-    /**
-     * @param mixed $current
-     *
-     * @return DateTimeInterface
-     */
-    public function getNextVersion($current)
+    public function getNextVersion(mixed $current): DateTimeInterface
     {
         return new DateTime();
     }

src/Types/Decimal128Type.php

@@ -13,8 +13,7 @@ class Decimal128Type extends Type implements Incrementable, Versionable
 {
     use ClosureToPHP;
 
-    /** @return Decimal128|null */
-    public function convertToDatabaseValue($value)
+    public function convertToDatabaseValue(mixed $value): ?Decimal128
     {
         if ($value === null) {
             return null;
@@ -27,24 +26,17 @@ public function convertToDatabaseValue($value)
         return $value;
     }
 
-    /** @return string|null */
-    public function convertToPHPValue($value)
+    public function convertToPHPValue(mixed $value): ?string
     {
         return $value !== null ? (string) $value : null;
     }
 
-    /** @return string */
-    public function diff($old, $new)
+    public function diff(mixed $old, mixed $new): string
     {
         return bcsub($new, $old);
     }
 
-    /**
-     * @param mixed $current
-     *
-     * @return string
-     */
-    public function getNextVersion($current)
+    public function getNextVersion(mixed $current): string
     {
         if ($current === null) {
             return '1';

src/Types/FloatType.php

@@ -9,14 +9,12 @@
  */
 class FloatType extends Type implements Incrementable
 {
-    /** @return float|null */
-    public function convertToDatabaseValue($value)
+    public function convertToDatabaseValue(mixed $value): ?float
     {
         return $value !== null ? (float) $value : null;
     }
 
-    /** @return float|null */
-    public function convertToPHPValue($value)
+    public function convertToPHPValue(mixed $value): ?float
     {
         return $value !== null ? (float) $value : null;
     }
@@ -31,8 +29,7 @@ public function closureToPHP(): string
         return '$return = (float) $value;';
     }
 
-    /** @return float|null */
-    public function diff($old, $new)
+    public function diff(mixed $old, mixed $new): ?float
     {
         return (float) ($new - $old);
     }

src/Types/HashType.php

@@ -13,8 +13,7 @@
  */
 class HashType extends Type
 {
-    /** @return object|null */
-    public function convertToDatabaseValue($value)
+    public function convertToDatabaseValue(mixed $value): ?object
     {
         if ($value !== null && ! is_array($value)) {
             throw MongoDBException::invalidValueForType('Hash', ['array', 'null'], $value);
@@ -24,7 +23,7 @@ public function convertToDatabaseValue($value)
     }
 
     /** @return array<string, mixed>|null */
-    public function convertToPHPValue($value)
+    public function convertToPHPValue(mixed $value): ?array
     {
         return $value !== null ? (array) $value : null;
     }