PHP Luminova: CLI Commands Input Object

The Luminova's Command Input Object class provides a consistent way to access command arguments and options in both Base Console and Base Command controllers. It allows you to:

• Retrieve arguments by position
• Access named options or aliases
• Handle input for routed or direct CLI commands

This class simplifies building flexible CLI tools by giving a single interface to read all command input, no matter how the command is executed.

Note:

Both Base Console and Base Command controllers already provide a pre-initialized $input property.You can use it directly to access the executed command’s arguments and options—there’s no need to create a new Input instance.

Usages

Parsed Global Command

Simulate a command executed in CLI:

php /public/index.php blog list --limit=5 --no-header

Automatically parse executed command into input object using parseCommands method in Terminal class:

use Luminova\Command\Input;
use Luminova\Command\Terminal;

$input = new Input(Terminal::parseCommands(
    $_SERVER['argv'] ?? $argv
));

Manual Initialization

Manually parse an array of command structure to input object:

use Luminova\Command\Input;

$input = new Input([
    // Original CLI input without the PHP binary
    'command'   => 'blog list --limit=5 --no-header',

    // Resolved command name
    'name'      => 'list',

    // Command group namespace
    'group'     => 'blog',

    // Positional arguments
    'arguments' => ['param=value'],

    // Named options (option => value). Use null for flags without value
    'options'   => [
        'limit' => 5,
        'no-header' => null,
    ],

    // Full executed command string including PHP binary
    'input'     => 'php /public/index.php blog list param=value --limit=5 --no-header',

    // Parsed parameter values (e.g., values extracted from arguments)
    'params'    => ['value'],
]);

Access Input

Accessing values manually:

$commandName = $input->getCommand();       // 'list'
$group       = $input->getGroup();         // 'blog'
$arg         = $input->getArgument(0, false);     // 'param=value'
$argsVal     = $input->getParam(0);        // 'value'
$noHeader    = $input->getOption('no-header'); // true
$limit       = $input->getOption('limit');  // 5

Controller Examples

These examples show how the command input object can be used in both Base Console and Base Command controller classes.

Base Console Command

For a command executed like:

php novakit command --message=Hello -c=red

You can handle input in a console controller as follows:

// /app/Console/ConsoleCommand.php

use Luminova\Base\Console;

class ConsoleCommand extends Console 
{
    public function run(?array $options = []): int
    {
        // Access the command name
        // This can be used as routing
        $command = $this->input->getCommand();

        // Access argument by position
        $arg1 = $this->input->getArgument(1);

        // Access named option
        $message = $this->input->getOption('message');

        // Access named option or alias
        $color = $this->input->getAnyOption('color', 'c');

        return STATUS_SUCCESS;
    }
}

Routable Base Command

For a command defined in a routable controller, like:

php /public/index.php example hello --message=Hello -c=red

You can access the input in your Base Command controller:

// /app/Controllers/Cli/RoutableCommand.php

use Luminova\Base\Command;
use Luminova\Attributes\Route;
use Luminova\Attributes\Group;

#[Group(name: 'example')]
class RoutableCommand extends Command
{
    #[Route('hello', group: 'example')]
    public function helloMessage(): int 
    {
        // Access named option
        $message = $this->input->getOption('message');

        // Access named option or alias
        $color = $this->input->getAnyOption('color', 'c');

        return STATUS_SUCCESS;
    }
}

Tip:

Both Base Console and Base Command use the same $this->input object to handle command arguments and options, but Base Command integrates with routing, making it ideal for structured CLI controllers.

Class Definition

• Class namespace: Luminova\Command\Input

Methods

constructor

Create a command input object.

public __construct(array $command)

Parameters:

Command Options:

[
    'command'    => string,        // Original CLI input (without PHP binary)
    'name'       => string,        // Resolved command name.
    'group'      => string,        // Command group namespace.
    'arguments'  => string[],      // Raw positional arguments (e.g. ['limit=2'])
    'options'    => array<string,mixed>, // Named options (e.g. ['no-header' => null])
    'input'      => string,        // Full executable command string
    'params'     => string[],      // positional arguments values
];

replace

Replace the command input with new one.

public replace(array $command): self

Parameters:

Return Value:

Luminova\Command\Input - Returns instance of command input.

hasOption

