Introduction to YAML in Drupal 8

YAML is a data serialisation format that is both powerful and easy for us humans to read and understand. In Drupal 8 it's used where Drupal needs a list but doesn’t need to execute PHP. One of the reasons why YAML was chosen for Drupal 8 is because it is already used in Symfony.

In last week’s introduction to namespacing tutorial, you saw YAML files used for the module info file and the route.

They are also used in Drupal 8 to replace info hooks in modules, declaring services, permissions and in the configuration management system.

A YAML file comprises of key and value pairs, separated with a colon. This is how a single line from a YAML file looks:

  1. name: Welcome

The key and value pair for this example is:

Key value pair in a YAML file

YAML files replaces .info files

In Drupal 7, .info files were used to provide information to Drupal about modules and themes. This information includes its human readable name, machine name, description, version number, any dependencies and so on. Without a .info file, Drupal wouldn't know that a module or theme existed.

Drupal 8 uses YAML (.yml) files instead of .info files.

Here is an example of the code in a YAML file. This is the code for the info.yml file for a module.

  1. name: Welcome
  2. type: module
  3. description: Display a message when a user logs in
  4. core: 8.x
  5. package: Custom

If you have done any Drupal 7 development, the information will look familiar. One of the key differences between Drupal 7 and 8 is that the key value pair are separated with an equals sign (“=“) in the INI format used in Drupal 7, and colon (“:”) in the YAML format used in Drupal 8. There needs to be a space after the colon.

YAML files define routes

In Drupal 8, YAML files do more than just provide information about modules and themes. As mentioned above, they are also used to define menu items, tabs, routes, services and so on.

Here is the example from last week’s email of the hello module route hello.routing.yml:

  1. hello.content:
  2. path: '/hello'
  3. defaults:
  4. _controller: 'Drupal\hello\Controller\FirstController::content'
  5. _title: 'Hello world'
  6. requirements:
  7. _permission: 'access content'


In the example above, some of the lines are indented. This is because YAML files support hierarchy via indentation.

Here is another example:

  1. first_module.admin:
  2. title: 'First module settings'
  3. description: 'A basic module to return hello world'
  4. parent: system.admin_config_development
  5. route_name: first_module.content
  6. weight: 100

In the above YAML, all lines below first_module.admin are indented, which means they are nested under first_module.admin. In YAML, this is called a compound data type, which sounds scary, but it a lot like an array in PHP. It means that everything listed under first_module.admin are children of it.

This would be the equivalent of the following PHP array:

  1. 'first_module.admin' => array(
  2. 'name' => 'First module settings',
  3. 'description' => 'A basic module to return hello world',
  4. 'parent' => 'system.admin_config_development',
  5. 'route_name' => 'first_module.content',
  6. 'weight' => '100',
  7. ),
  8. );

Hopefully it provides you with some context around YAML files. You’ll end up using YAML files a lot as you embark on Drupal 8 development.

If you liked this, you'll love my book, Conquer Drupal 8 Module Development.


In your opinion, what's the reasons that YAML files were brought into Drupal 8? What is it about them that can't be had by sticking with standard PHP?

The addition of this newest layer to the overall Drupal stack in 8.x is seen by many as an unnecessary inclusion and one that has added more headache than benefit. From my own experiences, this has, without a doubt, complicated things with little upfront gain to be experienced.

(But I'm sure it's leading to things--I'm just saying that it's difficult to see why this has been done when it hasn't made life any easier, which seems backwards.)

Great write up, btw.

Blair Wadman's picture

Good question. Here are some of the advantages that I see over standard PHP:

  • In Drupal 7, you define menu items and routes in hook_menu() in PHP. Drupal 8 replaces many hooks with a more modern architecture. I find writing routes and menu items in YAML files a cleaner way of doing it and it separates things out nicely. I suppose you could still do this with separate PHP files but that leads onto the next benefit..
  • YAML is very powerful and flexible but also much easier to read than the equivalent in PHP (see the array example).
  • YAML is easier to understand for developers from other platforms (YAML is widely used and supported by most programming languages). So they don't need to learn a "Drupalism" like a Drupal hook.
  • YAML is already used by Symfony and Drupal 8 is using a lot of Symfony. There are a lot of advantages in Drupal using the same concepts as the wider PHP community.

Hi, Blair,
Two questions about yaml using. 1. Where can I find the meaning of a key/value in a yaml file? For example, in your demo hello.routing.yml, there is a key
_permission: 'access...
where can I find the meaning of _permission and what value can be assinged to it without asking somebody else but finding it from Drupal official API/manual etc?
2. Where can I find the convention/rules for yaml files naming and structure? "hello.routing.yml" is simple so it is easy to name my own routing files. But like some configuration profile yaml files, they have a long name. Where can I find the rules to name my own?

Really I feel frustrated that I feel Drupal official API is not well organized or maybe just I didn't get it. I wasted couple of days trying to figure it out but have to give up. Could you help me with it?

How to have anchor link in description field of yaml.
for ex : if have project description in d7 like
description : 'Display a message when a user logs in. More info at <a href="" rel="nofollow">link</a>'

New comments for this tutorial have been turned off.