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:
Parameter | Type | Description |
---|---|---|
$seconds | int | Number of seconds for waiting. |
$countdown | bool | Show waiting countdown. |
$message | string | Waiting message instruction. |
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:
Parameter | Type | Description |
---|---|---|
$progressLine | int|bool | Current loop index number or false to terminate the progress bar |
$progressCount | int|null | Total count of progress bar to show or null to on termination |
$beep | bool | Beep when progress is completed, default is true |
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:
Parameter | Type | Description |
---|---|---|
$progressCount | int | Total count of progress bar to show |
$onFinish | ?Closure | Execute callback when progress finished |
$onProgress | ?Closure | Execute callback on each progress step |
$beep | bool | Beep when progress is completed, default is true |
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:
Parameter | Type | Description |
---|---|---|
$command | string | The command to execute |
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:
Parameter | Type | Description |
---|---|---|
$num | int | The number of times to beep |
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:
Parameter | Type | Description |
---|---|---|
$message | string | Prompt message |
$options | array | Options to prompt selection, |
$validations | string|null | Validation rules |
$silent | bool | Print validation failure message parameter is true (default: false) |
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:
Parameter | Type | Description |
---|---|---|
$text | string | Display text description for your multiple options |
$options | array | A list of options ['male' => 'Male', 'female' => 'Female] or ['male', 'female'] |
$required | bool | Require user to choose any option else the first array will be return as default |
Return Value:
array
- The selected array keys and values
Throws:
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:
Parameter | Type | Description |
---|---|---|
$prompt | string | The message to display when prompting for the password.. |
$retry | int | The number of retry attempts if the user provides an empty password (default: 3). |
$timeout | int | The number of seconds to wait for user input before displaying an error message (default: 0). |
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:
Parameter | Type | Description |
---|---|---|
$callback | Closure | The callback function to execute on timeout. |
$timeout | int | Timeout duration in seconds. If <= 0, callback is invoked immediately (default: 0). |
$stream | mixed | Optional stream to monitor for activity (default: STDIN). |
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:
Parameter | Type | Description |
---|---|---|
$string | string|null | The text to wrap. |
$max | int | The maximum width to use. |
$leftPadding | int | The left padding to apply. |
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:
Parameter | Type | Description |
---|---|---|
$text | string | The text display in card. |
$padding | int|null | Optional maximum padding to use. |
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:
Parameter | Type | Description |
---|---|---|
$default | int | Optional default width (default: 80) |
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:
Parameter | Type | Description |
---|---|---|
$default | int | Optional default height (default: 24) |
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:
Parameter | Type | Description |
---|---|---|
$prompt | string|null | You may specify a string to prompt the user after they have typed. |
$useFopen | bool | Optional use file-read, this opens STDIN stream in read-only binary mode (default: false).This creates a new file resource. |
Return Value:
string
- Return user inputed string.
validate
Input validation on prompts
protected static validate(string $value, array $rules): bool
Parameters:
Parameter | Type | Description | |
---|---|---|---|
$value | string | The user Input value. | |
$rules | array | The validation rules, array key input value ruels (e.g. ['input' => 'required | email']). |
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:
Parameter | Type | Description |
---|---|---|
$visibility | bool | True to show input, False to hide input (default: true). |
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:
Parameter | Type | Description |
---|---|---|
$text | string | Error message |
$foreground | string|null | Foreground color name |
$background | string|null | Optional background color name |
error
Display error message on CLI
public static error(string $text, string|null $foreground = 'white', string|null $background = 'red'): void
Parameters:
Parameter | Type | Description |
---|---|---|
$text | string | Error message |
$foreground | string|null | Foreground color name |
$background | string|null | Optional background color name |
writeln
Print message to CLI in a new line.
public static writeln(string $text = '', string|null $foreground = null, string|null $background = null): void
Parameters:
Parameter | Type | Description |
---|---|---|
$text | string | Text to display |
$foreground | string|null | Optional foreground color name |
$background | string|null | Optional background color name |
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:
Parameter | Type | Description |
---|---|---|
$text | string | Text to display |
$foreground | string|null | Optional foreground color name |
$background | string|null | Optional background color name |
Echo / output a message to CLI.
public static print(string $text, string|null $foreground = null, string|null $background = null): void
Parameters:
Parameter | Type | Description |
---|---|---|
$text | string | string to output |
$foreground | string|null | Optional foreground color name |
$background | string|null | Optional background color name |
table
Prints a formatted table header abd rows to the console.
table(array $headers, array $rows, ?string $headerColor = null, int $headerPadding = 1): void
Parameters:
Parameter | Type | Description |
---|---|---|
$headers | array<int,string> | The headers for the table columns. |
$rows | array<string,string> | The rows of data to display in the table. |
$headerColor | string|null | The table heading columns text color. |
$headerPadding | int | Optional table heading columns padding. |
fwrite
Write message to resource handler or output text if not in cli mode
protected static fwrite(string $text, resource $handle = STDOUT): void
Parameters:
Parameter | Type | Description |
---|---|---|
$text | string | string to output or write |
$handle | resource | resource handler |
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:
Parameter | Type | Description |
---|---|---|
$command | string | The executed command. |
$color | string|null | The command text color (default: red) |
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:
Parameter | Type | Description |
---|---|---|
$text | string | Text to color |
$foreground | string | Foreground color name |
$background | string|null | Optional background color name |
$format | int|null | Optionally apply text formatting. |
Return Value:
string
- A colored text if color is supported
newLine
Pring new lines to CLI
public static newLine(int $count = 1): void
Parameters:
Parameter | Type | Description |
---|---|---|
$count | int | Count of new lines to create |
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:
Parameter | Type | Description |
---|---|---|
$function | string | Function name to check |
$resource | resource | Resource to handle STDIN/STDOUT |
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:
Parameter | Type | Description |
---|---|---|
$options | array | Command arguments received in CommandController -> run() method |
getArgument
Get command argument by index number
public static getArgument(int $index): mixed
Parameters:
Parameter | Type | Description |
---|---|---|
$index | int | Argument Index position |
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:
Parameter | Type | Description |
---|---|---|
$key | string | Option key to retrieve. |
$default | string | Default value to return (default: false). |
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:
Parameter | Type | Description |
---|---|---|
$key | string | Option key to retrieve. |
$alias | string | Option key alias to retrieve. if main key is not found. |
$default | string | Default value to return (default: false). |
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:
Parameter | Type | Description |
---|---|---|
$name | string | Query key name |
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:
Parameter | Type | Description |
---|---|---|
$resource | resource | The stream resource STDIN/STDOUT/STDERR, (default: STDOUT) |
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:
Parameter | Type | Description |
---|---|---|
$resource | resource | STDIN/STDOUT |
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:
Parameter | Type | Description |
---|---|---|
$command | string | Command name to check |
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:
Parameter | Type | Description |
---|---|---|
$command | string | Command name to check |
Return Value:
bool
- Return true if command is help, false otherwise.