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.

• Class namespace: \Luminova\Command\Terminal

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();

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 Field

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 an input:

<?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 misaligning 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:

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.

final 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.

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

Parameters:

spinner

Displays a rotating spinner animation in the CLI.

final 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.

final 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.

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

Parameters:

Progress Callback Signature:

Receiving the current progress percentage using $onProgress Closure.

function(float|int $step): void {
    // Your implementation here
}

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.

final 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']).

final 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.

final 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 options for retry attempts and a timeout.

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

Parameters:

Return Value:

string - Return the client inputted password.

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.

final 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.

final 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.

final 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.

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

Parameters:

Return Value:

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

wrap

Wrap a text with padding left and width to a maximum number.

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

Parameters:

Return Value:

string - Return wrapped text with padding left and width.

card

Generate a card like with text centered within the card.

final 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 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.

input

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

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

Parameters:

Return Value:

string - Return user input string.

validate

Command user input validation on prompts.

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

Parameters:

Return Value:

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

escape

Escape command arguments for safe execution.

final public static escape(string|array $argument): string

Parameters:

Return Value:

string - Return the escaped command string.

replace

Replace command placeholders with environment variables.

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

Parameters:

Return Value:

string - Return replaced command string to be executed.

Throws:

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

error

Display card error message using red background and white text as default.

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

Parameters:

success

Display card success message, using green background and white text as default.

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

Parameters:

writeln

Print text to in a newline using stream STDOUT.

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

Parameters:

write

Print text to without a newline applied using stream STDOUT.

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

Parameters:

print

Print a message to using using echo.

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

Parameters:

fwrite

Write text to stream resource with any handler as needed,If called in non-command context, it will output text using echo.

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

Parameters:

clear

Clears all the output in console screen.

final public static clear(): void

flush

Clears console output to update new text.

final public static flush(): void

color

Apply color and text formatting to the given text if color is supported.

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

Parameters:

Return Value:

string - Return colored text if color is supported, otherwise return default text.

See Documentation Reference

• For more details about color formatting read documentation here.
• For more details about text formatting read documentation here.

newLine

Print new lines based on specified count.

final 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 header and rows to the console.

public static table(
    string[] $headers, 
    array<string,string> $rows, 
    ?string $headerColor = null, 
    int $headerPadding = 1
): void

Parameters:

streamSupports

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

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

Parameters:

Return Value:

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

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.

getArgument

Get command argument by index number.

final public static getArgument(int $index): mixed

Parameters:

Return Value:

mixed - Return command argument by index number.

getArguments

Get command arguments.

final public static getArguments(): array

Return Value:

array - Return command arguments.

getCommand

Get command name.

final public static getCommand(): ?string

Return Value:

string|null - Return the command name.

getCaller

Get command caller command string.

final 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.

final 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.

final 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.

final 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.

final 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.

final 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.

final public static getQueries(): array

Return Value:

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

isColorSupported

Check if the command line supports color formatting for specific STD.

final public static isColorSupported(resource|string $resource = STDOUT): bool

Parameters:

Return Value:

bool - Return true if the resource supports color formatting.

Note: On windows you must specify the stream resource (e.g, STDIN, STDOUT or STDERR).

isMacTerminal

Checks whether the current terminal is mac terminal.

final 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 STD resource to check on.

final public static isWindowsTerminal(resource|string $resource): bool

Parameters:

Return Value:

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

isLinuxTerminal

Determines if the current terminal is a supported Linux terminal.

final public static isLinuxTerminal(): bool

Return Value:

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

isAnsiSupported

Checks if the current terminal supports ANSI escape sequences.

final public static isAnsiSupported(): bool

Return Value:

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

isPtySupported

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

final public static isPtySupported(): bool

Return Value:

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

isTtySupported

Checks if the current system supports TTY (Teletypewriter).

final public static isTtySupported(): bool

Return Value:

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

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.

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.

header

Print NovaKit Command line header information.

final public static header(): void