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.
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 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:
php <your Magento install dir>/bin/magento --list
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,
modulefor actions with modules,
infofor commands that provide some information)
- Workflow area (for example,
adminfor commands that can be used by an administrator,
devfor a developer)
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 is an action the command does.
// general commands: just a group and an action magento setup:install magento module:status // set of commands with a subject magento setup:config:set magento setup:config:delete magento setup:db-schema:upgrade magento setup:db-data:upgrade
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.
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
magento dev:theme:create frontend vendor themename
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).
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 (
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,
Format: single word or a compound word separated with a dash or hyphen character.
magento dev:theme:create --parent=Magento/luma frontend arg1 arg2 magento dev:theme:create -p=Magento/luma frontend vendor themename magento dev:theme:create --extend-from=Magento/luma frontend vendor themename magento module:disable -f Magento_Cms
--parent is an option that specifies a parent theme
-p is a shortcut for
-f is a shortcut for a non-value option
themename are arguments (see Command options and arguments).
Use options for:
- Optional data
- Required data that has a default value
// correct magento dev:theme:create --extend-from=Magento/luma frontend Foo bar magento module:disable --force Magento_Catalog magento module:disable -f Magento_Catalog //incorrect magento module:disable --force=1 Magento_Catalog 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.
myname:dev:theme:createis 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.