What's included

Installation

# PHP8.0 and above v1.0.0composer require adhocore/cli:^v1.0.0# PHP 7.xcomposer require adhocore/cli:^v0.9.0

Usage

Argv parser

$command =newAhc\Cli\Input\Command('rmdir','Remove dirs');$command    ->version('0.0.1-dev')// Arguments are separated by space// Format: `<name>` for required, `[name]` for optional//  `[name:default]` for default value, `[name...]` for variadic (last argument)    ->arguments('<dir> [dirs...]')// `-h --help`, `-V --version`, `-v --verbosity` options are already added by default.// Format: `<name>` for required, `[name]` for optional    ->option('-s --with-subdir','Also delete subdirs (`with` means false by default)')    ->option('-e,--no-empty','Delete empty (`no` means true by default)')// Specify santitizer/callback as 3rd param, default value as 4th param    ->option('-d|--depth [nestlevel]','How deep to process subdirs','intval',5)    ->parse(['thisfile.php','-sev','dir','dir1','dir2','-vv'])// `$_SERVER['argv']`;// Print all values:print_r($command->values());/*Array(    [help] =>    [version] => 0.0.1    [verbosity] => 3    [dir] => dir    [dirs] => Array        (            [0] => dir1            [1] => dir2        )    [subdir] => true    [empty] => false    [depth] => 5)*/// To get values for options except the default ones (help, version, verbosity)print_r($command->values(false));// Pick a value by name$command->dir;// dir$command->dirs;// [dir1, dir2]$command->depth;// 5

Command help

Command version

0.0.1-dev

Console app

Git app

$app =newAhc\Cli\Application('git','0.0.1');$app// Register `add` command    ->command('add','Stage changed files','a')// alias a// Set options and arguments for this command        ->arguments('<path> [paths...]')        ->option('-f --force','Force add ignored file','boolval',false)        ->option('-N --intent-to-add','Add content later but index now','boolval',false)// Handler for this command: param names should match but order can be anything :)        ->action(function ($path,$paths,$force,$intentToAdd) {array_unshift($paths,$path);echo ($intentToAdd ?'Intent to add' :'Add')                .implode(',',$paths)                . ($force ?' with force' :'');// If you return integer from here, that will be taken as exit error code        })// Done setting up this command for now, tap() to retreat back so we can add another command        ->tap()    ->command('checkout','Switch branches','co')// alias co        ->arguments('<branch>')        ->option('-b --new-branch','Create a new branch and switch to it',false)        ->option('-f --force','Checkout even if index differs','boolval',false)        ->action(function ($branch,$newBranch,$force) {echo'Checkout to'                . ($newBranch ?'new' .$branch :$branch)                . ($force ?' with force' :'');        });// Parse only parses input but doesnt invoke action$app->parse(['git','add','path1','path2','path3','-f']);// Handle will do both parse and invoke action.$app->handle(['git','add','path1','path2','path3','-f']);// Will produce: Add path1, path2, path3 with force$app->handle(['git','co','-b','master-2','-f']);// Will produce: Checkout to new master-2 with force

Organized app

