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

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

@@ -12,6 +12,7 @@
 use yii\base\{BaseObject, InvalidArgumentException};
 use yii\web\Application;
 
+use function array_key_exists;
 use function define;
 use function defined;
 use function file_exists;
@@ -54,7 +55,8 @@
  *   container?: array{
  *     definitions?: array<array-key, DefinitionType>,
  *     singletons?: array<array-key, DefinitionType>,
- *   }
+ *   },
+ *   params?: array<string, mixed>,
  * }
  *
  * @copyright Copyright (C) 2023 Terabytesoftw.
@@ -97,6 +99,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 +142,7 @@ public function __construct(string $configPath = '')
         $this->processBehaviors($config);
         $this->processComponents($config);
         $this->processDefinition($config);
+        $this->processParams($config);
         $this->processSingletons($config);
     }
 
@@ -237,6 +247,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 +329,10 @@ private function loadConfig(string $configPath): array
             $this->throwErrorWhenConfigFileIsNotArray($configPath, 'components');
         }
 
+        if (array_key_exists('params', $config) && 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 +544,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 +628,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 +648,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),
+        );
     }
 }