PHPLIB-954: Add return types to all methods

Author: alcaeus

phpcs.xml.dist

@@ -133,14 +133,6 @@
     </rule>
 
 
-    <!-- *********************************************************** -->
-    <!-- Require native type hints for all code without a BC promise -->
-    <!-- *********************************************************** -->
-    <rule ref="SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingNativeTypeHint">
-        <exclude-pattern>src</exclude-pattern>
-    </rule>
-
-
     <!-- ************************************************************* -->
     <!-- Ignore errors for certain files where this is part of the API -->
     <!-- ************************************************************* -->

psalm-baseline.xml

@@ -320,13 +320,15 @@
     </InvalidParamDefault>
     <LessSpecificReturnStatement>
       <code><![CDATA[(object) $this->getArrayCopy()]]></code>
+      <code><![CDATA[(object) $this->getArrayCopy()]]></code>
     </LessSpecificReturnStatement>
     <MixedAssignment>
       <code><![CDATA[$this[$key]]]></code>
       <code><![CDATA[$value]]></code>
     </MixedAssignment>
     <MoreSpecificReturnType>
       <code><![CDATA[stdClass]]></code>
+      <code><![CDATA[stdClass]]></code>
     </MoreSpecificReturnType>
   </file>
   <file src="src/Model/BSONIterator.php">

src/BulkWriteResult.php