class InitCommandextendsAhc\Cli\Input\Command{publicfunction__construct()    {parent::__construct('init','Init something');$help ='<cyan>Custom help screen</end>';$writer =newAhc\Cli\Output\Writer();$this            ->argument('<arrg>','The Arrg')            ->argument('[arg2]','The Arg2')            ->option('-a --apple','The Apple')            ->option('-b --ball','The ball')            ->help($writer->colorizer()->colors($help))// Usage examples:            ->usage(// append details or explanation of given example with ` ## ` so they will be uniformly aligned when shown'<bold>  init</end> <comment>--apple applet --ball ballon <arggg></end> ## details 1<eol/>' .// $0 will be interpolated to actual command name'<bold>  $0</end> <comment>-a applet -b ballon <arggg> [arg2]</end> ## details 2<eol/>'            )            ->logo('Ascii art logo of your command');    }// This method is auto called before `self::execute()` and receives `Interactor $io` instancepublicfunctioninteract(Ahc\Cli\IO\Interactor$io) :void    {// Collect missing opts/argsif (!$this->apple) {$this->set('apple',$io->prompt('Enter apple'));        }if (!$this->ball) {$this->set('ball',$io->prompt('Enter ball'));        }// ...    }// When app->handle() locates `init` command it automatically calls `execute()`// with correct $ball and $apple valuespublicfunctionexecute($ball,$apple)    {$io =$this->app()->io();$io->write('Apple' .$apple,true);$io->write('Ball' .$ball,true);// more codes ...// If you return integer from here, that will be taken as exit error code    }}class OtherCommandextendsAhc\Cli\Input\Command{publicfunction__construct()    {parent::__construct('other','Other something');    }publicfunctionexecute()    {$io =$this->app()->io();$io->write('Other command');// more codes ...// If you return integer from here, that will be taken as exit error code    }}// Init App with name and version$app =newAhc\Cli\Application('App','v0.0.1');// Add commands with optional aliases`$app->add(newInitCommand,'i');$app->add(newOtherCommand,'o');// Set logo$app->logo('Ascii art logo of your app');// Custom help screen$app->help('Custom help screen (if omitted one will be generated)');$app->handle($_SERVER['argv']);// if argv[1] is `i` or `init` it executes InitCommand

Grouping commands

// Add grouped commands:$app->group('Configuration',function ($app) {$app->add(newConfigSetCommand);$app->add(newConfigListCommand);});// Alternatively, set group one by one in each commands:$app->add((newConfigSetCommand)->inGroup('Config'));$app->add((newConfigListCommand)->inGroup('Config'));...

Default command

$app->add(newInitCommand,'i',true);// Alternatively$app->command('init','Init something','i');$app->defaultCommand('init');// Retrieve the name of the default command$default_command =$app->getDefaultCommand();

Exception handler

$app =newAhc\Cli\Application('App','v0.0.1');$app->add(...);$app->onException(function (Throwable$e,int$exitCode) {// send to sentry// write to logs// optionally, exit with exit code:exit($exitCode);// or optionally rethrow, a rethrown exception is propagated to top layer caller.throw$e;})->handle($argv);

App help

App version

Shell

Basic usage

$shell =newAhc\Cli\Helper\Shell($command ='php -v',$rawInput =null);// Waits until proc finishes$shell->execute($async =false);// default falseecho$shell->getOutput();// PHP version string (often with zend/opcache info)

Advanced usage

$shell =newAhc\Cli\Helper\Shell('php /some/long/running/scipt.php');// With async flag, doesnt wait for proc to finish!$shell->setOptions($workDir ='/home',$envVars = [])    ->execute($async =true)    ->isRunning();// true// Force stop anytime (please check php.net/proc_close)$shell->stop();// also closes pipes// Force kill anytime (please check php.net/proc_terminate)$shell->kill();

Timeout

$shell =newAhc\Cli\Helper\Shell('php /some/long/running/scipt.php');// Wait for at most 10.5 seconds for proc to finish!// If it doesnt complete by then, throws exception$shell->setOptions($workDir,$envVars,$timeout =10.5)->execute();// And if it completes within timeout, you can access the stdout/stderrecho$shell->getOutput();echo$shell->getErrorOutput();

Cli Interaction

$interactor =newAhc\Cli\IO\Interactor;// For mocking io:$interactor =newAhc\Cli\IO\Interactor($inputPath,$outputPath);

Confirm

$confirm =$interactor->confirm('Are you happy?','n');// Default: n (no)$confirm// is a boolean    ?$interactor->greenBold('You are happy :)',true)// Output green bold text    :$interactor->redBold('You are sad :(',true);// Output red bold text

Single choice

$fruits = ['a' =>'apple','b' =>'banana'];$choice =$interactor->choice('Select a fruit',$fruits,'b');$interactor->greenBold("You selected:{$fruits[$choice]}",true);

Multiple choices

$fruits  = ['a' =>'apple','b' =>'banana','c' =>'cherry'];$choices =$interactor->choices('Select fruit(s)',$fruits, ['b','c']);$choices =\array_map(function ($c)use ($fruits) {return$fruits[$c]; },$choices);$interactor->greenBold('You selected:' .implode(',',$choices),true);

Prompt free input

$any =$interactor->prompt('Anything',rand(1,100));// Random default$interactor->greenBold("Anything is:$any",true);

Prompt with validation

$nameValidator =function ($value) {if (\strlen($value) <5) {thrownew \InvalidArgumentException('Name should be atleast 5 chars');    }return$value;};// No default, Retry 5 more times$name =$interactor->prompt('Name',null,$nameValidator,5);$interactor->greenBold("The name is:$name",true);

Prompt hidden

$passValidator =function ($pass) {if (\strlen($pass) <6) {thrownew \InvalidArgumentException('Password too short');    }return$pass;};$pass =$interactor->promptHidden('Password',$passValidator,2);

IO Components

Color

$color =newAhc\Cli\Output\Color;

Simple usage

echo$color->warn('This is warning');echo$color->info('This is info');echo$color->error('This is error');echo$color->comment('This is comment');echo$color->ok('This is ok msg');

Custom style

Ahc\Cli\Output\Color::style('mystyle', ['bg' =>Ahc\Cli\Output\Color::CYAN,'fg' =>Ahc\Cli\Output\Color::fg256(57),// 256 colors can be used as well'bold' =>1,// You can experiment with 0, 1, 2, 3 ... as well]);echo$color->mystyle('My text');

Built-in styles

Ahc\Cli\Output\Color::style('error', ['fg' =>Ahc\Cli\Output\Color::RED,'bold' =>1,]);

Disable colors

Ahc\Cli\Output\Color::$enabled =false;

Cursor

$cursor =newAhc\Cli\Output\Cursor;echo$cursor->up(1)    .$cursor->down(2)    .$cursor->right(3)    .$cursor->left(4)    .$cursor->next(0)    .$cursor->prev(2);.$cursor->eraseLine()    .$cursor->clear()    .$cursor->clearUp()    .$cursor->clearDown()    .$cursor->moveTo(5,8);// x, y

Progress Bar

$progress =newAhc\Cli\Output\ProgressBar(100);for ($i =0;$i <=100;$i++) {$progress->current($i);// Simulate something happeningusleep(80000);}

$progress =newAhc\Cli\Output\ProgressBar(100);// Do something$progress->advance();// Adds 1 to the current progress// Do something$progress->advance(10);// Adds 10 to the current progress// Do something$progress->advance(5,'Still going.');// Adds 5, displays a label

$progress =newAhc\Cli\Output\ProgressBar(100);$progress->option('pointer','>>');$progress->option('loader','▩');// You can set the progress fluently$progress->option('pointer','>>')->option('loader','▩');// You can also use an associative array to set many options in one time$progress->option(['pointer' =>'>>','loader'  =>'▩']);// Available options+---------------+------------------------------------------------------+---------------+| Option        | Description                                          | Default value |+===============+======================================================+===============+| pointer       | The progress bar head symbol                         | >             || loader        | The loader symbol                                    | =             || color         | The color of progress bar                            | white         || labelColor    | The text color of the label                          | white         || labelPosition | The position of thelabel (top, bottom, left, right) | bottom        |+---------------+------------------------------------------------------+---------------+

Writer

$writer =newAhc\Cli\Output\Writer;// All writes are forwarded to STDOUT// But if you specify error, then to STDERR$writer->errorBold('This is error');

Output formatting

$writer->bold->green->write('It is bold green');$writer->boldGreen('It is bold green');// Same as above$writer->comment('This is grayish comment',true);// True indicates append EOL character.$writer->bgPurpleBold('This is white on purple background');

Free style

$writer->colors('<red>This is red</end><eol><bgGreen>This has bg Green</end>');

Raw output

$writer->raw('Enter name:');

Tables

$writer->table([    ['a' =>'apple','b-c' =>'ball','c_d' =>'cat'],    ['a' =>'applet','b-c' =>'bee','c_d' =>'cute'],]);

+--------+------+------+| A      | B C  | C D  |+--------+------+------+| apple  | ball | cat  || applet | bee  | cute |+--------+------+------+

$writer->table([    ['a' =>'apple','b-c' =>'ball','c_d' =>'cat'],    ['a' =>'applet','b-c' =>'bee','c_d' =>'cute'],], [// for => styleName (anything that you would call in $writer instance)'head' =>'boldGreen',// For the table heading'odd'  =>'bold',// For the odd rows (1st row is odd, then 3, 5 etc)'even' =>'comment',// For the even rows (2nd row is even, then 4, 6 etc)'1:1'  =>'red',// For cell in row 1 col 1 (1 based count, 'apple' in this example)'2:*'  =>'',// For all cells in row 2 (1 based count)'*:2'  =>'',// For all cells in col 2 (1 based count)'b-c'  =>'',// For all columns named 'b-c' (same as '*:2' in this example)'*:*'  =>'blue',// For all cells in table (Set all cells to blue)]);

$rows = [    ['name' =>'John Doe','age' =>'30'],    ['name' =>'Jane Smith','age' =>'25'],    ['name' =>'Bob Johnson','age' =>'40'],];$styles = ['*:2' =>function ($val,$row) {return$row['age'] >=30 ?'boldRed' :'';    },];$writer->table($rows,$styles);

$rows = [    ['name' =>'John Doe','age' =>'30'],    ['name' =>'Jane Smith','age' =>'25'],    ['name' =>'Alice Bob','age' =>'10'],    ['name' =>'Big Johnson','age' =>'40'],    ['name' =>'Jane X','age' =>'50'],    ['name' =>'John Smith','age' =>'20'],    ['name' =>'Bob John','age' =>'28'],];$styles = ['*:*' =>function ($val,$row) {if ($val ==='Jane X') {return'yellow';        }if ($val ==10 ||$val ==20) {return'boldPurple';        }if (str_contains($val,'Bob')) {return'blue';        }return$row['age'] >=30 ?'boldRed' :'';    },];$writer->table($rows,$styles);

Justify content (Display setting)

$writer->justify('Environment');$writer->justify('PHP Version',PHP_VERSION);$writer->justify('App Version','1.0.0');$writer->justify('Locale','en');

Environment ........................................PHP Version .................................. 8.1.4App Version .................................. 1.0.0Locale .......................................... en

$writer->justify('Environment','', ['sep' =>'-']);$writer->justify('PHP Version',PHP_VERSION);

Environment ----------------------------------------PHP Version .................................. 8.1.4

$writer->justify('Cache Enable','true', ['first' => ['fg' =>Ahc\Cli\Output\Color::CYAN],// style of the key'second' => ['fg' =>Ahc\Cli\Output\Color::GREEN],// style of the value]);$writer->justify('Debug Mode','false', ['first' => ['fg' =>Ahc\Cli\Output\Color::CYAN],// style of the key'second' => ['fg' =>Ahc\Cli\Output\Color::RED],// style of the value]);

Reader

$reader =newAhc\Cli\Input\Reader;// No default, callback fn `ucwords()`$reader->read(null,'ucwords');// Default 'abc', callback `trim()`$reader->read('abc','trim');// Read at most first 5 chars// (if ENTER is pressed before 5 chars then further read is aborted)$reader->read('','trim',5);// Read but dont echo back the input$reader->readHidden($default,$callback);// Read from piped stream (or STDIN) if available without waiting$reader->readPiped();// Pass in a callback for if STDIN is empty// The callback recieves $reader instance and MUST return string$reader->readPiped(function ($reader) {// Wait to read a line!return$reader->read();// Wait to read multi lines (until Ctrl+D pressed)return$reader->readAll();});

Exceptions

I18n Support

\Ahc\Application::addLocale('fr', ['Only last argument can be variadic' =>'Seul le dernier argument peut être variadique',],true);

\Ahc\Application::addLocale('en', ['Show help' =>'Shows helpful information about a command',]);

Autocompletion

One time setup

mkdir -p~/.oh-my-zsh/custom/plugins/ahccli&&cd~/.oh-my-zsh/custom/plugins/ahccli[-f ./ahccli.plugin.zsh ]|| curl -sSLo ./ahccli.plugin.zsh https://raw.githubusercontent.com/adhocore/php-cli/master/ahccli.plugin.zshchmod 760 ./ahccli.plugin.zsh&&cd -

Load ahccli plugin

# Open .zshrcnano~/.zshrc# locate plugins=(... ...) and add ahccliplugins=(git ... ... ahccli)# ... then save it (Ctrl + O)

Registering app

# replace appname with real name eg: phintecho compdef _ahccli appname>>~/.oh-my-zsh/custom/plugins/ahccli/ahccli.plugin.zsh

source~/.oh-my-zsh/custom/plugins/ahccli/ahccli.plugin.zsh

Trigger autocomplete

appname<tab># autocompletes commands               (phint <tab>)appname subcommand<tab># autocompletes options for subcommand (phint init <tab>)

Related

Contributors

License

Credits