Laravel Artisan Command Input and Command Signatures

Most useful commands need to accept some sort of input from the user. The input can be as simple as requiring users to supply information in the form of parameters and options or can be more complicated by interactively entering data at the terminal. Command parameters are generally required data, but can have default values. Options are not necessarily required, and can be used as a sort of "flag" to change the behavior of the command's execution. Options must start with the -- (double hyphen) prefix.

Parameters and options are defined in the command's $signature property. The $signature is a simply a string constructed from specialized syntax for defining parameters and options). The signature must start with the terminal name of the command (such as make:model). Following the terminal name, any number of parameters or options can be defined as long as they are enclosed within curly braces ({ and }). When defining options within the signature, options must still start with the -- option prefix (options can also have shortcuts, which start with the - prefix).

#Input Parameters

For example, the following signature could be used to accept a user's first and last name:

1<?php
2 
3// ...
4 
5protected $signature = 'example:command {firstName} {lastName}';

Since the {firstName} and {lastName} input requirements were defined as parameters and do not define a default value, the command requires that arguments be supplied for them. Running the following command (without arguments):

1# Execute the example command without the required parameters.
2php artisan example:command

would result in an error similar to the following output:

1Not enough arguments (missing: "firstName, lastName").

The error message is indicating that the arguments for the firstName and lastName parameters have not been supplied. Arguments are given to command parameters in the order they appear in the command's signature. Supplying input to Artisan commands is as simple as supplying the value, separated by a space character. The following example would call the example:command command again with John being the value for firstName and Doe as the value for lastName:

1# Execute the example command with the required parameters.
2# 'John' would be the value of the firstName parameter.
3# 'Doe'  would be the value of the lastName  parameter.
4php artisan example:command John Doe

#Input Parameter Default Values

Command arguments can also have default values. Default values can be specified by assigning the argument a value within the signature. The following would assign the default value Doe to the lastName parameter. If a user does not specify any value when calling the command, the default value is used:

1<?php
2 
3// ...
4 
5// Assigning the lastName parameter a default value.
6protected $signature = 'example:command {firstName} {lastName=Doe}';

Now, when a user is executing the command, an argument for the lastName parameter is not required. The following two command calls would are equivalent:

1# Call the command, keeping the default value.
2php artisan example:command John
3 
4# Call the command, specifying a value for lastName.
5php artisan example:command John Doe

#Adding Descriptions to Command Parameters

If we were to display the help information for the hypothetical example:command at this point by adding the -h flag to the command execution:

1# Show the help information for the example:command
2php artisan example:command -h

The following information would be included in the output (the "Options" section of the output has been omitted for this section):

1Usage:
2  example:command <firstName> [<lastName>]
3
4Arguments:
5  firstName
6  lastName               [default: "Doe"]

The help information shows us each of the arguments, their order and any default values. As expected, a default value for lastName is shown (and is set to Doe). All of this information comes from the command's signature. As nice as the help information is, there are times when extra clarification for what an input argument is used for is not clear. To work around this issue, descriptions can be added to any input parameter or option by separating the argument or option declaration and description using a colon : character. The argument or option declaration should appear on the left side of the : character, and the description should appear on the right. The revised signature might look something like this:

1<?php
2 
3// ...
4 
5protected $signature = 'example:command
6        {firstName : The first name of the user.}
7        {lastName=Doe : The last name of the user}';

The resulting information would not include the descriptions in its output:

1Usage:
2  example:command <firstName> [<lastName>]
3
4Arguments:
5  firstName             The first name of the user.
6  lastName              The last name of the user [default: "Doe"]

#Command Options

So far the discussion has focused on command parameters. Options are also a useful way for users to provide input and control the execution of commands. Defining commands is similar to defining command parameters with the exception that option names begin with the two hyphen (--) prefix. The following signature defines the same two firstName and lastName parameters with an optional --age option:

1<?php
2 
3// ...
4 
5protected $signature = 'example:command
6        {firstName : The first name of the user.}
7        {lastName=Doe : The last name of the user}
8        {--age=}';

