CLI Builder is a PHP Command Line Builder that aims to help simplify building powerful CLI commands for PHP.
- Screenshot
- Getting Started
- Generating Commands
- Setup
- Registering Commands
- Example cli.php
- Layout
- Methods Available
- Helpers / Decorators
- Benchmark
The main CLI class implements a handler that parses the string passed via $argv
It is parsed into an array as follows.
String | Definition |
---|---|
command | Single word |
--option | Single word prefexed with -- and accepts values via = |
-f | Single character prefixed with - |
argument= | Single word that has value via = |
This makes your CLI options endless for each command you want to build.
Example
php cli.php mycommand --option_no_val --option_with_val="Hello World" myarg="foo_bar" -m debug
Would be an array of instructions to use in your command class like the following.
Array(4)
|
| [commands] => Array(1)
| |
| | [0] => String(6) "mycommand"
| |
| [options] => Array(2)
| |
| | [option_no_val] => String(0) ""
| | [option_with_val] => String(11) "Hello World"
| |
| [flags] => Array(1)
| |
| | [0] => String(1) "m"
| |
| [arguments] => Array(1)
| |
| | [myarg] => String(7) "foo_bar"
| |
|
In your command class.
$args = $this->_cli->get_args();
$myarg = ( isset( $args['arguments']['myarg'] ) ) ? $args['arguments']['myarg'] : null;
if( ! is_null( $myarg ) ) {
// Do something with your argument.
}
// Or if you want it required you could force an error output and exit;
if( is_null( $myarg ) ) {
// Will output with red background and white text and Exit.
$this->_cli->error( 'ERROR: myarg is required. Eg. myarg=something' );
exit;
}
Composer setup is coming soon which will be the preferred way.
mkdir cli
cd cli
git clone https://github.com/topdown/cli-builder.git
cd cli-builder
mkdir logs
chmod 777 logs
mkdir commands
# I use CLI Builder for generating scaffolds so I also have templates for my commands.
# This is where I put my template functions for adding pre templated code to files.
mkdir commands/templates
cp cli-builder/example-cli.php cli.php
php cli-builder/src/generate.php command=testing namespace=foo_bar
Will generate a command class named testing
with the namespace cli_builder\commands\foo_bar
in the commands
directory.
NOTE: Leaving the namespace=
off of this command makes the namespace default to namespace cli_builder\commands;
Namespaces will eventually generate proper directory structures. commands/foo_bar/testing.php
(see) example-cli.php
use cli_builder\command\invoker;
use cli_builder\command\receiver;
// Only command line
if ( php_sapi_name() !== 'cli' ) {
die( 'This is a command line tool only.' );
}
include_once 'cli-builder/setup.php';
// CLI Base methods
$cli_base = new \cli_builder\cli_base();
// Loads your command line args into an array( options=[], arguments=[] commands=[], flags=[] ).
$arguments = $cli_base->handler( $argv );
// Start the CLI
$cli = new \cli_builder\cli( $arguments );
// Our header output. (optional)
$cli_base->header();
// New CLI Builder with creation methods.
$builder = new \cli_builder\command\builder();
NOTE: If you change commands with a single $invoker and single $receiver they will all run and output at the end of the run.
It's better to use a switch and separate commands like in the next section Example Commands cli.php.
// Custom commands.
include_once "commands/HelloCommand.php";
include_once "commands/FooCommand.php";
include_once "commands/BarCommand.php";
// Register HelloCommand.
$invoker->set_command( new \cli_builder\commands\HelloCommand( $receiver ) );
// Run the command.
$invoker->run();
// Register FooCommand.
$invoker->set_command( new \cli_builder\commands\FooCommand( $receiver ) );
// Run the command.
$invoker->run();
// Register BarCommand.
$invoker->set_command( new \cli_builder\commands\BarCommand( $receiver ) );
// Run the command.
$invoker->run();
// Outputs the results from all three commands registered above.
echo $receiver->get_output();
In your cli.php or whatever your base command file is.
// Lots of commands
foreach ( $arguments['commands'] as $command ) {
switch ( $command ) {
case 'command1':
// Required to load our custom commands.
$invoker = new invoker();
$receiver = new receiver();
// Custom build path. Defaults to build/
$receiver->set_build_path( 'build/api' );
// Include your command.
include_once "commands/command1.php";
// Register BarCommand.
$invoker->set_command( new \cli_builder\commands\command1( $receiver ) );
// Run the command.
$invoker->run();
break;
case 'command2':
// Required to load our custom commands.
$invoker = new invoker();
$receiver = new receiver();
// Include your command.
include_once "commands/command2.php";
// Register BarCommand.
$invoker->set_command( new \cli_builder\commands\command2( $receiver ) );
// Run the command.
$invoker->run();
break;
}
}
Hiding the logo and date
// The first param is for logo and second for date.
$cli->header( false, false);
The following are available if you use the command generator to scaffold your commands so the proper objects are availble to the class.
// Get the args that were used in the command line input.
$args = $this->_cli->get_args();
// Create a directory. All directories have an index.php added on creation.
$this->_builder->create_directory( $this->_command->build_path . '/foobar' );
// Create nested directories
$this->_builder->create_directory( $this->_command->build_path . '/foo/bar/testing' );
// Create a file.
$this->_builder->create_file( $this->_command->build_path . '/foo/bar/testing/hello.php' );
// Write to file. $config would be your template to write into the file.
$this->_builder->write_file( $this->_command->build_path . '/foo/bar/testing/hello.php', $config );
// Dump your input command line arguments array into a colored output.
$this->_cli->pretty_dump( $args );
// Logging things to a log file. Also excepts a second param for custom log name.
$this->_command->log( __CLASS__ . ' completed run.' );
// Separator lines in your output with option custom param like + = etc...
$this->_cli->separator();
// New line space in your output
$this->_cli->nl();
// Outputs a separator, but can add text with another separator after it.
$this->_cli->lines('Testing lines');
// Output text now. Set second param to true for centering the text.
$this->_cli->text('My text');
// Outputs white text with a red background
// Exits the command.
$cli->error('My error!');
// Colored text and background.
echo $this->_cli->colors->get_colored( 'Colored text and background', 'light_blue', 'black' );
// Will output all content sent to the write method at the end even if it was set in the beginning.
$this->_command->write( __CLASS__ . ' completed run.' );
All of these styling helpers are optional.
All of these helpers are available in command classes via $this->_cli->
$cli->separator();
// Default output
-----------------------------------------------------------------
// Custom
$cli->separator('+');
// Custom output
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
// Adds a \n (new line) return on the end.
$cli->text('My text');
// Centered Text, will center it in the window
$cli->text('My centered text', true);
NOTE: Exits the command.
// Outputs white text with a red background. Exits the command.
$cli->error('My error!');
$cli->progress_bar( $done, $tasks);
// Example
for ( $done = 0; $done <= $tasks; $done ++ ) {
$cli->progress_bar( $done, $tasks);
usleep( ( rand() % 127 ) * 100 );
}
See the colored array in the Screenshot
$cli->pretty_dump( $your_array );
// At the top of your command class after your namespace
use cli_builder\helpers\cli_table;
// Example Use
$tbl = new cli_table();
$tbl->set_headers(
array( 'File Path', 'Size' )
);
// Your data array.
$items = array();
foreach ( $items as $item ) {
$size = filesize( $item );;
// Add your row.
//Make sure you have as many items in the addRow array as your setHeaders.
$tbl->add_row( array( $item, $size ) );
}
// Output the table.
echo $tbl->get_table();
Table Output Example
+--------------------------------+------+
| File Path | Size |
+--------------------------------+------+
| ./cli-builder/assets/index.php | 297 |
| ./index.php | 325 |
| ./logs/index.php | 297 |
| ./src/index.php | 297 |
| ./src/commands/index.php | 297 |
| ./src/command/index.php | 297 |
| ./src/helpers/index.php | 297 |
+--------------------------------+------+
In your main cli.php
$colors = new \cli_builder\helpers\cli_colors();
// Just colored text.
echo $colors->get_colored( 'Just colored text', 'green' );
// Colored text and background.
echo $colors->get_colored( 'Colored text and background', 'light_blue', 'black' );
In your command classes
// Just colored text.
echo $this->_cli->colors->get_colored( 'Just colored text', 'green' );
// Colored text and background.
echo $this->_cli->colors->get_colored( 'Colored text and background', 'light_blue', 'black' );
Text Colors | Background Colors |
---|---|
black | black |
dark_gray | red |
blue | green |
light_blue | yellow |
green | blue |
light_green | magenta |
cyan | cyan |
light_cyan | light_gray |
red | |
light_red | |
purple | |
light_purple | |
brown | |
yellow | |
light_gray | |
white |
// Will output the time to process in seconds and also the max memory used.
$cli_base->benchmark( $start );