Let Drupal 8 know about your module with an .info.yml file

Last updated on
11 February 2018

This documentation is incomplete. Add more information.

Main topic described: project metadata

A .info.yml file (aka, "info yaml file") is an essential part of a Drupal 8 module, theme, or install profile to store metadata about the project.

These .info.yml files are required to:

  • Notify Drupal about the existence of a module, theme, or install profile.
  • Provide information for the Drupal Web UI administration pages.
  • Provide criteria to control module activation and deactivation and Drupal version compatibility.
  • General administrative purposes in other contexts.

Hello World

The following is the hello_world.info.yml file we will be using. If you are following along, go ahead and create a new hello_world.info.yml file in your module's root folder, and paste this code into it.

name: Hello World Module
description: Creates a page showing "Hello World".
package: Custom

type: module
core: 8.x

Let's take a look at each line to see what it does.

The first three lines are primarily used in the administration UI when allowing users to enable or disable your module. The name and description keys provide the text that is shown on the module administration page and the package key allows you to group like modules together. Core, for example, uses package: Core to group all of the modules provided with Drupal 8 together, likewise you might use package: Custom to group all of your projects custom modules together making them easier to locate and enable.

The type key, which is new in Drupal 8, indicates the type of extension, e.g. module, theme, or profile.

For modules hosted on drupal.org, the version number will be filled in by the packaging script. You should not specify it manually, but leave out the version line entirely.

The core key specifies with which Drupal core version your module is compatible.

name, type and core are required keys.

Complete example

In addition to the basic properties shown in the previous example, there are also a number of optional properties. This is a complete example.

name: Hello World Module
description: Creates a page showing "Hello World".
package: Custom

type: module
core: 8.x

dependencies:
  - datetime:datetime
  - link:link
  - drupal:views

test_dependencies:
 - drupal:image

configure: hello_world.settings

php: 5.6

hidden: true

# Note: do not add the 'version'  property yourself!
# It will be added automatically by the packager on drupal.org.
version: 1.0
  • dependencies - A list of other modules your module depends on. Dependencies should be namespaced in the format {project}:{module}, where {project} is the project name as it appears in the Drupal.org URL (e.g. drupal.org/project/views) and {module} is the module's machine name. Dependencies can also include version restrictions, for examplewebform:webform (>=8.x-5.x). Note that if your module has dependencies on other contributed modules or libraries, these should be declared in the module's composer.json file
  • test_dependencies - A list of other modules in the process of being added as dependencies of your module. This allows testbot to correctly include new dependencies when running automated tests against patches that are submitted to the issue queue when they contain a new dependency. In general, you should add and commit new test_dependencies as soon as possible when considering a new dependency. This will allow testbot to function properly during the entire development process of whatever feature requires the new dependency. Once development of the feature requiring the new dependency is complete you should move the test dependency to the dependencies section. In the example above, testbot will include the image module during tests, but sites that install the "Hello World Module" will not be required to also install the image module. Test dependencies should be namespaced in the same manner as dependencies.
  • configure - If your module offers a configuration form, then you can specify the route to this form here. It will then show up as a link in the Extend page (/admin/modules) when the user expands the details.
  • php: 5.6  - Defines the minimal PHP version that is required for you module. Users will not be able to enable the module if they use an older PHP version. This can be used to avoid errors if your module uses newer functions that did not exists in earlier PHP versions.
  • hidden: true - This will hide your module from the module list on the Extend page (/admin/modules). You might find it useful to hide a module if it only contains tests, or is intended to serve as an example for developers who need to implement the main module's API. You can make these modules visible by adding $settings['extension_discovery_scan_tests'] = TRUE to your settings.php.

Debugging .info.yml files

Module is not listed on admin/modules

  • Ensure the info file is named {machine_name}.info.yml and is located in the root of the module directory.
  • Ensure that the file has this line.
    type: module
    
  • Ensure the module name starts either with a letter or an underscore. The following is an excerpt from the PHP documentation about valid function names.

    Function names follow the same rules as other labels in PHP. A valid function name starts with a letter or underscore, followed by any number of letters, numbers, or underscores. As a regular expression, it would be expressed thus: [a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*.

Module is listed on admin/modules but its checkbox is disabled.

  • Make sure that the core compatibility is set to 8.x.
    core: 8.x
    
  • Ensure that all the module dependencies are available. You can expand the module information to see which requirements are missing.
    expand_requirements.png
    Note that some modules have been moved out of Drupal 8 core, whereas other contributed modules have been moved into core or replaced by new core modules.

Module description is empty

  • Remember that the value of  description is used for the description.
    description: Example Module description.
    

Adding a composer.json file

In addition to declaring dependencies on other modules in the .info.yml, if a module is a contributed module on drupal.org wishes to test changes to module dependencies using drupalci as part of development, they must have a composer.json that expresses those drupal module dependencies (drupalci can only detect changes to dependencies in patches within composer.json, not in .info/info.yml files)

See also