PHP Luminova: Command Execution and Formatting with the Terminal Module

The Luminova Terminal class is a command utility helper designed to facilitate command operations for NovaKit, BaseCommand, and BaseConsole. While it can be initialized and used independently, most of its methods are defined statically for easy access. However, not all methods can be executed correctly without proper constructor initialization.

This class offers a powerful set of methods that enhance command-line interactions for developers utilizing the Luminova framework. Key features include:

• Table Generation: Create and display formatted tables.
• User Input Prompts: Easily prompt users for input, including secure password entries.
• Write Operations: Read from and write in command line tool using various methods.
• Command Argument Extraction: Efficiently extract command-line arguments.
• Command Execution: Execute commands directly within the terminal.
• Output Formatting and Styling: Format and style command text output for improved readability.

The Terminal class is inherited by the BaseCommand class, making its methods available for use within your controller classes, either statically or through the this keyword.

Basic Usage Examples

Using the Terminal Class in Command Controllers

When calling methods from the Terminal class within your command controller, use $this or self. This approach assumes that the Terminal instance is initialized within the command controller.

For example, avoid the following within the command controller class:

<?php
$terminal = new Terminal();
// or
Terminal::methodName();

Instead, use:

<?php
$this->methodName(); 
// or 
self::methodName();

Table Display

Display a simple table with names and emails:

<?php
$this->table(
     ['Name', 'Email'], 
     [
          ['Name' => 'Peter', 'Email' => '[email protected]'],
          ['Name' => 'Hana', 'Email' => '[email protected]']
     ]
);

Output:

┌───────┬───────────────────┐
│ Name  │ Email             │
├───────┼───────────────────┤
│ Peter │ [email protected] │
├───────┼───────────────────┤
│ Hana  │ [email protected]  │
└───────┴───────────────────┘

Multiple Chooser Prompts

Ask the user to choose an option or default to the first element:

<?php
$array = $this->chooser(
    'Choose your programming languages?', 
    ['PHP', 'JAVA', 'SWIFT', 'JS', 'SQL', 'CSS', 'HTML']
);

Require the user to choose at least one option is required:

<?php
$array = $this->chooser(
    'Choose your programming languages?', 
    ['PHP', 'JAVA', 'SWIFT', 'JS', 'SQL', 'CSS', 'HTML'], 
    true
);

User Prompts

Prompt the user with color-coded options and is required:

<?php
$color = $this->prompt(
    'Are you sure you want to continue?', 
    [
        'green' => 'YES', 
        'red' => 'NO'
    ]
);

Prompt the user to select their gender, without colored text nor validation required:

<?php
$gender = $this->prompt(
    'What is your gender?', 
    ['male', 'female'], 
    false
);

Prompt the user to select an option with custom validation rules:

<?php
$email = $this->prompt(
    'Are you sure you want to continue?', 
    ['YES', 'NO'], 
    'required|in_array(YES,NO)'
);

User Input Methods

Request user to enter an input.

$name = $this->input('What is your name? ');
echo $name;

Request user to enter password without displaying while typing:

$password = $this->password('Enter your password? ');
echo $password;

Using prompt to request the user to enter their email address:

<?php
$email = $this->prompt('What is your email?');
echo $email;

Waiting Examples

Display a waiting message until the user presses any key:

<?php
$this->waiting();

Show a waiting message for 20 seconds with a countdown:

<?php
$this->waiting(20);

Show a custom downloading message for 20 seconds:

<?php
$this->waiting(20, 'Downloading... (%d seconds)');

Freezing Examples

Freeze the console screen for 20 seconds:

<?php
$this->freeze(20); 

Freeze the console and clear all output and user input for 20 seconds:

<?php
$this->freeze(20, true);

Progress Bar Examples

Show a progress bar with step updates:

<?php
for ($i = 0; $i <= 100; $i++) {
    $step = $this->progress($i, 100);
    usleep(100000);

    if ($step >= 100) {
        echo 'Am done';
        break;
    }
}

Display a progress bar up to 50% without completing:

<?php
for ($i = 0; $i <= 100; $i++) {
    $step = $this->progress($i, 100);
    usleep(100000);

    if ($step >= 50) {
        echo 'Am done halfway';
        break;
    }
}

Watcher Examples

Show 100 lines of progress with callbacks and a beep upon completion:

<?php
$this->watcher(100, function() {
    $this->writeln("Am done here");
}, function(float|int $step) {
    // Avoid adding a new line here to prevent progress bars from miss-aligning except is intended
    $this->write(" Current {$step}");
});

Example Output:

Animation Example

Show a spinning animation with 5 spins, a 100ms sleep between frames, and a custom completion message:

