feat: add Yii::$app->params type inference from configuration for precise array shape typing.

Author: terabytesoftw

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - fix: update Rector command in `composer.json` to remove unnecessary 'src' argument.
 - feat: replace static stub files with dynamic stub generation for `Yii::$app` type inference, adding support for custom application types.
 - chore: remove `sync-metadata` script and `docs/development.md`, update documentation links.
+- feat: add `Yii::$app->params` type inference from configuration for precise array shape typing.
 
 ## 0.4.0 January 26, 2026
 

README.md

@@ -70,6 +70,12 @@ Create a PHPStan-specific config file (`config/phpstan-config.php`).
 declare(strict_types=1);
 
 return [
+    // Application params: enables precise type inference for Yii::$app->params
+    'params' => [
+        'turnstile.siteKey' => '',
+        'adminEmail' => 'admin@example.com',
+        'maxItems' => 100,
+    ],
     // PHPStan only: used by this extension for behavior property/method type inference
     'behaviors' => [
         app\models\User::class => [
@@ -136,6 +142,25 @@ if (Yii::$app->user->isGuest === false) {
 }
 ```
 
+#### Application params
+
+```php
+// Types are inferred from the values in your phpstan-config.php 'params' key
+
+// ✅ Typed as array{turnstile.siteKey: string, adminEmail: string, maxItems: int}
+$params = Yii::$app->params;
+
+// ✅ Typed as string
+$email = Yii::$app->params['adminEmail'];
+
+// ✅ Typed as int
+$maxItems = Yii::$app->params['maxItems'];
+
+// ✅ Nested arrays are also supported
+// 'nested' => ['db' => ['host' => 'localhost', 'port' => 3306]]
+$host = Yii::$app->params['nested']['db']['host']; // string
+```
+
 #### Behaviors
 
 ```php

composer.json

@@ -52,7 +52,7 @@
         "ecs": "./vendor/bin/ecs --fix",
         "rector": "./vendor/bin/rector process",
         "static": "./vendor/bin/phpstan --memory-limit=-1",
-        "tests": "./vendor/bin/phpunit"
+        "tests": "php -d memory_limit=-1 ./vendor/bin/phpunit"
     },
     "repositories": [
         {

src/ServiceMap.php

@@ -54,7 +54,8 @@
  *   container?: array{
  *     definitions?: array<array-key, DefinitionType>,
  *     singletons?: array<array-key, DefinitionType>,
- *   }
+ *   },
+ *   params?: array<string, mixed>,
  * }
  *
  * @copyright Copyright (C) 2023 Terabytesoftw.
@@ -97,6 +98,13 @@ final class ServiceMap
      */
     private array $componentsDefinitions = [];
 
+    /**
+     * Application params for PHPStan type inference.
+     *
+     * @phpstan-var array<string, mixed>
+     */
+    private array $params = [];
+
     /**
      * Service definitions map for Yii Application analysis.
      *
@@ -133,6 +141,7 @@ public function __construct(string $configPath = '')
         $this->processBehaviors($config);
         $this->processComponents($config);
         $this->processDefinition($config);
+        $this->processParams($config);
         $this->processSingletons($config);
     }
 
@@ -237,6 +246,19 @@ public function getComponentDefinitionById(string $id): array
         return is_array($definition) ? $definition : [];
     }
 
+    /**
+     * Retrieves the application params map for PHPStan type inference.
+     *
+     * Returns the `params` key-value pairs extracted from the Yii Application configuration file, enabling static
+     * analysis tools to infer precise array shape types for `Yii::$app->params` access.
+     *
+     * @return array<string, mixed> Params key-value pairs from configuration.
+     */
+    public function getParams(): array
+    {
+        return $this->params;
+    }
+
     /**
      * Retrieves the fully qualified class name of a Yii Service by its identifier.
      *
@@ -306,6 +328,10 @@ private function loadConfig(string $configPath): array
             $this->throwErrorWhenConfigFileIsNotArray($configPath, 'components');
         }
 
+        if (isset($config['params']) && is_array($config['params']) === false) {
+            $this->throwErrorWhenConfigFileIsNotArray($configPath, 'params');
+        }
+
         if (isset($config['container'])) {
             if (is_array($config['container']) === false) {
                 $this->throwErrorWhenConfigFileIsNotArray($configPath, 'container');
@@ -517,6 +543,23 @@ private function processDefinition(array $config): void
         }
     }
 
+    /**
+     * Processes application params from the Yii Application configuration array.
+     *
+     * Extracts the `params` section and stores it for type inference of `Yii::$app->params` array access.
+     *
+     * @param array $config Yii Application configuration array containing params definitions.
+     *
+     * @phpstan-import-type ServiceType from ServiceMap
+     * @phpstan-param ServiceType $config
+     */
+    private function processParams(array $config): void
+    {
+        if ($config !== []) {
+            $this->params = $config['params'] ?? [];
+        }
+    }
+
     /**
      * Processes singleton service definitions from the Yii Application configuration array.
      *
@@ -584,7 +627,9 @@ private function throwErrorWhenConfigFileIsNotArray(string ...$args): never
      */
     private function throwErrorWhenIsNotString(string ...$args): never
     {
-        throw new RuntimeException(sprintf("'%s': '%s' must be a 'string', got '%s'.", ...$args));
+        throw new RuntimeException(
+            sprintf("'%s': '%s' must be a 'string', got '%s'.", ...$args),
+        );
     }
 
     /**
@@ -602,6 +647,8 @@ private function throwErrorWhenIsNotString(string ...$args): never
      */
     private function throwErrorWhenUnsupportedDefinition(string $id): never
     {
-        throw new RuntimeException(sprintf("Unsupported definition for '%s'.", $id));
+        throw new RuntimeException(
+            sprintf("Unsupported definition for '%s'.", $id),
+        );
     }
 }

src/StubFilesExtension.php

@@ -7,11 +7,19 @@
 use RuntimeException;
 use yii\base\Application;
 
+use function array_keys;
 use function file_exists;
 use function file_put_contents;
 use function getmypid;
+use function implode;
+use function is_array;
+use function is_bool;
+use function is_float;
+use function is_int;
+use function is_string;
 use function ltrim;
 use function md5;
+use function preg_match;
 use function rename;
 use function sprintf;
 use function strrpos;
@@ -76,8 +84,14 @@ public function getFiles(): array
      */
     private function buildApplicationTypeDeclaration(string $applicationType): string
     {
+        $paramsProperty = $this->buildParamsPropertyDeclaration();
+
         $baseDeclaration = <<<PHP
         namespace yii\base {
+            class Module
+            {{$paramsProperty}
+            }
+
             abstract class Application {}
         }
         PHP;
@@ -107,6 +121,33 @@ class {$className} extends \yii\base\Application {}
             PHP;
     }
 
+    /**
+     * Builds the `$params` property declaration for the stub file.
+     *
+     * Generates a PHPDoc `@var` annotation with an array shape type inferred from the configured application params.
+     * Returns an empty string if no params are configured, allowing the native `array` type to remain unchanged.
+     *
+     * @return string PHP property declaration block with array shape annotation, or empty string if no params.
+     */
+    private function buildParamsPropertyDeclaration(): string
+    {
+        $params = $this->serviceMap->getParams();
+
+        if ($params === []) {
+            return '';
+        }
+
+        $typeString = $this->inferTypeString($params);
+
+        return <<<PHP
+
+                /**
+                 * @var {$typeString}
+                 */
+                public \$params;
+        PHP;
+    }
+
     /**
      * Builds the full stub content for the specified application type.
      *
@@ -178,9 +219,11 @@ private function generateStub(string $applicationType): string
             );
         }
 
-        // @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.
+        /**
+         * @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);
 
@@ -192,8 +235,81 @@ private function generateStub(string $applicationType): string
                 sprintf("Failed to write stub file to '%s'. Ensure the temporary directory is writable.", $stubPath),
             );
         }
-        // @codeCoverageIgnoreEnd
+        /** @codeCoverageIgnoreEnd */
 
         return $stubPath;
     }
