From 66d9db17bc01ea5bb7175020c44ae60ab65a043c Mon Sep 17 00:00:00 2001
From: Maksim Spirkov <63721828+mspirkov@users.noreply.github.com>
Date: Wed, 29 Oct 2025 14:43:20 +0300
Subject: [PATCH] Fix #20650: Add PHPStan/Psalm annotations for
 `yii\di\Container`

---
 framework/CHANGELOG.md     |  1 +
 framework/di/Container.php | 26 +++++++++++++++++++++++++-
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/framework/CHANGELOG.md b/framework/CHANGELOG.md
index 2cf6732a63..e9c3fd225c 100644
--- a/framework/CHANGELOG.md
+++ b/framework/CHANGELOG.md
@@ -73,6 +73,7 @@ Yii Framework 2 Change Log
 - Bug #20639: Add missing generics in `yii\web` namespace (mspirkov)
 - Bug #20645: Add missing generics in `yii\helpers` and `yii\test` namespaces. Fix PHPDoc annotations in `ArrayAccessTrait` (mspirkov)
 - Bug #20640: Fix `@param` annotation for `$block` in `yii\console\Markdown::renderParagraph()` (mspirkov)
+- Enh #20650: Add PHPStan/Psalm annotations for `yii\di\Container` (mspirkov)
 - Bug #20654: Add missing generics in `yii\db` namespace. Fix PHPDoc annotations in `yii\db\ArrayExpression` (mspirkov)
 - Bug #20651: Add missing generics in `yii\filters` namespace (mspirkov)
 
diff --git a/framework/di/Container.php b/framework/di/Container.php
index 6ea68a19ba..4238dca4d5 100644
--- a/framework/di/Container.php
+++ b/framework/di/Container.php
@@ -124,6 +124,8 @@ class Container extends Component
     /**
      * @var array cached dependencies indexed by class/interface names. Each class name
      * is associated with a list of constructor parameter types or default values.
+     *
+     * @phpstan-var array<class-string, array<string, mixed>>
      */
     private $_dependencies = [];
     /**
@@ -386,10 +388,21 @@ class Container extends Component
      * @param array $config configurations to be applied to the new instance
      * @return object the newly created instance of the specified class
      * @throws NotInstantiableException If resolved to an abstract class or an interface (since 2.0.9)
+     *
+     * @template T of object
+     *
+     * @phpstan-param class-string<T> $class
+     * @psalm-param class-string<T> $class
+     *
+     * @phpstan-return T
+     * @psalm-return T
      */
     protected function build($class, $params, $config)
     {
-        /** @var ReflectionClass $reflection */
+        /**
+         * @var ReflectionClass $reflection
+         * @phpstan-var ReflectionClass<T> $reflection
+         */
         list($reflection, $dependencies) = $this->getDependencies($class);
 
         $addDependencies = [];
@@ -503,6 +516,14 @@ class Container extends Component
      * @param string $class class name, interface name or alias name
      * @return array the dependencies of the specified class.
      * @throws NotInstantiableException if a dependency cannot be resolved or if a dependency cannot be fulfilled.
+     *
+     * @template T of object
+     *
+     * @phpstan-param class-string<T> $class
+     * @psalm-param class-string<T> $class
+     *
+     * @phpstan-return array{ReflectionClass<T>, array<string, mixed>}
+     * @psalm-return array{ReflectionClass<T>, array<string, mixed>}
      */
     protected function getDependencies($class)
     {
@@ -590,6 +611,9 @@ class Container extends Component
      * @param ReflectionClass|null $reflection the class reflection associated with the dependencies
      * @return array the resolved dependencies
      * @throws InvalidConfigException if a dependency cannot be resolved or if a dependency cannot be fulfilled.
+     *
+     * @phpstan-param ReflectionClass<object>|null $reflection
+     * @psalm-param ReflectionClass<object>|null $reflection
      */
     protected function resolveDependencies($dependencies, $reflection = null)
     {