Add handy 'create' static methods for detectors and launcher classes.

Author: MagicPush

docs/todo.md

@@ -87,20 +87,6 @@ The list of plans and ideas for future development.
 <details>
 <summary>Points to consider</summary>
 
-1. - [ ] [features-manual.md](features-manual.md):
-    1. - [x] A comparison between "plain scripts" and "classes".
-        1. - [x] Start with a "summary" paragraph.
-    1. - [x] Launcher performance. Describe possible approaches (including the built-in caching mechanism).
-        1. - [x] Make a link to this from the comparison.
-    1. - [x] [execute-class.php](../tools/cli-toolkit/execute-class.php)
-    1. - [x] Built-in subcommands.
-        1. - [x] `list` as a default value.
-             No other parameters are processed correctly unless `list` is specified explicitly.
-        1. - [x] `ConfigBuilder::shortDescription()`
-    1. - [x] [Question.php](../src/Question/Question.php)
-    1. - [ ] (if relevant) Update comments generated in
-         [LauncherSkeleton.php](../tools/cli-toolkit/ScriptClasses/Generate/LauncherSkeleton.php)
-         with links to the manual.
 1. - [ ] FINISHING MOVES:
     1. - [x] Renaming, moving and other trivial refactoring:
         1. - [x] `../src/Parametizer/Script` -> `.../ScriptClass`
@@ -124,7 +110,8 @@ The list of plans and ideas for future development.
 
         - generating an empty `ConfigBuilder` instance "automatically" (mainly for temp scripts);
         - ~~making `getConfigBuilder()` non-static, creating `ConfigBuilder` instance inside `__construct()`.~~
