feat: support add CmdHandler class to CliApp

Author: inhere

README.md

@@ -292,6 +292,7 @@ Create an multi commands application, run subcommand. see example file [example/
 use Toolkit\Cli\Cli;
 use Toolkit\PFlag\CliApp;
 use Toolkit\PFlag\FlagsParser;
+use Toolkit\PFlagTest\Cases\DemoCmdHandler;
 
 $app = new CliApp();
 
@@ -322,6 +323,8 @@ $app->add('test2', function (FlagsParser $fs) {
 // fn - required php 7.4+
 $app->add('show-err', fn() => throw new RuntimeException('test show exception'));
 
+$app->addHandler(DemoCmdHandler::class);
+
 $app->run();
 ```
 

example/cliapp.php

@@ -3,6 +3,7 @@
 use Toolkit\Cli\Cli;
 use Toolkit\PFlag\CliApp;
 use Toolkit\PFlag\FlagsParser;
+use Toolkit\PFlagTest\Cases\DemoCmdHandler;
 
 require dirname(__DIR__) . '/test/bootstrap.php';
 
@@ -37,5 +38,7 @@
 
 $app->add('show-err', fn() => throw new RuntimeException('test show exception'));
 
+$app->addHandler(DemoCmdHandler::class);
+
 $app->run();
 

src/CliApp.php

@@ -8,7 +8,10 @@
 use Throwable;
 use Toolkit\Cli\Cli;
 use Toolkit\Cli\Color;
+use Toolkit\PFlag\Contract\CmdHandlerInterface;
 use Toolkit\Stdlib\Arr;
+use Toolkit\Stdlib\Helper\Assert;
+use Toolkit\Stdlib\Helper\Valid;
 use Toolkit\Stdlib\Obj\Traits\AutoConfigTrait;
 use function array_merge;
 use function array_shift;
@@ -61,12 +64,14 @@ class CliApp
     /**
      * @var FlagsParser
      */
-    protected FlagsParser|SFlags $flags;
+    protected FlagsParser $flags;
 
     /**
+     * Flags for current run command
+     *
      * @var FlagsParser|null
      */
-    protected ?FlagsParser $cmdFlags;
+    protected ?FlagsParser $cmdFlags = null;
 
     /**
      * @var string
@@ -358,6 +363,27 @@ public function add(string $command, callable $handler, array $config = []): voi
         $this->addCommand($command, $handler, $config);
     }
 
+    /**
+     * @param class-string|CmdHandlerInterface $handler
+     */
+    public function addHandler(string|CmdHandlerInterface $handler): void
+    {
+        if (is_string($handler)) {
+            // class string.
+            if (class_exists($handler)) {
+                $handler = new $handler;
+                Assert::isTrue($handler instanceof CmdHandlerInterface, 'must be an class and instance of CmdHandlerInterface');
+            } else {
+                throw new InvalidArgumentException('must be an class string');
+            }
+        }
+
+        $config  = $handler->metadata();
+        $command = Valid::arrayHasNoEmptyKey($config, 'name');
+
+        $this->addCommand($command, $handler, $config);
+    }
+
     /**
      * @param string $command
      * @param callable|object|class-string $handler

src/CliCmd.php

@@ -2,7 +2,6 @@
 
 namespace Toolkit\PFlag;
 
-use InvalidArgumentException;
 use RuntimeException;
 use Throwable;
 use Toolkit\Stdlib\Obj\Traits\AutoConfigTrait;
@@ -27,7 +26,7 @@ class CliCmd
     /**
      * @var FlagsParser
      */
-    private FlagsParser|SFlags $flags;
+    private FlagsParser $flags;
 
     /**
      * @var callable(FlagsParser): mixed
@@ -102,7 +101,7 @@ protected function prepare(FlagsParser $fs): void
     }
 
     /**
-     * @return int|mixed
+     * @return mixed
      */
     public function run(): mixed
     {

src/Contract/CmdHandlerInterface.php

@@ -0,0 +1,34 @@
+<?php declare(strict_types=1);
+
+namespace Toolkit\PFlag\Contract;
+
+use Toolkit\PFlag\CliApp;
+use Toolkit\PFlag\FlagsParser;
+
+/**
+ * interface CmdHandlerInterface
+ *
+ * @author inhere
+ */
+interface CmdHandlerInterface
+{
+    /**
+     * @return array{name:string, desc: string, example:string, help: string}
+     */
+    public function metadata(): array;
+
+    /**
+     * @param FlagsParser $fs
+     *
+     * @return void
+     */
+    public function configure(FlagsParser $fs): void;
+
+    /**
+     * @param FlagsParser $fs
+     * @param CliApp $app
+     *
+     * @return mixed
+     */
+    public function execute(FlagsParser $fs, CliApp $app): mixed;
+}

test/Cases/DemoCmdHandler.php

@@ -0,0 +1,51 @@
+<?php declare(strict_types=1);
+
+namespace Toolkit\PFlagTest\Cases;
+
+use Toolkit\PFlag\CliApp;
+use Toolkit\PFlag\Contract\CmdHandlerInterface;
+use Toolkit\PFlag\FlagsParser;
+use function vdump;
+
+/**
+ * class DemoCmdHandler
+ *
+ * @author inhere
+ */
+class DemoCmdHandler implements CmdHandlerInterface
+{
+    /**
+     * @return array{name:string, desc: string, example:string, help: string}
+     */
+    public function metadata(): array
+    {
+        return [
+            'name' => 'demo',
+            'desc' => 'desc for demo command handler',
+        ];
+    }
+
+    /**
+     * @param FlagsParser $fs
+     *
+     * @return void
+     */
+    public function configure(FlagsParser $fs): void
+    {
+        $fs->addOptsByRules([
+            'opt1' => 'string;a string opt1 for command test2, and is required;true',
+            'opt2' => 'int;a int opt2 for command test2',
+        ]);
+    }
+
+    /**
+     * @param FlagsParser $fs
+     * @param CliApp $app
+     *
+     * @return mixed
+     */
+    public function execute(FlagsParser $fs, CliApp $app): mixed
+    {
+        vdump(__METHOD__);
+    }
+}

test/RuleParser.php test/Cases/RuleParser.php

@@ -1,6 +1,6 @@
 <?php declare(strict_types=1);
 
-namespace Toolkit\PFlagTest;
+namespace Toolkit\PFlagTest\Cases;
 
 use Toolkit\PFlag\Concern\RuleParserTrait;
 

test/CliAppTest.php

@@ -3,6 +3,7 @@
 namespace Toolkit\PFlagTest;
 
 use Toolkit\PFlag\CliApp;
+use Toolkit\PFlagTest\Cases\DemoCmdHandler;
 use Toolkit\Stdlib\Obj\DataObject;
 
 /**
@@ -17,10 +18,7 @@ private function initApp(CliApp $app): DataObject
         $buf = DataObject::new();
 
         // php 7.4+
-        // $app->add('test1', fn() => $buf->set('key', 'in test1'));
-        $app->add('test1', function () use ($buf) {
-            $buf->set('key', 'in test1');
-        });
+        $app->add('test1', fn() => $buf->set('key', 'in test1'));
 
         $app->addCommands([
             'test2' => [
@@ -35,6 +33,8 @@ private function initApp(CliApp $app): DataObject
             ],
         ]);
 
+        $app->addHandler(DemoCmdHandler::class);
+
         return $buf;
     }
 
@@ -52,6 +52,7 @@ public function testCliApp_basic(): void
 
         $this->assertTrue($app->hasCommand('test1'));
         $this->assertTrue($app->hasCommand('test2'));
+        $this->assertTrue($app->hasCommand('demo'));
 
         $app->runByArgs(['test1']);
         $this->assertEquals('in test1', $buf->get('key'));

test/Concern/RuleParserTest.php

@@ -3,8 +3,7 @@
 namespace Toolkit\PFlagTest\Concern;
 
 use Toolkit\PFlagTest\BaseFlagsTestCase;
-use Toolkit\PFlagTest\RuleParser;
-use function vdump;
+use Toolkit\PFlagTest\Cases\RuleParser;
 
 /**
  * class RuleParserTest

test/FlagsTest.php

@@ -13,8 +13,6 @@
 use Toolkit\PFlag\Flags;
 use Toolkit\PFlag\Flag\Option;
 use Toolkit\PFlag\FlagType;
-use function edump;
-use function vdump;
 
 /**
  * Class FlagsTest