Download the PHP package iviphp/console without Composer

Ivi Console

Console commands, command-line input parsing and terminal output for the IviPHP ecosystem.

iviphp/console provides a framework-independent foundation for creating CLI applications, registering commands, parsing arguments and options, displaying command help and returning process exit codes.

Requirements

• PHP 8.2 or later
• iviphp/contracts
• iviphp/support

Installation

Features

• Closure-backed console commands
• Custom command implementations
• Command aliases
• Hidden commands
• Positional argument parsing
• Long and short option parsing
• Boolean, string and integer option helpers
• Repeated options
• Standard output and error streams
• Optional ANSI terminal colors
• Automatic command listings
• Built-in help behavior
• Application version output
• Unknown-command suggestions
• Configurable exception handling
• Framework-independent contracts

Core concepts

Console manager

ConsoleManager coordinates:

• command registration;
• command resolution;
• input parsing;
• terminal output;
• command execution;
• help pages;
• command listings;
• version output;
• exception handling;
• process exit codes.

Console API

Console is the public application-facing wrapper around ConsoleManager.

Command

A command defines:

• a unique name;
• a description;
• optional aliases;
• a usage expression;
• whether it is hidden;
• execution logic.

Input

ArgvInput parses an argv-compatible array into:

• executable script;
• command name;
• positional arguments;
• named options;
• original tokens.

Output

ConsoleOutput writes regular messages to standard output and errors to standard error.

ANSI terminal decoration can be detected automatically or configured explicitly.

Creating a console application

Creating a command

Run the command:

Output:

Command exit codes

Command handlers must return an integer between 0 and 255.

The console manager provides common exit-code constants:

Their values are:

Example:

Returning an exit code outside the supported range throws ConsoleException.

Positional arguments

Run it:

Output:

Retrieve all positional arguments:

Check whether an argument exists:

Argument indexes start at zero.

Long options

The parser supports boolean long options:

Retrieve the option:

Options may use an equals sign:

Options may also use the following token as their value:

Disabled boolean options

Options prefixed with --no- are stored as false.

Retrieve the normalized option name:

The value is false.

Short options

Single short options are supported:

Combined short flags are also supported:

This creates the following options:

A short option may contain a value:

Stopping option parsing

The special -- token stops option parsing.

Every following token becomes a positional argument.

The command receives:

as positional arguments.

Repeated options

Repeated options are stored as arrays.

The result is:

Typed option helpers

Boolean options

Recognized true values:

Recognized false values:

String options

Integer options

An invalid integer value throws ConsoleException.

Command aliases

All of these execute the same command:

Command names and aliases must be unique across the registry.

Usage expressions

Display the command help:

Output includes:

Hidden commands

Hidden commands remain executable but are excluded from normal command listings.

Registering command objects

Commands may be created explicitly.

Create a command from another callable:

Custom command classes

Applications may implement:

Example:

Register it:

Registering multiple commands

Replace commands with matching primary names:

Command registry

Retrieve the registry:

Determine whether a command or alias exists:

Check only primary command names:

Check aliases:

Resolve an alias to its primary name:

Result:

Listing commands

Return all commands:

Exclude hidden commands:

Return command names:

Return aliases:

Example:

Replacing a command

The command must already be registered under the same primary name.

Removing commands

An alias may also be supplied:

The command and all its aliases are removed.

Built-in command list

When no command is supplied, the console displays the application name, version and visible commands.

The same list is available through:

The built-in list behavior is used only when an application command named list is not registered.

Built-in help

Display all commands:

Display help for one command:

A command may also request its help page through an option:

or:

The built-in help behavior is used only when an application command named help is not registered.

Version output

or:

Example output:

Render the version programmatically:

Terminal output

Write with a newline:

Semantic output methods are also available:

Regular messages are written to standard output.

Errors are written to standard error.

Creating console output

Disable ANSI decoration:

Enable it explicitly:

Change it later:

Check the current setting:

Custom output streams

Externally supplied streams remain owned by the application.

Streams created internally by ConsoleOutput are closed automatically.

Blank lines

The concrete ConsoleOutput implementation provides a newline helper:

Write several blank lines:

Writing directly to standard error

No semantic color is applied by writeError().

Creating input manually

Retrieve parsed information:

Creating input without a script token

Reading global argv

This reads PHP's global $argv value.

Executing custom input

Running the console application

A minimal executable file may look like this:

Make it executable:

Run it:

Exception handling

ConsoleManager catches command exceptions by default.

When a command fails, the manager writes the exception message and returns exit code 1.

Disable automatic exception catching:

Exceptions are then propagated to the calling application.

Check the current configuration:

Debug exception output

Detailed exception output is disabled by default.

Enable it:

Debug output includes:

• exception class;
• source file;
• source line;
• stack trace;
• previous exception chain.

Check the current mode:

Detailed exception output should not normally be enabled in production environments.

Unknown command suggestions

When an unknown command is executed, the manager searches for similar registered commands.

The console may suggest:

Retrieve suggestions programmatically:

Limit the number of suggestions:

Custom input implementations

Applications may implement:

Required methods:

Custom output implementations

Applications may implement:

Required methods:

Exceptions

Console-system failures are represented by:

Examples include:

• invalid command names;
• duplicate command registration;
• unknown commands;
• invalid aliases;
• alias conflicts;
• invalid input;
• invalid argument indexes;
• invalid option names;
• command execution failures;
• invalid exit codes;
• unavailable streams;
• terminal write failures;
• invalid configuration.

Exception context intentionally excludes raw command arguments and option values.

Clearing the registry

Remove every registered command and alias:

Return the number of registered commands:

Determine whether the registry is empty:

Design principles

iviphp/console follows these principles:

• framework-independent command execution;
• explicit input and output contracts;
• predictable command and alias resolution;
• simple closure-backed commands;
• support for custom command classes;
• safe exception context;
• separate standard output and error streams;
• explicit process exit codes;
• optional terminal decoration;
• compatibility with application-specific CLI architectures.

License

Ivi Console is open-source software released under the MIT License.

Maintainer

Maintained by Gaspard Kirira and Softadastra.