Notice, in the above example, that the --age option has a trailing equals (=) sign. This indicates that the end user can supply a value to the option. The absence of the trailing equals sign indicates that the option behaves like a switch or flag; flags can only assume a true or false value (a flag evaluates to true if the user specifies the flag and false if they do not).

A command with the signature above could be executed like so:

1# Call the command with all parameters, without options.
2php artisan example:command John Doe
3 
4# Call the command with all parameters and options.
5php artisan example:command John Doe --age=26
6 
7# Call the command with only the required parameters
8# and the available options.
9php artisan example:command John --age=26

#Command Option Default Values

It is also possible to specify a default value for the options. The following signature is similar to the previous one, except that the --age option will have a default value of 0 that will be used if the end user does not specify an age:

1<?php
2 
3// ...
4 
5protected $signature = 'example:command
6        {firstName : The first name of the user.}
7        {lastName=Doe : The last name of the user}
8        {--age=0}';

The new --age option will also appear in the help information:

1Usage:
2  example:command [options] [--] <firstName> [<lastName>]
3
4Arguments:
5  firstName             The first name of the user.
6  lastName              The last name of the user [default: "Doe"]
7
8Options:
9      --age[=AGE]        [default: "0"]

#Adding Descriptions to Command Options

You can see from the above output that the command accepts an --age option and it has a default value of 0. Although --age is fairly descriptive, it would be nice to give the option a good description. The process to add a description to options is the same as adding descriptions to parameters:

1<?php
2 
3// ...
4 
5protected $signature = 'example:command
6        {firstName : The first name of the user.}
7        {lastName=Doe : The last name of the user}
8        {--age=0 : The age of the user (optional);
9            "0" indicates age not disclosed.}';

The help information would now display the description for the --age option:

1...
2
3Options:
4      --age[=AGE]       The age of the user (optional); "0" indicates age not disclosed. [default: "0"]
5
6...

#Command Option Shortcuts

In practice, options can become long to type for the end user; this is partly a side effect of having to type the -- prefix along with the option name. To help alleviate this, options support shortcuts. In the previous example the --age option was used to demonstrate options. A shortcut could be created to allow the user to type -a instead of --age each time they wanted to use the --age option. Shortcuts are defined before the full option name, separated by a vertical bar (|) delimiter:

1<?php
2 
3// ...
4 
5protected $signature = 'example:command
6        {firstName : The first name of the user.}
7        {lastName=Doe : The last name of the user}
8        {--a|age=0}';

An options shortcut requires a slightly different prefix. Instead of using the double hyphen (--) prefix, shortcuts use a single hyphen (-) prefix. Executing a command with the above signature might look something like this:

1# Use the full option name
2php artisan example:command John Doe --age=26
3 
4# Use the option shortcut.
5php artisan example:command John Doe -a=26

Any option shortcuts that have been defined will also appear in the commands help output. Shortcuts will appear before the option in the output. Shortcuts will appear before the full option name in the help output.

The example command that has been used so far would produce help information similar to the following:

1...
2
3Options:
4  -a, --age[=AGE]        [default: "0"]
5
6...

#Using Command Options as Flags

So far the examples of command options make the assumption that the user is required to enter a value for a command option. Options can be used as flags or switches to change the execution behavior of the command. To have an option behave like a flag, simply omit the trailing equals (=) sign when defining the option in a command's signature. The following example signature adds an option to allow end users to indicate whether or not a particular user is an administrator:

 1<?php
 2 
 3// ...
 4 
 5protected $signature = 'example:command
 6        {firstName : The first name of the user.}
 7        {lastName=Doe : The last name of the user}
 8        {--age=0 : The age of the user (optional);
 9            "0" indicates age not disclosed.}
10        {--admin : Indicates whether not a user is an administrator.}';

A command with the signature above could be executed like so:

1# Indicate the user is an administrator.
2php artisan example:command John Doe --admin
3 
4# The user is not an administrator (the flag is omitted).
5php artisan example:command John Doe

