Add support for custom help screens

Author: kodie

README.md

@@ -175,6 +175,7 @@ class InitCommand extends Ahc\Cli\Input\Command
             ->argument('[arg2]', 'The Arg2')
             ->option('-a --apple', 'The Apple')
             ->option('-b --ball', 'The ball')
+            ->help('Custom help screen (if omitted one will be generated)')
             // Usage examples:
             ->usage(
                 // append details or explanation of given example with ` ## ` so they will be uniformly aligned when shown
@@ -243,6 +244,9 @@ $app->add(new OtherCommand, 'o');
 // Set logo
 $app->logo('Ascii art logo of your app');
 
+// Custom help screen
+$app->help('Custom help screen (if omitted one will be generated)');
+
 $app->handle($_SERVER['argv']); // if argv[1] is `i` or `init` it executes InitCommand
 ```
 

src/Application.php

@@ -52,6 +52,10 @@ class Application
     /** @var string Ascii art logo */
     protected string $logo = '';
 
+    /** @var string Custom help screen */
+    protected string $_help = '';
+
+    /** @var string Name of default command */
     protected string $default = '__default__';
 
     /** @var null|Interactor */
@@ -344,9 +348,41 @@ protected function aliasesFor(Command $command): array
     }
 
     /**
-     * Show help of all commands.
+     * Sets or gets the custom help screen contents.
+     *
+     * @param string|null $help
+     *
+     * @return string|self
+     */
+    public function help(?string $help = null): mixed
+    {
+        if (func_num_args() === 0) {
+          return $this->_help;
+        }
+
+        $this->_help = $help;
+
+        return $this;
+    }
+
+    /**
+     * Show custom help screen if one is set, otherwise shows the default one.
      */
     public function showHelp(): mixed
+    {
+        if ($help = $this->help()) {
+            $writer = $this->io()->writer();
+            $writer->write($help, true);
+            return ($this->onExit)();
+        }
+
+        return $this->showDefaultHelp();
+    }
+
+    /**
+     * Shows command help then aborts.
+     */
+    public function showDefaultHelp(): mixed
     {
         $writer = $this->io()->writer();
         $header = "{$this->name}, version {$this->version}";

src/Input/Command.php

@@ -52,6 +52,8 @@ class Command extends Parser implements Groupable
 
     protected ?string $_alias = null;
 
+    protected string $_help = '';
+
     private array $_events = [];
 
     private bool $_argVariadic = false;
@@ -291,9 +293,41 @@ protected function handleUnknown(string $arg, ?string $value = null): mixed
     }
 
     /**
-     * Shows command help then aborts.
+     * Sets or gets the custom help screen contents.
+     *
+     * @param string|null $help
+     *
+     * @return string|self
+     */
+    public function help(?string $help = null): mixed
+    {
+        if (func_num_args() === 0) {
+          return $this->_help;
+        }
+
+        $this->_help = $help;
+
+        return $this;
+    }
+
+    /**
+     * Show custom help screen if one is set, otherwise shows the default one.
      */
     public function showHelp(): mixed
+    {
+        if ($help = $this->help()) {
+            $writer = $this->io()->writer();
+            $writer->write($help, true);
+            return $this->emit('_exit', 0);
+        }
+
+        return $this->showDefaultHelp();
+    }
+
+    /**
+     * Shows command help then aborts.
+     */
+    public function showDefaultHelp(): mixed
     {
         $io     = $this->io();
         $helper = new OutputHelper($io->writer());

tests/ApplicationTest.php

@@ -147,6 +147,17 @@ public function test_help()
         $this->assertStringContainsString('stage change', $out);
     }
 
+    public function testCustomHelp()
+    {
+        $this->newApp('git', '0.0.2')
+          ->help('This should be my custom help screen')
+          ->parse(['git', '--help']);
+
+        $out = file_get_contents(static::$ou);
+
+        $this->assertStringContainsString('This should be my custom help screen', $out);
+    }
+
     public function test_action()
     {
         ($a = $this->newApp('git', '0.0.2'))

tests/Input/CommandTest.php

@@ -284,6 +284,13 @@ public function __construct($tester)
             }
         };
     }
+ 
+    public function test_custom_help()
+    {
+        $p = $this->newCommand();
+        $p->help('This should be my custom help screen');
+        $this->assertStringContainsString('This should be my custom help screen', $p->help());
+    }
 
     protected function newCommand(string $version = '0.0.1', string $desc = '', bool $allowUnknown = false, $app = null)
     {