Convert @psalm-* annotations to generic or @phpstan-* annotation (#…

…2685)
doctrine · Oct 14, 2024 · fe0f1ff · fe0f1ff
1 parent ff90e9a
commit fe0f1ff
Show file tree

Hide file tree

Showing 91 changed files with 556 additions and 1,155 deletions.
diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml
@@ -105,8 +105,6 @@ jobs:
         if: "${{ matrix.symfony-version == '7' }}"
         run: |
           composer config minimum-stability dev
-          # not yet ready for v7
-          composer remove --no-update --dev vimeo/psalm
           # update symfony deps
           composer require --no-update symfony/console:^7@dev
           composer require --no-update symfony/var-dumper:^7@dev

diff --git a/.github/workflows/static-analysis.yml b/.github/workflows/static-analysis.yml
@@ -59,36 +59,3 @@ jobs:
 
       - name: "Run a static analysis with phpstan/phpstan"
         run: "vendor/bin/phpstan analyse --error-format=github"
-
-  static-analysis-psalm:
-    name: "Static Analysis with Psalm"
-    runs-on: "ubuntu-22.04"
-
-    strategy:
-      matrix:
-        php-version:
-          - "8.2"
-
-    steps:
-      - name: "Checkout code"
-        uses: "actions/checkout@v4"
-
-      - name: "Install PHP"
-        uses: "shivammathur/setup-php@v2"
-        with:
-          coverage: "none"
-          extensions: "mongodb"
-          php-version: "${{ matrix.php-version }}"
-
-      - name: "Install dependencies with Composer"
-        uses: "ramsey/composer-install@v3"
-
-      - name: "Upload composer.lock as build artifact"
-        uses: actions/upload-artifact@v4
-        with:
-          name: "composer-lock-static-analysis-psalm"
-          path: composer.lock
-          overwrite: true
-
-      - name: "Run a static analysis with vimeo/psalm"
-        run: "vendor/bin/psalm --show-info=false --stats --output-format=github --threads=$(nproc)"
diff --git a/.gitignore b/.gitignore
@@ -11,4 +11,3 @@ vendor/
 .phpunit.cache
 .phpunit.result.cache
 phpcs.xml
-psalm.xml
diff --git a/composer.json b/composer.json
@@ -47,8 +47,7 @@
         "phpstan/phpstan-phpunit": "^1.0",
         "phpunit/phpunit": "^10.4",
         "squizlabs/php_codesniffer": "^3.5",