<?php
$this->spinner(['-', '\\', '|', '/'], 5, 100000, function() {
    $this->write("Finished spinning!\n");
});

Example Output:

Class Definition

• Class namespace: \Luminova\Command\Terminal

Constants

These constants represent the standard input, output, and error streams, often used in terminal or command-line applications to manage and control where data flows.

Properties

Input validations object.

protected static \Luminova\Security\Validation|null $validation

Methods

constructor

Initialize command line instance before running any commands.

public __construct(): mixed

waiting

Displays a countdown timer in the console, with a custom message pattern, or prompts the user to press any key to continue.

public static waiting(int $seconds, string $pattern = 'Waiting...(%d seconds)'): void

Parameters:

Return Value:

Note:During count down, the CLI screen will be wiped out of any output.If number of seconds is less than 1, it will prompt message Press any key to continue....

freeze

Freeze and pause execution for a specified number of seconds, optionally clear the screen and the user input during the freeze.

public static freeze(int $seconds = 10, bool $clear = true): void

Parameters:

spinner

Displays a rotating spinner animation in the CLI.

public static spinner(
    array $spinners = [...], 
    int $spins = 10, 
    int $sleep = 100000, 
    \Closure|bool|null $onComplete = null
): void

Parameters:

progress

Displays a progress bar in the console for a given number of steps.

public static progress(int|false $step = 1, int $steps = 10, bool $beep = true): float|int

Parameters:

Return Value:

float|int - Return the percentage of completion between (0-100) or 100 if completed.

Note: Progress should be called in a loop otherwise use watcher method.

watcher

Displays a progress bar on the console and executes optional callbacks at each step and upon completion.

public static watcher(
    int $limit, 
    ?\Closure $onFinish = null, 
    ?\Closure $onProgress = null, 
    bool $beep = true
): void

Parameters:

Progress Callback Signature:

Receiving the current progress percentage using $onProgress Closure.

Terminal::watcher(5, function(float|int $step): void {
    echo "Progress: $step%";
});

This method is designed to be called without a loop, as it handles the iteration internally.It is useful for showing progress while performing a task and executing subsequent actions when complete.

beeps

Beep or make a bell sound for a certain number of time.

public static beeps(int $total = 1): void

Parameters:

prompt

Prompt user to type something, optionally pass an array of options for user to enter any.Additionally, you can make a colored options by using the array key for color name (e.g,['green' => 'YES', 'red' => 'NO']).

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

Parameters:

Return Value:

string - Return the client input value.

See Also:

• Read the user input validation module documentation here for more details.

chooser

Request user with multiple option selection.This method will use the array index key as the option identifier to select, even if the array is an associative array users will still see indexed key instead.

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

Parameters:

Return Value:

array<string|int,mixed> Return the client selected option array key and values.

Throws:

• \Luminova\Exceptions\InvalidArgumentException - Throw if options is not specified or an empty array.

password

Prompts the user to enter a password with hidden input. Supports retry attempts and optional timeout.

• On Windows, it uses a VBS script or PowerShell to hide the input.
• On Linux/Unix, it uses a bash command to hide the input.

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

Parameters:

Return Value:

string - Return the entered password or an empty string if the maximum retry attempts are exceeded.

link

Highlights URL to indicate it clickable in terminal.

public static link(string $url, ?string $title = null): void 

Parameters:

terminate

Terminates the script execution with an optional message and status code.

This method provides a consistent way to end script execution, optionally printing a message before termination. The script exits with the provided status code, which defaults to a success code. If a non-success status code is provided, the script will still terminate, but the status code can be used to indicate an error or abnormal termination to the system.

public static terminate(?string $message = null, int $statusCode = STATUS_SUCCESS): never

Parameters:

timeout

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

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

Parameters:

Return Value:

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

execute

Execute a system command.

public execute(string $command): array|false

Parameters:

Return Value:

array|false - Return the output of executed command as an array of lines, or false on failure.

_exec

Executes a command via exec and redirect error output to null based on the platform (Windows or Unix-like).

public static _exec(string $command, array& $output = [], int &$result_code = STATUS_ERROR): string|bool

Parameters:

Return Value:

string|false - Return the last line of the command output, or false on failure.

_shell

Executes a shell command via shell_exec and return the complete output as a string.Also it redirects error output to NUL based on the platform (Windows or Unix-like).

public static _shell(string $command): string|bool|null

Parameters:

Return Value:

string|bool|null - Return the output of the command, or null on error.

visibility

Toggles the terminal visibility of user input.

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

Parameters:

Return Value:

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

input

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

public static input(?string $prompt = null, bool $use_fopen = false): string

Parameters:

Return Value:

string - Return user input string.

validate

