blob: 5e42a55ebad6d3dc6f89ab9a4912a30cbbb7053e (
plain)
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
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
# PHP-CLI
PHP-CLI is a simple library that helps with creating nice looking command line scripts.
It takes care of
- **option parsing**
- **help page generation**
- **automatic width adjustment**
- **colored output**
- **optional PSR3 compatibility**
It is lightweight and has **no 3rd party dependencies**. Note: this is for non-interactive scripts only. It has no readline or similar support.
[](https://travis-ci.org/splitbrain/php-cli)
## Installation
Use composer:
```php composer.phar require splitbrain/php-cli```
## Usage and Examples
Minimal example:
```php
#!/usr/bin/php
<?php
require __DIR__ . '/../vendor/autoload.php';
use splitbrain\phpcli\CLI;
use splitbrain\phpcli\Options;
class Minimal extends CLI
{
// register options and arguments
protected function setup(Options $options)
{
$options->setHelp('A very minimal example that does nothing but print a version');
$options->registerOption('version', 'print version', 'v');
}
// implement your code
protected function main(Options $options)
{
if ($options->getOpt('version')) {
$this->info('1.0.0');
} else {
echo $options->help();
}
}
}
// execute it
$cli = new Minimal();
$cli->run();
```
The basic usage is simple:
- create a class and ``extend splitbrain\phpcli\CLI``
- implement the ```setup($options)``` method and register options, arguments, commands and set help texts
- ``$options->setHelp()`` adds a general description
- ``$options->registerOption()`` adds an option
- ``$options->registerArgument()`` adds an argument
- ``$options->registerCommand()`` adds a sub command
- implement the ```main($options)``` method and do your business logic there
- ``$options->getOpts`` lets you access set options
- ``$options->getArgs()`` returns the remaining arguments after removing the options
- ``$options->getCmd()`` returns the sub command the user used
- instantiate your class and call ```run()``` on it
More examples can be found in the examples directory. Please refer to the [API docs](https://splitbrain.github.io/php-cli/)
for further info.
## Exceptions
By default the CLI class registers an exception handler and will print the exception's message to the end user and
exit the programm with a non-zero exit code. You can disable this behaviour and catch all exceptions yourself by
passing false to the constructor.
You can use the provided ``splitbrain\phpcli\Exception`` to signal any problems within your main code yourself. The
exceptions's code will be used as the exit code then.
Stacktraces will be printed on log level `debug`.
## Colored output
Colored output is handled through the ``Colors`` class. It tries to detect if a color terminal is available and only
then uses terminal colors. You can always suppress colored output by passing ``--no-colors`` to your scripts.
Disabling colors will also disable the emoticon prefixes.
Simple colored log messages can be printed by you using the convinence methods ``success()`` (green), ``info()`` (cyan),
``error()`` (red) or ``fatal()`` (red). The latter will also exit the programm with a non-zero exit code.
For more complex coloring you can access the color class through ``$this->colors`` in your script. The ``wrap()`` method
is probably what you want to use.
The table formatter allows coloring full columns. To use that mechanism pass an array of colors as third parameter to
its ``format()`` method. Please note that you can not pass colored texts in the second parameters (text length calculation
and wrapping will fail, breaking your texts).
## Table Formatter
The ``TableFormatter`` class allows you to align texts in multiple columns. It tries to figure out the available
terminal width on its own. It can be overwritten by setting a ``COLUMNS`` environment variable.
The formatter is used through the ``format()`` method which expects at least two arrays: The first defines the column
widths, the second contains the texts to fill into the columns. Between each column a border is printed (a single space
by default).
See the ``example/table.php`` for sample usage.
Columns width can be given in three forms:
- fixed width in characters by providing an integer (eg. ``15``)
- precentages by provifing an integer and a percent sign (eg. ``25%``)
- a single fluid "rest" column marked with an asterisk (eg. ``*``)
When mixing fixed and percentage widths, percentages refer to the remaining space after all fixed columns have been
assigned.
Space for borders is automatically calculated. It is recommended to always have some relative (percentage) or a fluid
column to adjust for different terminal widths.
The table formatter is used for the automatic help screen accessible when calling your script with ``-h`` or ``--help``.
## PSR-3 Logging
The CLI class is a fully PSR-3 compatible logger (printing colored log data to STDOUT and STDERR). This is useful when
you call backend code from your CLI that expects a Logger instance to produce any sensible status output while running.
To use this ability simply inherit from `splitbrain\phpcli\PSR3CLI` instead of `splitbrain\phpcli\CLI`, then pass `$this`
as the logger instance. Be sure you have the suggested `psr/log` composer package installed.
You can adjust the verbosity of your CLI tool using the `--loglevel` parameter. Supported loglevels are the PSR-3
loglevels and our own `success` level:
* debug
* info
* notice
* success
* warning
* error
* critical
* alert
* emergency
Convenience methods for all log levels are available. Placeholder interpolation as described in PSR-3 is available, too.
Messages from `warning` level onwards are printed to `STDERR` all below are printed to `STDOUT`.
The default log level of your script can be set by overwriting the `$logdefault` member.
See `example/logging.php` for an example.
|
