[1.x] Add output helpers, deprecate direct usage of them (#29)

* feat(output): add line helper

* feat(output): add question helper

* chore(io): introduce io trait

* feat(console): allow using the `handle()` method

* feat(output): add title and labeled title helpers

* chore: deprecate direct usage of output methods

* Create UPGRADE-2.0.md

UPGRADE-2.0.md

@@ -0,0 +1,17 @@
+# Upgrade from 1.x to 2.0
+
+## High impact changes
+
+- Replace direct usage out output helpers with a call to the `$this->outoput->methodName()`.
+
+```diff
+// Instead of
+- $this->info('Hello world'); // A single example, but all output helpers are affected
+
+// Use
++ $this->output->info('Hello world');
+```
+
+## Medium impact changes
+
+## Low impact changes

docs/README.md

@@ -31,6 +31,22 @@ class SendEmailCommand extends Command
 }
 ```
 
+You can also replace the `execute()` method with a `handle()` method:
+
+```php
+use Symblaze\Console\Command;
+use Symfony\Component\Console\Attribute\AsCommand;
+
+ #[ASCommand(name: 'send:email', description: 'Send a marketing email to a user')]
+class SendEmailCommand extends Command
+{
+    public function handle(): int
+    {
+        //...
+    }
+}
+```
+
 ## Defining command Inputs
 
 No need to override the `configure` method to define the command arguments. All you need to do is to add the
@@ -168,4 +184,5 @@ $this->output->warning('This is an info message');
 $this->output->note('This is an info message');
 $this->output->info('This is an info message');
 $this->output->caution('This is a line message');
+$this->output->question('This is a question message');
 ```

src/Command.php

@@ -4,8 +4,8 @@
 
 namespace Symblaze\Console;
 
-use Symblaze\Console\IO\Helper\InputTrait;
-use Symblaze\Console\IO\Helper\OutputTrait;
+use RuntimeException;
+use Symblaze\Console\IO\IOTrait;
 use Symblaze\Console\IO\Output;
 use Symfony\Component\Console\Command\Command as SymfonyCommand;
 use Symfony\Component\Console\Input\InputInterface;
@@ -18,8 +18,7 @@
  */
 abstract class Command extends SymfonyCommand
 {
-    use InputTrait;
-    use OutputTrait;
+    use IOTrait;
 
     protected InputInterface $input;
     protected Output $output;
@@ -42,6 +41,18 @@ public function run(InputInterface $input, OutputInterface $output): int
         return parent::run($input, $output);
     }
 
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        if (method_exists($this, 'handle')) {
+            $result = $this->handle();
+            assert(is_int($result), 'The handle method must return an integer.');
+
+            return $result;
+        }
+
+        throw new RuntimeException('Either the `handle()` method must be implemented or the `execute()` method must be overridden.');
+    }
+
     public function getInput(): InputInterface
     {
         return $this->input;

src/IO/Helper/InputTrait.php → src/IO/IOTrait.php

@@ -2,15 +2,28 @@
 
 declare(strict_types=1);
 
-namespace Symblaze\Console\IO\Helper;
+namespace Symblaze\Console\IO;
 
 /**
- * A collection of methods to interact with the input.
+ * @mixin Output
  *
  * @internal
  */
-trait InputTrait
+trait IOTrait
 {
+    public function __call(string $name, array $arguments): mixed
+    {
+        if (method_exists($this->output, $name)) {
+            trigger_deprecation(
+                'symblaze/console',
+                '1.2.0',
+                sprintf('The method "%s" is deprecated, use the output method directly.', $name)
+            );
+        }
+
+        return $this->output->$name(...$arguments);
+    }
+
     /**
      * Get the value of a command argument.
      */

src/IO/Output.php

@@ -13,7 +13,9 @@
 /**
  * The Symblaze output helper class.
  *
- * @internal - This class is for internal use only
+ * @internal  - This class is for internal use only
+ *
+ * @psalm-api - Provides a custom output helper for the console.
  */
 class Output extends SymfonyStyle
 {
@@ -87,6 +89,37 @@ public function caution(string|array $message): void
         $this->newLine();
     }
 
+    public function line(string $message, ?string $style = null): void
+    {
+        $styled = $style ? "<$style>$message</$style>" : $message;
+
+        $this->writeln($styled);
+    }
+
+    public function question(string|array $message): void
+    {
+        $this->write(sprintf('<fg=black;bg=cyan>? %s</>', $message));
+        $this->newLine();
+    }
+
+    public function title(string|array $message): void
+    {
+        $this->write(sprintf('<fg=default;bg=default;options=underscore> %s </>', $message));
+        $this->newLine();
+    }
+
+    public function labeledTitle(
+        string $label,
+        string $title,
+        string $labelStyle = 'fg=white;bg=green;options=bold',
+        string $labelPrefix = '➜ ',
+        string $labelSeparator = ' ',
+    ): void {
+        $this->write(sprintf('<%s>%s%s%s</>', $labelStyle, $labelPrefix, $label, $labelSeparator));
+        $this->write($title);
+        $this->newLine();
+    }
+
     private function autoPrependText(): void
     {
         $fetched = $this->bufferedOutput->fetch();

tests/Doubles/MyCommand.php

@@ -25,7 +25,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         return self::SUCCESS;
     }
 
-    public function __call(string $name, array $arguments)
+    public function __call(string $name, array $arguments): mixed
     {
         return parent::$name(...$arguments);
     }