Download the PHP package adhocore/cli without Composer

adhocore/cli

Framework agnostic Command Line Interface utilities and helpers for PHP. Build Console App with ease, fun and love.

• Command line application made easy
• Inspired by nodejs commander (thanks tj)
• Zero dependency.
• For PHP7, PHP8 and for good

What's included

Core: Shell

IO: Stream reader

Other: Autocompletion

Installation

Usage

Argv parser

Command help

It can be triggered manually with $command->showHelp() or automatic when -h or --help option is passed to $command->parse().

For above example, the output would be:

Command version

It can be triggered manually with $command->showVersion() or automatic when -V or --version option is passed to $command->parse().

For above example, the output would be:

Console app

Definitely check adhocore/phint - a real world console application made using adhocore/cli.

Here we simulate a git app with limited functionality of add, and checkout. You will see how intuitive, fluent and cheese building a console app is!

Git app

Organized app

Instead of inline commands/actions, we define and add our own commands (having interact() and execute()) to the app:

Grouping commands

Grouped commands are listed together in commands list. Explicit grouping a command is optional. By default if a command name has a colon : then the part before it is taken as a group, else * is taken as a group.

Example: command name app:env has a default group app, command name appenv has group *.

Default command

By default, running your CLI app without any arguments will show the help screen. However you can set the default action to run one of your commands either by setting the third parameter of the add function to true or by using the defaultCommand function.

Exception handler

Set a custom exception handler as callback. The callback receives exception & exit code. The callback may rethrow exception or may exit the program or just log exception and do nothing else.

App help

It can be triggered manually with $app->showHelp() or automatic when -h or --help option is passed to $app->parse(). Note If you pass something like ['app', cmd', '-h'] to $app->parse() it will automatically and instantly show you help of that cmd and not the $app.

For above example, the output would be:

App version

Same version number is passed to all attached Commands. So you can trigger version on any of the commands.

Shell

Very thin shell wrapper that provides convenience methods around proc_open().

Basic usage

Advanced usage

Timeout

Cli Interaction

You can perform user interaction like printing colored output, reading user input programatically and moving the cursors around with provided Ahc\Cli\IO\Interactor.

Confirm

Single choice

Multiple choices

Prompt free input

Prompt with validation

Prompt hidden

On windows platform, it may change the fontface which can be fixed.

IO Components

The interactor is composed of Ahc\Cli\Input\Reader and Ahc\Cli\Output\Writer while the Writer itself is composed of Ahc\Cli\Output\Color. All these components can be used standalone.

Color

Color looks cool!

Simple usage

Custom style

Built-in styles

There are a number of pre-defined built-in styles that allows you granular customization to different output conditions such as help and prompts:

• answer
• choice
• comment
• error
• help_category
• help_description_even
• help_description_odd
• help_example
• help_footer
• help_group
• help_header
• help_item_even
• help_item_odd
• help_summary
• help_text
• info
• logo
• ok
• question
• version
• warn

Overriding a built-in style works the same way as defining a new style:

Disable colors

Colors will be automatically disabled if the NO_COLOR environment variable is set to true.

Cursor

Move cursor around, erase line up or down, clear screen.

Progress Bar

Easily add a progress bar to your output:

You can also manually advance the bar:

You can override the progress bar options to customize it to your liking:

Writer

Write anything in style.

Output formatting

You can call methods composed of any combinations: '<colorName>', 'bold', 'bg', 'fg', 'warn', 'info', 'error', 'ok', 'comment' ... in any order (eg: bgRedFgBlaock, boldRed, greenBold, commentBgPurple and so on ...)

Free style

Many colors with one single call: wrap text with tags <method> and </end> For NL/EOL just use <eol> or </eol> or <eol/>.

Great for writing long colorful texts for example command usage info.

Raw output

Tables

Just pass array of assoc arrays. The keys of first array will be taken as heading. Heading is auto inflected to human readable capitalized words (ucwords).

Gives something like:

Designing table look and feel

Just pass 2nd param $styles:

You can define the style of a cell dynamically using a callback. You could then apply one style or another depending on a value.

The example above only processes the cells in the second column of the table. If you want to process any cell, you can use the *:* key. You could then customise each cell in the table

Note: Priority in increasing order:

• odd or even
• 2:* (row)
• *:2 or b-c <-> column name (col)
• *:* any cell in table
• 1:1 (cell) = highest priority

Justify content (Display setting)

If you want to display certain configurations (from your .env file for example) a bit like Laravel does (via the php artisan about command) you can use the justify method.

Gives something like:

You can use the sep parameter to define the separator to use.

Gives something like:

In addition, the text color, the background color and the thickness of the two texts can be defined via the 3rd argument of this method.

For more details regarding the different color options, see Custom style

Reader

Read and pre process user input.

Exceptions

Whenever an exception is caught by Application::handle(), it will show a beautiful stack trace and exit with non 0 status code.

I18n Support

adhocore/cli also supports internationalisation. This is particularly useful if you are not very comfortable with English or if you are creating a framework or CLI application that could be used by people from a variety of backgrounds.

By default, all the texts generated by our system are in English. But you can easily modify them by defining your translations as follows

You can also change the default English text to make the description more explicit if you wish.

you can find all the translation keys supported by the package in this gist : https://gist.github.com/dimtrovich/1597c16d5c74334e68eef15a4e7ba3fd

Autocompletion

Any console applications that are built on top of adhocore/cli can entertain autocomplete of commands and options in zsh shell with oh-my-zsh.

All you have to do is add one line to the end of ~/.oh-my-zsh/custom/plugins/ahccli/ahccli.plugin.zsh:

compdef _ahccli <appname>

Example: compdef _ahccli phint for phint.

That is cumbersome to perform manually, here's a complete command you can copy/paste/run:

One time setup

Load ahccli plugin

This is also one time setup.

Registering app

Of course you can add multiple apps, just change appname in above command

Then either restart the shell or source the plugin like so:

Trigger autocomplete

Related

• adhocore/phalcon-ext · Phalcon extension using adhocore/cli
• adhocore/phint · PHP project scaffolding app using adhocore/cli
• adhocore/type-hinter · Auto PHP7 typehinter tool using adhocore/cli

Contributors

• adhocore
• sushilgupta

License

© 2017-2020, Jitendra Adhikari | MIT

Credits

This project is release managed by please.