Replace static stub files with dynamic stub generation for Yii::$app type inference, adding support for custom application types.

Author: terabytesoftw

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 0.4.1 Under development
 
 - Bug #81: Update Rector command in `composer.json` to remove unnecessary 'src' argument (@terabytesoftw)
+- Enh: Replace static stub files with dynamic stub generation for `Yii::$app` type inference, adding support for custom application types (@terabytesoftw)
 
 ## 0.4.0 January 26, 2026
 

phpstan.neon

@@ -10,6 +10,7 @@ parameters:
     excludePaths:
         analyse:
             - tests/console/
+            - tests/custom/
 
     ignoreErrors:
         - '#Calling PHPStan\\Reflection\\Annotations\\AnnotationsPropertiesClassReflectionExtension\:\:(has|get)Property\(\) is not covered.+#'

src/StubFilesExtension.php

@@ -4,27 +4,27 @@
 
 namespace yii2\extensions\phpstan;
 
+use RuntimeException;
 use yii\base\Application;
 
+use function file_exists;
+use function file_put_contents;
+use function ltrim;
+use function md5;
+use function sprintf;
+use function strrpos;
+use function substr;
+use function sys_get_temp_dir;
+
 /**
- * Provides stub file resolution for PHPStan analysis based on a Yii Application type.
- *
- * Determines the appropriate stub file to use for static analysis by inspecting the application type from the provided
- * {@see ServiceMap} instance.
- *
- * This enables PHPStan to reflect the correct set of Yii Application properties and methods for web, console, or base
- * application contexts.
- *
- * The class supports mapping of application types to their corresponding stub files and falls back to a default stub if
- * the application type is not explicitly mapped.
+ * Provides dynamic stub file generation for PHPStan analysis based on the configured Yii Application type.
  *
- * Stub files are resolved from the `stub/` directory relative to the extension source.
+ * Generates a stub file at runtime that overrides the `Yii::$app` property type annotation to match the application
+ * type specified in the project configuration. This enables PHPStan to infer the correct application class for web,
+ * console, or custom application contexts without requiring separate static stub files.
  *
- * Key features:
- * - Maps Yii Application types to specific stub files for accurate static analysis.
- * - Provides a fallback stub for unknown or custom application types.
- * - Resolves stub file paths relative to the extension directory.
- * - Supports web, console, and base application contexts.
+ * The generated stub is written to a deterministic temporary file path, cached across PHPStan runs for the same
+ * application type.
  *
  * @see ServiceMap for service and component map for Yii Application static analysis.
  *
@@ -33,55 +33,123 @@
  */
 final class StubFilesExtension implements \PHPStan\PhpDoc\StubFilesExtension
 {
-    private const APPLICATION_TYPE_STUBS = [
-        Application::class => 'BaseYii.stub',
-        \yii\console\Application::class => 'BaseYiiConsole.stub',
-        \yii\web\Application::class => 'BaseYiiWeb.stub',
-    ];
-
-    private const DEFAULT_STUB = 'BaseYiiWeb.stub';
-
     /**
      * @param ServiceMap $serviceMap Service and component map for Yii Application static analysis.
      */
     public function __construct(private readonly ServiceMap $serviceMap) {}
 
     /**
-     * Retrieves the appropriate stub file path for PHPStan analysis based on the Yii Application type.
+     * Retrieves the dynamically generated stub file path for PHPStan analysis.
      *
-     * Determines the stub file to use for static analysis by inspecting the application type provided by the
-     * {@see ServiceMap} instance.
+     * Generates a stub file with the correct `@var` type annotation for `Yii::$app` based on the configured application
+     * type from the {@see ServiceMap} instance.
      *
-     * This enables PHPStan to reflect the correct set of Yii Application properties and methods for web, console, or
-     * base application contexts.
+     * @return array Array containing the absolute path to the generated stub file for PHPStan analysis.
      *
-     * @return string[] Array containing the absolute path to the resolved stub file for PHPStan analysis.
+     * @phpstan-return string[]
      */
     public function getFiles(): array
     {
-        $stubsDirectory = $this->getStubsDirectory();
-        $applicationType = $this->serviceMap->getApplicationType();
+        return [$this->generateStub($this->serviceMap->getApplicationType())];
+    }
+
+    /**
+     * Builds the application type class declaration block for the stub.
+     *
+     * Generates the necessary namespace and class declarations to satisfy PHPStan stub type resolution for the
+     * configured application type. Includes the base `\yii\base\Application` declaration and, if the configured type
+     * differs, an additional declaration for the specific application class.
+     *
+     * @param string $applicationType Fully qualified class name of the application type (without leading backslash).
+     *
+     * @return string PHP namespace block declarations for the stub file.
+     */
+    private function buildApplicationTypeDeclaration(string $applicationType): string
+    {
+        $baseDeclaration = <<<PHP
+        namespace yii\base {
+            abstract class Application {}
+        }
+        PHP;
 
-        $stubFileName = self::APPLICATION_TYPE_STUBS[$applicationType] ?? self::DEFAULT_STUB;
-        $stubFilePath = $stubsDirectory . DIRECTORY_SEPARATOR . $stubFileName;
+        if ($applicationType === Application::class) {
+            return $baseDeclaration;
+        }
 
-        return [$stubFilePath];
+        $lastSeparator = strrpos($applicationType, '\\');
+
+        if ($lastSeparator === false) {
+            $namespace = '';
+            $className = $applicationType;
+        } else {
+            $namespace = substr($applicationType, 0, $lastSeparator);
+            $className = substr($applicationType, $lastSeparator + 1);
+        }
+
+        $namespaceBlock = $namespace !== '' ? "namespace {$namespace}" : 'namespace';
+
+        return <<<PHP
+            {$baseDeclaration}
+
+            {$namespaceBlock} {
+                class {$className} extends \yii\base\Application {}
+            }
+            PHP;
     }
 
     /**
-     * Retrieves the absolute path to the stub files directory for PHPStan analysis.
+     * Generates a stub file for the specified application type.
      *
-     * Resolves the path to the `stub/` directory relative to the extension source directory, ensuring that stub files
-     * are correctly located regardless of the current working directory or environment.
+     * Creates a PHP stub that overrides the `BaseYii::$app` property type annotation to match the configured
+     * application type. Includes necessary class declarations for PHPStan stub type resolution. The stub is written to
+     * a deterministic temporary file path based on the application type hash, providing natural caching across PHPStan
+     * runs.
      *
-     * This method is used internally to construct absolute paths for stub file resolution in static analysis.
+     * @param string $applicationType Fully qualified class name of the application type.
      *
-     * @return string Absolute path to the stub files directory.
+     * @throws RuntimeException If the stub file can't be written to the temporary directory.
+     *
+     * @return string Absolute path to the generated stub file.
      */
-    private function getStubsDirectory(): string
+    private function generateStub(string $applicationType): string
     {
         $ds = DIRECTORY_SEPARATOR;
 
-        return dirname(__DIR__) . "{$ds}stub";
+        $stubPath = sys_get_temp_dir() . "{$ds}yii2-phpstan-stub-" . md5($applicationType) . '.stub';
+
+        if (file_exists($stubPath)) {
+            return $stubPath;
+        }
+
+        $escapedType = ltrim($applicationType, '\\');
+        $typeDeclaration = $this->buildApplicationTypeDeclaration($escapedType);
+
+        $content = <<<PHP
+        <?php
+
+        {$typeDeclaration}
+
+        namespace yii {
+            class BaseYii
+            {
+                /**
+                 * @var \\{$escapedType}
+                 */
+                public static \$app;
+            }
+        }
+
+        namespace {
+            class Yii extends \yii\BaseYii {}
+        }
+        PHP;
+
+        if (file_put_contents($stubPath, $content) === false) {
+            throw new RuntimeException(
+                sprintf("Failed to write stub file to '%s'. Ensure the temporary directory is writable.", $stubPath),
+            );
+        }
+
+        return $stubPath;
     }
 }