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.');