Determine if an option was provided in the command input.

Supports both long (--option) and short (-o) forms.

public hasOption(string $option, ?string $alias = null): bool

Parameters:

Return Value:

bool - Returns true if the option or its alias exists, false otherwise.

getParam

Get command argument param value by index.

This method holds the extracted values from arguments, it shares same array index with getArgument ensuring correct vale is returned based on argument index.

Supports negative indexes:

• 1 => last param
• 2 => second last, etc.

public getParam(int $index = 0): mixed

Parameters:

Return Value:

mixed - Returns the argument param value, or null if not found.

getArgument

Get command argument by index.

Supports negative indexes:

• 1 => last argument
• 2 => second last, etc.

public getArgument(int $index = 0, bool $value = true): mixed

Parameters:

Return Value:

mixed - Returns the argument, or null if not found.

Note:Both getParam and getArgument shared same index for consistency.

getArguments

Get all command arguments.

public getArguments(): array

Return Value:

array - Return command arguments.

getCommand

Get executed command name.

Alias getName()

public getCommand(): ?string

Return Value:

string|null - Return the command name.

getGroup

Get executed command group namespace.

public getGroup(): ?string

Return Value:

string|null - Return the command group name.

getInput

Get raw executed command string.

public getInput(): ?string

Return Value:

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

getOptions

Returns the array of executed command option key values.

public getOptions(): array

Return Value:

array - Return array of executed command options.

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 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 using either the main option name or an alias.

This method allows you to retrieve a flag or arguments value, using The full name --option or short alias -o for lookup.

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

$which = $input->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.

getVerbose

Get the verbosity level from CLI options.

This method checks for both short (-v, -vv, -vvv)and long (--verbose or --verbose=<level>) flags.
Returns an integer level between 0 (silent) and max $verbosity (most verbose).

Level meaning:

• 0 = Silent or default mode
• 1 = Verbose
• 2 = More verbose
• 3 = Debug-level verbosity
• n = More-level verbosity

public getVerbose(
   string $short = 'v', 
   string $long = 'verbose', 
   int $verbosity = 3,
   int $default = 0
): int

Parameters:

Return Value:

int - Returns the verbosity level between 0 and $verbosity or default if not specified.

Example:

In Code:

$verbose = $input->getVerbose(verbosity: 5, default: 0);

In Command:

php novakit script -v           # returns 1
php novakit script -vv          # returns 2
php novakit script -vvv         # returns 3
php novakit script --verbose=2  # returns 2
php novakit script              # returns default level 0

getMethod

Returns the command controller class method name.

public getMethod(): ?string

Return Value:

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

getEntry

Gets a single command-line input entry by name.

This method returns an executed command entry information by the array index key, if it doesn't exists return null.

public getEntry(string $name): mixed

Parameters:

Return Value:

mixed - Return command option entry data.

getArray

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 getArray(): array

Return Value:

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

isHelp

Determine if the command is a help command.

public isHelp(): bool

Return Value:

bool - Returns true if the command is --help or its alias -h, false otherwise.

isNovakit

Determine if the command was executed via novakit.

public isNovakit(): bool

Return Value:

bool - Returns true if the command starts with novakit, false otherwise.

isDryRun

Determine if the command is a dry-run.

public isDryRun(): bool

Return Value:

bool - Returns true if the command includes the --dry-run option, false otherwise.

isNoHeader

Determine if the command was run with the 'no-header' option.

public isNoHeader(): bool

Return Value:

bool - Returns true if --no-header is present, false otherwise.

isNoColor

Determine if the command was run with the 'no-color' option.

public isNoColor(): bool

Return Value:

bool - Returns true if --no-color is present, false otherwise.

isNoAnsi

Determine if the command was run with the 'no-ansi' option.

public isNoAnsi(): bool

Return Value:

bool - Returns true if --no-ansi is present, false otherwise.

isVersion

Determine if the command was run with the version option.

Checks for --version or its short alias --v.

public isVersion(): bool

Return Value:

bool - Returns true if the command includes --version or --v, false otherwise.

isSystemInfo

Determine if the command was run with the 'system-info' option.

Checks for --system-info only (no short alias defined).

public isSystemInfo(): bool

Return Value:

bool - Returns true if the command includes --system-info, false otherwise.