feat: writes a key/value set to two columns in a row

README.md

@@ -583,36 +583,55 @@ $writer->table([
 ]);
 ```
 
+#### Two columns detail (Display setting)
+
+If you want to display certain configurations (from your .env file for example) a bit like Laravel does (via the php artisan `about` command) you can use the `twoColumnDetail` method.
+
+```php
+$writer->twoColumnDetail('Environment');
+$writer->twoColumnDetail('PHP Version', PHP_VERSION);
+$writer->twoColumnDetail('App Version', '1.0.0');
+$writer->twoColumnDetail('Locale', 'en');
+```
+
 Gives something like:
 
 ```
-+--------+------+------+
-| A      | B C  | C D  |
-+--------+------+------+
-| apple  | ball | cat  |
-| applet | bee  | cute |
-+--------+------+------+
+Environment ........................................
+PHP Version .................................. 8.1.4
+App Version .................................. 1.0.0
+Locale .......................................... en
 ```
 
-> Designing table look and feel
+You can use the `sep` parameter to define the separator to use.
 
-Just pass 2nd param `$styles`:
+```php
+$writer->twoColumnDetail('Environment', '', ['sep' => '-']);
+$writer->twoColumnDetail('PHP Version', PHP_VERSION);
+```
+
+Gives something like:
+
+```
+Environment ----------------------------------------
+PHP Version .................................. 8.1.4
+```
+
+In addition, the text color, the background color and the thickness of the two texts can be defined via the 3rd argument of this method.
 
 ```php
