Command Terminal

The Luminova Terminal class for NovaKit is a powerful utility designed to enhance the command-line interface (CLI) interaction for developers leveraging the Luminova framework. Designed to enhance CLI tool development and application operations within the framework, it offers an array of functionalities and utilities.

• Class namespace: \Luminova\Command\Terminal

constructor

Initialize command line instance before running any commands.

new Terminal()

Methods

waiting

Show a waiting countdown, intentionally freeze screen while waiting or ask user for a key press to continue.

protected static waiting(int $seconds, bool $countdown = false, string $message='...'): void

Examples

Parameters:

progress

Displays a progress bar on the CLI.

protected static progress(int|bool $progressLine = 1, int|null $progressCount = 10, bool $beep = true): float|int

Progress should be called in a loop otherwise use watcher() method.

Parameters:

watcher

Displays a and watch progress bar on the CLI with a callback functions, this method shouldn't be called in a loop, you can pass your callable to execute in $onProgress callback function.

protected static watcher(int $progressCount, ?Closure $onFinish = null, ?Closure $onProgress = null, bool $beep = true): void

Parameters:

This is useful when you just want to display a progress bar and execute next method when it finished

execute

This method allows you to execute a system command.

protected static execute(string $command): mixed

Parameters:

Return Value

mixed - Returns the output of command as an array of lines, or STATUS_ERROR on failure

beeps

Trigger beeps a certain number of times.

protected static beeps(int $num = 1): void

Parameters:

prompt

