Update to psalm 5

Author: alcaeus

composer.json

@@ -24,7 +24,7 @@
         "rector/rector": "^0.16.0",
         "squizlabs/php_codesniffer": "^3.7",
         "symfony/phpunit-bridge": "^5.2",
-        "vimeo/psalm": "^4.28"
+        "vimeo/psalm": "^5.13"
     },
     "autoload": {
         "psr-4": { "MongoDB\\": "src/" },

examples/changestream.php

@@ -53,7 +53,7 @@ function toJSON(object $document): string
     $changeStream->next();
 
     if (time() - $startTime > 3) {
-        printf("Aborting after 3 seconds...\n");
+        echo "Aborting after 3 seconds...\n";
         break;
     }
 }

examples/command_logger.php

@@ -31,14 +31,14 @@ public function commandStarted(CommandStartedEvent $event): void
         printf("%s command started\n", $event->getCommandName());
 
         printf("command: %s\n", toJson($event->getCommand()));
-        printf("\n");
+        echo "\n";
     }
 
     public function commandSucceeded(CommandSucceededEvent $event): void
     {
         printf("%s command succeeded\n", $event->getCommandName());
         printf("reply: %s\n", toJson($event->getReply()));
-        printf("\n");
+        echo "\n";
     }
 
     public function commandFailed(CommandFailedEvent $event): void
@@ -50,7 +50,7 @@ public function commandFailed(CommandFailedEvent $event): void
         printf("exception: %s\n", get_class($exception));
         printf("exception.code: %d\n", $exception->getCode());
         printf("exception.message: %s\n", $exception->getMessage());
-        printf("\n");
+        echo "\n";
     }
 }
 

psalm-baseline.xml

@@ -3,6 +3,8 @@
     errorLevel="1"
     errorBaseline="psalm-baseline.xml"
     resolveFromConfigFile="true"
+    findUnusedBaselineEntry="false"
+    findUnusedCode="false"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns="https://getpsalm.org/schema/config"
     xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"

psalm.xml.dist

@@ -37,6 +37,7 @@
  * @see https://mongodb.com/docs/manual/reference/method/db.watch/#mongodb-method-db.watch
  *
  * @psalm-type ResumeCallable = callable(array|object|null, bool): ChangeStreamIterator