Command user input validation on prompts.

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

Parameters:

Return Value:

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

escape

Escapes a command argument to ensure safe execution in the shell.

public static escape(?string $argument = null): string

Parameters:

Return Value:

string - Return the escaped command string.

Example:

<?php
$argument = 'example argument with "special" characters & symbols';
$escaped = Terminal::escape($argument);

Terminal::_exec("echo $escaped", $output);

print_r($output);

replace

Replace placeholders in a command with environment variable values.

Placeholders follow the format ${:VAR_NAME}, where VAR_NAME corresponds to a key in the $env array.Optionally escapes each replacement for safe shell execution.

public static replace(string $command, <string,mixed> $env, bool $escape = false): string

Parameters:

Return Value:

string - Throws if a placeholder variable is not found in $env or is set to false.

Throws:

• \Luminova\Exceptions\InvalidArgumentException - Throws if an error occurs.

Example:

Example of the environment variables:

<?php
$command = 'echo "${:USER} is running a ${:TASK}"';
$env = [
    'USER' => 'Alice',
    'TASK' => 'test command'
];

Replace placeholders:

<?php
$command = Terminal::replace($command, $env);
echo $command; 
// Output: echo "Alice is running a test command"

Execute the command:

<?php
Terminal::_exec($escaped, $output);
print_r($output);

error

Display an error message box with a default red background and white text.

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

Parameters:

Note: The message is formatted as a block and written to STDOUT.

success

Display a success message with a default green background and white text.

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

Parameters:

writeln

Print text followed by a newline to the specified stream, defaulting to Terminal::STD_OUT.

public static writeln(
    string $text = '', 
    ?string $foreground = null, 
    ?string $background = null, 
    int $stream = self::STD_OUT
): void

Parameters:

write

Print text without appending a newline to the specified stream, defaulting to Terminal::STD_OUT.

public static write(
    string $text = '', 
    ?string $foreground = null, 
    ?string $background = null, 
    int $stream = self::STD_OUT
): void

Parameters:

print

Print text directly using echo without any stream handling.

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

Parameters:

fwrite

Write text to the specified stream resource, without applying any colors defaulting to STDOUT.

public static fwrite(string $text, resource|int $handler = self::STD_OUT): void

Parameters:

Note: If the environment is non-command-based, the text will be output using echo instead of fwrite.

clear

Clears the entire console screen for both Windows and Unix-based systems.

This method refreshes the entire terminal view, removing all previously displayed content.

public static clear(): void

flush

Clears the last printed line or lines of text in the terminal output.

This method is useful for updating the terminal with new content withoutclearing the entire screen, allowing for a more controlled output.

public static flush(?string $lastOutput = null): void

Parameters:

If $lastOutput is provided, the it calculates how many lines it occupied and clears them.If not provided, it clears the current line only.

newLine

Print new lines based on specified count.

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

Parameters:

oops

Oops! command, show an error message for unknown executed command.

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

Parameters:

Return Value:

int - Return status code STATUS_ERROR.

table

Generate and print a formatted table with headers and rows to the console.

This method constructs a visually appealing table using the specified headers and data rows.It supports customization of text colors for both the header and the table content, as well as options for displaying borders after each table row.

public static table(
    string[] $headers, 
    array<int,array<string,string>> $rows, 
    ?string $foreground = null,
    ?string $headerColor = null, 
    ?string $borderColor = null,
    bool $border = true
): string

Parameters:

Return Value:

string - Return the formatted table as a string, ready to be output to the console.

isStreamSupports

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

public static isStreamSupports(string $function, resource|string|int $resource = self::STD_OUT): bool

Parameters:

Return Value:

bool - Return true if stream resource is supported, otherwise false.

getWidth

Attempts to determine the width of the viewable command line window.

final public static getWidth(int $default = 80): int

Parameters:

Return Value:

int - Return terminal window width or default.

getHeight

Attempts to determine the height of the viewable command line window.

final public static getHeight(int $default = 24): int

Parameters:

Return Value:

int - Return terminal window height or default.

getArgument

Get command argument by index number.

public static getArgument(int $index): mixed

Parameters:

Return Value:

mixed - Return command argument by index number.

getArguments

Get command arguments.

public static getArguments(): array

Return Value:

array - Return command arguments.

getCommand

Get command name.

public static getCommand(): ?string

Return Value:

string|null - Return the command name.

getCaller

Get command caller command string.

public static getCaller(): ?string

Return Value:

string|null - Return the full passed command, options and arguments.

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, mixed $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:

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

Get Any Option 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 the above example, getAnyOption('which', 'w') checks for both --which and -w, allowing you to use either option in your command.

getMethod

Returns the command controller class method name.

public static getMethod(): ?string