@@ -38,10 +38,9 @@ public function __construct(private WriteResult $writeResult, private array $ins
      * This method should only be called if the write was acknowledged.
      *
      * @see BulkWriteResult::isAcknowledged()
-     * @return integer|null
      * @throws BadMethodCallException if the write result is unacknowledged
      */
-    public function getDeletedCount()
+    public function getDeletedCount(): ?int
     {
         if ($this->isAcknowledged) {
             return $this->writeResult->getDeletedCount();
@@ -56,10 +55,9 @@ public function getDeletedCount()
      * This method should only be called if the write was acknowledged.
      *
      * @see BulkWriteResult::isAcknowledged()
-     * @return integer|null
      * @throws BadMethodCallException if the write result is unacknowledged
      */
-    public function getInsertedCount()
+    public function getInsertedCount(): ?int
     {
         if ($this->isAcknowledged) {
             return $this->writeResult->getInsertedCount();
@@ -76,10 +74,8 @@ public function getInsertedCount()
      * the driver did not generate an ID), the index will contain its "_id"
      * field value. Any driver-generated ID will be a MongoDB\BSON\ObjectId
      * instance.
-     *
-     * @return array
      */
-    public function getInsertedIds()
+    public function getInsertedIds(): array
     {
         return $this->insertedIds;
     }
@@ -90,10 +86,9 @@ public function getInsertedIds()
      * This method should only be called if the write was acknowledged.
      *
      * @see BulkWriteResult::isAcknowledged()
-     * @return integer|null
      * @throws BadMethodCallException if the write result is unacknowledged
      */
-    public function getMatchedCount()
+    public function getMatchedCount(): ?int
     {
         if ($this->isAcknowledged) {
             return $this->writeResult->getMatchedCount();
@@ -111,10 +106,9 @@ public function getMatchedCount()
      * This method should only be called if the write was acknowledged.
      *
      * @see BulkWriteResult::isAcknowledged()
-     * @return integer|null
      * @throws BadMethodCallException if the write result is unacknowledged
      */
-    public function getModifiedCount()
+    public function getModifiedCount(): ?int
     {
         if ($this->isAcknowledged) {
             return $this->writeResult->getModifiedCount();
@@ -129,10 +123,9 @@ public function getModifiedCount()
      * This method should only be called if the write was acknowledged.
      *
      * @see BulkWriteResult::isAcknowledged()
-     * @return integer|null
      * @throws BadMethodCallException if the write result is unacknowledged
      */
-    public function getUpsertedCount()
+    public function getUpsertedCount(): ?int
     {
         if ($this->isAcknowledged) {
             return $this->writeResult->getUpsertedCount();
@@ -152,10 +145,9 @@ public function getUpsertedCount()
      * This method should only be called if the write was acknowledged.
      *
      * @see BulkWriteResult::isAcknowledged()
-     * @return array
      * @throws BadMethodCallException if the write result is unacknowledged
      */
-    public function getUpsertedIds()
+    public function getUpsertedIds(): array
     {
         if ($this->isAcknowledged) {
             return $this->writeResult->getUpsertedIds();
@@ -169,10 +161,8 @@ public function getUpsertedIds()
      *
      * If the update was not acknowledged, other fields from the WriteResult
      * (e.g. matchedCount) will be undefined.
-     *
-     * @return boolean
      */
-    public function isAcknowledged()
+    public function isAcknowledged(): bool
     {
         return $this->isAcknowledged;
     }

src/ChangeStream.php

@@ -27,7 +27,6 @@
 use MongoDB\Exception\BadMethodCallException;
 use MongoDB\Exception\ResumeTokenException;
 use MongoDB\Model\ChangeStreamIterator;
-use ReturnTypeWillChange;
 
 use function assert;
 use function call_user_func;
@@ -108,20 +107,14 @@ public function getCursorId(): Int64
      * Null may be returned if no change documents have been iterated and the
      * server did not include a postBatchResumeToken in its aggregate or getMore
      * command response.
-     *
-     * @return array|object|null
      */
-    public function getResumeToken()
+    public function getResumeToken(): array|object|null
     {
         return $this->iterator->getResumeToken();
     }
 
-    /**
-     * @see https://php.net/iterator.key
-     * @return int|null
-     */
-    #[ReturnTypeWillChange]
-    public function key()
+    /** @see https://php.net/iterator.key */
+    public function key(): ?int
     {
         if ($this->valid()) {
             return $this->key;
@@ -132,11 +125,9 @@ public function key()
 
     /**
      * @see https://php.net/iterator.next
-     * @return void
      * @throws ResumeTokenException
      */
-    #[ReturnTypeWillChange]
-    public function next()
+    public function next(): void
     {
         try {
             $this->iterator->next();
@@ -148,11 +139,9 @@ public function next()
 
     /**
      * @see https://php.net/iterator.rewind
-     * @return void
      * @throws ResumeTokenException
      */
-    #[ReturnTypeWillChange]
-    public function rewind()
+    public function rewind(): void
     {
         try {
             $this->iterator->rewind();
@@ -165,12 +154,8 @@ public function rewind()
         }
     }
 
-    /**
-     * @see https://php.net/iterator.valid
-     * @return boolean
-     */
-    #[ReturnTypeWillChange]
-    public function valid()
+    /** @see https://php.net/iterator.valid */
+    public function valid(): bool
     {
         return $this->iterator->valid();
     }

src/Client.php

@@ -143,9 +143,8 @@ public function __construct(?string $uri = null, array $uriOptions = [], array $
      * Return internal properties for debugging purposes.
      *
      * @see https://php.net/manual/en/language.oop5.magic.php#language.oop5.magic.debuginfo
-     * @return array
      */
-    public function __debugInfo()
+    public function __debugInfo(): array
     {
         return [
             'manager' => $this->manager,
@@ -166,19 +165,16 @@ public function __debugInfo()
      * @see https://php.net/oop5.overloading#object.get
      * @see https://php.net/types.string#language.types.string.parsing.complex
      * @param string $databaseName Name of the database to select
-     * @return Database
      */
-    public function __get(string $databaseName)
+    public function __get(string $databaseName): Database
     {
         return $this->selectDatabase($databaseName);
     }
 
     /**
      * Return the connection string (i.e. URI).
-     *
-     * @return string
      */
-    public function __toString()
+    public function __toString(): string
     {
         return $this->uri;
     }
@@ -197,10 +193,8 @@ final public function addSubscriber(Subscriber $subscriber): void
      * Returns a ClientEncryption instance for explicit encryption and decryption
      *
      * @param array $options Encryption options
-     *
-     * @return ClientEncryption
      */
-    public function createClientEncryption(array $options)
+    public function createClientEncryption(array $options): ClientEncryption
     {
         if (isset($options['keyVaultClient'])) {
             if ($options['keyVaultClient'] instanceof self) {
@@ -224,7 +218,7 @@ public function createClientEncryption(array $options)
      * @throws InvalidArgumentException for parameter/option parsing errors
      * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
      */
-    public function dropDatabase(string $databaseName, array $options = [])
+    public function dropDatabase(string $databaseName, array $options = []): array|object
     {
         if (! isset($options['typeMap'])) {
             $options['typeMap'] = $this->typeMap;
@@ -243,10 +237,8 @@ public function dropDatabase(string $databaseName, array $options = [])
 
     /**
      * Return the Manager.
-     *
-     * @return Manager
      */
-    public function getManager()
+    public function getManager(): Manager
     {
         return $this->manager;
     }
@@ -255,29 +247,24 @@ public function getManager()
      * Return the read concern for this client.
      *
      * @see https://php.net/manual/en/mongodb-driver-readconcern.isdefault.php
-     * @return ReadConcern
      */
-    public function getReadConcern()
+    public function getReadConcern(): ReadConcern
     {
         return $this->readConcern;
     }
 
     /**
      * Return the read preference for this client.
-     *
-     * @return ReadPreference
      */
-    public function getReadPreference()
+    public function getReadPreference(): ReadPreference
     {
         return $this->readPreference;
     }
 
     /**
      * Return the type map for this client.
-     *
-     * @return array
      */
-    public function getTypeMap()
+    public function getTypeMap(): array
     {
         return $this->typeMap;
     }
@@ -286,9 +273,8 @@ public function getTypeMap()
      * Return the write concern for this client.
      *
      * @see https://php.net/manual/en/mongodb-driver-writeconcern.isdefault.php
-     * @return WriteConcern
      */
-    public function getWriteConcern()
+    public function getWriteConcern(): WriteConcern
     {
         return $this->writeConcern;
     }
@@ -313,12 +299,11 @@ public function listDatabaseNames(array $options = []): Iterator
      * List databases.
      *
      * @see ListDatabases::__construct() for supported options
-     * @return DatabaseInfoIterator
      * @throws UnexpectedValueException if the command response was malformed
      * @throws InvalidArgumentException for parameter/option parsing errors
      * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
      */
-    public function listDatabases(array $options = [])
+    public function listDatabases(array $options = []): DatabaseInfoIterator
     {
         $operation = new ListDatabases($options);
         $server = select_server($this->manager, $options);
@@ -343,10 +328,9 @@ final public function removeSubscriber(Subscriber $subscriber): void
      * @param string $databaseName   Name of the database containing the collection
      * @param string $collectionName Name of the collection to select
      * @param array  $options        Collection constructor options
-     * @return Collection
      * @throws InvalidArgumentException for parameter/option parsing errors
      */
-    public function selectCollection(string $databaseName, string $collectionName, array $options = [])
+    public function selectCollection(string $databaseName, string $collectionName, array $options = []): Collection
     {
         $options += ['typeMap' => $this->typeMap, 'builderEncoder' => $this->builderEncoder];
 
@@ -359,10 +343,9 @@ public function selectCollection(string $databaseName, string $collectionName, a
      * @see Database::__construct() for supported options
      * @param string $databaseName Name of the database to select
      * @param array  $options      Database constructor options
-     * @return Database
      * @throws InvalidArgumentException for parameter/option parsing errors
      */
-    public function selectDatabase(string $databaseName, array $options = [])
+    public function selectDatabase(string $databaseName, array $options = []): Database
     {
         $options += ['typeMap' => $this->typeMap, 'builderEncoder' => $this->builderEncoder];
 
@@ -374,9 +357,8 @@ public function selectDatabase(string $databaseName, array $options = [])
      *
      * @see https://php.net/manual/en/mongodb-driver-manager.startsession.php
      * @param array $options Session options
-     * @return Session
      */
-    public function startSession(array $options = [])
+    public function startSession(array $options = []): Session
     {
         return $this->manager->startSession($options);
     }
@@ -387,10 +369,9 @@ public function startSession(array $options = [])
      * @see Watch::__construct() for supported options
      * @param array $pipeline Aggregation pipeline
      * @param array $options  Command options
-     * @return ChangeStream
      * @throws InvalidArgumentException for parameter/option parsing errors
      */
-    public function watch(array $pipeline = [], array $options = [])
+    public function watch(array $pipeline = [], array $options = []): ChangeStream
     {
         if (is_builder_pipeline($pipeline)) {
             $pipeline = new Pipeline(...$pipeline);

src/Codec/DecodeIfSupported.php

@@ -30,17 +30,13 @@ abstract public function canDecode(mixed $value): bool;
 
     /**
      * @psalm-param BSONType $value
-     * @return mixed
      * @psalm-return NativeType
      * @throws UnsupportedValueException if the decoder does not support the value
      */
-    abstract public function decode(mixed $value);
+    abstract public function decode(mixed $value): mixed;
 
-    /**
-     * @return mixed
-     * @psalm-return ($value is BSONType ? NativeType : $value)
-     */
-    public function decodeIfSupported(mixed $value)
+    /** @psalm-return ($value is BSONType ? NativeType : $value) */
+    public function decodeIfSupported(mixed $value): mixed
     {
         return $this->canDecode($value) ? $this->decode($value) : $value;
     }