-    1. - [ ] Make creating buildable instances (like detectors) with `create` static methods. 
+    1. - [x] Make creating buildable instances that are expected to be called by users (like detectors)
+         with `create` static methods. 
     1. - [ ] Consider adding even more [backward incompatibilities](todo.md#next-major-release) ~~or delaying
        the next major release, see [already implemented backward incompatibilities](changelog.md#v300)~~.
 
@@ -311,6 +298,20 @@ The list of plans and ideas for future development.
     1. - [ ] ~~Composer post install message with the generator launch command.~~
 
          ~~See https://getcomposer.org/doc/articles/scripts.md~~
+1. - [x] [features-manual.md](features-manual.md):
+    1. - [x] A comparison between "plain scripts" and "classes".
+        1. - [x] Start with a "summary" paragraph.
+    1. - [x] Launcher performance. Describe possible approaches (including the built-in caching mechanism).
+        1. - [x] Make a link to this from the comparison.
+    1. - [x] [execute-class.php](../tools/cli-toolkit/execute-class.php)
+    1. - [x] Built-in subcommands.
+        1. - [x] `list` as a default value.
+             No other parameters are processed correctly unless `list` is specified explicitly.
+        1. - [x] `ConfigBuilder::shortDescription()`
+    1. - [x] [Question.php](../src/Question/Question.php)
+    1. - [ ] ~~(if relevant) Update comments generated in
+         [LauncherSkeleton.php](../tools/cli-toolkit/ScriptClasses/Generate/LauncherSkeleton.php)
+         with links to the manual.~~
 </details>
 
 ## Next major release

src/Parametizer/ScriptClass/ScriptClassLauncher/ScriptClassLauncher.php

@@ -17,13 +17,19 @@ class ScriptClassLauncher {
     protected bool $throwOnException                 = false;
 
 
-    public function __construct(
-        protected readonly ScriptClassDetector $scriptClassDetector,
+    protected function __construct(protected readonly ScriptClassDetector $scriptClassDetector) { }
+
+    public static function create(
+        ScriptClassDetector $scriptClassDetector,
         ?ConfigBuilder $configBuilder = null,
-    ) {
+    ): static {
+        $launcher = new static($scriptClassDetector);
+
         if (null !== $configBuilder) {
-            $this->configBuilder = $configBuilder;
+            $launcher->configBuilder = $configBuilder;
         }
+
+        return $launcher;
     }
 
     /**
@@ -37,7 +43,7 @@ public function useParentEnvConfigForSubcommands(bool $isEnabled = true): static
 
     /**
      * Always affects subcommands. Also, affects main {@see ConfigBuilder} instance only if the latter is created
-     * automatically - if `null` (default value) is passed to {@see static::__construct()} as the relevant parameter.
+     * automatically - if `null` (default value) is passed to {@see static::__construct()}'s connected parameter.
      *
      * By default (without this method call), the corresponding internal property value is `false`.
      *

src/Parametizer/ScriptDetector/ScriptDetectorAbstract.php

@@ -24,10 +24,14 @@ abstract class ScriptDetectorAbstract {
     protected array $excludedDirectoryPaths = [];
 
 
+    protected function __construct(protected readonly bool $throwOnException) { }
+
     /**
      * @param bool $throwOnException Useful to debug issues with paths (read / write).
      */
-    public function __construct(protected readonly bool $throwOnException = true) { }
+    public static function create(bool $throwOnException = true): static {
+        return new static($throwOnException);
+    }
 
     public function cacheFilePath(?string $cacheFilePath): static {
         $cacheFilePathReal = null !== $cacheFilePath ? realpath($cacheFilePath) : false;

src/Parametizer/ScriptDetector/ScriptFileDetector.php

@@ -15,8 +15,8 @@ class ScriptFileDetector extends ScriptDetectorAbstract {
     protected const string SUBSTR_PARAMETIZER_CONSTRUCT = 'Parametizer::newConfig(';
     /** @see Parametizer::run() */
     protected const string SUBSTR_PARAMETIZER_EXEC = '->run()';
-    /** @see ScriptClassLauncher::__construct() */
-    protected const string SUBSTR_LAUNCHER_CONSTRUCT = 'ScriptClassLauncher(';
+    /** @see ScriptClassLauncher::create() */
+    protected const string SUBSTR_LAUNCHER_CONSTRUCT = 'ScriptClassLauncher::create(';
     /** @see ScriptClassLauncher::execute() */
     protected const string SUBSTR_LAUNCHER_EXEC = '->execute()';
 

tests/Tests/Parametizer/Completion/CompletionTest.php

@@ -391,7 +391,7 @@ public static function provideSubcommandSwitch(): array {
     /**
      * Tests completion affected by default subcommand switch value deeply in configs tree.
      *
-     * For now the only possible default subcommand is {@see ListSubcommands::getScriptName()}, it is hardcoded.
+     * For now, the only possible default subcommand is {@see ListSubcommands::getScriptName()}, it is hardcoded.
      * However if different default values are possible, we may test here any default value.
      *
      * @param string[] $expectedOutputLines

tests/Tests/Parametizer/ScriptClass/scripts/by-single-name.php

@@ -10,8 +10,8 @@
 $scriptClassName = $_SERVER['argv'][1];
 unset($_SERVER['argv'][1]);
 
-$scriptClassDetector = (new ScriptClassDetector(throwOnException: true))
+$scriptClassDetector = ScriptClassDetector::create(throwOnException: true)
     ->scriptClassName($scriptClassName);
-(new ScriptClassLauncher($scriptClassDetector))
+ScriptClassLauncher::create($scriptClassDetector)
     ->throwOnException()
     ->execute();

tests/Tests/Parametizer/ScriptClass/scripts/local-names.php

@@ -8,7 +8,7 @@
 use MagicPush\CliToolkit\Parametizer\ScriptDetector\ScriptClassDetector;
 
 /** @noinspection PhpFullyQualifiedNameUsageInspection */
-$scriptClassDetector = (new ScriptClassDetector(throwOnException: true))
+$scriptClassDetector = ScriptClassDetector::create(throwOnException: true)
     ->scriptClassNames([
         \MagicPush\CliToolkit\Tests\Tests\Parametizer\ScriptClass\ScriptClasses\LocalNames\lowercasename::class,
         \MagicPush\CliToolkit\Tests\Tests\Parametizer\ScriptClass\ScriptClasses\LocalNames\Uppercasename::class,
@@ -19,6 +19,6 @@
         \MagicPush\CliToolkit\Tests\Tests\Parametizer\ScriptClass\ScriptClasses\LocalNames\SomeABBRWord::class,
     ]);
 
-(new ScriptClassLauncher($scriptClassDetector))
+ScriptClassLauncher::create($scriptClassDetector)
     ->throwOnException()
     ->execute();

tests/Tests/Parametizer/ScriptClass/scripts/sections.php

@@ -8,14 +8,14 @@
 use MagicPush\CliToolkit\Parametizer\ScriptDetector\ScriptClassDetector;
 
 /** @noinspection PhpFullyQualifiedNameUsageInspection */
-$scriptClassDetector = (new ScriptClassDetector(throwOnException: true))
+$scriptClassDetector = ScriptClassDetector::create(throwOnException: true)
     ->scriptClassNames([
         \MagicPush\CliToolkit\Tests\Tests\Parametizer\ScriptClass\ScriptClasses\Sections\Single::class,
         \MagicPush\CliToolkit\Tests\Tests\Parametizer\ScriptClass\ScriptClasses\Sections\Double::class,
         \MagicPush\CliToolkit\Tests\Tests\Parametizer\ScriptClass\ScriptClasses\Sections\Triple::class,
         \MagicPush\CliToolkit\Tests\Tests\Parametizer\ScriptClass\ScriptClasses\Sections\Spaced::class,
     ]);
 
-(new ScriptClassLauncher($scriptClassDetector))
+ScriptClassLauncher::create($scriptClassDetector)
     ->throwOnException()
     ->execute();

tests/Tests/Parametizer/ScriptClassLauncher/SameEnvConfig/scripts/setting-parent-config-for-subcommands.php

@@ -14,7 +14,7 @@
 $cacheFilePath                 = $_SERVER['argv'][3];
 unset($_SERVER['argv'][1], $_SERVER['argv'][2], $_SERVER['argv'][3]);
 
-$scriptClassDetector = (new ScriptClassDetector(true))
+$scriptClassDetector = ScriptClassDetector::create(true)
     ->cacheFilePath($cacheFilePath)
     ->searchDirectory(__DIR__ . '/../ScriptClasses');
 
@@ -28,6 +28,6 @@
     $configBuilder = null;
 }
 
-(new ScriptClassLauncher($scriptClassDetector, $configBuilder))
+ScriptClassLauncher::create($scriptClassDetector, $configBuilder)
     ->useParentEnvConfigForSubcommands($isSameEnvConfigForSubcommands)
     ->execute();

tests/Tests/Parametizer/ScriptClassLauncher/ThrowOnException/setting-throw-on-exception.php

@@ -12,6 +12,6 @@
 
 // No ConfigBuilder instance must be specified to ensure `throwOnException` flag
 // is passed to the automatically created instance.
-(new ScriptClassLauncher((new ScriptClassDetector())->searchDirectory(__DIR__), configBuilder: null))
+ScriptClassLauncher::create(ScriptClassDetector::create()->searchDirectory(__DIR__), configBuilder: null)
     ->throwOnException($launcherThrowOnException)
     ->execute();