Add more specific phpdoc to DocumentRepository (#2326)

* Bump phpstan and psalm

* Update phpdoc of DocumentRepository

Psalm does not work well inheriting phpdoc templates in methods,
so duplicating them fixes the issue.

Author: franmomu

composer.json

@@ -43,12 +43,12 @@
         "doctrine/coding-standard": "^9.0",
         "jmikola/geojson": "^1.0",
         "phpbench/phpbench": "^1.0.0",
-        "phpstan/phpstan": "^0.12.32",
+        "phpstan/phpstan": "^0.12.89",
         "phpstan/phpstan-phpunit": "^0.12.19",
         "phpunit/phpunit": "^8.5 || ^9",
         "squizlabs/php_codesniffer": "^3.5",
         "symfony/cache": "^4.4 || ^5.0",
-        "vimeo/psalm": "^4.2.1"
+        "vimeo/psalm": "^4.8.1"
     },
     "suggest": {
         "ext-bcmath": "Decimal128 type support"

lib/Doctrine/ODM/MongoDB/Repository/DocumentRepository.php

@@ -101,6 +101,8 @@ public function clear(): void
      *
      * @param mixed $id Identifier.
      *
+     * @psalm-return T|null
+     *
      * @throws MappingException
      * @throws LockException
      */
@@ -155,6 +157,8 @@ public function find($id, int $lockMode = LockMode::NONE, ?int $lockVersion = nu
 
     /**
      * Finds all documents in the repository.
+     *
+     * {@inheritDoc}
      */
     public function findAll(): array
     {
@@ -164,8 +168,7 @@ public function findAll(): array
     /**
      * Finds documents by a set of criteria.
      *
-     * @param int|null $limit
-     * @param int|null $offset
+     * {@inheritDoc}
      */
     public function findBy(array $criteria, ?array $orderBy = null, $limit = null, $offset = null): array
     {
@@ -175,14 +178,20 @@ public function findBy(array $criteria, ?array $orderBy = null, $limit = null, $
     /**
      * Finds a single document by a set of criteria.
      *
-     * @param array      $criteria
-     * @param array|null $sort
+     * @param array<string, mixed>|null $sort
+     * @param array<string, mixed>      $criteria
+     *
+     * @return object|null The object.
+     * @psalm-return T|null
      */
     public function findOneBy(array $criteria, ?array $sort = null): ?object
     {
         return $this->getDocumentPersister()->load($criteria, null, [], 0, $sort);
     }
 
+    /**
+     * @psalm-return class-string<T>
+     */
     public function getDocumentName(): string
     {
         return $this->documentName;
@@ -193,11 +202,17 @@ public function getDocumentManager(): DocumentManager
         return $this->dm;
     }
 
+    /**
+     * @psalm-return ClassMetadata<T>
+     */
     public function getClassMetadata(): ClassMetadata
     {
         return $this->class;
     }
 
+    /**
+     * @psalm-return class-string<T>
+     */
     public function getClassName(): string
     {
         return $this->getDocumentName();
@@ -207,7 +222,7 @@ public function getClassName(): string
      * Selects all elements from a selectable that match the expression and
      * returns a new collection containing these elements.
      *
-     * @see Selectable::matching()
+     * {@inheritDoc}
      */
     public function matching(Criteria $criteria): ArrayCollection
     {

phpstan-baseline.neon

@@ -229,11 +229,6 @@ parameters:
             count: 1
             path: tests/Doctrine/ODM/MongoDB/Tests/Mapping/ClassMetadataTest.php
 
-        -
-            message: "#^Function mongodb\\\\bson\\\\tophp invoked with 1 parameter, 2 required\\.$#"
-            count: 2
-            path: tests/Doctrine/ODM/MongoDB/Tests/Mapping/ClassMetadataTest.php
-
         -
             message: "#^Access to an undefined property Documents\\\\CmsArticle\\:\\:\\$title\\.$#"
             count: 4

tests/Doctrine/ODM/MongoDB/Tests/Mapping/ClassMetadataTest.php

@@ -67,7 +67,6 @@ public function testClassMetadataInstanceSerialization()
         $cm->setVersioned(true);
         $cm->setVersionField('version');
         $validatorJson = '{ "$and": [ { "email": { "$regex": { "$regularExpression" : { "pattern": "@mongodb\\\\.com$", "options": "" } } } } ] }';
-        /** @psalm-suppress TooFewArguments */
         $cm->setValidator(toPHP(fromJSON($validatorJson)));
         $cm->setValidationAction(ClassMetadata::SCHEMA_VALIDATION_ACTION_WARN);
         $cm->setValidationLevel(ClassMetadata::SCHEMA_VALIDATION_LEVEL_OFF);
@@ -100,7 +99,6 @@ public function testClassMetadataInstanceSerialization()
         $this->assertEquals('lock', $cm->lockField);
         $this->assertEquals(true, $cm->isVersioned);
         $this->assertEquals('version', $cm->versionField);
-        /** @psalm-suppress TooFewArguments */
         $this->assertEquals(toPHP(fromJSON($validatorJson)), $cm->getValidator());
         $this->assertEquals(ClassMetadata::SCHEMA_VALIDATION_ACTION_WARN, $cm->getValidationAction());
         $this->assertEquals(ClassMetadata::SCHEMA_VALIDATION_LEVEL_OFF, $cm->getValidationLevel());