This library helps you to create CLI applications quicky.
You can install the package via composer:
composer require martijnvdb/php-cli
Add the composer autoloader to your application and create a new instance of the CLI class. To run the application, use the run()
method. This example will be placed in a file called myapp
(without the .php
extension).
require __DIR__ . '/vendor/autoload.php';
use Martijnvdb\PhpCli\Cli;
$cli = (new Cli('First CLI App', '0.1.0'))->run();
To add a default command to the application use the add()
method. Use a callback function as the first argument. This callback will be called without giving any extra arguments. To execute the script, run php myapp
.
$cli = new Cli('First CLI App', '0.1.0');
$cli->add(function ($input, $output) {
// ...
})
->run();
The add()
method can also be used to register a command to your application. This example will be executed by running php myapp helloworld
.
$cli = new Cli('First CLI App', '0.1.0');
$cli->add('helloworld', function ($input, $output) {
// ...
})
->run();
The $options
object will contain all the command line arguments. You can retrieve the values using the all()
and get()
methods. The example will return the following while running php myapp helloworld --message "Hello, World!"'
.
$cli->add('helloworld', function ($options, $output) {
// This will return all options
$options = $options->all();
// This will return the value of the '--message' option
$message = $options->get('--message');
// Will return the value of the '--message' or '-m' option
$message = $options->get('--message', '-m');
// $options = ["--message" => "Hello, World!"];
// $message = "Hello, World!";
})
The $output
object will help you formatting your output.
This library support a custom version of BB code to help you style your output. You can mix and match any tags as long as they start with an opening and closing tag.
$output->line('[bold]Bold Text[/bold]');
$output->line('[red]Red Text[/red]');
$output->line('[bg:green]Green Background[/bg:green]');
$output->line('[bg:white][magenta][italic]Italic magenta text on a white background[/italic][/magenta][/bg:white]');
These will change the style of the text.
[bold]
, [b]
, [dim]
, [italic]
, [i]
, [underline]
, [u]
, [blink]
, [inverse]
, [reverse]
, [invisible]
, [strikethrough]
, [s]
These will change the color of the text.
[black]
,[red]
,[green]
,[yellow]
,[blue]
,[magenta]
,[cyan]
,[white]
These will change the background color of the text.
[bg:black]
, [bg:red]
, [bg:green]
, [bg:yellow]
, [bg:blue]
, [bg:magenta]
, [bg:cyan]
, [bg:white]
The $output
object contains the following methods:
Four basis text output methods. The only difference between them is how they handle new lines.
$output->echo(string $value = '');
$output->line(string $value = '');
$output->lines(array $lines = []);
$output->paragraph(string $value = '');
Output the current version of the application.
$output->version();
Output a formatted column. The $rows
variable is an array containing arrays in which each entry is a cell. The $column_styles
variable allows you to style a full column in the same style. You should use the BB code without brackets for this.
$output->columns(string $label, array $rows = [], array $column_styles = []);
Take a look at examples/generate
to see some examples of how to use these methods.
This library also contains a helper class which allows the application to easily get a specific input of the user.
$input = Input::text(string $label)->get();
$input = Input::number(string $label)->get();
$input = Input::url(string $label)->get();
$input = Input::email(string $label)->get();
$input = Input::choice(string $label, array $options)->get();
Example of the choice input helper:
$input = Input::choice('[yellow]Select an option[/yellow] [green](1/2/3)[/green]:', [
'1' => 'Option 1',
'2' => 'Option 2',
'3' => 'Option 3'
])
->required()
->setDefault('1')
->get();
If the given input is empty, then a required message will show up.
$input->required(string $message);
If the user doesn't give an input, the given default value will be returned.
$input->setDefault($default);
The message that will show up when the user enters an invalid input.
$input->setInvalidMessage(string $message);
The $options
array can be filled with BB code tags without the brackets (eg. ['red', 'bold']
).
$input->inputStyling($options = []);
The Progress class shows a progressbar in the console. Using a float between 0
and 1
as an argument in the set()
method, you can set the current percentage of the progressbar. The progressbar will also display how long it is running and the expected remaing time (ETA). The start()
method will start the timer for those values. The stop()
method will stop the timers and the progressbar.
$progress = Progress::new();
$progress->start();
$progress->set(0.25);
$progress->set(0.5);
$progress->set(0.75);
$progress->set(1);
$progress->stop();
You can customize the look of the progressbar using the size()
, foreground()
and background()
methods.
// Default size
$progress->size(30);
// Default templates
$progress->foreground('[bg:white][invisible]|[/invisible][/bg:white]');
$progress->background('[bg:240][invisible].[/invisible][/bg:240]');