fix: Update licenses, docs, configuration, and reflection/type logic. (#20)

Author: terabytesoftw

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## 0.2.1 Under development
 
+- Bug #20: Update licenses, docs, configuration, and reflection/type logic (@terabytesoftw)
+
 ## 0.2.0 June 02, 2025
 
 - Enh #12: Upgrade to `PHPStan` `2.1` (@glpzzz)

LICENSE

@@ -0,0 +1,25 @@
+Copyright © 2008 by Terabytesoftw (<https://github.com/terabytesoftw/>)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, 
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice, 
+  this list of conditions and the following disclaimer in the documentation 
+  and/or other materials provided with the distribution.
+* Neither the name of Yii Software nor the names of its contributors may be 
+  used to endorse or promote products derived from this software without 
+  specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

LICENSE.md

@@ -73,7 +73,7 @@ parameters:
 
 ## Quality code
 
-[![phpstan-level](https://img.shields.io/badge/PHPStan%20level-6-blue)](https://github.com/yii2-extensions/phpstan/actions/workflows/static.yml)
+[![phpstan-level](https://img.shields.io/badge/PHPStan%20level-9-blue)](https://github.com/yii2-extensions/phpstan/actions/workflows/static.yml)
 [![style-ci](https://github.styleci.io/repos/701347895/shield?branch=main)](https://github.styleci.io/repos/701347895?branch=main)
 
 ## Testing
@@ -86,7 +86,7 @@ parameters:
 
 ## License
 
-The MIT License. Please see [License File](LICENSE) for more information.
+BSD-3-Clause license. Please see [License File](LICENSE.md) for more information.
 
 ## Fork 
 

README.md

@@ -6,7 +6,7 @@
         "yii2",
         "phpstan"
     ],
-    "license": "mit",
+    "license": "BSD-3-Clause",
     "require": {
         "php": ">=8.1",
         "nikic/php-parser": "^4.1|^5.4.0",

composer.json

@@ -9,7 +9,7 @@ parameters:
         - '#Calling PHPStan\\Reflection\\Annotations\\AnnotationsPropertiesClassReflectionExtension\:\:(has|get)Property\(\) is not covered.+#'
         - '#Creating new PHPStan\\Reflection\\Dummy\\DummyPropertyReflection is not covered.+#'
 
-    level: 6
+    level: 9
 
     paths:
         - src

phpstan.neon

@@ -2,7 +2,7 @@
 <phpunit
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.2/phpunit.xsd"
-  bootstrap="vendor/autoload.php"
+  bootstrap="tests/bootstrap.php"
   cacheDirectory=".phpunit.cache"
   colors="true"
   executionOrder="depends,defects"
@@ -20,5 +20,9 @@
     <include>
       <directory suffix=".php">./src</directory>
     </include>
+    <exclude>
+      <directory suffix=".php">./src/reflection</directory>
+      <directory suffix=".php">./src/type</directory>
+    </exclude>
   </source>
 </phpunit>

phpunit.xml.dist

@@ -5,42 +5,80 @@
 namespace yii2\extensions\phpstan;
 
 use Closure;
-use InvalidArgumentException;
 use PhpParser\Node;
 use ReflectionException;
 use ReflectionFunction;
 use ReflectionNamedType;
 use RuntimeException;
-use yii\base\BaseObject;
+use yii\base\{BaseObject, InvalidArgumentException};
 
 use function class_exists;
 use function define;
 use function defined;
+use function file_exists;
 use function get_class;
 use function is_array;
 use function is_object;
 use function is_string;
 use function is_subclass_of;
 use function sprintf;
 
+/**
+ * Provides service and component class resolution for Yii application analysis in PHPStan.
+ *
+ * Integrates Yii's dependency injection and component configuration with PHPStan's static analysis, enabling accurate
+ * type inference, autocompletion, and service/component resolution for dynamic application services and components.
+ *
+ * This class parses the Yii application configuration to extract service and component definitions mapping service IDs
+ * and component IDs to their corresponding class names.
+ *
+ * It supports both singleton and definition-based service registration, as well as component configuration via arrays
+ * or instantiated objects.
+ *
+ * The implementation provides lookup methods for resolving the class name of a service or component by its ID, which
+ * are used by PHPStan reflection extensions to enable static analysis and IDE support for dynamic properties and
+ * dependency-injected services.
+ *
+ * Key features.
+ * - Handles both array and object component configuration.
+ * - Integrates with PHPStan reflection and type extensions for accurate analysis.
+ * - Maps service and component IDs to their fully qualified class names.
+ * - Parses Yii application config for service and component definitions.
+ * - Provides lookup methods for service and component class resolution by ID.
+ * - Supports singleton, definition, and closure-based service registration.
+ * - Throws descriptive exceptions for invalid or unsupported definitions.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 final class ServiceMap
 {
     /**
-     * @var string[]
+     * Service definitions map for Yii application analysis.
+     *
+     * @phpstan-var string[]
      */
     private array $services = [];
 
     /**
-     * @var array<string, string>
+     * Component definitions map for Yii application analysis.
+     *
+     * @phpstan-var array<string, string>
      */
     private array $components = [];
 
     /**
-     * @throws ReflectionException
+     * Creates a new instance of the {@see ServiceMap} class.
+     *
+     * @param string $configPath Path to the Yii application configuration file.
+     *
+     * @throws InvalidArgumentException If the provided config path doesn't exist.
+     * @throws ReflectionException If the service definitions can't be resolved or are invalid.
+     * @throws RuntimeException If the provided configuration path doesn't exist or is invalid.
      */
     public function __construct(string $configPath)
     {
-        if (!file_exists($configPath)) {
+        if (file_exists($configPath) === false) {
             throw new InvalidArgumentException(sprintf('Provided config path %s must exist', $configPath));
         }
 
@@ -50,6 +88,7 @@ public function __construct(string $configPath)
         defined('YII_ENV_TEST') || define('YII_ENV_TEST', true);
 
         $config = require $configPath;
+
         foreach ($config['container']['singletons'] ?? [] as $id => $service) {
             $this->addServiceDefinition($id, $service);
         }
@@ -61,49 +100,108 @@ public function __construct(string $configPath)
         foreach ($config['components'] ?? [] as $id => $component) {
             if (is_object($component)) {
                 $this->components[$id] = get_class($component);
+
                 continue;
             }
 
-            if (!is_array($component)) {
+            if (is_array($component) === false) {
                 throw new RuntimeException(
                     sprintf('Invalid value for component with id %s. Expected object or array.', $id),
                 );
             }
 
-            if (null !== $class = $component['class'] ?? null) {
-                $this->components[$id] = $class;
+            if (isset($component['class']) && is_string($component['class']) && $component['class'] !== '') {
+                $this->components[$id] = $component['class'];
             }
         }
     }
 
-    public function getServiceClassFromNode(Node $node): ?string
+    /**
+     * Registers a service definition in the service map for Yii application analysis.
+     *
+     * Adds a service definition to the internal service map resolving the fully qualified class name for the specified
+     * service ID.
+     *
+     * This method supports various service definition formats, including class names, arrays, closures, and integer
+     * identifiers, enabling accurate type inference and autocompletion for dependency injected services in PHPStan
+     * analysis.
+     *
+     * The method delegates the resolution of the service class to {@see guessServiceDefinition()} which determines the
+     * appropriate class name based on the provided service definition.
+     *
+     * This ensures compatibility with Yii's flexible service registration mechanisms and supports both singleton and
+     * definition-based services.
+     *
+     * @param string $id Service identifier to register in the service map.
+     * @param array|Closure|int|string $service Service definition in supported format.
+     *
+     * @throws ReflectionException if the service definition is invalid or can't be resolved.
+     *
+     * @phpstan-param array<mixed>|Closure|string|int $service
+     */
+    private function addServiceDefinition(string $id, array|string|Closure|int $service): void
     {
-        if ($node instanceof Node\Scalar\String_ && isset($this->services[$node->value])) {
-            return $this->services[$node->value];
-        }
-
-        return null;
+        $this->services[$id] = $this->guessServiceDefinition($id, $service);
     }
 
-    public function getComponentClassById(string $id): ?string
+    /**
+     * Retrieves the fully qualified class name of a Yii application component by its identifier.
+     *
+     * Looks up the component class name registered under the specified component ID in the internal component map.
+     *
+     * This method enables static analysis tools and IDEs to resolve the actual class type of dynamic application
+     * components for accurate type inference, autocompletion, and property reflection.
+     *
+     * @param string $id Component identifier to look up in the component map.
+     *
+     * @return string|null Fully qualified class name of the component, or `null` if not found.
+     */
+    public function getComponentClassById(string $id): string|null
     {
         return $this->components[$id] ?? null;
     }
 
     /**
-     * @throws ReflectionException
+     * Resolves the fully qualified class name of a service from a PHP-Parser AST node.
      *
-     * @phpstan-param array<mixed>|string|Closure|int $service
+     * Inspects the provided AST node to determine if it represents a string service identifier, and if so, look up
+     * the corresponding class name in the internal service map.
+     *
+     * This method enables static analysis tools and IDEs to infer the actual class type of services referenced by
+     * string IDs in Yii application code supporting accurate type inference, autocompletion, and dependency injection
+     * analysis.
+     *
+     * @param Node $node PHP-Parser AST node representing a service identifier.
+     *
+     * @return string|null Fully qualified class name of the service, or `null` if not found.
      */
-    private function addServiceDefinition(string $id, array|string|Closure|int $service): void
+    public function getServiceClassFromNode(Node $node): ?string
     {
-        $this->services[$id] = $this->guessServiceDefinition($id, $service);
+        if ($node instanceof Node\Scalar\String_ && isset($this->services[$node->value])) {
+            return $this->services[$node->value];
+        }
+
+        return null;
     }
 
     /**
-     * @throws ReflectionException
+     * Infers the fully qualified class name for a Yii service definition.
+     *
+     * Determines the class name associated with a service definition provided in various supported formats, including
+     * class name strings, configuration arrays, closures, or integer identifiers.
      *
-     * @phpstan-param array<mixed>|string|Closure|int $service
+     * This method enables static analysis tools and IDEs to resolve the actual class type of dependency injected
+     * services for accurate type inference, autocompletion, and service resolution in PHPStan analysis.
+     *
+     * @param string $id Service identifier being resolved.
+     * @param array|Closure|int|string $service Service definition in supported format.
+     *
+     * @throws ReflectionException if the service definition is invalid or can't be resolved.
+     * @throws RuntimeException if the service definition format is unsupported or missing required information.
+     *
+     * @return string Fully qualified class name of the resolved service.
+     *
+     * @phpstan-param array<mixed>|Closure|string|int $service
      */
     private function guessServiceDefinition(string $id, array|string|Closure|int $service): string
     {
@@ -113,22 +211,23 @@ private function guessServiceDefinition(string $id, array|string|Closure|int $se
 
         if ($service instanceof Closure || is_string($service)) {
             $returnType = (new ReflectionFunction($service))->getReturnType();
-            if (!$returnType instanceof ReflectionNamedType) {
+
+            if ($returnType instanceof ReflectionNamedType === false) {
                 throw new RuntimeException(sprintf('Please provide return type for %s service closure', $id));
             }
 
             return $returnType->getName();
         }
 
-        if (!is_array($service)) {
+        if (is_array($service) === false) {
             throw new RuntimeException(sprintf('Unsupported service definition for %s', $id));
         }
 
-        if (isset($service['class'])) {
+        if (isset($service['class']) && is_string($service['class']) && $service['class'] !== '') {
             return $service['class'];
         }
 
-        if (isset($service[0]['class'])) {
+        if (isset($service[0]['class']) && is_string($service[0]['class']) && $service[0]['class'] !== '') {
             return $service[0]['class'];
         }