#Array Parameters

Users can supply a list of information to commands using array parameters. To create an array parameter add an asterisk (*) character after the name of the input parameter in the command's signature. Array parameters do not have default value.

The following example adds a websites parameter to the example command. Notice the * character after the parameter name.

 1<?php
 2 
 3// ...
 4 
 5protected $signature = 'example:command
 6        {firstName : The first name of the user.}
 7        {lastName : The last name of the user}
 8        {websites* : The websites the user contributes to.}
 9        {--age=0 : The age of the user (optional);
10            "0" indicates age not disclosed.}
11        {--admin : Indicates whether not a user is an administrator.}';

Displaying the help information for this command would display something similar to the following output. Pay attention to how the websites parameter is expressed in the usage section:

1Usage:
2  example:command [options] [--]
3  <firstName> <lastName> <websites> (<websites>)...
4
5Arguments:
6  firstName             The first name of the user.
7  lastName              The last name of the user
8  websites              The websites the user contributes to.

An array parameter can be identified by the repeated parameter name in parenthesis. In the above example, it can be seen that the websites parameter is in fact an array because it is represented as <websites> (<websites>)... in the usage section.

The following example demonstrates how to execute a command with a signature similar to the previous example. The firstName is set to John; the last name is set to Doe; and the websites supplied are laravel.com, laracon.us and laracon.eu.

1php artisan example:command John Doe laravel.com laracon.us laracon.eu

There is now way to define a default value for an array argument in the command's signature. However, an effect similar to default array argument values can be achieved in the implementation of the command itself.

#Array Options

Lists of data can also be collected from the user using command options. The syntax is similar to defining command parameter arrays, the only difference is that the double hyphen (--) option prefix is required as well as the addition of an equals sign (=) when defining the array option. The following example rewrites the command array argument example as a command option instead:

 1<?php
 2 
 3// ...
 4 
 5protected $signature = 'example:command
 6    {firstName : The first name of the user.}
 7    {lastName : The last name of the user}
 8    {--age=0 : The age of the user (optional);
 9        "0" indicates age not disclosed.}
10    {--websites=* : The websites the user contributes to.}
11    {--admin : Indicates whether not a user is an administrator.}';

Notice that the websites option includes both the prefix and the =* suffix. The =* suffix is important and array options will not work without it. The following help information output shows how the command array option will be represented when viewing the help information. Array options can be identified easily since the name of the option will appear in brackets (this is [=WEBSITES] in the example output) as well as have the trailing text (multiple values allowed).

1Options:
2    ...
3    --websites[=WEBSITES]  The websites the user contributes to.
4      (multiple values allowed)
5    ...

A command with a signature similar to the above example could be executed like so:

1php artisan example:command John Doe --websites=laravel.com
2    --websites=laracon.us

When the command above is issued, the firstName value would be John, the lastName value would be Doe and the array of websites would contain laravel.com and laracon.us.

Similar to array arguments, array options cannot define a default value in the command's signature. A similar effect could be added later in the command's implementation.

#Making Input Arguments Optional

So far we've looked at defining command arguments with either required or default values. Another useful thing is to make command arguments optional. By default, an argument with a default value is categorized as an optional argument. However, arguments can be created without a default value and still be optional. To create an optional command argument, simply add a question mark (?) symbol after the argument's name.

The following example signature would define an argument named system that is optional:

1<?php
2 
3// ...
4 
5protected $signature = 'example:command
6    {system? : The system architecture.}';

There are a few things to take note of when viewing the help information for a command with a signature similar to the previous example:

1Usage:
2  example:command [<system>]
3
4Arguments:
5  system                The system architecture.

In the "Usage" section, we can see that the <system> argument has been placed inside brackets. Any argument or option that appears in brackets in the usage section is an optional argument or option.

A command with a signature similar to the previous example could be executed like so:

1# Execute the command without supplying an argument.
2php artisan example:command
3 
4# Execute the command while supplying an argument.
5php artisan example:command x64

Any type of command argument can be made optional, including argument arrays.

∎