+ * @template-implements Iterator<int, array|object>
  */
 class ChangeStream implements Iterator
 {
@@ -94,7 +95,7 @@ public function __construct(ChangeStreamIterator $iterator, callable $resumeCall
 
     /**
      * @see https://php.net/iterator.current
-     * @return mixed
+     * @return array|object|null
      */
     #[ReturnTypeWillChange]
     public function current()
@@ -124,7 +125,7 @@ public function getResumeToken()
 
     /**
      * @see https://php.net/iterator.key
-     * @return mixed
+     * @return int|null
      */
     #[ReturnTypeWillChange]
     public function key()

src/ChangeStream.php

@@ -20,9 +20,12 @@
 use MongoDB\Exception\InvalidArgumentException;
 use MongoDB\Exception\UnsupportedValueException;
 
+/** @template-implements Codec<mixed, mixed> */
 class CodecLibrary implements Codec
 {
+    /** @template-use DecodeIfSupported<mixed, mixed> */
     use DecodeIfSupported;
+    /** @template-use EncodeIfSupported<mixed, mixed> */
     use EncodeIfSupported;
 
     /** @var list<Decoder> */

src/Codec/CodecLibrary.php

@@ -18,6 +18,7 @@
 namespace MongoDB\Command;
 
 use MongoDB\Driver\Command;
+use MongoDB\Driver\Cursor;
 use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException;
 use MongoDB\Driver\Server;
 use MongoDB\Driver\Session;
@@ -99,11 +100,13 @@ public function __construct(string $databaseName, array $options = [])
     /**
      * Execute the operation.
      *
+     * @return CachingIterator<int, array>
      * @see Executable::execute()
      * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
      */
     public function execute(Server $server): CachingIterator
     {
+        /** @var Cursor<array> $cursor */
         $cursor = $server->executeReadCommand($this->databaseName, $this->createCommand(), $this->createOptions());
         $cursor->setTypeMap(['root' => 'array', 'document' => 'array']);
 

src/Command/ListCollections.php

@@ -33,10 +33,15 @@
  *
  * @see \MongoDB\Collection::mapReduce()
  * @see https://mongodb.com/docs/manual/reference/command/mapReduce/
+ * @template-implements IteratorAggregate<int, array|object>
+ * @psalm-type MapReduceCallable = callable(): Traversable<int, array|object>
  */
 class MapReduceResult implements IteratorAggregate
 {
-    /** @var callable */
+    /**
+     * @var callable
+     * @psalm-var MapReduceCallable
+     */
     private $getIterator;
 
     private int $executionTimeMS;
@@ -49,6 +54,7 @@ class MapReduceResult implements IteratorAggregate
      * @internal
      * @param callable $getIterator Callback that returns a Traversable for mapReduce results
      * @param stdClass $result      Result document from the mapReduce command
+     * @psalm-param MapReduceCallable $getIterator
      */
     public function __construct(callable $getIterator, stdClass $result)
     {
@@ -82,7 +88,7 @@ public function getExecutionTimeMS()
      * Return the mapReduce results as a Traversable.
      *
      * @see https://php.net/iteratoraggregate.getiterator
-     * @return Traversable
+     * @return Traversable<int, array|object>
      */
     #[ReturnTypeWillChange]
     public function getIterator()

src/MapReduceResult.php

@@ -31,6 +31,8 @@
  *
  * The internal data will be filtered through array_values() during BSON
  * serialization to ensure that it becomes a BSON array.
+ *
+ * @template-extends ArrayObject<int, mixed>
  */
 class BSONArray extends ArrayObject implements JsonSerializable, Serializable, Unserializable
 {
@@ -78,7 +80,7 @@ public function bsonSerialize()
      * Unserialize the document to BSON.
      *
      * @see https://php.net/mongodb-bson-unserializable.bsonunserialize
-     * @param array $data Array data
+     * @param array<int, mixed> $data Array data
      */
     #[ReturnTypeWillChange]
     public function bsonUnserialize(array $data)

src/Model/BSONArray.php

@@ -30,6 +30,8 @@
  *
  * The internal data will be cast to an object during BSON serialization to
  * ensure that it becomes a BSON document.
+ *
+ * @template-extends ArrayObject<string, mixed>
  */
 class BSONDocument extends ArrayObject implements JsonSerializable, Serializable, Unserializable
 {
@@ -48,6 +50,7 @@ public function __clone()
      * by default.
      *
      * @see https://php.net/arrayobject.construct
+     * @param array<string, mixed> $input
      */
     public function __construct(array $input = [], int $flags = ArrayObject::ARRAY_AS_PROPS, string $iteratorClass = 'ArrayIterator')
     {
@@ -85,7 +88,7 @@ public function bsonSerialize()
      * Unserialize the document to BSON.
      *
      * @see https://php.net/mongodb-bson-unserializable.bsonunserialize
-     * @param array $data Array data
+     * @param array<string, mixed> $data Array data
      */
     #[ReturnTypeWillChange]
     public function bsonUnserialize(array $data)

src/Model/BSONDocument.php

@@ -31,6 +31,8 @@
 
 /**
  * Iterator for BSON documents.
+ *
+ * @template-implements Iterator<int, mixed>
  */
 class BSONIterator implements Iterator
 {
@@ -89,7 +91,7 @@ public function current()
 
     /**
      * @see https://php.net/iterator.key
-     * @return mixed
+     * @return int
      */
     #[ReturnTypeWillChange]
     public function key()

src/Model/BSONIterator.php

@@ -36,14 +36,19 @@
  * those operations (e.g. MongoDB\Driver\Cursor).
  *
  * @internal
+ * @template TKey of array-key
+ * @template TValue
+ * @template-implements Iterator<TKey, TValue>
  */
 class CachingIterator implements Countable, Iterator
 {
     private const FIELD_KEY = 0;
     private const FIELD_VALUE = 1;
 
+    /** @var list<array{0: TKey, 1: TValue}> */
     private array $items = [];
 
+    /** @var Iterator<TKey, TValue> */
     private Iterator $iterator;
 
     private bool $iteratorAdvanced = false;
@@ -56,7 +61,7 @@ class CachingIterator implements Countable, Iterator
      * Additionally, this mimics behavior of the SPL iterators and allows users
      * to omit an explicit call to rewind() before using the other methods.
      *
-     * @param Traversable $traversable
+     * @param Traversable<TKey, TValue> $traversable
      */
     public function __construct(Traversable $traversable)
     {
@@ -83,12 +88,13 @@ public function current()
     {
         $currentItem = current($this->items);
 
-        return $currentItem !== false ? $currentItem[self::FIELD_VALUE] : false;
+        return $currentItem !== false ? $currentItem[self::FIELD_VALUE] : null;
     }
 
     /**
      * @see https://php.net/iterator.key
      * @return mixed
+     * @psalm-return TKey|null
      */
     #[ReturnTypeWillChange]
     public function key()

src/Model/CachingIterator.php

@@ -46,6 +46,8 @@
  * rewind() do not execute getMore commands.
  *
  * @internal
+ * @template TValue of array|object
+ * @template-extends IteratorIterator<int, TValue, Cursor<TValue>>
  */
 class ChangeStreamIterator extends IteratorIterator implements CommandSubscriber
 {
@@ -67,6 +69,7 @@ class ChangeStreamIterator extends IteratorIterator implements CommandSubscriber
     /**
      * @internal
      * @param array|object|null $initialResumeToken
+     * @psalm-param Cursor<TValue> $cursor
      */
     public function __construct(Cursor $cursor, int $firstBatchSize, $initialResumeToken, ?object $postBatchResumeToken)
     {
@@ -122,12 +125,13 @@ final public function commandSucceeded(CommandSucceededEvent $event): void
 
     /**
      * @see https://php.net/iteratoriterator.current
-     * @return mixed
+     * @return array|object|null
+     * @psalm-return TValue|null
      */
     #[ReturnTypeWillChange]
     public function current()
     {
-        return $this->isValid ? parent::current() : null;
+        return $this->valid() ? parent::current() : null;
     }
 
     /**
@@ -168,12 +172,12 @@ public function getServer(): Server
 
     /**
      * @see https://php.net/iteratoriterator.key
-     * @return mixed
+     * @return int|null
      */
     #[ReturnTypeWillChange]
     public function key()
     {
-        return $this->isValid ? parent::key() : null;
+        return $this->valid() ? parent::key() : null;
     }
 
     /** @see https://php.net/iteratoriterator.rewind */
@@ -213,7 +217,10 @@ public function rewind(): void
         $this->onIteration(false);
     }
 
-    /** @see https://php.net/iteratoriterator.valid */
+    /**
+     * @see https://php.net/iteratoriterator.valid
+     * @psalm-assert-if-true TValue $this->current()
+     */
     public function valid(): bool
     {
         return $this->isValid;
@@ -276,11 +283,11 @@ private function onIteration(bool $incrementBatchPosition): void
         /* Disable rewind()'s NOP behavior once we advance to a valid position.
          * This will allow the driver to throw a LogicException if rewind() is
          * called after the cursor has advanced past its first element. */
-        if ($this->isRewindNop && $this->isValid) {
+        if ($this->isRewindNop && $this->valid()) {
             $this->isRewindNop = false;
         }
 
-        if ($incrementBatchPosition && $this->isValid) {
+        if ($incrementBatchPosition && $this->valid()) {
             $this->batchPosition++;
         }
 
@@ -292,7 +299,7 @@ private function onIteration(bool $incrementBatchPosition): void
          * from the current document if possible. */
         if ($this->isAtEndOfBatch() && $this->postBatchResumeToken !== null) {
             $this->resumeToken = $this->postBatchResumeToken;
-        } elseif ($this->isValid) {
+        } elseif ($this->valid()) {
             $this->resumeToken = $this->extractResumeToken($this->current());
         }
     }

src/Model/ChangeStreamIterator.php

@@ -32,6 +32,7 @@
  *
  * @see \MongoDB\Database::listCollections()
  * @see https://github.com/mongodb/specifications/blob/master/source/enumerate-collections.rst
+ * @template-implements ArrayAccess<string, mixed>
  */
 class CollectionInfo implements ArrayAccess
 {

src/Model/CollectionInfo.php

@@ -30,11 +30,13 @@
  * @see \MongoDB\Database::listCollections()
  * @see https://github.com/mongodb/specifications/blob/master/source/enumerate-collections.rst
  * @see https://mongodb.com/docs/manual/reference/command/listCollections/
+ * @template-extends IteratorIterator<int, array, Traversable<int, array>>
  */
 class CollectionInfoCommandIterator extends IteratorIterator implements CollectionInfoIterator
 {
     private ?string $databaseName = null;
 
+    /** @param Traversable<int, array> $iterator */
     public function __construct(Traversable $iterator, ?string $databaseName = null)
     {
         parent::__construct($iterator);

src/Model/CollectionInfoCommandIterator.php

@@ -26,6 +26,7 @@
  * This iterator is used for enumerating collections in a database.
  *
  * @see \MongoDB\Database::listCollections()
+ * @template-extends Iterator<int, CollectionInfo>
  */
 interface CollectionInfoIterator extends Iterator
 {

src/Model/CollectionInfoIterator.php

@@ -31,6 +31,7 @@
  *
  * @see \MongoDB\Client::listDatabases()
  * @see https://mongodb.com/docs/manual/reference/command/listDatabases/
+ * @template-implements ArrayAccess<string, mixed>
  */
 class DatabaseInfo implements ArrayAccess
 {

src/Model/DatabaseInfo.php

@@ -26,6 +26,7 @@
  * This iterator is used for enumerating databases on a server.
  *
  * @see \MongoDB\Client::listDatabases()
+ * @template-extends Iterator<int, DatabaseInfo>
  */
 interface DatabaseInfoIterator extends Iterator
 {

src/Model/DatabaseInfoIterator.php

@@ -40,6 +40,7 @@
  * @see \MongoDB\Collection::listIndexes()
  * @see https://github.com/mongodb/specifications/blob/master/source/enumerate-indexes.rst
  * @see https://mongodb.com/docs/manual/reference/method/db.collection.createIndex/
+ * @template-implements ArrayAccess<string, mixed>
  */
 class IndexInfo implements ArrayAccess
 {

src/Model/IndexInfo.php

@@ -26,6 +26,7 @@
  * This iterator is used for enumerating indexes in a collection.
  *
  * @see \MongoDB\Collection::listIndexes()
+ * @template-extends Iterator<int, IndexInfo>
  */
 interface IndexInfoIterator extends Iterator
 {