Download the PHP package asika/simple-console without Composer

PHP Simple Console V2.0

Single file console framework to help you write scripts quickly, v2.0 requires PHP 8.4 or later.

This package is highly inspired by Symfony Console and Python argparse.

• PHP Simple Console V2.0
  • Installation
  • Getting Started
  • Run Console by Closure
  • Run Console by Custom Class
  • The Return Value
  • Parameter Parser
  • Parameter Definitions
  • Show Help
  • Override Help Information
  • Parameter Configurations
  • Get Parameters Value
  • Parameters Type
    • ARRAY type
    • LEVEL type
  • Parameters Options
    • description
    • required
    • default
    • negatable
  • Parameters Parsing
  • Error Handling
  • Wrong Parameters
  • Verbosity
  • The Built-In Options
  • Disable Built-In Options for Console App
  • Input/Output
  • STDIN/STDOUT/STDERR
  • Output Methods
  • Input and Asking Questions
  • Run Sub-Process
  • Hide Command Name
  • Custom Output
  • Disable the Output
  • Override exec()
  • Delegating Multiple Tasks
  • Contributing and PR is Welcome

Installation

Use composer:

Download single file: Download Here

CLI quick download:

Getting Started

Run Console by Closure

Use closure to create a simple console script.

The closure can receive a Console object as parameter, so you can use $this or $app to access the console object.

The $argv can be omit, Console will get it from $_SERVER['argv']

Run Console by Custom Class

You can also use class mode, extends Asika\SimpleConsole\Console class to create a console application.

The Return Value

You can return true or 0 as success, false or any int larger than 0 as failure. Please refer to GNU/Linux Exit Codes.

Simple Console provides constants for success and failure:

Parameter Parser

Simple Console supports arguments and options pre-defined. Below is a parser object to help use define parameters and parse argv variables. You can pass the parsed data to any function or entry point.

Same as:

Parameter Definitions

After upgraded to 2.0, the parameter defining is required for Console app, if a provided argument or option is not exists in pre-defined parameters, it will raise an error.

Also same as:

Now if we enter

It shows:

Then, if we enter wrong parameters, Simple Console will throw errors:

Show Help

Simple Console supports to describe arguments/options information which follows docopt standards.

Add --help or -h to Console App:

Will print the help information:

Add your heading/epilog and command name:

The result:

Override Help Information

If your are using class extending, you may override showHelp() method to add your own help information.

Parameter Configurations

To define parameters, you can use addParameter() method.

The parameter name without - and -- will be treated as argument.

The parameter name starts with - and -- will be treated as options, you can use | to separate primary name and shortcuts.

Arguments' name cannot same as options' name, otherwise it will throw an error.

Get Parameters Value

To get parameters' value, you can use get() method, all values will cast to the type which you defined.

Array access also works:

If a parameter is not provided, it will return FALSE, and if a parameter provided but has no value, it will return as NULL.

So you can easily detect the parameter existence and give a default value.

Parameters Type

You can define the type of parameters, it will auto convert to the type you defined.

All parameter values parsed from argv is default as string type, and convert to the type you defined.

ARRAY type

The ARRAY can be use to arguments and options.

If you set an argument as ARRAY type, it must be last argument, and you can add more tailing arguments.

Use -- to escape all following options, all will be treated as arguments, it is useful if you are writing a proxy script.

If you set an option as ARRAY type, it can be used as --tag a --tag b --tag c.

LEVEL type

The LEVEL type is a special type, it will convert the times to int. For example, a verbosity level of -vvv will be converted to 3, and -v will be converted to 1. You can use this type to define the verbosity level of your argv parser.

If you are using Console class, the verbosity is built-in option, you don't need to define it again.

Parameters Options

description

• Argument: Description for the argument, will be shown in help information.
• Option: Description for the option, will be shown in help information.

required

• Argument: Required argument must be provided, otherwise it will throw an error.
  • You should not set a required argument after an optional argument.
