Apply fixed Coderabbitai review.

terabytesoftw · terabytesoftw · commit 47125f8464bb · 2026-04-02T20:42:53.000-03:00
diff --git a/src/StubFilesExtension.php b/src/StubFilesExtension.php
@@ -9,12 +9,18 @@
 
 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 dynamic stub file generation for PHPStan analysis based on the configured Yii Application type.
@@ -23,8 +29,8 @@
  * 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.
  *
- * The generated stub is written to a deterministic temporary file path, cached across PHPStan runs for the same
- * application type.
+ * 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.
  *
@@ -35,8 +41,12 @@ final class StubFilesExtension implements \PHPStan\PhpDoc\StubFilesExtension
 {
     /**
      * @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 dynamically generated stub file path for PHPStan analysis.
@@ -98,33 +108,20 @@ class {$className} extends \yii\base\Application {}
     }
 
     /**
-     * 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 stub is written to
-     * a deterministic temporary file path based on the application type hash, providing natural caching across PHPStan
-     * runs.
+     * Builds the full stub content for the specified application type.
      *
-     * @param string $applicationType Fully qualified class name of the 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`.
      *
-     * @throws RuntimeException If the stub file can't be written to the temporary directory.
+     * @param string $applicationType Fully qualified class name of the application type (without leading backslash).
      *
-     * @return string Absolute path to the generated stub file.
+     * @return string Complete PHP stub file content.
      */
-    private function generateStub(string $applicationType): string
+    private function buildStubContent(string $applicationType): string
     {
-        $ds = DIRECTORY_SEPARATOR;
-
-        $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);
+        $typeDeclaration = $this->buildApplicationTypeDeclaration($applicationType);
 
-        $content = <<<PHP
+        return <<<PHP
         <?php
 
         {$typeDeclaration}
@@ -133,7 +130,7 @@ private function generateStub(string $applicationType): string
             class BaseYii
             {
                 /**
-                 * @var \\{$escapedType}
+                 * @var \\{$applicationType}
                  */
                 public static \$app;
             }
@@ -143,12 +140,59 @@ class BaseYii
             class Yii extends \yii\BaseYii {}
         }
         PHP;
+    }
+
+    /**
+     * 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.
+     *
+     * @param string $applicationType Fully qualified class name of the application type.
+     *
+     * @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 generateStub(string $applicationType): string
+    {
+        $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;
+            }
 
-        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),
             );
         }
+        // @codeCoverageIgnoreEnd
 
         return $stubPath;
     }
diff --git a/tests/StubFilesExtensionTest.php b/tests/StubFilesExtensionTest.php
@@ -5,10 +5,14 @@
 namespace yii2\extensions\phpstan\tests;
 
 use PHPUnit\Framework\TestCase;
+use RuntimeException;
 use yii2\extensions\phpstan\ServiceMap;
 use yii2\extensions\phpstan\StubFilesExtension;
 
 use function file_get_contents;
+use function glob;
+use function sys_get_temp_dir;
+use function unlink;
 
 /**
  * Unit tests for {@see StubFilesExtension} dynamic stub file generation.
@@ -18,6 +22,13 @@
  */
 final class StubFilesExtensionTest extends TestCase
 {
+    /**
+     * Tracked stub file paths generated during tests, cleaned up in tearDown.
+     *
+     * @phpstan-var string[]
+     */
+    private array $generatedStubs = [];
+
     public function testGeneratedStubIsCached(): void
     {
         $stubFilesExtension = new StubFilesExtension(new ServiceMap());
@@ -32,8 +43,54 @@ public function testGeneratedStubIsCached(): void
         );
     }
 
+    public function testGetFilesReturnsStubForBaseApplicationType(): void
+    {
+        $this->cleanGeneratedStubs();
+
+        $ds = DIRECTORY_SEPARATOR;
+        $configPath = __DIR__ . "{$ds}config{$ds}phpstan-base-app-config.php";
+
+        $stubFilesExtension = new StubFilesExtension(new ServiceMap($configPath));
+
+        $files = $stubFilesExtension->getFiles();
+
+        self::assertCount(
+            1,
+            $files,
+            'Should return exactly one stub file.',
+        );
+
+        $stubPath = $files[0] ?? null;
+
+        self::assertNotNull(
+            $stubPath,
+            "Stub file path should not be 'null'.",
+        );
+        self::assertFileExists(
+            $stubPath,
+            'Generated stub file should exist on disk.',
+        );
+
+        $stubContent = (string) file_get_contents($stubPath);
+
+        self::assertStringContainsString(
+            '@var \yii\base\Application',
+            $stubContent,
+            "Stub should declare 'Yii::\$app' as '\yii\base\Application' for base configuration.",
+        );
+        self::assertStringNotContainsString(
+            'class Application extends',
+            $stubContent,
+            'Stub should not declare a child application class for the base application type.',
+        );
+
+        $this->generatedStubs[] = $stubPath;
+    }
+
     public function testGetFilesReturnsStubForConsoleApplicationType(): void
     {
+        $this->cleanGeneratedStubs();
+
         $ds = DIRECTORY_SEPARATOR;
         $configPath = __DIR__ . "{$ds}config{$ds}phpstan-console-config.php";
 
@@ -62,10 +119,14 @@ public function testGetFilesReturnsStubForConsoleApplicationType(): void
             (string) file_get_contents($stubPath),
             "Stub should declare 'Yii::\$app' as '\yii\console\Application' for console configuration.",
         );
