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

Author: terabytesoftw

.github/workflows/ecs.yml

@@ -19,3 +19,5 @@ permissions:
 jobs:
   easy-coding-standard:
     uses: yii2-framework/actions/.github/workflows/ecs.yml@v1
+    with:
+      php-version: '["8.3"]'

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,33 @@
 
 namespace yii2\extensions\phpstan;
 
+use RuntimeException;
 use yii\base\Application;
 
+use function file_exists;
+use function file_put_contents;
+use function getmypid;
+use function ltrim;
+use function md5;
+use function rename;
+use function sprintf;
+use function strrpos;
+use function substr;
+use function sys_get_temp_dir;
+use function unlink;
+
+use const DIRECTORY_SEPARATOR;
+use const LOCK_EX;
+
 /**
- * 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 atomically to a deterministic temporary file path, cached across PHPStan runs for the
+ * same content.
  *
  * @see ServiceMap for service and component map for Yii Application static analysis.
  *
@@ -33,55 +39,161 @@
  */
 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.
+     * @param string $stubDirectory Directory for generated stub files (default: system temporary directory).
      */
-    public function __construct(private readonly ServiceMap $serviceMap) {}
+    public function __construct(
+        private readonly ServiceMap $serviceMap,
+        private readonly string $stubDirectory = '',
+    ) {}
 
     /**
-     * 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;
+
+        if ($applicationType === Application::class) {
+            return $baseDeclaration;
+        }
+
+        $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;
+    }
+
+    /**
+     * Builds the full stub content for the specified application type.
+     *
+     * Assembles the PHP stub content including class declarations for PHPStan stub type resolution, the `BaseYii`
+     * class with the `$app` property type annotation, and the `Yii` class extending `BaseYii`.
+     *
+     * @param string $applicationType Fully qualified class name of the application type (without leading backslash).
+     *
+     * @return string Complete PHP stub file content.
+     */
+    private function buildStubContent(string $applicationType): string
+    {
+        $typeDeclaration = $this->buildApplicationTypeDeclaration($applicationType);
+
+        return <<<PHP
+        <?php
 
-        $stubFileName = self::APPLICATION_TYPE_STUBS[$applicationType] ?? self::DEFAULT_STUB;
-        $stubFilePath = $stubsDirectory . DIRECTORY_SEPARATOR . $stubFileName;
+        {$typeDeclaration}
 
-        return [$stubFilePath];
+        namespace yii {
+            class BaseYii
+            {
+                /**
+                 * @var \\{$applicationType}
+                 */
+                public static \$app;
+            }
+        }
+
+        namespace {
+            class Yii extends \yii\BaseYii {}
+        }
+        PHP;
     }
 
     /**
-     * Retrieves the absolute path to the stub files directory for PHPStan analysis.
+     * Generates a stub file for the specified application type.
+     *
+     * 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 cache key is
+     * derived from the generated content, preventing stale files after generator changes. The stub is written
+     * atomically using a temporary file and `rename()` to prevent concurrent PHPStan runs from reading half-written
+     * files.
      *
-     * 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.
+     * @param string $applicationType Fully qualified class name of the application type.
      *
-     * This method is used internally to construct absolute paths for stub file resolution in static analysis.
+     * @throws RuntimeException If the stub file can't be written to the temporary directory.
      *
-     * @return string Absolute path to the stub files directory.
+     * @return string Absolute path to the generated stub file.
      */
-    private function getStubsDirectory(): string
+    private function generateStub(string $applicationType): string
     {
-        $ds = DIRECTORY_SEPARATOR;
+        $escapedType = ltrim($applicationType, '\\');
+
+        $content = $this->buildStubContent($escapedType);
+
+        $directory = $this->stubDirectory !== '' ? $this->stubDirectory : sys_get_temp_dir();
+        $stubPath = $directory . DIRECTORY_SEPARATOR . 'yii2-phpstan-stub-' . md5($content) . '.stub';
+
+        if (file_exists($stubPath)) {
+            return $stubPath;
+        }
+
+        $temporaryPath = $stubPath . '.' . getmypid() . '.tmp';
+
+        if (@file_put_contents($temporaryPath, $content, LOCK_EX) === false) {
+            throw new RuntimeException(
+                sprintf("Failed to write stub file to '%s'. Ensure the temporary directory is writable.", $stubPath),
+            );
+        }
+
+        // @codeCoverageIgnoreStart
+        // atomic publish: rename within the same filesystem is atomic on POSIX. This fallback handles Windows (where
+        // rename fails if target exists) and other non-POSIX edge cases during concurrent PHPStan runs.
+        if (!@rename($temporaryPath, $stubPath)) {
+            @unlink($temporaryPath);
+
+            if (file_exists($stubPath)) {
+                return $stubPath;
+            }
+
+            throw new RuntimeException(
+                sprintf("Failed to write stub file to '%s'. Ensure the temporary directory is writable.", $stubPath),
+            );
+        }
+        // @codeCoverageIgnoreEnd
 
-        return dirname(__DIR__) . "{$ds}stub";
+        return $stubPath;
     }
 }