README

Webisters CLI Library This library is designed for reuse in Composer-based PHP applications.

What It Provides

A lightweight PHP library for building command line applications. It has three core components:

`Framework\CLI\CLI`

A static toolkit for terminal output and input:

write(), style(), success(), info(), error(), box(), newLine() for formatted output with optional Framework\CLI\Styles\ForegroundColor, BackgroundColor and Format styling
progress(), spinner(), liveLine() for live terminal feedback
prompt(), getInput(), secret() for reading user input
table() for rendering tabular data
getWidth(), wrap(), strlen(), clear(), beep() and terminal helpers
ANSI control with setAnsi() and quiet mode with setQuiet()
Signal handling with onSignal(), onSigint() and restoreSignal() when pcntl is available

`Framework\CLI\Command`

The abstract base class for every console command. Extend it and implement run():

$name, getDescription(), setGroup(), setUsage() and setAliases() describe the command and its help output
getOptions() defines the options a command accepts
activate() / deactivate() control availability

`Framework\CLI\Console`

Discovers, registers and runs commands:

addCommand() / addCommands() accept Command instances or class names
run() parses argv, matches the requested command (including aliases) and dispatches it
Unknown commands print an error and exit 1, suggesting the closest matching command name when there is a close match
getArgument(), getArguments(), getOption() and getOptions() expose the parsed command line
exec() re-parses a command string and then calls run()

Output and Color Helpers

All output helpers live on the static Framework\CLI\CLI class and write to STDOUT. Colors are emitted only when the terminal supports ANSI; use CLI::setAnsi(false) to force plain output.

Writing text

use Framework\CLI\CLI;
use Framework\CLI\Styles\BackgroundColor;
use Framework\CLI\Styles\ForegroundColor;
use Framework\CLI\Styles\Format;

CLI::write('Plain text');
CLI::write('Colored text', ForegroundColor::green);
CLI::write('On a red background', null, BackgroundColor::red);
CLI::write('Wrapped to 40 columns', null, null, 40);

// Full control with style(): color, background and formats
CLI::write(CLI::style('Warning!', 'yellow', null, [Format::bold]));

Colors and formats can be passed as enum cases or as plain strings, for example 'red', 'bright_cyan', 'underline'.

Convenience shortcuts

CLI::success('Task completed');  // green
CLI::info('Just so you know');   // cyan
CLI::error('Something broke');   // red, then exits with code 1

Reading input

// prompt() prints the question and reads a line; options are shown as hints
// and the first option is used as the default when the user presses Enter
$answer  = CLI::prompt('Continue?', ['y', 'n']);
$token   = CLI::secret('Token: ');               // hidden input

// getInput() reads a line without printing anything. The $prepend argument
// is used internally for backslash line continuation and is prefixed to the
// returned value, not displayed.
$line = CLI::getInput();

Live output

foreach ($items as $i => $item) {
    // process $item ...
    CLI::progress($i + 1, \count($items), 'Importing');
}
CLI::spinner(); // spin one frame while waiting
CLI::newLine();

Creating a Custom Command

Create a command by extending Framework\CLI\Command and implementing run():

<?php

use Framework\CLI\CLI;
use Framework\CLI\Command;

class GreetCommand extends Command
{
    protected string $name = 'greet';

    public function getDescription() : string
    {
        return 'Greets the user.';
    }

    public function getOptions() : array
    {
        return ['-s' => 'Shout the greeting.']; // options the command accepts
    }

    public function run() : void
    {
        $name = $this->getConsole()->getArgument(0) ?? 'world';
        $message = "Hello, {$name}!";

        if ($this->getConsole()->getOption('s')) {
            $message = \strtoupper($message);
        }

        CLI::write($message);
    }
}

use Framework\CLI\Console;

$console = new Console();
$console->addCommand(GreetCommand::class);
$console->run();

Call it from the terminal:

php app greet Alice          # Hello, Alice!
php app greet Alice -s       # HELLO, ALICE!
php app help greet           # auto generated usage output

run() is invoked automatically. The Console parses argv for you: positional values are available via getArgument() and options via getOption().

An option always takes a value written with an equal sign, as in --option=value. It also takes the next token, as in -o value and --option value, when the command declares that option in $optionDefinitions with a type other than flag:

protected array $optionDefinitions = [
    'h' => ['type' => 'string', 'description' => 'The host to bind.'],
    'port' => ['type' => 'int', 'default' => 8080],
    'v' => ['type' => 'flag'],
];

php app serve -h 0.0.0.0 --port 8080   # h => 0.0.0.0, port => 8080

An option with no definition, or one defined as a flag, is set to true and the next token becomes an argument. A negative number such as -5 is read as an argument, so it does not need the -- end of options marker. Commands can also declare setAliases() to be reachable by multiple names and setGroup() to organize them in the index listing.

Installation

composer require webisters/cli

Requirements

PHP: >=8.2
Composer: Compatible with Composer 2.x.

Documentation

Guide: https://docs.webisters.com/guides/libraries/cli/
Package: https://webisters.com/packages/cli

Included in Webisters Framework

If you're building a full Webisters application, install the framework meta-package:

composer require webisters/framework

Development

composer install
vendor/bin/phpunit

Follow consistent coding style and run available linters before opening pull requests.

Support

Issues: https://github.com/webisters/cli/issues
Source: https://github.com/webisters/cli
Documentation: https://webisters.com
Forum: https://github.com/webisters/forum
Email: support@webisters.com

License

MIT

webisters / cli

Package info

Security

Fund package maintenance!

Statistics