Name and locate modules with conventions

There are two parts that make up naming a module: the vendor name and module name.

The vendor name comes first and is usually the company or person who has developed the module. The thing to remember about vendor names is they must be unique throughout the entire Magento ecosystem, so when you pick a vendor name, make sure it is different than what's already out there. If you are developing a module just for a specific client, you will probably want to use the company name of the client as the vendor name. If you think the module can be used across multiple Magento installs, it may be best to use your company name as the vendor name instead.

The second part is the module name, which should be something that gets to the root of what the module is or does, but without being overly long or verbose. Don't get too specific here. Keep it short & concise, but long enough to know what the module accomplishes.

Both vendor and module names need to start with an uppercase letter, and can't contain any non-alphanumeric characters like dashes or underscores. Type

bin/magento module:status

and you can see a list of modules that are registered within your Magento instance.

Note that there is an underscore which delimits the vendor name from the module name. Whenever Magento needs to reference a module in one string, it uses this special syntax.

We can see another example of this by connecting to the MySQL database and checking out the data within the setup_module table. This table keeps track of all of the active database schema and data versions of all modules. By referencing the Vendor underscore Module special syntax, Magento code can easily reference modules using a single string.

There are two different types of modules in Magento: local and distributed. Local modules are located within the app/code folder. Distributed modules can also be located here, but they are typically installed with Composer and are therefore instead located within the vendor folder.

Module development will typically always start within the app/code directory. When you create a module, you'll want to decide if it is going to be used just for this specific website, within multiple websites of a multi-store install, or if it is generic enough to be used for just about any Magento project. Determining this up front will help you know how to name this module, and where it will eventually be located within the filesystem.

For modules located in app/code, the subsequent directory is the vendor name, with a subdirectory under that of the module name. Remember that all of these names are case-sensitive, and it is imperative things are spelled correctly.

For distributed modules in the vendor directory, modules follow a bit of a different format. Since these modules are installed with Composer, they will take on the Composer vendor/package-name format. For example, if the Magento_Catalog module was located locally it would be located at app/code/Magento/Catalog, but since it was installed with Composer, it's located at vendor/magento/module-catalog.

Note that the casing of folder names within the vendor folder is all lowercase, as opposed to title case for app/code. If we open up the composer.json file within this module, we can see the name of the module known from Composer matches the folder hierarchy as it was installed from Composer.

There isn't any standard or hard rule of what these Composer hierarchies need to be, as they are driven from third-party code repositories. However all core Magento modules will be located within vendor/magento and be prefixed with a module-.

If we go further down the composer.json file, we'll see the PSR4 autoload property. Whenever Magento\Catalog is used as a namespace or class name, this autoload property automagically maps that name to this directory. The Composer autoload functionality is what makes modules located within the vendor folder possible.

Discussion

2 comments