+
+        $this->generatedStubs[] = $stubPath;
     }
 
     public function testGetFilesReturnsStubForCustomApplicationType(): void
     {
+        $this->cleanGeneratedStubs();
+
         $ds = DIRECTORY_SEPARATOR;
         $configPath = __DIR__ . "{$ds}config{$ds}phpstan-custom-app-config.php";
 
@@ -95,10 +156,14 @@ public function testGetFilesReturnsStubForCustomApplicationType(): void
             "Stub should declare 'Yii::\$app' as '\yii2\extensions\phpstan\tests\support\stub\ApplicationCustom'"
             . ' for custom configuration.',
         );
+
+        $this->generatedStubs[] = $stubPath;
     }
 
     public function testGetFilesReturnsStubForDefaultApplicationType(): void
     {
+        $this->cleanGeneratedStubs();
+
         $stubFilesExtension = new StubFilesExtension(new ServiceMap());
 
         $files = $stubFilesExtension->getFiles();
@@ -124,10 +189,58 @@ public function testGetFilesReturnsStubForDefaultApplicationType(): void
             (string) file_get_contents($stubPath),
             "Stub should default to '\yii\web\Application' when no configuration is provided.",
         );
+
+        $this->generatedStubs[] = $stubPath;
+    }
+
+    public function testGetFilesReturnsStubForGlobalNamespaceApplicationType(): void
+    {
+        $this->cleanGeneratedStubs();
+
+        $ds = DIRECTORY_SEPARATOR;
+        $configPath = __DIR__ . "{$ds}config{$ds}phpstan-global-class-app-config.php";
+
+        $stubFilesExtension = new StubFilesExtension(new ServiceMap($configPath));
+
+        $files = $stubFilesExtension->getFiles();
+
+        self::assertCount(
+            1,
+            $files,
+            'Should return exactly one stub file.',
+        );
+
+        $stubPath = $files[0] ?? null;
+
+        self::assertNotNull(
+            $stubPath,
+            "Stub file path should not be 'null'.",
+        );
+        self::assertFileExists(
+            $stubPath,
+            'Generated stub file should exist on disk.',
+        );
+
+        $stubContent = (string) file_get_contents($stubPath);
+
+        self::assertStringContainsString(
+            '@var \GlobalApplication',
+            $stubContent,
+            "Stub should declare 'Yii::\$app' as '\GlobalApplication' for global namespace configuration.",
+        );
+        self::assertStringContainsString(
+            'class GlobalApplication extends \yii\base\Application {}',
+            $stubContent,
+            'Stub should declare the global namespace application class extending base Application.',
+        );
+
+        $this->generatedStubs[] = $stubPath;
     }
 
     public function testGetFilesReturnsStubForWebApplicationType(): void
     {
+        $this->cleanGeneratedStubs();
+
         $ds = DIRECTORY_SEPARATOR;
         $configPath = __DIR__ . "{$ds}config{$ds}phpstan-config.php";
 
@@ -156,5 +269,46 @@ public function testGetFilesReturnsStubForWebApplicationType(): void
             (string) file_get_contents($stubPath),
             "Stub should declare 'Yii::\$app' as '\yii\web\Application' for web configuration.",
         );
+
+        $this->generatedStubs[] = $stubPath;
+    }
+
+    public function testThrowExceptionWhenStubFileCannotBeWritten(): void
+    {
+        $ds = DIRECTORY_SEPARATOR;
+        $nonWritableDir = $ds . 'nonexistent' . $ds . 'directory' . $ds . 'path';
+
+        $stubFilesExtension = new StubFilesExtension(new ServiceMap(), $nonWritableDir);
+
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage('Ensure the temporary directory is writable.');
+
+        $stubFilesExtension->getFiles();
+    }
+
+    protected function tearDown(): void
+    {
+        foreach ($this->generatedStubs as $path) {
+            if (file_exists($path)) {
+                unlink($path);
+            }
+        }
+
+        $this->generatedStubs = [];
+    }
+
+    /**
+     * Removes all generated PHPStan stub files from the temporary directory.
+     */
+    private function cleanGeneratedStubs(): void
+    {
+        $ds = DIRECTORY_SEPARATOR;
+        $pattern = sys_get_temp_dir() . "{$ds}yii2-phpstan-stub-*.stub";
+
+        $files = glob($pattern);
+
+        foreach ($files !== false ? $files : [] as $file) {
+            unlink($file);
+        }
     }
 }
diff --git a/tests/config/phpstan-base-app-config.php b/tests/config/phpstan-base-app-config.php
@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+use yii\base\Application;
+
+return [
+    'phpstan' => [
+        'application_type' => Application::class,
+    ],
+];
diff --git a/tests/config/phpstan-global-class-app-config.php b/tests/config/phpstan-global-class-app-config.php
@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+return [
+    'phpstan' => [
+        'application_type' => 'GlobalApplication',
+    ],
+];
diff --git a/tests/custom/data/property/ApplicationPropertiesClassReflectionType.php b/tests/custom/data/property/ApplicationPropertiesClassReflectionType.php
