Command naming guidelines
Naming guideline overview
Magento 2 introduces a new command-line interface (CLI) that enables component developers to plug in commands provided by modules.
As an extension developer, you can now create and distribute your own commands for Magento applications. But as for any implementation, it’s also important to follow some general conventions to keep your commands consistent with commands from other developers. Being consistent in this way reduces the user’s learning curve.
This topic discusses our recommended naming conventions.
Command name
A command name is a part of the command, which defines behavior of the command on the very high level. In the command it goes right after the command’s name.
For example, in bin/magento setup:upgrade
, bin/magento
is the command’s name and setup:upgrade
is the name of the command.
If you have a Magento installation handy, enter the following to display the current list of commands:
1
bin/magento list
Format: group:[subject:]action
group
group
represents a group of related commands. Commands in a group display in a list, which in turn makes it easier for the user to find the desired command. To find a group name for a command, imagine an subject area where it can be used. The subject area can be any of the following:
- Domain area (for example,
module
for actions with modules,info
for commands that provide some information) - Workflow area (for example,
admin
for commands that can be used by an administrator,dev
for a developer)
subject
subject
is a subject for the action. The subject is optional, but it can be useful for defining sets of commands that work with the same object. If a subject is represented by a compound word, use a dash or hyphen character to separate the words.
action
action
is an action the command does.
Examples
1
2
3
4
5
6
7
8
9
// general commands: just a group and an action
bin/magento setup:install
bin/magento module:status
// set of commands with a subject
bin/magento setup:config:set
bin/magento setup:config:delete
bin/magento setup:db-schema:upgrade
bin/magento setup:db-data:upgrade
db-schema
and db-data
are examples of compound words.
Command options and arguments
Options and arguments follow the command name and modify the command’s behavior.
For example, in bin/magento module:disable --force Magento_Catalog
, the --force
option and the Magento_Catalog
argument bypass the restrictions and specify a particular module to be disabled; in this case, regardless of dependencies on other modules.
Options and arguments create different user experiences. As a developer, you can choose which type of input is better for your particular case.
Command arguments
Arguments are values passed by the user in a specified order. The argument name is not visible to the user.
Format: single word or a compound word separated with a dash or hyphen character
Example:
1
bin/magento dev:theme:create frontend vendor themename
where:
frontend
is a subject area argument
vendor
is a vendor argument
themename
is a theme name argument
Use arguments when you need required data from the user. We recommend as few arguments as possible (no more then three) so the user will not confuse their order.
To make it simpler for the user, we recommend the following:
- Run the CLI multiple times for providing multiple similar values instead of running it once with 20 values
-
Use default values for required arguments where possible.
You can then use options instead of arguments to minimize the amount of required data the user must enter.
- Replace arguments with options: options are named, so the user can provide them in any order. This requires additional data validation (by default, all options are optional).
Command Options
Options are name-value pairs. The sequence of entered values doesn’t matter.
An option can have a value or no value. An option that does not require a value represents a flag (yes
or no
).
An option can also have a one-letter shortcut as an alternative to its full name. Enable shortcuts for often-used options or if it’s easy to determine what the shortcut means. Usually it makes sense to enable shortcuts for options similar to the ones used in widely-used commands (for example, -f
for --force
, -v
for --verbose
, -h
for --help
).
Format: single word or a compound word separated with a dash or hyphen character.
For example,
1
bin/magento dev:theme:create --parent=Magento/luma frontend arg1 arg2
1
bin/magento dev:theme:create -p=Magento/luma frontend vendor themename
1
bin/magento dev:theme:create --extend-from=Magento/luma frontend vendor themename
1
bin/magento module:disable -f Magento_Cms
Where:
--parent
is an option that specifies a parent theme
-p
is a shortcut for --parent
-f
is a shortcut for a non-value option --force
arg1
, arg2
, frontend
, vendor
and themename
are arguments (see Command options and arguments).
Use options for:
- Optional data
- Required data that has a default value
Example:
1
2
3
4
5
6
7
8
// correct
bin/magento dev:theme:create --extend-from=Magento/luma frontend Foo bar
bin/magento module:disable --force Magento_Catalog
bin/magento module:disable -f Magento_Catalog
//incorrect
bin/magento module:disable --force=1 Magento_Catalog
bin/magento module:disable -f=yes Magento_Catalog
Recommendations to avoid naming collisions
To avoid naming your command the same as another command, we recommend:
-
Looking at other extensions in the Magento Marketplace before you choose a name for your commands. By planning ahead, you can avoid naming collisions entirely.
-
Restricting command names to start with a unique name, such as a vendor name. The usability of the command depends on what you choose for a vendor name.
For example,
myname:dev:theme:create
is not obvious and is hard to remember.The vendor name doesn’t have to start the command name; it could be in the middle. This way, related commands are grouped together.
Examples:
1 2
dev:myname:theme:create dev:myname:theme:delete
Related topic