PHP Luminova: CLI Terminal Helper Class

The CLI Terminal class is a command-line helper for Novakit. It handles common CLI tasks such as input, output, formatting, and command execution within the Luminova framework.

It works in both routable Luminova\Base\Command controllers and console-based Luminova\Base\Console controllers.

All methods are static for ease of use. However, some features require initialization. This can be done by calling Terminal::init() or by creating an instance with new Terminal().

Key Features

The Terminal class simplifies CLI development by providing:

• Table Output – Display data in clean, readable tables.
• User Prompts – Collect user input, including hidden password input.
• CLI I/O Helpers – Write to and read from the terminal with ease.
• Argument Parsing – Extract and work with CLI arguments and flags.
• Command Execution – Run system commands from your CLI tool.
• Styled Output – Add colors and formatting for better readability.

Usage

Terminal Initialization

If you use the Terminal class outside command controllers (Luminova\Base\Command or Luminova\Base\Console), you must initialize it manually.

use Luminova\Command\Terminal;

// Initialize terminal support
Terminal::init();

Table Display

Display a simple table with names and emails:

Terminal::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:

$array = Terminal::chooser(
    'Choose your programming languages?', 
    ['PHP', 'JAVA', 'SWIFT', 'JS', 'SQL', 'CSS', 'HTML']
);

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

$array = Terminal::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:

$color = Terminal::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:

$gender = Terminal::prompt(
    'What is your gender?', 
    ['male', 'female'], 
    false
);

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

$email = Terminal::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 = Terminal::input('What is your name? ');

Required:

Setting the $default parameter forces user to enter something.

$name = Terminal::input('What is your name? ', default: null);

Request user to enter password without displaying while typing:

$password = Terminal::password('Enter your password? ');

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

$email = Terminal::prompt('What is your email?');

Waiting Examples

Display a waiting message until the user presses any key:

Terminal::waiting();

Show a waiting message for 20 seconds with a countdown:

Terminal::waiting(20);

Show a custom downloading message for 20 seconds:

Terminal::waiting(20, 'Downloading... (%d seconds)');

Freezing Examples

Freeze the console screen for 20 seconds:

Terminal::freeze(20); 

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

Terminal::freeze(20, true);

Progress Bar Examples

Draw a progress bar with with manual step updates:

