1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
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:
- `<info>...</info>` will apply a green color sequence around the provided text.
- `<error>...</error>` 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 `<error></error>` 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(
'<info>Hello</info> %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.
|