+
+    /**
+     * Infers a PHPStan type string from a PHP value.
+     *
+     * Converts PHP scalar values and arrays to their corresponding PHPStan type annotation strings. Supports `string`,
+     * `int`, `float`, `bool`, `null`, associative arrays (array shapes), and list arrays.
+     *
+     * @param mixed $value PHP value to infer a type string from.
+     *
+     * @return string PHPStan type annotation string.
+     */
+    private function inferTypeString(mixed $value): string
+    {
+        if ($value === null) {
+            return 'null';
+        }
+
+        if (is_string($value)) {
+            return 'string';
+        }
+
+        if (is_int($value)) {
+            return 'int';
+        }
+
+        if (is_float($value)) {
+            return 'float';
+        }
+
+        if (is_bool($value)) {
+            return 'bool';
+        }
+
+        if (is_array($value)) {
+            if ($value === []) {
+                return 'array<mixed, mixed>';
+            }
+
+            $allStringKeys = true;
+
+            foreach (array_keys($value) as $k) {
+                if (is_string($k) === false) {
+                    $allStringKeys = false;
+
+                    break;
+                }
+            }
+
+            if ($allStringKeys) {
+                $entries = [];
+
+                foreach ($value as $k => $v) {
+                    /** @phpstan-var string $k */
+                    $formattedKey = preg_match('/^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$/', $k) === 1
+                        ? $k
+                        : "'$k'";
+                    $entries[] = $formattedKey . ': ' . $this->inferTypeString($v);
+                }
+
+                return 'array{' . implode(', ', $entries) . '}';
+            }
+
+            $entries = [];
+
+            foreach ($value as $v) {
+                $entries[] = $this->inferTypeString($v);
+            }
+
+            return 'array{' . implode(', ', $entries) . '}';
+        }
+
+        return 'mixed';
+    }
 }