for ($i = 0; $i <= 100; $i++) {
    $step = Terminal::progress($i, 100);
    usleep(100000);

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

Stope a progress bar halfway, up to 50% without completing:

for ($i = 0; $i <= 100; $i++) {
    $step = Terminal::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:

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

Example Output:

Animation Example

Draw a spinning animation with an array list of any charters. Animate 5 spins, a 100ms sleep between frames, and a custom completion message:

Terminal::spinner(['-', '\\', '|', '/'], 5, 100000, function() {
    Terminal::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

isReadLine

Is the readline library on the system.

public static bool $isReadLine

Methods

init

Initialize the terminal instance for CLI operations.

• Sets up standard input/output streams.
• Detects whether readline extension is available.
• Checks for color support in the terminal output.

Subsequent calls to this method have no effect once initialization is complete.

public static init(): void

Example:

use Luminova\Command\Terminal;

// Initialize statically
Terminal::init();
Terminal::print("Hello from static init!");

waiting

Displays a countdown timer in the console.

This method shows a countdown with a custom message,or prompts the user to press any key to continue if the timer is 0 or negative.

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

Parameters:

Return Value:

Note:

• The console screen will be cleared during the countdown.
• If $seconds is less than 1, it displays Press any key to continue... and waits for input.

freeze

Pauses execution for a specified number of seconds, optionally clearing the screen during the freeze.

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

Parameters:

spinner

Displays a rotating spinner animation in the CLI.

The spinner cycles through a set of characters to create a simple loading animation.You can customize the spinner frames, the number of rotations, the speed, andoptionally execute a callback or print "Done!" when finished.

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 step out of a total.

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 and executes optional callbacks at each step and upon completion.

Handles iteration internally and provides hooks for progress and finish events.Useful for visual feedback during long-running tasks.

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%";
});

Note: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.

prompt

Prompt the user to type input with optional validation and selectable options.

You can optionally pass an array of options to suggest possible values.Each option can also have a color if supported (e.g., ['green' => 'YES', 'red' => 'NO']).Validation rules can restrict allowed values or be disabled entirely.

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

Display a multiple-choice selection prompt in the terminal.

Users select options using index numbers. Supports single or multiple selection.

• If $required is true, at least one option must be selected.
• $multiChoice allows selecting multiple options separated by commas.

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

Parameters:

Return Value:

array<string|int,mixed> Returns an array of selected keys and their corresponding values.

Throws:

• \Luminova\Exceptions\IOException - If $options is empty or invalid.

password

Prompt the user to enter a password securely (input hidden).

Works cross-platform:

• Windows: uses PowerShell or VBS to hide input.
• Linux/macOS: uses terminal raw input to hide password.

Supports retry attempts, optional empty passwords, and optional timeout.

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

Parameters:

Return Value:

string - Returns the entered password, or empty string if max retries exceeded.

input

Read a single line of user input from the terminal or piped input.

If $default is null, input is required and the prompt repeats until a value is entered.Supports optional prompts, default values, and a separate STDIN stream handle.For multi-line input, use Luminova\Command\self::read() instead.

public static input(?string $prompt = null, ?string $default = '', bool $newStream = false): string

Parameters:

Return Value:

string - Returns the trimmed input string or the default value.

read

Read input from STDIN, supporting single or multi-line input.

Suitable for piped data or long content. For interactive prompts or single-line input,use Luminova\Command\self::input() instead.

When $eof is true, the entire STDIN stream is read until EOF.When $eof is false, a single line is read.

Alias Luminova\Command\self::readInput()

public static read(string $default = '', bool $eof = true, bool $newStream = false): string

Parameters:

Return Value:

string - Returns trimmed input string or default if empty/failure.

Example:

Read From Pipe Input:

echo "Log Message From Pipe" | php index.php logger
php index.php list-something | php index.php logger

tablist

Displays a selectable list in the terminal with keyboard navigation.

Users can navigate the options using:

• Arrow keys (up/down)
• Tab / Shift+Tab
• Enter to select
• Escape to cancel (returns empty string)
• Ctrl+C to exit

The selected option is returned as a string. Supports optional placeholder text,foreground and background colors for the highlighted selection, and clearing the screen after selection.

public static tablist(
    array $options, 
    int $default = 0,
    ?string $placeholder = null,
    bool $clearOnSelect = true,
    string $foreground = 'green', 
    ?string $background = null
): string

Parameters:

Return Value:

string - Returns the selected option as a string, or empty string if cancelled.

table

Generate and print a formatted table structure to the console.

Each row is an associative array where the keys match the column headers.Supports optional text coloring for headers, body, and borders, as well as controllingwhether borders are shown and whether newlines within cells are retained.

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 - Returns the formatted table as a string, ready for console output.

error

Display an error message box in the console.

The message is formatted as a block with a default red background and white text.

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

Parameters:

success

Display a success message box in the console.

The message is formatted as a block with a default green background and white text.

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

Parameters:

info

Display an informational message in the console.

By default, the text is displayed with a blue foreground and no background.

public static info(
    string $text,
    ?string $foreground = 'blue',
    ?string $background = null,
    ?int $width = null
): void

Parameters:

writeln

Print text followed by a newline to the specified stream (default: STDOUT).

Supports optional foreground and background colors.

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

Parameters:

write

Print text without a newline to the specified stream (default: STDOUT).

Supports optional foreground and background colors.

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

Parameters:

print

Print text directly to the console using echo.

Optional colors can be applied for foreground and background.

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

Parameters:

fwrite

Write text directly to a stream resource without applying colors.

Falls back to echo if the environment is non-command-based.

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

Parameters:

about

Displays system and environment information in a table format.

Intended for CLI usage, this method outputs details such as PHP version, operating system, terminal size, and other runtime-related information.

public static about(): void

header

Prints the NovaKit CLI header banner.

Displays framework version, CLI tool version, and current server time.The header is skipped if the --no-header argument is present.

public static header(): bool

Return Value:

bool - Returns true if the header was printed, false if suppressed.

whoami

Returns the system user executing the current script.

Attempts to resolve the actual OS-level user using a shell command.If unavailable, falls back to PHP's process user.

public static whoami(): string

Return Value:

string - Return the current system username with whitespace removed.

terminate

Terminates script execution immediately, optionally displaying a message and providing an exit code.

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

Parameters:

timeout

Executes a callback function if no activity is detected on the specified stream within a timeout.

public static timeout(\Closure $callback, int $timeout = 0, resource|string|int $stream = self::STD_IN): bool

Parameters:

Return Value:

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

execute

Execute a system command and return its output as an array of lines.

public static execute(string $command): array|false

Parameters:

Return Value:

array|false - Returns the output lines of the command on success, or false on failure.

beeps

Emits a beep (bell) sound in the terminal a specified number of times.

Useful for notifications, alerts, or signaling the user in CLI scripts.

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

Parameters:

oops

Display an error message for an unknown command.

Prints a formatted command not found message to STDERR.

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

Parameters:

Return Value:

int - Always returns STATUS_ERROR.

link

Highlights a URL in the terminal to indicate it is clickable.

If ANSI hyperlinks are supported, the URL will be clickable. Otherwise, it will be underlined.

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

Parameters:

visibility

Show or hide user input in the terminal.

Useful for password prompts or sensitive input.

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

Parameters:

Return Value:

bool - Returns true on success, false on failure.

clear

Clear the terminal screen.

Supported modes:

• default: Clear the entire screen.
• partial: Clear from cursor to bottom.
• full: Clear screen and scroll-back buffer.

public static clear(string $mode = 'default'): void

Parameters:

flush

Remove the last printed line(s) from the terminal output.

If no output is provided, clears the previous line.If output is provided, clears the exact number of wrapped lines.

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

Parameters:

validate

Validate user input against a set of rules, typically used for prompts.

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

Parameters:

Return Value:

bool - Returns true if validation passes, false otherwise.

escape

Escape a command-line argument to ensure it is safely executed in the shell.

Handles special characters differently for Windows and Unix-like platforms.

public static escape(?string $argument): string

Parameters:

Return Value:

string - Returns the safely escaped string ready for shell execution.

Example:

$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 string with values from an environment array.

Placeholders must follow the format ${:VAR_NAME}, where VAR_NAME corresponds to a key in $env.Optionally, replacements can be escaped for safe shell execution.

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

Parameters:

Return Value:

string - Returns the command with all placeholders replaced.

Throws:

• \Luminova\Exceptions\IOException - If a placeholder is missing in $env or its value is false.

Example:

Example of the environment variables:

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

Replace placeholders:

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

Execute the command:

Terminal::_exec($escaped, $output);
print_r($output);

cursorVisibility

Controls the cursor visibility in the terminal.

public static cursorVisibility(bool $showCursor): void

Parameters:

newLine

Print new lines based on specified count.

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

Parameters:

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.

getStd

Resolve a Terminal stream identifier to its PHP global stream.

Maps Terminal::STD_OUT, Terminal::STD_ERR, and Terminal::STD_INto their corresponding PHP predefined streams (STDOUT, STDERR, STDIN).

Any other value is returned as-is, allowing custom stream handlers.

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

Parameters:

Return Value:

resource|mixed - Returns the resolved PHP stream resource, or the original valueif it is not a recognized Terminal stream constant.

getSystemInfo

Retrieves key system and environment information in a structured array format.

This method collects details about the PHP runtime, operating system,terminal environment, and framework versions to provide a summarysuitable for diagnostics or display in CLI tools.

public static getSystemInfo(): array<int,array>

Return Value:

array<int,array{Name: string, Value: string}> - Return an associative array of system information.

getSystemId

Generates a consistent and unique system identifier for CLI authentication.

This method constructs a persistable identifier by hashing a combination of machine-specific and user-specific data, including the MAC address and key environment/system values.

The result is a unique hash that varies across machines, users, or terminal sessions.

public static getSystemId(string $prefix = '', string $algo = 'sha256', bool $binary = false): string

Parameters:

Return Value:

string - Return a hashed system identifier based on the specified algorithm.

getPid

Retrieves the parent process ID (PPID) of the current CLI session.

On Unix-like systems, this uses the ps command to obtain the PPID.

On Windows, it uses wmic to extract the parent process ID of the current process. This can help distinguish different terminal sessions or shells launched by the same user.

public static getPid(): string

Return Value:

string - Return the parent process ID, or '0' if unavailable.

getSystemModel

Retrieve the system's model name (e.g., MacBook Pro, Dell XPS).

public static getSystemModel(): string

Return Value:

string - Return model name or Unknown if not found.

getTerminalName

Retrieves the name of the terminal in use.

For Windows, it tries to detect PowerShell or Command Prompt.On Unix-based systems, it returns the TTY device name.

public static getTerminalName(): string

Return Value:

string - Terminal name or N/A if undetectable.

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.

This method determines if a command is help by search for flag --help or -h in command.

public static isHelp(string|array|null $command = null): 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.

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.

hasArgument

Determines if a specific command argument is present.

Supports both short (-f) and long (--flag) forms.

public static hasArgument(string $name): bool

Parameters:

Return Value:

bool - Returns true if the argument exists, 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.

_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|false

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 null based on the platform (Windows or Unix-like).

public static _shell(string $command): ?string

Parameters:

Return Value:

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