Download the PHP package windwalker/console without Composer

Windwalker Console

The Windwalker Console package provides an elegant and nested command structure for your cli application.

Installation via Composer

Add this to the require block in your composer.json.

The Nested Command Structure

If we type:

Then we will been direct to CommandC class, and the following foo bar will be arguments.

Initialising Console

Console is the main application help us create a command line program.

An example console application skeleton in cli/console.php file:

The execute() will find commands matched the cli input argument. If there are not any command registered, console will execute the Default Command.

Default RootCommand

RootCommand is a command object extends from base Command. It provides some useful helpers, we can list all commands by typing:

By default, the output is:

Set Handler for RootCommand

We can add closure to every commands, that this command will execute this function first. Use setHandler() on $console, the Console will auto pass the code to RootCommand:

This code will do same action:

Retype $ php cli/console.php and output:

If we want to get help again, just type:

Note: Command only return integer between 0 and 255, 0 means success, while others means failure or other status. The exit code of Unix/Linux meaning please see: Exit Codes Meanings

Add Help Message to Console

Console includes some help message like: name, version, description, usage and help.

If we add this messages to Console:

The help will show:

Add First Level Command to Console

Now, we just use the default root command. But there are no first level command are available to call except HelpCommand.

We can add a new command by this code:

Then we type:

We will get:

If we type help:

The foo command description has auto added to default command arguments list.

Declaring Command Class

We can create our own command object instead setting it in runtime.

This is an example FooCommand declaration:

Then we register it in Console:

Get Arguments and Options

We can use this code to get arguments and options, setting them in FooCommand.

If we type:

The getOption() method will auto detect option aliases, then we can get:

Note: We have to use addOption() to define options first, then the $this->getOption('x') will be able to get the input option which we want. If we didn't do this, we have to use $this->io->get('x') to get option value, but this way do not support option aliases.

Add Second Level Commands and more...

Now, FooCommand is the first level commands in our command tree, if we want to add several commands under FooCommand, we can use addCommand() method. Now we add two bar and yoo command under FooCommand.

Adding command in runtime.

We can use addCommand() to add a command as other commands' child.

If a command has one or more children, the arguments means to call children which the name equals to this argument.

If a command has no child, Command object will run handler closure if has set, or run doExecute() if handler not set. Then the remaining arguments will be able to get by $this->getArgument({offset}).

Adding command by classes

We declare BarCommand and YooCommand class first.

Then register them to FooCommand:

OK, let's typing:

We get:

And typing

get:

Get Child by Path

The Prompter

Prompter is a set of dialog tools help us asking questions for user.

OR set question in constructor.

Validate Input Value

If we didn't type anything, ValidatePrompter will try ask us three times (We set this number by setAttempt()).

We can set closure to validate our rule:

Result

If validate fail, we can choose shut down our process:

Result

Select List

Output

Boolean Prompter

BooleanPrompter convert input string to boolean type, the (y, yes, 1) weill be true, (n, no, 0, null) will be false.

Result

Available Prompters

• TextPrompter
• SelectPrompter
• CallbackPrompter
• ValidatePrompter
• NotNullPrompter
• PasswordPrompter

Available Prompters

HelpCommand

HelpCommand will auto generate help list for us.

When we use addCommand(), addOption() and set some description or other information to these objects, they will save all information in it. Then when we type $ cli/console.php help somethine or $ cli/console.php somethine --help, The HelpCommand will return the help message to us.

Every command has these information, you can use setter and getter to access them:

• Name (Command name. The name of RootCommand is file name.)
• Description (Command description, will show after title in help output.)
• Usage (Will show in help output of current command.)
• Help (Will show in the help output bottom as a manual of current command)

The Console information:

• Name (Name of this application, will show as title in help output.)
• Description (RootCommand description.)
• Usage (RootCommand usage.)
• Help (RootCommand help)

Use Your Own Descriptor

If you want to override the Descriptor for your apps, you can do this:

Use Command Without Console

We can using Command without, please see Command README.

Credits

Windwalker Console incorporated many ideas from other CLI packages. Below is a short list of projects which Windwalker drew inspiration.

• Symfony Console
• Commando
• CLIFramework
• Composer