You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A simple helper library for writing console/CLI applications in PHP.
3
+
A small, dependency-free helper library for writing console / CLI applications in PHP — command routing, typed arguments, coloured output, interactive questions and a styleable ANSI table renderer.
4
4
5
-
Starting with **2.1**, this package also ships the ANSI-coloured table renderer that used to be distributed as the separate [`initphp/cli-table`](https://github.com/InitPHP/CLITable) package (now deprecated). See the [migration section](#migrating-from-initphpcli-table) below if you are coming from that package.
[](https://packagist.org/packages/initphp/console)
10
+
11
+
> Starting with **2.1** this package also ships the ANSI table renderer that used to be distributed as the separate [`initphp/cli-table`](https://github.com/InitPHP/CLITable) package (now deprecated). See [Migrating from `initphp/cli-table`](#migrating-from-initphpcli-table).
12
+
13
+
## Features
14
+
15
+
-**Command routing** — register commands as closures or as classes extending `Command`.
-**Typed arguments** — declare `--name` arguments with a type (`INT`, `FLOAT`, `BOOL`, …), a default and an optional/required flag; values are validated automatically.
18
+
-**Input parsing** — long arguments (`--name=value`), short options (`-v`, `-abc`, `-k=value`) and bare positional segments, with automatic scalar type casting.
19
+
-**Coloured output** — 16/256-colour SGR helpers, message styles (`error`, `success`, `warning`, `info`), key/value lists and a progress bar.
20
+
-**Interactive prompts** — free-form `ask()` and option-constrained `question()`.
21
+
-**Table rendering** — a styleable, multibyte-aware ASCII/ANSI table.
22
+
-**Testable I/O** — output and input streams are injectable, so commands can be unit tested without touching `STDOUT`/`STDIN`.
6
23
7
24
## Requirements
8
25
9
-
- PHP 7.2 or higher
26
+
- PHP **7.2** or higher
27
+
-`ext-mbstring`*(optional)* — improves table alignment for multibyte (UTF-8) values
10
28
11
29
## Installation
12
30
13
-
```
31
+
```bash
14
32
composer require initphp/console
15
33
```
16
34
17
-
## Usage
35
+
## Quick start
36
+
37
+
Create an entry script (e.g. `console.php`):
18
38
19
39
```php
20
40
#!/usr/bin/env php
21
41
<?php
22
-
require_once __DIR__ . '/../vendor/autoload.php';
23
-
use \InitPHP\Console\{Application, Input, Output};
24
42
25
-
$console = new Application("My Console Application", '1.0');
43
+
require_once __DIR__ . '/vendor/autoload.php';
44
+
45
+
use InitPHP\Console\{Application, Input, Output};
26
46
27
-
// Register commands ...
47
+
$console = new Application('My Console Application', '1.0.0');
28
48
29
-
// hello -name=John
49
+
// A closure command: php console.php hello --name=John
30
50
$console->register('hello', function (Input $input, Output $output) {
31
-
if ($input->hasArgument('name')) {
32
-
$output->writeln('Hello {name}', [
33
-
'name' => $input->getArgument('name')
34
-
]);
35
-
} else {
36
-
$output->writeln('Hello World!');
37
-
}
51
+
$output->writeln('Hello {name}!', [
52
+
'name' => $input->getArgument('name', 'World'),
53
+
]);
38
54
}, 'Says hello.');
39
55
40
-
41
56
$console->run();
42
57
```
43
58
59
+
Run it:
60
+
61
+
```bash
62
+
php console.php hello --name=John # Hello John!
63
+
php console.php hello # Hello World!
64
+
php console.php list # Show all registered commands
44
65
```
45
-
php console.php list
66
+
67
+
## Terminology
68
+
69
+
This library distinguishes three kinds of tokens that follow the command name:
|**Segment**| bare value, e.g. `migrate`|`getSegment()`|
76
+
77
+
> **Note:** here `--long` tokens are called *arguments* and `-short` tokens are called *options*. This is the opposite of some other frameworks — keep it in mind when porting code.
78
+
79
+
All scalar values are cast automatically: `"true"`/`"false"`/`"yes"`/`"no"` → `bool`, `"null"` → `null`, integer/decimal strings → `int`/`float`.
80
+
81
+
## Class-based commands
82
+
83
+
For anything beyond a one-liner, extend `Command`:
84
+
85
+
```php
86
+
use InitPHP\Console\{Command, Input, InputArgument, Output};
87
+
88
+
class GreetCommand extends Command
89
+
{
90
+
public $command = 'app:greet';
91
+
92
+
public function definition(): string
93
+
{
94
+
return 'Greets a person.';
95
+
}
96
+
97
+
public function help(): string
98
+
{
99
+
return 'Prints a friendly greeting to the given name.';
100
+
}
101
+
102
+
public function arguments(): array
103
+
{
104
+
return [
105
+
new InputArgument('name', InputArgument::STR, 'World', true, 'Who to greet.'),
106
+
];
107
+
}
108
+
109
+
public function execute(Input $input, Output $output)
Declared `arguments()` are validated *before*`execute()` runs: missing required arguments or values that do not match the declared type abort the command with an error.
49
119
50
-
This package ships a styleable ASCII/ANSI table renderer under `\InitPHP\Console\Utils\Table`:
The renderer is intentionally lightweight: it stringifies non-string cell values (`[NULL]`, `[TRUE]`, `[FALSE]`, `[CALLABLE]`, `[RESOURCE]`, class name for objects), auto-sizes columns, and emits standard SGR escape sequences. `mb_strlen()` is used when available so multibyte values align correctly.
179
+
Non-string cell values are stringified (`[NULL]`, `[TRUE]`, `[FALSE]`, `[ARRAY]`, `[CALLABLE]`, `[RESOURCE]`, or the class name for objects), columns are auto-sized, and `mb_strlen()` is used when available so multibyte values align correctly.
180
+
181
+
## Documentation
182
+
183
+
In-depth, example-driven guides live in [`docs/`](./docs):
8.[Migrating from `initphp/cli-table`](./docs/08-migrating-from-cli-table.md)
68
193
69
194
## Migrating from `initphp/cli-table`
70
195
71
-
The standalone [`initphp/cli-table`](https://github.com/InitPHP/CLITable) package has been merged into this one starting with**2.1** and is now deprecated.
196
+
The standalone [`initphp/cli-table`](https://github.com/InitPHP/CLITable) package has been merged into this one as of**2.1** and is now deprecated.
72
197
73
-
If your code currently uses `\InitPHP\CLITable\Table`, **no source changes are required** — this package ships a `class_alias`that keeps the old fully-qualified class name working. Just switch your dependency:
198
+
If your code uses `\InitPHP\CLITable\Table`, **no source changes are required** — this package ships a `class_alias`keeping the old fully-qualified name working. Just switch the dependency:
74
199
75
200
```diff
76
201
- "initphp/cli-table": "^1.0",
77
202
+ "initphp/console": "^2.1"
78
203
```
79
204
80
-
(`initphp/console:^2.1` declares a Composer `replace` for `initphp/cli-table`, so Composer will not install both side-by-side.)
81
-
82
-
When you next touch the code, prefer the new canonical namespace:
205
+
(`initphp/console` declares a Composer `replace` for `initphp/cli-table`, so the two will never be installed side by side.) When you next touch the code, prefer the canonical namespace:
83
206
84
207
```php
85
208
// Before
86
209
use InitPHP\CLITable\Table;
87
-
88
210
// After
89
211
use InitPHP\Console\Utils\Table;
90
212
```
91
213
92
-
The alias is intended as a transition aid and may be removed in a future major release.
214
+
The alias is a transition aid and may be removed in a future major release. See the [migration guide](./docs/08-migrating-from-cli-table.md) for details.
215
+
216
+
## Testing & quality
217
+
218
+
```bash
219
+
composer test# PHPUnit
220
+
composer cs # PHP_CodeSniffer (PSR-12)
221
+
composer stan # PHPStan (level 6)
222
+
composer qa # all of the above
223
+
```
224
+
225
+
## Contributing
226
+
227
+
Contributions are welcome. Please run `composer qa` before opening a pull request. See the organisation [contributing guidelines](https://github.com/InitPHP/.github/blob/main/CONTRIBUTING.md).
0 commit comments