-$writer->table([
-    ['a' => 'apple', 'b-c' => 'ball', 'c_d' => 'cat'],
-    ['a' => 'applet', 'b-c' => 'bee', 'c_d' => 'cute'],
-], [
-    // for => styleName (anything that you would call in $writer instance)
-    'head' => 'boldGreen', // For the table heading
-    'odd'  => 'bold',      // For the odd rows (1st row is odd, then 3, 5 etc)
-    'even' => 'comment',   // For the even rows (2nd row is even, then 4, 6 etc)
+$writer->twoColumnDetail('Cache Enable', 'true', [
+    'first' => ['fg' => Ahc\Cli\Output\Color::CYAN], // style of the key
+    'second' => ['fg' => Ahc\Cli\Output\Color::GREEN], // style of the value
+]);
+$writer->twoColumnDetail('Debug Mode', 'false', [
+    'first' => ['fg' => Ahc\Cli\Output\Color::CYAN], // style of the key
+    'second' => ['fg' => Ahc\Cli\Output\Color::RED], // style of the value
 ]);
-
-// 'head', 'odd', 'even' are all the styles for now
-// In future we may support styling a column by its name!
 ```
 
+For more details regarding the different color options, see [Custom style](#custom-style)
+
 #### Reader
 
 Read and pre process user input.

src/Helper/Arr.php

@@ -0,0 +1,65 @@
+<?php
+
+/*
+ * This file is part of the PHP-CLI package.
+ *
+ * (c) Jitendra Adhikari <[email protected]>
+ *     <https://github.com/adhocore>
+ *
+ * Licensed under MIT license.
+ */
+
+namespace Ahc\Cli\Helper;
+
+use function current;
+use function func_get_args;
+use function is_array;
+use function is_int;
+use function next;
+
+/**
+ * helper specializing in table manipulation
+ *
+ * @author  Dimitri Sitchet Tomkeu <[email protected]>
+ * @license MIT
+ *
+ * @link    https://github.com/adhocore/cli
+ */
+class Arr
+{
+    /**
+     * This function can be thought of as a hybrid between PHP's `array_merge` and `array_merge_recursive`.
+     *
+     * The difference between this method and the built-in ones, is that if an array key contains another array, then
+     * Hash::merge() will behave in a recursive fashion (unlike `array_merge`). But it will not act recursively for
+     * keys that contain scalar values (unlike `array_merge_recursive`).
+     *
+     * Note: This function will work with an unlimited amount of arguments and typecasts non-array parameters into arrays.
+     *
+     * @param array $data  Array to be merged
+     * @param mixed $merge Array to merge with. The argument and all trailing arguments will be array cast when merged
+     *
+     * @return array Merged array
+     *
+     * @credit CakePHP - http://book.cakephp.org/2.0/en/core-utility-libraries/hash.html#Hash::merge
+     */
+    public static function merge(array $data, $merge)
+    {
+        $args   = func_get_args();
+        $return = current($args);
+
+        while (($arg = next($args)) !== false) {
+            foreach ((array) $arg as $key => $val) {
+                if (! empty($return[$key]) && is_array($return[$key]) && is_array($val)) {
+                    $return[$key] = self::merge($return[$key], $val);
+                } elseif (is_int($key) && isset($return[$key])) {
+                    $return[] = $val;
+                } else {
+                    $return[$key] = $val;
+                }
+            }
+        }
+
+        return $return;
+    }
+}

src/Output/ProgressBar.php

@@ -96,7 +96,7 @@ public function __construct(?int $total = null, ?Writer $writer = null)
 
         $this->writer   = $writer ?: new Writer();
         $this->cursor   = $this->writer->cursor();
-        $this->terminal = new Terminal();
+        $this->terminal = $this->writer->terminal();
     }
 
     /**

src/Output/Writer.php

@@ -11,12 +11,16 @@
 
 namespace Ahc\Cli\Output;
 
+use Ahc\Cli\Helper\Arr;
+use Ahc\Cli\Helper\Terminal;
+
 use function fopen;
 use function fwrite;
 use function max;
 use function method_exists;
 use function str_repeat;
 use function stripos;
+use function strlen;
 use function strpos;
 use function ucfirst;
 
@@ -183,6 +187,8 @@ class Writer
 
     protected Cursor $cursor;
 
+    protected Terminal $terminal;
+
     public function __construct(string $path = null, Color $colorizer = null)
     {
         if ($path) {
@@ -194,6 +200,7 @@ public function __construct(string $path = null, Color $colorizer = null)
 
         $this->cursor    = new Cursor;
         $this->colorizer = $colorizer ?? new Color;
+        $this->terminal  = new Terminal();
     }
 
     /**
@@ -212,6 +219,14 @@ public function cursor(): Cursor
         return $this->cursor;
     }
 
+    /**
+     * Get Terminal.
+     */
+    public function terminal(): Terminal
+    {
+        return $this->terminal;
+    }
+
     /**
      * Magically set methods.
      *
@@ -288,6 +303,42 @@ public function table(array $rows, array $styles = []): self
         return $this->colors($table);
     }
 
+    /**
+     * writes a key/value set to two columns in a row
+     *
+     * @example PHP Version ............................................................. 8.1.4
+     *
+     * @param string $first The text to write in left side
+     * @param string|null $second The text to write in right side
+     * @param array $options Options to use when writing Eg: ['fg' => Color::GREEB, 'bold' => 1, 'sep' => '-']
+     *
+     * @return self
+     */
+    public function twoColumnDetail(string $first, ?string $second = null, array $options = []): self
+    {
+        $options = Arr::merge([
+            'first'  => ['bg' => null, 'fg' => Color::WHITE, 'bold' => 0],
+            'second' => ['bg' => null, 'fg' => Color::WHITE, 'bold' => 1],
+            'sep'    => '.',
+        ], $options);
+
+        $second   = (string) $second;
+
+        $dashWidth  = $this->terminal->width() - (strlen($first) + strlen($second));
+        // remove left and right margins because we're going to add 1 space on each side (after/before the text).
+        // if we don't have a second element, we just remove the left margin
+        $dashWidth -= $second === '' ? 1 : 2;
+
+        $first = $this->colorizer->line($first, $options['first']);
+        if ($second !== '') {
+            $second = $this->colorizer->line($second, $options['second']);
+        }
+
+        $this->write($first . ' ' . str_repeat((string) $options['sep'], $dashWidth) . ' ' . $second);
+
+        return $this->eol();
+    }
+
     /**
      * Write to stdout or stderr magically.
      *

tests/Output/WriterTest.php

@@ -11,6 +11,7 @@
 
 namespace Ahc\Cli\Test\Output;
 
+use Ahc\Cli\Helper\Terminal;
 use Ahc\Cli\Output\Color;
 use Ahc\Cli\Output\Writer;
 use Ahc\Cli\Test\CliTestCase;
@@ -111,4 +112,24 @@ public function test_colorizer()
     {
         $this->assertInstanceOf(Color::class, (new Writer)->colorizer());
     }
+
+    public function test_terminal()
+    {
+        $this->assertInstanceOf(Terminal::class, (new Writer)->terminal());
+    }
+
+    public function test_two_column_detail()
+    {
+        $w = new Writer(static::$ou);
+
+        $w->twoColumnDetail('PHP Version', PHP_VERSION, [
+            'sep' => '-'
+        ]);
+
+        $buffer = trim($this->buffer());
+
+        $this->assertStringContainsString("PHP Version", $buffer);
+        $this->assertStringContainsString('---', $buffer);
+        $this->assertStringContainsString(PHP_VERSION, $buffer);
+    }
 }