feat: improve phpstan level 7 and add phpstan-symfony rules (#2161)

Co-authored-by: Gabriel Ostrolucký <[email protected]>
Co-authored-by: Gabriel Ostrolucký <[email protected]>

Author: shakaran

.github/workflows/static-analysis.yml

@@ -24,6 +24,25 @@ on:
       - tests/**
 
 jobs:
-  static-analysis:
-    name: "Static Analysis"
-    uses: "doctrine/.github/.github/workflows/[email protected]"
+  phpstan:
+    name: "PHPStan"
+    runs-on: "ubuntu-latest"
+
+    steps:
+      - name: "Checkout code"
+        uses: "actions/checkout@v5"
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "8.4"
+
+      - name: "Install dependencies with Composer"
+        uses: "ramsey/composer-install@v3"
+
+      - name: "Warm up Symfony cache"
+        run: "php tests/console-application.php"
+
+      - name: "Run a static analysis with phpstan/phpstan"
+        run: "vendor/bin/phpstan analyse -v"

composer.json

@@ -48,6 +48,7 @@
         "phpstan/phpstan": "2.1.1",
         "phpstan/phpstan-phpunit": "2.0.3",
         "phpstan/phpstan-strict-rules": "^2",
+        "phpstan/phpstan-symfony": "^2.0",
         "phpunit/phpunit": "^12.3.10",
         "psr/log": "^3.0",
         "symfony/doctrine-messenger": "^6.4 || ^7.0 || ^8.0",

phpstan.neon.dist

@@ -1,8 +1,14 @@
+includes:
+    - vendor/phpstan/phpstan-symfony/extension.neon
 parameters:
-   level: 6
+   level: 7
    reportUnmatchedIgnoredErrors: true
    paths:
       - config
       - src
       - tests
-   ignoreErrors:
+   scanFiles:
+      - vendor/symfony/dependency-injection/Loader/Configurator/ContainerConfigurator.php
+   symfony:
+       constantHassers: false
+       containerXmlPath: var/cache/test/Doctrine_Bundle_DoctrineBundle_Tests_DependencyInjection_Fixtures_TestKernelTestDebugContainer.xml

src/Command/DoctrineCommand.php

@@ -8,6 +8,8 @@
 use Doctrine\Persistence\ManagerRegistry;
 use Symfony\Component\Console\Command\Command;
 
+use function assert;
+
 /**
  * Base class for Doctrine console commands to extend from.
  *
@@ -26,7 +28,10 @@ public function __construct(
      */
     protected function getDoctrineConnection(string $name): Connection
     {
-        return $this->getDoctrine()->getConnection($name);
+        $connection = $this->getDoctrine()->getConnection($name);
+        assert($connection instanceof Connection);
+
+        return $connection;
     }
 
     protected function getDoctrine(): ManagerRegistry

src/ConnectionFactory.php

@@ -27,7 +27,7 @@
 /**
  * @internal This class is not meant to be used outside this bundle
  *
- * @phpstan-import-type Params from DriverManager
+ * @phpstan-type Params = array<string, mixed>
  */
 final class ConnectionFactory
 {
@@ -44,7 +44,6 @@ final class ConnectionFactory
         'sqlite3'    => 'pdo_sqlite',
     ];
 
-    /** @phpstan-ignore property.onlyWritten */
     private readonly DsnParser $dsnParser;
 
     private bool $initialized = false;
@@ -60,7 +59,6 @@ public function __construct(
     /**
      * Create a connection by name.
      *
-     * @param mixed[]               $params
      * @param array<string, string> $mappingTypes
      * @phpstan-param Params $params
      */
@@ -86,7 +84,6 @@ public function createConnection(
             }
         }
 
-        /** @phpstan-ignore-next-line We should adjust when https://github.com/phpstan/phpstan/issues/12414 is fixed */
         if (! isset($params['pdo']) && (! isset($params['charset']) || isset($params['dbname_suffix']))) {
             $wrapperClass = null;
 
@@ -213,22 +210,18 @@ private function addDatabaseSuffix(array $params): array
      * @param mixed[] $params The list of parameters.
      * @phpstan-param Params $params
      *
-     * @return mixed[] A modified list of parameters with info from a database
+     * @return Params params A modified list of parameters with info from a database
      *                 URL extracted into individual parameter parts.
      * @phpstan-return Params
      *
      * @throws DBALException
-     *
-     * @phpstan-ignore throws.unusedType
      */
     private function parseDatabaseUrl(array $params): array
     {
-        /** @phpstan-ignore isset.offset (for DBAL < 4) */
         if (! isset($params['url'])) {
             return $params;
         }
 
-        /** @phpstan-ignore deadCode.unreachable */
         try {
             $parsedParams = $this->dsnParser->parse($params['url']);
         } catch (MalformedDsnException $e) {

src/DataCollector/DoctrineDataCollector.php

@@ -46,7 +46,19 @@
  *    }>>,
  *    entityCounts: array<string, array<class-string, int>>
  * }
- * @psalm-property DataType $data
+ * @phpstan-type GroupedQueryItemType = array{
+ *    executionMS: float,
+ *    explainable: bool,
+ *    sql: string,
+ *    params: ?array<array-key, mixed>,
+ *    runnable: bool,
+ *    types: ?array<array-key, Type|int|string|null>,
+ *    count: int,
+ *    index: int,
+ *    executionPercent?: float
+ * }
+ * @phpstan-type GroupedQueriesType = array<string, array<int, GroupedQueryItemType>>
+ * @phpstan-property DataType $data
  */
 class DoctrineDataCollector extends BaseCollector
 {
@@ -56,17 +68,7 @@ class DoctrineDataCollector extends BaseCollector
 
     /**
      * @var mixed[][]|null
-     * @phpstan-var ?array<string, list<array{
-     *    executionMS: float,
-     *    explainable: bool,
-     *    sql: string,
-     *    params: ?array<array-key, mixed>,
-     *    runnable: bool,
-     *    types: ?array<array-key, Type|int|string|null>,
-     *    count: int,
-     *    index: int,
-     *    executionPercent?: float
-     * }>>
+     * @phpstan-var ?GroupedQueriesType
      */
     private array|null $groupedQueries = null;
 
@@ -269,17 +271,7 @@ public function getManagedEntityCountByClass(): array
 
     /**
      * @return string[][]
-     * @phpstan-return array<string, list<array{
-     *    executionMS: float,
-     *    explainable: bool,
-     *    sql: string,
-     *    params: ?array<array-key, mixed>,
-     *    runnable: bool,
-     *    types: ?array<array-key, Type|int|string|null>,
-     *    count: int,
-     *    index: int,
-     *    executionPercent?: float
-     * }>>
+     * @phpstan-return GroupedQueriesType
      */
     public function getGroupedQueries(): array
     {

src/Dbal/ManagerRegistryAwareConnectionProvider.php

@@ -8,6 +8,8 @@
 use Doctrine\DBAL\Tools\Console\ConnectionProvider;
 use Doctrine\Persistence\AbstractManagerRegistry;
 
+use function assert;
+
 class ManagerRegistryAwareConnectionProvider implements ConnectionProvider
 {
     public function __construct(
@@ -17,11 +19,17 @@ public function __construct(
 
     public function getDefaultConnection(): Connection
     {
-        return $this->managerRegistry->getConnection();
+        $connection = $this->managerRegistry->getConnection();
+        assert($connection instanceof Connection);
+
+        return $connection;
     }
 
     public function getConnection(string $name): Connection
     {
-        return $this->managerRegistry->getConnection($name);
+        $connection = $this->managerRegistry->getConnection($name);
+        assert($connection instanceof Connection);
+
+        return $connection;
     }
 }

src/DependencyInjection/Configuration.php

@@ -12,7 +12,6 @@
 use RuntimeException;
 use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
 use Symfony\Component\Config\Definition\Builder\NodeDefinition;
-use Symfony\Component\Config\Definition\Builder\NodeParentInterface;
 use Symfony\Component\Config\Definition\Builder\TreeBuilder;
 use Symfony\Component\Config\Definition\ConfigurationInterface;
 use Symfony\Component\DependencyInjection\Exception\LogicException;
@@ -49,7 +48,6 @@ public function __construct(private bool $debug)
     {
     }
 
-    /** @return TreeBuilder<'array'> */
     public function getConfigTreeBuilder(): TreeBuilder
     {
         $treeBuilder = new TreeBuilder('doctrine');
@@ -63,14 +61,13 @@ public function getConfigTreeBuilder(): TreeBuilder
 
     /**
      * Add DBAL section to configuration tree
-     *
-     * @param ArrayNodeDefinition<TreeBuilder<'array'>> $node
      */
     private function addDbalSection(ArrayNodeDefinition $node): void
     {
         // Key that should not be rewritten to the connection config
         $excludedKeys = ['default_connection' => true, 'driver_schemes' => true, 'driver_scheme' => true, 'types' => true, 'type' => true];
 
+        /** @phpstan-ignore class.notFound (Phpstan Symfony extension does not know yet how to deal with these) */
         $node
             ->children()
             ->arrayNode('dbal')
@@ -157,8 +154,6 @@ private function addDbalSection(ArrayNodeDefinition $node): void
 
     /**
      * Return the dbal connections node
-     *
-     * @return ArrayNodeDefinition<TreeBuilder<'array'>>
      */
     private function getDbalConnectionsNode(): ArrayNodeDefinition
     {
@@ -172,6 +167,7 @@ private function getDbalConnectionsNode(): ArrayNodeDefinition
 
         $this->configureDbalDriverNode($connectionNode);
 
+        /** @phpstan-ignore class.notFound (Phpstan Symfony extension does not know yet how to deal with these) */
         $connectionNode
             ->fixXmlConfig('option')
             ->fixXmlConfig('mapping_type')
@@ -218,6 +214,7 @@ private function getDbalConnectionsNode(): ArrayNodeDefinition
                 ->scalarNode('result_cache')->end()
             ->end();
 
+        /** @phpstan-ignore class.notFound (Phpstan Symfony extension does not know yet how to deal with these) */
         $replicaNode = $connectionNode
             ->children()
                 ->arrayNode('replicas')
@@ -232,13 +229,10 @@ private function getDbalConnectionsNode(): ArrayNodeDefinition
      * Adds config keys related to params processed by the DBAL drivers
      *
      * These keys are available for replica configurations too.
-     *
-     * @param ArrayNodeDefinition<TP> $node
-     *
-     * @template TP of NodeParentInterface|null
-     **/
+     */
     private function configureDbalDriverNode(ArrayNodeDefinition $node): void
     {
+        /** @phpstan-ignore class.notFound (Phpstan Symfony extension does not know yet how to deal with these) */
         $node
             ->validate()
             ->always(static function (array $values) {
@@ -364,8 +358,6 @@ private function configureDbalDriverNode(ArrayNodeDefinition $node): void
 
     /**
      * Add the ORM section to configuration tree
-     *
-     * @param ArrayNodeDefinition<TreeBuilder<'array'>> $node
      */
     private function addOrmSection(ArrayNodeDefinition $node): void
     {
@@ -378,6 +370,7 @@ private function addOrmSection(ArrayNodeDefinition $node): void
             'controller_resolver' => true,
         ];
 
+        /** @phpstan-ignore class.notFound (Phpstan Symfony extension does not know yet how to deal with these) */
         $node
             ->children()
                 ->arrayNode('orm')
@@ -525,6 +518,7 @@ private function getOrmEntityListenersNode(): NodeDefinition
             return ['entities' => $entities];
         };
 
+        /** @phpstan-ignore class.notFound (Phpstan Symfony extension does not know yet how to deal with these) */
         $node
             ->beforeNormalization()
                 // Yaml normalization
@@ -564,14 +558,13 @@ private function getOrmEntityListenersNode(): NodeDefinition
 
     /**
      * Return ORM entity manager node
-     *
-     * @return ArrayNodeDefinition<TreeBuilder<'array'>>
      */
     private function getOrmEntityManagersNode(): ArrayNodeDefinition
     {
         $treeBuilder = new TreeBuilder('entity_managers');
         $node        = $treeBuilder->getRootNode();
 
+        /** @phpstan-ignore class.notFound (Phpstan Symfony extension does not know yet how to deal with these) */
         $node
             ->requiresAtLeastOneElement()
             ->useAttributeAsKey('name')
@@ -740,14 +733,13 @@ private function getOrmEntityManagersNode(): ArrayNodeDefinition
 
     /**
      * Return an ORM cache driver node for a given entity manager
-     *
-     * @return ArrayNodeDefinition<TreeBuilder<'array'>>
      */
     private function getOrmCacheDriverNode(string $name): ArrayNodeDefinition
     {
         $treeBuilder = new TreeBuilder($name);
         $node        = $treeBuilder->getRootNode();
 
+        /** @phpstan-ignore class.notFound (Phpstan Symfony extension does not know yet how to deal with these) */
         $node
             ->beforeNormalization()
                 ->ifString()