Make $configPath optional in constructor ServiceMap class and update docs README.md. (#22)

Author: terabytesoftw

CHANGELOG.md

@@ -1,6 +1,8 @@
 # Change Log
 
-## 0.2.2 Under development
+## 0.2.2 June 04, 2025
+
+- Bug #22: Make `$configPath` optional in constructor `ServiceMap` class and update docs `README.md` (@terabytesoftw)
 
 ## 0.2.1 June 03, 2025
 

README.md

@@ -32,7 +32,7 @@ The preferred way to install this extension is through [composer](https://getcom
 
 Either run
 
-```shel
+```shell
 composer require --dev --prefer-dist yii2-extensions/phpstan:^0.2
 ```
 
@@ -44,33 +44,119 @@ or add
 
 ## Usage
 
+This extension provides enhanced static analysis for `Yii2` applications by adding:
+
+- **Container service resolution** with proper type inference.
+- **Dynamic method return types** for `ActiveRecord` and `ActiveQuery`.
+- **Header collection dynamic methods** support.
+- **Property reflection extensions** for `Application`, `Request`, `Response`, and `User` components.
+- **Service map integration** for dependency injection analysis.
+
+### Basic Configuration
+
 To use this extension, you need to add the following configuration to your `phpstan.neon` file:
 
 ```neon
 includes:
-	- vendor/yii2-extensions/phpstan/extension.neon
+    - vendor/yii2-extensions/phpstan/extension.neon
 
 parameters:
     bootstrapFiles:
         - tests/bootstrap.php
 
-    dynamicConstantNames:
-        - YII_DEBUG
-        - YII_ENV
-
     level: 5
 
     paths:
         - src
 
-    scanFiles:
-        - vendor/yiisoft/yii2/Yii.php
+    # Exclude paths from analysis
+    excludePaths:
+        - c3.php
+        - requirements.php
+        - config
+        - tests
+        - vendor
 
     yii2:
-        # Path to your Yii2 configuration file
+        # Path to your `Yii2` configuration file (optional)
+        # If not provided or empty, will work without explicit configuration 
         config_path: %currentWorkingDirectory%/config/test.php
 ```
 
+### Dynamic Constants Configuration
+
+The extension automatically recognizes common `Yii2` dynamic constants:
+
+- `YII_DEBUG`
+- `YII_ENV`
+- `YII_ENV_DEV`
+- `YII_ENV_PROD`
+- `YII_ENV_TEST`
+
+If you need to add additional dynamic constants, you can extend the configuration:
+
+```neon
+includes:
+    - vendor/yii2-extensions/phpstan/extension.neon
+
+parameters:
+    # Your existing dynamic constants will be merged with the extension's defaults
+    dynamicConstantNames:
+        - YII_DEBUG         # Already included by the extension
+        - YII_ENV           # Already included by the extension
+        - YII_ENV_DEV       # Already included by the extension
+        - YII_ENV_PROD      # Already included by the extension
+        - YII_ENV_TEST      # Already included by the extension
+        - MY_CUSTOM_CONSTANT
+        - ANOTHER_CONSTANT
+
+    yii2:
+        config_path: %currentWorkingDirectory%/config/test.php
+```
+
+**Note:** When you define `dynamicConstantNames` in your configuration, it **replaces** the extension's default
+constants. 
+To maintain the `Yii2` constants recognition, you must include them explicitly along with your custom constants, as
+shown above.
+
+### Advanced Configuration Example
+
+```neon
+includes:
+    - vendor/yii2-extensions/phpstan/extension.neon
+
+parameters:
+    level: 8
+    
+    paths:
+        - src
+        - controllers
+        - models
+        - widgets
+
+    excludePaths:
+        - src/legacy
+        - tests/_support
+        - vendor
+        
+    bootstrapFiles:
+        - config/bootstrap.php
+        - tests/bootstrap.php
+
+    # Complete dynamic constants list (extension defaults + custom)
+    dynamicConstantNames:
+        - YII_DEBUG
+        - YII_ENV
+        - YII_ENV_DEV
+        - YII_ENV_PROD
+        - YII_ENV_TEST
+        - APP_VERSION
+        - MAINTENANCE_MODE
+
+    yii2:
+        config_path: %currentWorkingDirectory%/config/web.php
+```
+
 ## Quality code
 
 [![phpstan-level](https://img.shields.io/badge/PHPStan%20level-9-blue)](https://github.com/yii2-extensions/phpstan/actions/workflows/static.yml)

extension.neon

@@ -1,13 +1,24 @@
 parameters:
+    dynamicConstantNames:
+        - YII_DEBUG
+        - YII_ENV
+        - YII_ENV_DEV
+        - YII_ENV_PROD
+        - YII_ENV_TEST
+
     yii2:
-        config_path: null
+        config_path: ''
+
     stubFiles:
         - stubs/BaseYii.stub
+        - vendor/yiisoft/yii2/Yii.php
 
 parametersSchema:
-	yii2: structure([
-		config_path: schema(string(), nullable())
-	])
+	yii2: structure(
+        [
+		    config_path: schema(string())
+	    ]
+    )
 
 services:
     -

src/ServiceMap.php

@@ -70,15 +70,16 @@ final class ServiceMap
     /**
      * Creates a new instance of the {@see ServiceMap} class.
      *
-     * @param string $configPath Path to the Yii application configuration file.
+     * @param string $configPath Path to the Yii application configuration file (default: `''`). If provided, the
+     * configuration file must exist and be valid. If empty or not provided, operates with empty service/component maps.
      *
      * @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)
+    public function __construct(string $configPath = '')
     {
-        if (file_exists($configPath) === false) {
+        if ($configPath !== '' && file_exists($configPath) === false) {
             throw new InvalidArgumentException(sprintf('Provided config path %s must exist', $configPath));
         }
 
@@ -87,7 +88,7 @@ public function __construct(string $configPath)
         defined('YII_ENV_PROD') || define('YII_ENV_PROD', false);
         defined('YII_ENV_TEST') || define('YII_ENV_TEST', true);
 
-        $config = require $configPath;
+        $config = $configPath !== '' ? require $configPath : [];
 
         foreach ($config['container']['singletons'] ?? [] as $id => $service) {
             $this->addServiceDefinition($id, $service);

tests/ServiceMapTest.php

@@ -122,6 +122,26 @@ public function testItLoadsServicesAndComponents(): void
         );
     }
 
+    /**
+     * @throws ReflectionException if the service definition is invalid or can't be resolved.
+     */
+    public function testItAllowsWithoutEmptyConfigPath(): void
+    {
+        $this->expectNotToPerformAssertions();
+
+        new ServiceMap();
+    }
+
+    /**
+     * @throws ReflectionException if the service definition is invalid or can't be resolved.
+     */
+    public function testItAllowsWithoutEmptyConfigPathStringValue(): void
+    {
+        $this->expectNotToPerformAssertions();
+
+        new ServiceMap('');
+    }
+
     /**
      * @throws ReflectionException if the service definition is invalid or can't be resolved.
      */