-        "symfony/cache": "^5.4 || ^6.0 || ^7.0",
-        "vimeo/psalm": "~5.24.0"
+        "symfony/cache": "^5.4 || ^6.0 || ^7.0"
     },
     "conflict": {
         "doctrine/annotations": "<1.12 || >=3.0"

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Aggregation.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Aggregation.php
@@ -18,13 +18,13 @@
 use function array_merge;
 use function assert;
 
-/** @psalm-import-type PipelineExpression from Builder */
+/** @phpstan-import-type PipelineExpression from Builder */
 final class Aggregation implements IteratorAggregate
 {
     /**
      * @param array<string, mixed> $pipeline
      * @param array<string, mixed> $options
-     * @psalm-param PipelineExpression $pipeline
+     * @phpstan-param PipelineExpression $pipeline
      */
     public function __construct(private DocumentManager $dm, private ?ClassMetadata $classMetadata, private Collection $collection, private array $pipeline, private array $options = [], private bool $rewindable = true)
     {

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php
@@ -28,9 +28,9 @@
 /**
  * Fluent interface for building aggregation pipelines.
  *
- * @psalm-import-type SortShape from Sort
- * @psalm-import-type StageExpression from Stage
- * @psalm-type PipelineExpression = list<StageExpression>
+ * @phpstan-import-type SortShape from Sort
+ * @phpstan-type StageExpression array<string, mixed>
+ * @phpstan-type PipelineExpression list<StageExpression>
  */
 class Builder
 {
@@ -44,7 +44,7 @@ class Builder
      */
     private ClassMetadata $class;
 
-    /** @psalm-var class-string */
+    /** @var class-string */
     private ?string $hydrationClass = null;
 
     /**
@@ -60,7 +60,7 @@ class Builder
     /**
      * Create a new aggregation builder.
      *
-     * @psalm-param class-string $documentName
+     * @param class-string $documentName
      */
     public function __construct(DocumentManager $dm, string $documentName)
     {
@@ -270,8 +270,8 @@ public function getAggregation(array $options = []): Aggregation
      * you should not apply filters as this may cause wrong results to be
      * given.
      *
-     * @return array<array<string, mixed>>
-     * @psalm-return PipelineExpression
+     * @return list<array<string, mixed>>
+     * @phpstan-return PipelineExpression
      */
     // phpcs:enable Squiz.Commenting.FunctionComment.ExtraParamComment
     public function getPipeline(/* bool $applyFilters = true */): array
@@ -609,7 +609,7 @@ public function skip(int $skip): Stage\Skip
      *
      * @param array<string, int|string|array<string, string>>|string $fieldName Field name or array of field/order pairs
      * @param int|string|null                                        $order     Field order (if one field is specified)
-     * @psalm-param SortShape|string $fieldName Field name or array of field/order pairs
+     * @phpstan-param SortShape|string $fieldName Field name or array of field/order pairs
      */
     public function sort($fieldName, $order = null): Stage\Sort
     {
@@ -699,7 +699,7 @@ public function addStage(Stage $stage): Stage
      */
     private function applyFilters(array $query): array
     {
-        $documentPersister = $this->dm->getUnitOfWork()->getDocumentPersister($this->class->name);
+        $documentPersister = $this->getDocumentPersister();
 
         $query = $documentPersister->addDiscriminatorToPreparedQuery($query);
         $query = $documentPersister->addFilterToPreparedQuery($query);

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
@@ -45,7 +45,7 @@
 /**
  * Fluent interface for building aggregation pipelines.
  *
- * @psalm-type OperatorExpression = array<string, mixed>|object
+ * @phpstan-type OperatorExpression array<string, mixed>|object
  */
 class Expr implements
     AccumulatorOperators,

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage.php
@@ -14,8 +14,8 @@
  *
  * @internal
  *
- * @psalm-import-type PipelineExpression from Builder
- * @psalm-type StageExpression = array<non-empty-string, mixed>
+ * @phpstan-import-type PipelineExpression from Builder
+ * @phpstan-import-type StageExpression from Builder
  */
 abstract class Stage
 {
@@ -31,7 +31,7 @@ public function __construct(Builder $builder)
      * Assembles the aggregation stage
      *
      * @return array<string, mixed>
-     * @psalm-return StageExpression
+     * @phpstan-return StageExpression
      */
     abstract public function getExpression(): array;
 
@@ -189,8 +189,8 @@ public function geoNear($x, $y = null): Stage\GeoNear
     /**
      * Returns the assembled aggregation pipeline
      *
-     * @return array<array<string, mixed>>
-     * @psalm-return PipelineExpression
+     * @return list<array<string, mixed>>
+     * @phpstan-return PipelineExpression
      */
     public function getPipeline(): array
     {

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/AddFields.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/AddFields.php
@@ -9,8 +9,8 @@
 /**
  * Fluent interface for adding a $addFields stage to an aggregation pipeline.
  *
- * @psalm-import-type OperatorExpression from Expr
- * @psalm-type AddFieldsStageExpression = array{'$addFields': array<string, OperatorExpression|mixed>}
+ * @phpstan-import-type OperatorExpression from Expr
+ * @phpstan-type AddFieldsStageExpression array{'$addFields': array<string, OperatorExpression|mixed>}
  */
 final class AddFields extends Operator
 {

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Bucket.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Bucket.php
@@ -63,7 +63,6 @@ public function output(): Bucket\BucketOutput
     /** @return array{boundaries: mixed[], default: mixed} */
     protected function getExtraPipelineFields(): array
     {
-        /** @psalm-suppress RedundantPropertyInitializationCheck because the property might not be set yet */
         $fields = ['boundaries' => $this->boundaries ?? null];
         if ($this->default !== null) {
             $fields['default'] = $this->default;

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/CollStats.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/CollStats.php
@@ -10,7 +10,7 @@
 /**
  * Fluent interface for adding a $collStats stage to an aggregation pipeline.
  *
- * @psalm-type CollStatsStageExpression = array{
+ * @phpstan-type CollStatsStageExpression array{
  *     '$collStats': array{
  *         latencyStats?: array{histograms?: bool},
  *         storageStats?: array{},
@@ -52,7 +52,7 @@ public function showStorageStats(): static
         return $this;
     }
 
-    /** @psalm-return CollStatsStageExpression */
+    /** @phpstan-return CollStatsStageExpression */
     public function getExpression(): array
     {
         $collStats = [];

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Count.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Count.php
@@ -10,7 +10,7 @@
 /**
  * Fluent interface for adding a $count stage to an aggregation pipeline.
  *
- * @psalm-type CountStageExpression = array{'$count': string}
+ * @phpstan-type CountStageExpression array{'$count': string}
  */
 class Count extends Stage
 {
@@ -19,7 +19,7 @@ public function __construct(Builder $builder, private string $fieldName)
         parent::__construct($builder);
     }
 
-    /** @psalm-return CountStageExpression */
+    /** @phpstan-return CountStageExpression */
     public function getExpression(): array
     {
         return [

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Densify.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Densify.php
@@ -13,9 +13,9 @@
 /**
  * Fluent interface for adding a $densify stage to an aggregation pipeline.
  *
- * @psalm-type BoundsType = 'full'|'partition'|array{0: int|float|UTCDateTime, 1: int|float|UTCDateTime}
- * @psalm-type UnitType = 'year'|'month'|'week'|'day'|'hour'|'minute'|'second'|'millisecond'
- * @psalm-type DensifyStageExpression = array{
+ * @phpstan-type BoundsType 'full'|'partition'|array{0: int|float|UTCDateTime, 1: int|float|UTCDateTime}
+ * @phpstan-type UnitType 'year'|'month'|'week'|'day'|'hour'|'minute'|'second'|'millisecond'
+ * @phpstan-type DensifyStageExpression array{
  *     '$densify': object{
  *         field: string,
  *         partitionByFields?: list<string>,
@@ -54,8 +54,8 @@ public function partitionByFields(string ...$fields): static
     /**
      * @param array|string $bounds
      * @param int|float    $step
-     * @psalm-param BoundsType  $bounds
-     * @psalm-param ''|UnitType $unit
+     * @phpstan-param BoundsType  $bounds
+     * @phpstan-param ''|UnitType $unit
      */
     public function range($bounds, $step, string $unit = ''): static
     {
@@ -71,7 +71,7 @@ public function range($bounds, $step, string $unit = ''): static
         return $this;
     }
 
-    /** @psalm-return DensifyStageExpression */
+    /** @phpstan-return DensifyStageExpression */
     public function getExpression(): array
     {
         $params = (object) [

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Facet.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Facet.php
@@ -14,8 +14,8 @@
 /**
  * Fluent interface for adding a $facet stage to an aggregation pipeline.
  *
- * @psalm-import-type PipelineExpression from Builder
- * @psalm-type FacetStageExpression = array{'$facet': array<string, PipelineExpression>}
+ * @phpstan-import-type PipelineExpression from Builder
+ * @phpstan-type FacetStageExpression array{'$facet': array<string, PipelineExpression>}
  */
 class Facet extends Stage
 {
@@ -48,7 +48,6 @@ public function field(string $field): static
      */
     public function pipeline($builder): static
     {
-        /** @psalm-suppress RedundantPropertyInitializationCheck because the property might not be set yet */
         if (! isset($this->field)) {
             throw new LogicException(__METHOD__ . ' requires setting a current field using field().');
         }

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Fill.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Fill.php
@@ -17,11 +17,11 @@
 /**
  * Fluent interface for adding a $fill stage to an aggregation pipeline.
  *
- * @psalm-import-type SortDirectionKeywords from Sort
- * @psalm-import-type OperatorExpression from Expr
- * @psalm-type SortDirection = int|SortDirectionKeywords
- * @psalm-type SortShape = array<string, SortDirection>
- * @psalm-type FillStageExpression = array{
+ * @phpstan-import-type SortDirectionKeywords from Sort
+ * @phpstan-import-type OperatorExpression from Expr
+ * @phpstan-type SortDirection int|SortDirectionKeywords
+ * @phpstan-type SortShape array<string, SortDirection>
+ * @phpstan-type FillStageExpression array{
  *     '$fill': array{
  *         partitionBy?: string|OperatorExpression,
  *         partitionByFields?: list<string>,
@@ -67,8 +67,8 @@ public function partitionByFields(string ...$fields): static
     /**
      * @param array<string, int|string>|string $fieldName Field name or array of field/order pairs
      * @param int|string                       $order     Field order (if one field is specified)
-     * @psalm-param SortShape|string           $fieldName
-     * @psalm-param SortDirection|null         $order
+     * @phpstan-param SortShape|string           $fieldName
+     * @phpstan-param SortDirection|null         $order
      */
     public function sortBy($fieldName, $order = null): static
     {

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Fill/Output.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Fill/Output.php
@@ -16,7 +16,7 @@
 /**
  * Fluent builder for output param of $fill stage
  *
- * @psalm-import-type SortShape from Fill
+ * @phpstan-import-type SortShape from Fill
  */
 class Output extends Stage
 {
@@ -44,7 +44,7 @@ public function partitionByFields(string ...$fields): Fill
     /**
      * @param array<string, int|string>|string $fieldName Field name or array of field/order pairs
      * @param int|string                       $order     Field order (if one field is specified)
-     * @psalm-param SortShape|string           $fieldName
+     * @phpstan-param SortShape|string           $fieldName
      */
     public function sortBy($fieldName, $order = null): Fill
     {

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/GraphLookup.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/GraphLookup.php
@@ -20,7 +20,7 @@
 use function is_string;
 use function substr;
 
-/** @psalm-import-type FieldMapping from ClassMetadata */
+/** @phpstan-import-type FieldMapping from ClassMetadata */
 class GraphLookup extends Stage
 {
     private ?string $from;
@@ -130,7 +130,7 @@ public function depthField(string $depthField): static
      * Target collection for the $graphLookup operation to search, recursively
      * matching the connectFromField to the connectToField.
      *
-     * @psalm-param class-string|string $from
+     * @param class-string|string $from
      */
     public function from(string $from): static
     {
@@ -281,7 +281,7 @@ private function getDocumentPersister(ClassMetadata $class): DocumentPersister
         return $this->dm->getUnitOfWork()->getDocumentPersister($class->name);
     }
 
-    /** @psalm-param FieldMapping $mapping */
+    /** @phpstan-param FieldMapping $mapping */
     private function getReferencedFieldName(string $fieldName, array $mapping): string
     {
         if (! $this->targetClass) {

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Group.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Group.php
@@ -12,7 +12,7 @@
 /**
  * Fluent interface for adding a $group stage to an aggregation pipeline.
  *
- * @psalm-type GroupStageExpression = array{'$group': array<string, mixed>}
+ * @phpstan-type GroupStageExpression array{'$group': array<string, mixed>}
  */
 class Group extends Operator implements GroupAccumulatorOperators
 {
@@ -28,7 +28,7 @@ public function __construct(Builder $builder)
         $this->expr = $builder->expr();
     }
 
-    /** @psalm-return GroupStageExpression */
+    /** @phpstan-return GroupStageExpression */
     public function getExpression(): array
     {
         return [

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/IndexStats.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Stage/IndexStats.php
@@ -10,11 +10,11 @@
 /**
  * Fluent interface for adding a $indexStats stage to an aggregation pipeline.
  *
- * @psalm-type IndexStatsStageExpression = array{'$indexStats': object}
+ * @phpstan-type IndexStatsStageExpression array{'$indexStats': object}
  */
 class IndexStats extends Stage
 {
-    /** @psalm-return IndexStatsStageExpression */
+    /** @phpstan-return IndexStatsStageExpression */
     public function getExpression(): array
     {
         return [