• Option: All options are optional.
  • If you set an option as required, it means this option requires a value, only --option without value is not allowed.
  • boolean option should not be required.

default

• Argument: Default value for the argument.
  • If not provided, it will be null, false for boolean type, or [] for array type.
• Option: Default value for the option.
  • If not provided, it will be null, false for boolean type, or [] for array type.

negatable

• Argument: Argument cannot use this option.
• Option: Negatable option. Should work with boolean type.
  • If set to true, it will support --xxx|--no-xxx 2 styles to set true|false.
  • If you want to set a boolean option's default as TRUE and use --no-xxx to set it as FALSE, you can do this:

Parameters Parsing

Simple Console follows docopt style to parse parameters.

• Long options starts with --
• Option shortcut starts with -
• If an option -a requires value, -abc will parse as $a = bc
• If option -a dose not require value, -abc will parse as $a = true, $b = true, $c = true
• Long options supports = while shortcuts are not. The --foo=bar is valid and -f=bar is invalid, you should use -f bar.
• Add -- to escape all following options, all will be treated as arguments.

Error Handling

Just throw Exception in doExecute(), Console will auto catch error.

If Console app receive an Throwable or Exception, it will render an [ERROR] message:

Add -v to show backtrace if error.

Wrong Parameters

If you provide wrong parameters, Console will render a [WARNING] message with synopsis:

You can manually raise this [WARNING] by throwing InvalidParameterException:

Verbosity

You can set verbosity by option -v

or ser it manually in PHP:

If verbosity is larger than 0, it will show backtrace in exception output.

You can show your own debug information on different verbosity:

The Built-In Options

The --help|-h and --verbosity|-v options are built-in options if you use Console app.

If you parse argv by ArgvParser, you must add it manually. To avoid the required parameters error, you can set validate to false when parsing. Then validate and cast parameters after parsing and help content display.

Disable Built-In Options for Console App

If you don't want to use built-in options for Console App, you can set disableDefaultParameters to true:

Input/Output

STDIN/STDOUT/STDERR

Simple Console supports to read from STDIN and write to STDOUT/STDERR. The default stream can be set at constructor.

If you want to catch the output, you can set stdout to a file pointer or a stream.

Output Methods

To output messages, you can use these methods:

• write(string $message, bool $err = false): Write to STDOUT or STDERR
• writeln(string $message, bool $err = false): Write to STDOUT or STDERR with a new line
• newLine(int $lines, bool $err = false): Write empty new lines to STDOUT or STDERR

Input and Asking Questions

To input data, you can use in() methods:

Use ask() to ask a question, if return empty string, the default value will instead.

Use askConfirm() to ask a question with Y/n:

• The 'n', 'no', 'false', 0, '0' will be FALSE.
• The 'y', 'yes', 'true', 1, '1' will be TRUE.

To add your boolean mapping, set values to boolMapping

Run Sub-Process

Use exec() to run a sub-process, it will instantly print the output and return the result code of the command.

Use mustExec() to make sure a sub-process should run success, otherwise it will throw an exception.

Hide Command Name

Bt default, exec() and mustExec() will show the command name before executing, for example.

if you want to hide it, set the arg: showCmd to false.

Custom Output

Simple Console use proc_open() to run sub-process, so you can set your own output stream by callback.

Disable the Output

Use false to disable the output, you can get full output from result object after sub-process finished.

Note, the output will only write to result object if output set to false. If you set output as closure or keep default NULL, the output will be empty in result object.

Override exec()

By now, running sub-process by prop_open() is in BETA, if prop_open() not work for your environment, simply override exec() to use PHP system() instead.

Delegating Multiple Tasks

If your script has multiple tasks, for example, the build script contains configure|make|clear etc...

Here is an example to show how to delegate multiple tasks and pass the necessary params to method interface.

Now run:

Contributing and PR is Welcome

I'm apologize that I'm too busy to fix or handle all issues and reports, but pull-request is very welcome and will speed up the fixing process.