From 70242b213be94911473373615ae9e250ebd6d6dc Mon Sep 17 00:00:00 2001 From: George Steel Date: Tue, 12 Sep 2023 07:52:35 +0100 Subject: [PATCH 1/4] Prepare v4 docs adding an empty migration guide Signed-off-by: George Steel --- docs/book/v4/console-helper.md | 126 +++++++++++++++++++++++++++++++++ docs/book/v4/migration.md | 5 ++ mkdocs.yml | 10 ++- 3 files changed, 138 insertions(+), 3 deletions(-) create mode 100644 docs/book/v4/console-helper.md create mode 100644 docs/book/v4/migration.md diff --git a/docs/book/v4/console-helper.md b/docs/book/v4/console-helper.md new file mode 100644 index 00000000..1920cfaf --- /dev/null +++ b/docs/book/v4/console-helper.md @@ -0,0 +1,126 @@ +# Console Helper + +Writing one-off scripts or vendor binaries for a package is often problematic: + +- You need to parse arguments manually. +- You need to send output to the console in a meaningful fashion: + - Using `STDOUT` for meaningful, expected output + - Using `STDERR` for error messages + - Ensuring any line breaks are converted to `PHP_EOL` + - Optionally, using console colors to provide context, which means: + - Detecting whether or not the console supports colors in the first place + - Providing appropriate escape sequences to produce color + +`Laminas\Stdlib\ConsoleHelper` helps to address the second major bullet point and +all beneath it in a minimal fashion. + +## Usage + +Typical usage is to instantiate a `ConsoleHelper`, and call one of its methods: + +```php +use Laminas\Stdlib\ConsoleHelper; + +$helper = new ConsoleHelper(); +$helper->writeLine('This is output'); +``` + +You can optionally pass a PHP stream resource to the constructor, which will be +used to determine whether or not color support is available: + +```php +$helper = new ConsoleHelper($stream); +``` + +By default, it assumes `STDOUT`, and tests against that. + +## Available methods + +`ConsoleHelper` provides the following methods. + +### colorize + +- `colorize(string $string) : string` + +`colorize()` accepts a formatted string, and will then apply ANSI color +sequences to them, if color support is detected. + +The following sequences are currently supported: + +- `...` will apply a green color sequence around the provided text. +- `...` will apply a red color sequence around the provided text. + +You may mix multiple sequences within the same stream. + +### write + +- `write(string $string, bool $colorize = true, resource $stream = STDOUT) : void` + +Emits the provided `$string` to the provided `$stream` (which defaults to +`STDOUT` if not provided). Any EOL sequences are convered to `PHP_EOL`. If +`$colorize` is `true`, the string is first passed to `colorize()` as well. + +### writeline + +- `writeLine(string $string, bool $colorize = true, resource $stream = STDOUT) : void` + +Same as `write()`, except it also appends a `PHP_EOL` sequence to the `$string`. + +### writeErrorMessage + +- `writeErrorMessage(string $message)` + +Wraps `$message` in an `` sequence, and passes it to +`writeLine()`, using `STDERR` as the `$stream`. + +## Example + +Below is an example class that accepts an argument list, and determines how and +what to emit. + +```php +namespace Foo; + +use Laminas\Stdlib\ConsoleHelper; + +class HelloWorld +{ + private $helper; + + public function __construct(ConsoleHelper $helper = null) + { + $this->helper = $helper ?: new ConsoleHelper(); + } + + public function __invoke(array $args) + { + if (! count($args)) { + $this->helper->writeErrorMessage('Missing arguments!'); + return; + } + + if (count($args) > 1) { + $this->helper->writeErrorMessage('Too many arguments!'); + return; + } + + $target = array_shift($args); + + $this->helper->writeLine(sprintf( + 'Hello %s', + $target + )); + } +} +``` + +## When to upgrade + +`ConsoleHelper` is deliberately simple, and assumes that your primary need for +console tooling is for output considerations. + +If you need to parse complex argument strings, we recommend using +[laminas-console](https://docs.laminas.dev/laminas-console/)/[zf-console](https://github.com/zfcampus/zf-console) +or [symfony/console](http://symfony.com/doc/current/components/console.html), +as these packages provide those capabilities, as well as far more colorization +and console feature detection facilities. diff --git a/docs/book/v4/migration.md b/docs/book/v4/migration.md new file mode 100644 index 00000000..d3f533f0 --- /dev/null +++ b/docs/book/v4/migration.md @@ -0,0 +1,5 @@ +# Migration Guide + +## From v3 to v4 + +Version 4 of `laminas-stdlib` contains a number of backwards incompatible changes. This guide is intended to help you upgrade from the version 3 series to version 4. diff --git a/mkdocs.yml b/mkdocs.yml index fa4ffa08..8cb8fb98 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,16 +5,20 @@ nav: - v3: - "Console Helper": v3/console-helper.md - Migration: v3/migration.md + - v4: + - "Console Helper": v4/console-helper.md + - Migration: v4/migration.md site_name: laminas-stdlib site_description: Laminas\Stdlib repo_url: 'https://github.com/laminas/laminas-stdlib' extra: project: Components - current_version: v3 + current_version: v4 versions: - v3 + - v4 plugins: - redirects: redirect_maps: - migration.md: v3/migration.md - console-helper.md: v3/console-helper.md + migration.md: v4/migration.md + console-helper.md: v4/console-helper.md From 23576b3100eee8123378368acd3c3313245b682b Mon Sep 17 00:00:00 2001 From: George Steel Date: Tue, 12 Sep 2023 10:21:07 +0100 Subject: [PATCH 2/4] Improve title MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Frank Brückner Signed-off-by: George Steel --- docs/book/v4/migration.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/book/v4/migration.md b/docs/book/v4/migration.md index d3f533f0..e45c2ccc 100644 --- a/docs/book/v4/migration.md +++ b/docs/book/v4/migration.md @@ -1,5 +1,3 @@ -# Migration Guide - -## From v3 to v4 +# Migration from Version 3 to 4 Version 4 of `laminas-stdlib` contains a number of backwards incompatible changes. This guide is intended to help you upgrade from the version 3 series to version 4. From 55259c28d4cf42c21f8e00fcdfad043ab217d7e7 Mon Sep 17 00:00:00 2001 From: George Steel Date: Tue, 12 Sep 2023 12:52:25 +0100 Subject: [PATCH 3/4] Move 3-4 migration docs to a subdirectory Signed-off-by: George Steel --- docs/book/v4/{migration.md => migration/v3-to-v4.md} | 0 mkdocs.yml | 5 +++-- 2 files changed, 3 insertions(+), 2 deletions(-) rename docs/book/v4/{migration.md => migration/v3-to-v4.md} (100%) diff --git a/docs/book/v4/migration.md b/docs/book/v4/migration/v3-to-v4.md similarity index 100% rename from docs/book/v4/migration.md rename to docs/book/v4/migration/v3-to-v4.md diff --git a/mkdocs.yml b/mkdocs.yml index 8cb8fb98..c416219e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,8 +6,9 @@ nav: - "Console Helper": v3/console-helper.md - Migration: v3/migration.md - v4: - - "Console Helper": v4/console-helper.md - - Migration: v4/migration.md + - "Console Helper": v4/console-helper.md + - Migration: + - "Migration from Version 3 to 4": v4/migration/v3-to-v4.md site_name: laminas-stdlib site_description: Laminas\Stdlib repo_url: 'https://github.com/laminas/laminas-stdlib' From c7fa4648b6c3ca20a8df6a7b27bcc8d53c3872a0 Mon Sep 17 00:00:00 2001 From: George Steel Date: Tue, 12 Sep 2023 16:43:21 +0100 Subject: [PATCH 4/4] Remove laminas-console recommendation Signed-off-by: George Steel --- docs/book/v4/console-helper.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/book/v4/console-helper.md b/docs/book/v4/console-helper.md index 1920cfaf..3c139109 100644 --- a/docs/book/v4/console-helper.md +++ b/docs/book/v4/console-helper.md @@ -120,7 +120,6 @@ class HelloWorld console tooling is for output considerations. If you need to parse complex argument strings, we recommend using -[laminas-console](https://docs.laminas.dev/laminas-console/)/[zf-console](https://github.com/zfcampus/zf-console) -or [symfony/console](http://symfony.com/doc/current/components/console.html), -as these packages provide those capabilities, as well as far more colorization +[symfony/console](http://symfony.com/doc/current/components/console.html), +as this package provides those capabilities, as well as far more colorization and console feature detection facilities.