In this tutorial we're going to look at one the first files you will need in order to create a Drupal module: the info file. Each module is required to have a MODULE_NAME.info.yml file to help Drupal identify that a bundle of code is a unique module. This specially-formatted YAML file not only informs Drupal about the module, but also allows us to provide other useful metadata. In this tutorial, we'll walk through all of the metadata possibilities that can be included in an info file.
- Create an info file in YAML format with all of the required metadata for a custom Drupal module.
Every info file must contain certain keys in order for Drupal to be able to actually install the accompanying module. At a minimum you must provide:
- a name for your module
- a brief description of its functionality
- the type (module or theme)
- the major version of core supported by this code
These are the basics you need in place in order to see your module available on Drupal's installation screen. For a module called hello_world, here are the contents of hello_world/hello_world.info.yml
name: Hello World description: A silly example module type: module core: 8.x
Notice that our Hello World module has been added to a new group called Other on the module administration page. We can specify a different name for this group for organizational purposes by using the package key in our info file if desired.
The YAML info file can also specify dependencies. If our custom Hello World module is going to require code from other modules, whether core or contributed, we can explicitly list them. When dependencies are specified Drupal will not allow your module to be installed unless the dependencies can be satisified. This may be achieved by first installing other available modules, or Drupal may tell you that you need to download another contributed project before your new module can be enabled.
Dependencies should be a list of dependencies with the format
project is the machine name of the project as it appears in its Drupal.org project page URL and
module is the machine name of the module, which can be derived from the directory name that houses the module's code. Many times the project and the module name will be identical, but sometimes a project will contain several modules with distinct functionality. Use project name
drupal for modules in the core/ directory.
Example 1: List a contributed module as a dependency
- Project: Webform
- Project URL: https://www.drupal.org/project/webform
- Module machine name(s):
- Probably installed at: modules/contrib/webform
To list Webform module as a dependency for your module:
dependencies: - webform:webform
Example 2: List a core module as a dependency
- Project: Drupal (core)
- Project URL: https://www.drupal.org/project/drupal
- Module machine name(s): node
- Installation location: core/modules/node
To list Node module as a depdendency for your module:
dependencies: - drupal:node
Example 3: List a sub-module within a contributed project as a dependency
- Project: Devel
- Project URL: https://www.drupal.org/project/devel
- Module machine name(s): main module:
- Probably installed at: modules/contrib/devel, modules/contrib/devel/devel_generate, modules/contrib/devel/kint, modules/contrib/devel/webprofiler
To list Kint as a dependency for your module:
dependencies: - devel:kint
You can also define version restrictions on any listing, or even on Drupal's core system, for example,
drupal:system (>=8.2.0). This will result in a warning on the status report page that a module is incompatible with the core version.
Here is a complete example of what these dependencies would look like in our demo module's "info" file:
name: Hello World description: A silly example module type: module core: 8.x dependencies: - drupal:node - webform:webform - devel:kint - drupal:system (>=8.2.0)
In this case we're telling Drupal that our module can not be installed unless the core Node module is enabled and the contributed modules Webform and Kint (part of Devel) are enabled as well. Also, we're indicating that the module is compatible with Drupal core version 8.2.0 and higher.
The other main key you may find in info files is configure. Use this only if your module needs to provide particular configuration settings that are exposed to the site administrators. The
configure key in your module's info file specifies the route that will be used to navigate to the module's configuration settings form. A link to this configuration form will automatically be added to the module administration Extend page in the extended information about your module. For example, the REST UI module uses this value to provide a link to its configuration form.
And the corresponding restui.info.yml file:
name: REST UI type: module description: "Provides a user interface to manage REST resources" package: Web services core: 8.x configure: restui.list dependencies: - drupal:rest - drupal:system (>=8.2.0)
If you look at other info YAML files, especially from contributed modules you might notice additional key/value pairs. In particular, Drupal.org's packaging script adds information about the specific version and a datestamp for when that module was generated. None of this metadata is required in a custom module you develop, but can be useful when troubleshooting during development.
In this tutorial, we looked at the main elements that make up info files for Drupal modules. This type of file is required in order for Drupal to recognize our code as a module, and to get it to show up on the module administration's Extend page. At a minimum our info file needs to provide the name, description, type and core compatibility keys. Additional metadata specifying the dependencies of our module, the route to the configuration form may also be added.
Further your understanding
- Take a look at the info.yml files included with core and contributed modules on your site. Are there any additional options this tutorial doesn't cover?
- Use Drupal Console to generate a module. Look at the YAML file it generates. Are there any differences there?
- Try writing a info.yml file for one of your existing modules (without looking at the documentation). Did you get all of the dependencies correct?
- Introduction to YAML (Drupalize.Me)
- Drupal Console (Drupalize.Me)
- Let Drupal 8 know about your module with an .info.yml file (Drupal.org)
- Module version dependency in .info.yml is ineffective for patch releases (Drupal.org)