Creating Commands

The Console component is a lightweight and powerful PHP library for building modern command-line applications with minimal effort. It provides everything you need to create structured CLI applications, including commands, arguments, options, aliases, input validation, interactive input, formatted output, tables, progress bars, loading spinners, colors, and more.

Its simple API and sensible defaults allow you to focus on your application's functionality instead of dealing with the complexity of CLI input and output handling.

Creating a Command

SigmaPHP provides a CLI utility for generating new commands. You can create a command using the create:command command followed by the desired class name.


./bin/sigma-cli create:command ValidateOrders

This command automatically generates a new command class inside your application's configured commands directory.

By default, commands are stored in app/Commands. You can customize this location through the commands_path setting in config/app.php.

/**
 * Console commands file path.
 */
'commands_path' => env('COMMANDS_PATH', 'app/Commands'),

This allows you to organize your command classes according to your application's structure without modifying the framework's internal implementation.

Command Structure

A Command represents an executable action within the The Console component application. Commands are responsible for defining the arguments and options they accept, processing user input, executing application logic, and communicating with the user through the console.

A command is typically created by extending the SigmaPHP\Console\Command abstract class and implementing the required command lifecycle methods.

<?php

namespace App\Commands;

use SigmaPHP\Console\Command;

class HelloCommand extends Command
{
    public function init()
    {
        $this->setName('hello');
        $this->setDescription('Print a greeting.');
    }

    public function execute()
    {
        $this->writeln('Hello World!');
    }
}

Initialization

The init() method is used to configure the command. This is where command metadata, arguments, options, and aliases can be defined.

public function init()
{
    $this->setName('hello');
    $this->setDescription('Print a greeting.');

    $this->addArgument(
        'name',
        'Name of the person to greet.',
        DataType::STRING
    );
}

Execution

The execute() method contains the actual command logic. It is called when the command is executed by the application.

public function execute()
{
    $this->writeln('Hello World!');
}

Arguments

Arguments represent positional values provided to a command.

Arguments are required by default. If a command defines an argument and the user does not provide it, The Console component will throw an exception during input processing.

For example:


./bin/sigma-cli hello Mohamed
    

Here, Mohamed is the value of the name argument.

Arguments and options can be provided in any order. Their position relative to each other is irrelevant.

For example, the following commands are equivalent:


./bin/sigma-cli hello Mohamed --verbose
    

and


./bin/sigma-cli hello --verbose Mohamed
    

The command parser identifies arguments and options independently, so options do not have to appear before or after arguments.

Adding an Argument

Use addArgument() to define an argument:

$this->addArgument(
    'name',
    'Name of the person to greet.',
    DataType::STRING
);

The method accepts the following parameters:

  • $name — Argument name.
  • $description — Description displayed in the help menu.
  • $dataType — Expected data type of the argument.

Getting an Argument

Use getArgument() to retrieve the value provided by the user:


$name = $this->getArgument('name');
    

For example:

public function execute()
{
    $name = $this->getArgument('name');

    $this->writeln("Hello {$name}!");
}

Checking an Argument

hasArgument() checks whether an argument was provided in the command input. It does not check whether the argument has been defined in the command.

if ($this->hasArgument('name')) {
    $this->writeln('A name was provided.');
}

Removing an Argument

An argument can be removed from the command definition using removeArgument().


$this->removeArgument('name');
    

Options

Options are named values or flags that can be provided to a command.

Unlike arguments, options are optional. A command can be executed without providing any of its defined options.

For example:


./bin/sigma-cli hello
    

The same command can optionally receive an option:


./bin/sigma-cli hello --name Mohamed
    

Options and arguments can appear in any order. Their position relative to each other is irrelevant.

For example, both of the following are valid:


./bin/sigma-cli hello Mohamed --verbose
    

and


./bin/sigma-cli hello --verbose Mohamed
    

Option Parameter Types

Each option can define whether it accepts a parameter. The Console component supports three parameter types:

  • PARAMETER_REQUIRED — The option must be followed by a parameter value.
  • PARAMETER_OPTIONAL — The option may be followed by a parameter value.
  • PARAMETER_NONE — The option does not accept a parameter and acts as a boolean flag.

The constants are defined as follows:

Option::PARAMETER_REQUIRED

Option::PARAMETER_OPTIONAL

Option::PARAMETER_NONE

Required Parameter

An option with a required parameter must receive a value.

$this->addOption(
    'connect',
    'c',
    'Connect to the specified host.',
    Option::PARAMETER_REQUIRED,
    DataType::STRING,
    null
);

It can be used with the following formats:


--connect localhost
--connect=localhost
-c localhost
-clocalhost
    

Optional Parameter

An option with an optional parameter may be used with or without a value.

$this->addOption(
    'verbose',
    'v',
    'Show detailed information.',
    Option::PARAMETER_OPTIONAL,
    DataType::STRING,
    null
);

No Parameter

An option with no parameter does not accept a value and acts as a boolean flag.

$this->addOption(
    'interactive',
    'i',
    'Enable interactive mode.',
    Option::PARAMETER_NONE,
    DataType::BOOL,
    false
);

It can be used simply as:

--interactive
-i

Adding an Option

Use addOption() to define an option:

$this->addOption(
    'name',
    'n',
    'Name of the person to greet.',
    Option::PARAMETER_REQUIRED,
    DataType::STRING,
    null
);

The method accepts the following parameters:

  • $name — Long option name.
  • $shortcut — Short option name.
  • $description — Description displayed in the help menu.
  • $parameterOptionality — Defines whether the option requires a parameter.
  • $dataType — Expected data type of the option value.
  • $defaultValue — Value used when the option is not provided.

Supported Option Patterns