Return Value:

string|null - Return the command controller class method name, otherwise null.

getOptions

Returns the array of executed command option key values.

public static getOptions(): array

Return Value:

array - Return array of executed command options.

getQuery

Gets a single value from executed command information by the array option key name, if it doesn't exists return null.

public static getQuery(string $name): mixed

Parameters:

Return Value:

mixed - Return the command option key value.

getQueries

Returns the entire command associative that was executed.This is a complied array of executed command details which has been processed for final use.

public static getQueries(): array

Return Value:

array<string,mixed> - Return an associative array of the entire command information.

getStd

Resolves the provided stream constant (Terminal::STD_OUT, Terminal::STD_ERR, or Terminal::STD_IN) and returns the corresponding PHP predefined stream (STDOUT, STDERR, or STDIN).

If the input does not match any of these constants, it returns the original input.

final public static getStd(resource|int $std): resource|string

Parameters:

Return Value:

resource|string - Return the corresponding PHP stream resource (STDOUT, STDERR, STDIN)or the original input if it doesn't match any standard streams.

setColorOutputEnabled

Force enables color output for all standard streams (STDOUT, STDERR, STDIN) without checking whether the terminal or console supports colors.

public static setColorOutputEnabled(): void

This method bypasses any checks and ensures that color formatting will be applied to the output, regardless of compatibility.

setAnsiSupportEnabled

Force enables ANSI escape codes (for formatting like text color, cursor movement, etc.) for all standard streams (STDOUT, STDERR, STDIN), without checking whether the terminal or console supports ANSI codes.

public static setAnsiSupportEnabled(): void

This method will ensure that ANSI sequences will be processed, regardlessof the actual terminal capabilities.

isColorSupported

Checks if the terminal supports ANSI escape codes for color output.

This method determines whether the current terminal can display colored text,based on the platform and the resource (e.g., STDOUT, STDERR, or STDIN).

public static isColorSupported(int $std = self::STD_OUT): bool

Parameters:

Return Value:

bool - Returns true if color output is supported, false otherwise.

Note: On windows you must specify the stream resource (e.g, Terminal::STD_*).

isAnsiSupported

Checks if the terminal supports ANSI escape codes, including color and text formatting.

This method detects whether the terminal supports ANSI features such as colors, bold, underline,and cursor movement, which are used for enhanced CLI output.

public static isAnsiSupported(int $std = self::STD_OUT): bool

Parameters:

Return Value:

bool - Returns true if ANSI escape codes are supported, false otherwise.

isMacTerminal

Checks whether the current terminal is mac terminal.

public static isMacTerminal(): bool

Return Value:

bool - Return true if is mac, otherwise false.

isWindowsTerminal

Determine whether the current terminal is windows os terminal by passing the stream Terminal::STD_* resource to check on.

public static isWindowsTerminal(resource|string|int $resource = self::STD_IN): bool

Parameters:

Return Value:

bool - Return true if is windows terminal, false otherwise.

isLinuxTerminal

Determines if the current terminal is a supported Linux terminal.

public static isLinuxTerminal(): bool

Return Value:

bool - Return true if the terminal is a supported Linux terminal, false otherwise.

isPtySupported

Determines if PTY (Pseudo-Terminal) is supported on the current system.

public static isPtySupported(): bool

Return Value:

bool - Return true if PTY is supported, false otherwise.

isTtySupported

Checks if the current system supports TTY (Teletypewriter).

public static isTtySupported(): bool

Return Value:

bool - Return true if TTY is supported, false otherwise.

isColorDisabled

Checks whether the no color is available in environment, including command flag --no-color.

public static isColorDisabled(): bool

Return Value:

bool - Return true if color is disabled, false otherwise.

isHelp

Check if command is help command.

final public static isHelp(string|array $command): bool

Parameters:

Return Value:

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

isAnsiDisabled

Determines if ANSI escape codes are disabled explicitly, including command flag --no-ansi.

This method checks environment variables and other indicators to determineif ANSI escape codes (for colors, text formatting, etc.) should be disabled.

public static isAnsiDisabled(): bool

Return Value:

bool Returns true if ANSI escape codes are disabled, false otherwise.

toString

Convert executed command array arguments to their original string form.

public static toString(array $arguments): ?string

Parameters:

Return Value:

string|null - Returns the parsed command arguments as a string, or null if the array is empty.

hasCommand

Checks whether framework has the requested command.

final public static hasCommand(string $command): bool

Parameters:

Return Value:

bool - Return true if command exist, false otherwise.

header

Print NovaKit Command line header information.This method also honors command flag --no-header.

final public static header(): bool

Return Value:

bool - Return true if header was printed, false otherwise.