Prompt for user to input or select an option, pass options as an array ["YES", "NO].

protected static prompt(string $message, array $options = [], string|null $validations = null, bool $silent = false): string

Parameters:

Return Value:

string - The user input

You can make a colored options by use the array key for color name ["green" => "YES","red" => "NO"]

chooser

Prompt for multi choice selection, display array index key as the option identifier to select.

protected static chooser(string $text, array $options, bool $required = false): array<string|int,mixed>

Parameters:

Return Value:

array - The selected array keys and values

Throws:

• \Luminova\Exceptions\InvalidArgumentException

If you use associative array users will see index key instead.

password

Prompts the user to enter a password, with options for retry attempts and a timeout.

protected static password(string $message = 'Enter Password', int $retry = 3, int $timeout = 0): string

Parameters:

Return Value:

string - Return the entered password.

timeout

Execute a callback function after a specified timeout when no input or output is received.

public static timeout(Closure $callback, int $timeout = 0, mixed $stream = STDIN): bool

Parameters:

Return Value:

bool - Returns true if the timeout occurred and callback was executed, otherwise false.

wrap

Wrap it with padding left and width to a maximum

public static wrap(string|null $string = null, int $max, int $leftPadding): string

Parameters:

Return Value:

string - Return wrapped text with padding left and width.

card

Create a card text.

public static card(string $text, int|null $padding = null): string

Parameters:

Return Value:

string - Return beautiful card with text.

getWidth

Attempts to determine the width of the viewable CLI window.

protected static getWidth(int $default = 80): int

Parameters:

Return Value:

int - Width or fallback to default

getHeight

Attempts to determine the height of the viewable CLI window.

protected static getHeight(int $default = 24): int

Parameters:

Return Value:

int - Height or fallback to default

input

Get user input from the shell, after requesting for user to type or select an option.

protected static input(string|null $prompt = null, bool $useFopen = false): string

Parameters:

Return Value:

string - Return user inputed string.

validate

Input validation on prompts

protected static validate(string $value, array $rules): bool

Parameters:

Return Value:

bool - Return true if validation succeeded, false if validation failed.

visibility

Toggles the terminal visibility of user input.

protected static visibility(bool $visibility = true): bool

Parameters:

Return Value:

bool - Return true if visibility toggling was successful, false otherwise.

success

Display success text on CLI

public static success(string $text, string|null $foreground = 'white', string|null $background = 'green'): void

Parameters:

error

Display error message on CLI

public static error(string $text, string|null $foreground = 'white', string|null $background = 'red'): void

Parameters:

writeln

Print message to CLI in a new line.

public static writeln(string $text = '', string|null $foreground = null, string|null $background = null): void

Parameters:

write

Print a message to CLI output without a newline.

public static write(string $text = '', string|null $foreground = null, string|null $background = null): void

Parameters:

print

Echo / output a message to CLI.

public static print(string $text, string|null $foreground = null, string|null $background = null): void

Parameters:

table

Prints a formatted table header abd rows to the console.

table(array $headers, array $rows, ?string $headerColor = null, int $headerPadding = 1): void

Parameters:

fwrite

Write message to resource handler or output text if not in cli mode

protected static fwrite(string $text, resource $handle = STDOUT): void

Parameters:

oops

The oops method can be use to display default error message "Unknown command "foo" not found".

protected static oops(string $command, string|null $color = 'red'): int

Parameters:

Return Value

int - Return status code STATUS_ERROR.

clear

Clears the CLI screen of output

public static clear(): void

flush

Clears CLI output to update new text.

public static flush(): void

color

Returns the given text with the correct color codes for a foreground and optionally a background color.

public static color(string $text, string $foreground, string|null $background = null, int|null $format = null): string

Parameters:

Return Value:

string - A colored text if color is supported

newLine

Pring new lines to CLI

public static newLine(int $count = 1): void

Parameters:

streamSupports

Checks whether the current stream resource supports or refers to a valid terminal type device.

public static streamSupports(string $function, resource $resource): bool

Parameters:

Return Value:

bool - if the stream resource is supported

explain

Register command line queries to make available in using methods like getOptions(), getArgument() etc.

public static explain(array $options): void

Parameters:

getArgument

Get command argument by index number

public static getArgument(int $index): mixed

Parameters:

Return Value:

mixed - Passed argument or null.

getArguments

Get command arguments

public static getArguments(): array

Return Value:

array - Passed arguments.

getCommand

Get the passed command name.

public static getCommand(): string|null

Return Value:

string||null - Command name or null.

getCaller

Get the full passed command, options and arguments as its original form.

public static getCaller(): string|null

Return Value:

string||null - Command string or null.

getOption

Get options value from command arguments.If option key is passed with an empty value true will be return otherwise the default value.

public static getOption(string $key, string $default = false): mixed

Parameters:

Return Value:

mixed - Return option value, true if empty value, otherwise default value.

getAnyOption

Get options value from command arguments with an alias key to lookup if main key isn't found.If option key is passed with an empty value true will be return otherwise the default value.

public static getAnyOption(string $key, string $alias, mixed $default = false): mixed

Parameters:

Return Value:

array - Return option value, true if empty value, otherwise default value.

Example

Assume you have a command, such as php index.php my-command --which=a. If you want to also accept an alias of --which as -w, then getAnyOption is what you need.

<?php
$which = $this->getAnyOption('which', 'w');
echo $which;

In this example, getAnyOption('which', 'w') checks for both --which and -w, allowing you to use either option in your command.

getOptions

Returns array of command options and arguments.

public static getOptions(): array

Return Value:

array - Return Options and arguments passed to cli as array.

getQueries

Returns the raw array of requested query command structure.

public static getQueries(): array

This is a complied array of passed query which has been processed for final usage by Luminova framework.

Return Value:

array - Complied structured command queries.

getQuery

Gets complied command queries by it's array key name, keys (arguments, command, caller, options).

public static getQuery(string $name): mixed

Parameters:

Return Value:

mixed - Query values or null if it doesn't exists.

isColorSupported

Check if the your CLI terminal supports colors.On windows you must specify the stream resource (STDIN, STDOUT or STDERR).

public static isColorSupported(resource $resource = STDOUT): bool

Parameters:

Return Value:

bool - Return true if supported, false otherwise.

isMacTerminal

Determine whether if the current terminal is mac os terminal.

public static isMacTerminal(): bool

Return Value:

bool - Return true if mac terminal, false otherwise.

isWindowsTerminal

Determine whether if the current terminal is windows os terminal by passing the stream resource.

public static isWindowsTerminal(resource $resource): bool

Parameters:

Return Value:

bool - Return true if windows terminal, false otherwise.

hasCommand

Checks whether framework has the requested command.

public static hasCommand(string $command): bool

Parameters:

Return Value:

bool - Return true if command exist, false otherwise.

header

Print NovaKit Command line header information

public static header(): void

isHelp

Check if command is help command.

public static isHelp(string $command): boll

Parameters:

Return Value:

bool - Return true if command is help, false otherwise.