The Console component supports several common option formats:


-i
--interactive
--connect xyz
--connect=xyz
-c=xyz
-cxyz
-ic
    

These patterns support long and short options, options with parameters, and combined short options.

For example, -i represents a short boolean option, while --interactive represents its long form.

An option that accepts a parameter can use either a space or an equals sign:


--connect xyz
--connect=xyz
    

Short options can also use the same forms:


-c=xyz
-cxyz
    

Multiple short boolean options can be combined:


-ic
    

This is equivalent to providing both -i and -c as separate short options when both options are defined as flags.

Getting an Option

Use getOption() to retrieve the value provided by the user:


$name = $this->getOption('name');
    

Checking an Option

hasOption() checks whether an option was provided in the command input. It does not check whether the option has been defined in the command.

if ($this->hasOption('verbose')) {
    $this->writeln('Verbose mode enabled.');
}
    

Removing an Option

An option can be removed from the command definition using removeOption().


$this->removeOption('verbose');
    

Data Types

Arguments and options can define an expected data type. The Console component provides four built-in data types.

  • DataType::STRING — A string value.
  • DataType::NUMBER — A numeric value, including integers and floating-point numbers.
  • DataType::LIST — A list of values.
  • DataType::BOOL — A boolean flag that does not accept a parameter.

String

DataType::STRING is used for textual values.

$this->addArgument(
    'name',
    'Name of the user.',
    DataType::STRING
);

For example:


./bin/sigma-cli user Ahmed
    

Number

DataType::NUMBER is used for numeric values and supports both integers and floating-point numbers.

$this->addArgument(
    'amount',
    'Amount to process.',
    DataType::NUMBER
);

Examples include:


./bin/sigma-cli process 100
    

And:


./bin/sigma-cli process 10.5
    

List

DataType::LIST is used when an input contains multiple values. A list is represented as an array:


['ahmed', 'omar']
    

For example, a list option can be used to provide multiple values to a command.

Boolean

DataType::BOOL represents a boolean option and does not accept a parameter.

For example:


--interactive
    

Or:


-i
    

A boolean option is enabled by providing the option itself.

Arguments and Options State

The command provides methods for determining whether arguments or options were provided by the user.

It is important to distinguish these methods from methods that inspect the command definition.

hasArgument() and hasOption() check the current command input. They determine whether the user actually supplied the corresponding argument or option; they do not determine whether an argument or option has been registered in the command.

Checking Arguments

Use argumentsAreEmpty() to check whether no arguments were provided:

if ($this->argumentsAreEmpty()) {
    $this->writeln('No arguments provided.');
}

Checking Options

Use optionsAreEmpty() to check whether no options were provided:

if ($this->optionsAreEmpty()) {
    $this->writeln('No options provided.');
}

Checking All Input

Use isEmpty() to determine whether neither arguments nor options were provided:

if ($this->isEmpty()) {
    $this->writeln('No input provided.');
}

These methods are useful when a command supports different execution modes depending on the input provided by the user.

Global Options

By default, every command inherits the application's global options, with the exception of the version option.

This means that options such as --help, --quiet, --silent, and --verbose are automatically available to commands without having to define them again.

For example, a command can use the application's --verbose option directly:


./bin/sigma-cli hello --verbose
    

Commands can also customize their inherited global options. An inherited option can be removed when it is not applicable to a particular command, or its configuration can be updated when different behavior is required.

For example, a command can remove an inherited option:


$this->removeOption('verbose');
    

A command can also define or update an option according to its own requirements:

$this->addOption(
    'verbose',
    'v',
    'Show detailed command information.',
    Option::PARAMETER_NONE,
    DataType::BOOL,
    false
);

The inherited global options therefore provide a common set of application-wide functionality while still allowing individual commands to customize the options available to them.

The version option is excluded from command inheritance because it is an application-level option and is handled by the application itself.

Command Aliases

A command can have one or more aliases. Aliases allow users to execute the same command using different names.

Use setAliases() to define aliases:

$this->setAliases([
    'greet',
    'hi'
]);

The command can then be invoked using any of its registered names.

Use getAliases() to retrieve the configured aliases:


$aliases = $this->getAliases();
    

Help Method

The help() method provides the command's help handler:


$this->help();
    

The help output can include the command description, arguments, options, aliases, and other information defined by the command.

Commands can use this method when custom logic needs to explicitly display their help information. The method can also be overridden by child commands when custom help behavior is required.

Input and Output

Commands provide a set of methods for interacting with the standard CLI streams through the command's IO handler.

Writing to Standard Output

Use write() to write text without automatically adding a new line:


$this->write('Processing...');
    

Use writeln() when a new line should be added:


$this->writeln('Processing complete.');
    

Both methods accept an optional style:


$this->writeln('Processing complete.', 'fg=green;bold');
    

Writing to Standard Error

Use writeErr() to write directly to the standard error stream:


$this->writeErr('Something went wrong.');
    

This is useful for errors and diagnostic messages that should be separated from normal command output.

Reading Input

Use read() to read input from the standard input stream:

$name = $this->read();

$this->writeln("Hello {$name}!");
    

The command's IO handler uses the application's configured input stream, making interactive input testable with custom streams.

Message Helpers

Commands provide several methods for displaying commonly used message types. These helpers offer a consistent way to communicate information and operation results without requiring every command to manually configure its output formatting.

Info

Use info() for informational messages:


$this->info('Starting the operation...');
    

Success

Use success() for successful operations:


$this->success('Operation completed successfully.');
    

Warning

Use warning() for warning messages:


$this->warning('The configuration file was not found.');
    

Error

Use error() for error messages:


$this->error('Unable to connect to the database.');
    
↑ Back to top