An Introduction to YAML

Video loading...

0:01
YAML with Joe Shindelar
0:06
As soon as you start writing code for Drupal 8,
0:09
you're going to encounter files that end in a .yml extension.
0:13
These are YAML files.
0:15
YAML is a data serialization format.
0:17
And I want to talk about why YAML and then look at the YAML syntax
0:21
so that when you encounter these files in all the various places
0:24
they're used Drupal, you'll have a better
0:26
understanding of what you're looking at.
0:28
In this tutorial, we'll look at why YAML is good for data
0:31
serialization, the YAML syntax, and then do some experimenting
0:35
with YAML in the context of Drupal to see how YAML
0:38
data structures are represented in PHP.
0:41
By the end of this lesson, you should be able to read and write
0:44
a YAML file and understand how the information it contains
0:47
will be represented as PHP data structures.
0:51
So YAML is an acronym.
0:53
And the acronym stands for YAML Ain't Markup Language.
0:56
It's a recursive acronym, kind of like PHP,
1:00
though the acronym is often confused with Yet Another Markup
1:04
Language, which is incorrect.
1:06
A markup language is something like XML or HTML,
1:09
which is a way of giving additional information to strings of text.
1:14
YAML, on the other hand, is a data serialization format.
1:18
It's intended to take complex data structures
1:20
and represent them in a human readable way that's also
1:23
easy for computer programming languages
1:26
to parse into their native data structures.
1:30
In this presentation, I want to talk about some of the strengths of YAML
1:33
as a data serialization format.
1:35
Then we'll take a look at the syntax of a YAML document
1:38
and how you can represent your variable data inside
1:42
of a YAML file.
1:43
And we'll talk about different YAML data types and collections.
1:48
So why YAML?
1:50
First off, it's easy to read.
1:53
There's no opening or closing tags that you have to worry about.
1:55
You just start up a text file and you
1:57
can start typing your YAML right into the file.
1:59
It is, after all, intended to be a human readable data serialization
2:04
format.
2:05
It's similar to JSON.
2:06
In fact, YAML is a superset of JSON.
2:09
So you can use JSON-like syntax within YAML.
2:12
But you can also use a little bit more friendly syntax.
2:14
And it doesn't require things like the opening
2:16
and closing curly braces that JSON does.
2:19
YAML is supported by almost every programming language.
2:22
Some languages have native support for YAML,
2:25
so it's built into the language itself.
2:28
Others, like PHP, don't have built in support,
2:30
but there are other libraries that you
2:32
can include that have YAML parsers.
2:34
YAML is smart about scalar data types.
2:37
So what does that mean?
2:39
It means that when you're writing a YAML value-- so you've
2:42
got your key value pair represented in YAML-- you can write a string
2:46
and not have to worry about putting quotation marks around it.
2:49
So I can, if I want to, put the string, hello world,
2:52
in quotation marks.
2:53
Or I can leave them out.
2:54
And YAML will figure out that that's a string.
2:57
It does the same for things like Boolean values.
3:00
I can write, true, and it will represent it
3:02
as the Boolean value true and not the string true.
3:05
Or the number one will be represented as an integer.
3:09
This makes it even more human friendly to read YAML files.
3:13
One of my favorite things about YAML files--
3:15
you can leave comments right in your YAML file.
3:17
There's not a ton of this throughout Drupal,
3:19
but it is a pretty neat feature.
3:20
So unlike some other data serialization formats where you
3:24
can't leave comments, this makes it even more human readable because I
3:27
can tell you more information about the data that's in the file.
3:30
And finally, one of the main reasons that Drupal is using YAML
3:35
is that the Symfony Framework, which Drupal is incorporating components
3:38
of as of Drupal version 8, is already making use of YAML.
3:43
So it made sense for the Drupal project
3:45
to continue to use the standard from the Symfony project,
3:49
which it's incorporating pieces of.
3:52
This is a really simple example of a value represented in a YAML file.
3:58
In YAML, you'll notice that there is one value per line in the file.
4:03
And every value is made up of a key, in a value pair.
4:07
Think of it like of an associative array
4:09
in PHP, the key being the variable name of the thing that you're
4:14
representing and then the value being the string or the integer
4:18
or whatever data it is that's in that variable.
4:21
In this example, you can see there's the key name, and then
4:24
colon, which acts as a separator, and then the value.
4:28
So all YAML values are represented like this.
4:30
You've got the key.
4:31
You've got a colon as the separator.
4:33
And then you've got the value.
4:35
Here's an example of a YAML file.
4:36
This one's actually taken straight out of Drupal's system module
4:39
so you can get an idea of what something like this
4:41
might look like.
4:42
In YAML, new lines are important and have
4:45
syntactically significant meaning, kind of like in Python.
4:49
So do tab characters.
4:51
YAML does not allow for literal tab characters at all-- spaces only--
4:56
but indentation is important because we
4:58
use it to represent lists or compound data types.
5:02
You'll note that there is in this example
5:04
one key/value pair per line.
5:06
So the first couple of key/value pairs are uuid being the key--
5:11
and it has a value of just a empty string-- name
5:14
being the key on the second line, and then
5:16
Drupalize.Me being the value.
5:18
Because YAML's smart about scalar data types,
5:21
it'll know that Drupalize.Me is actually a string, even though I
5:25
haven't put it in quotation marks.
5:27
A little bit further down, you see the value, page:.
5:30
And then under that, there's three lines, each of which
5:33
are indented two spaces.
5:35
This is what YAML refers to as a compound data type.
5:38
It's kind of like creating a list or an array
5:40
in other programming languages.
5:42
You're saying, all of the things under this indented by two spaces
5:47
are children of the page key.
5:49
YAML has support for a bunch of different scalar data types.
5:53
There is the basics, like strings.
5:55
So you could type a string with or without the quotation marks.
5:58
You can have an integer.
6:00
You can also have float values like pi or any decimal place value.
6:05
YAML or the YAML parser will automatically interpret those
6:08
as the appropriate scalar type within the programming language
6:11
that you're using.
6:12
So that would be represented as a PHP float.
6:15
True, false both interpreted as Boolean values.
6:19
Null will turn into a null value.
6:22
And then date time values will actually turn into Unix timestamps
6:27
in PHP.
6:28
So 2014-04-03 will turn into the Unix
6:32
timestamp representing that date.
6:35
YAML also has support for compound data types or collections.
6:40
You'll hear them referred to those kind of interchangeably.
6:43
Some people call it compound data.
6:44
Some call it collections.
6:45
Really what we're talking about is lists of things grouped
6:48
together under a single parent key.
6:50
These lists are also infinitely nestable,
6:52
kind of like an associative array in PHP,
6:55
where you can have it go any level deep.
6:57
The example on the left here is a list in YAML.
7:00
And what you'll end up with in PHP is an array that is just
7:05
numerically indexed-- so no keys in the index.
7:09
Notice how in YAML, you've got key colon and then
7:12
below that, two spaces and then a hyphen and the value.
7:16
Hyphen indicates this is a new element
7:19
in the list and then the value.
7:22
Of course, the 2 there will be represented as an integer,
7:24
and the other 2 will be strings.
7:26
On the right hand side, you've got an associative array.
7:29
Same thing-- you've got the initial key colon.
7:33
And then underneath it, nested in with two spaces, you've got
7:38
a key/value pair, name being the key,
7:42
joe being the string value here.
7:45
Places that you'll encounter YAML in Drupal-- really,
7:49
you're going to encounter YAML a lot where Drupal needs to get lists
7:52
of things that don't require code execution.
7:54
In a lot of cases, these are things that
7:56
used to be info hooks in Drupal 7.
7:58
So you have that paradigm of an info hook,
7:59
which returns an array of data.
8:01
A lot of that in Drupal 8 has been replaced by YAML files.
8:05
Other places that you'll encounter it
8:07
are info files for themes and modules and so forth.
8:11
Instead of using Drupal's sort of custom variation
8:14
of the php.ini syntax, we're now using YAML.
8:17
So those are all mytheme.info.yml or mymodule.info.yml files.
8:23
One of the killer features in Drupal 8
8:25
is the configuration management system.
8:27
And all of the data, all of the configuration data that it's
8:30
storing when it's written to disk, is stored in YAML format.
8:34
So you'll see YAML files used in that system quite a bit.
8:37
It's also in various other places too.
8:40
The new routing system, service declarations,
8:42
permissions, all of these things are defined in YAML files.
8:46
If you're curious about how Drupal handles the parsing of these YAML
8:50
files in turning them into PHP, take a look at the class
8:54
Drupal\Component\Serialization\YAML.
8:58
This is the class that is ultimately responsible for reading
9:00
in those files and parsing them into the PHP data structure
9:03
that you make use of.
9:05
If you want more information about the YAML language
9:09
and the syntax and language support and so forth,
9:11
take a look at the website www.yaml.org.
9:15
It doesn't look like much, but it does provide a lot of information
9:18
about the language.
9:21
If you want to play around with YAML in the context of Drupal,
9:23
which we're going to do right now, I've created a handy little module
9:27
to demonstrate what a YAML file will look like when
9:31
parsed into Drupal, or into PHP, rather.
9:34
You can get this module at drupal.org/project/yaml_sandbox.
9:42
It's a Drupal 8 module, super simple.
9:44
Download it and install it via the normal means.
9:47
And when you do so, what you'll end up with is this.
9:50
On a Drupal 8 site with the YAML Sandbox module enabled,
9:54
you've got a simple text area into which you can type YAML or copy
9:58
and paste YAML from a file in Drupal and then hit the Submit button.
10:02
And it'll show you the PHP representation of that data.
10:05
For example, I could type hello and then I could say hello world.
10:10
So I've got my key, hello, my separator, colon,
10:13
and then the string hello world.
10:15
And then I'll maybe have a one name number.
10:17
And we'll say 42.
10:21
When I submit this, all the module's doing
10:24
is using the Drupal YAML parser to turn this into a PHP data structure
10:29
and then using variable dump, var_dump, to print it to the page.
10:33
I've also got the Xdebug PHP extension installed.
10:36
So you do get a little bit prettier output with that.
10:38
But this is really great, because you can see, OK,
10:40
when this YAML in the text field here was read by PHP,
10:44
this is the data structure that it got interpreted to-- an array.
10:48
So all of the contents of that file were turned into a single array.
10:52
And you can see the hello key here maps to the hello key
10:55
in this associative array and that hello world
10:59
is turned into a string value of hello world.
11:02
42 was turned into an integer value.
11:05
You could also try some things that are a little more complex.
11:08
Let's try just to demonstrate some of the other scalar
11:12
types and things that you can do.
11:13
So I've just copy and pasted some text in here.
11:16
Let me expand this so you can see the whole thing.
11:19
So I've got an example of a float type, a scientific notation.
11:23
I didn't mention this in the presentation,
11:25
but YAML can also represent numbers in scientific notation.
11:29
We've got a Boolean, a null value, a date, a normal array,
11:34
or a YAML list, and associative array.
11:38
Let's click Submit on that one.
11:40
You can see how when this was parsed into PHP,
11:45
what that PHP data structure looks like.
11:47
Our float value turned into a float.
11:50
Our Boolean is the Boolean value true.
11:53
Our date was turned into a Unix timestamp.
11:56
And we've got a numerically indexed array
11:59
from our list and an associative array
12:02
from our associative array in YAML.
12:04
That covers all of the basics of YAML.
12:07
There's a few more complicated things
12:08
that you can do with the YAML language like anchors or aliases
12:12
for other values with a YAML file or joining sequences of things
12:17
together.
12:17
YAML is a superset of the JSON language.
12:20
So you can also put any JSON into this, and it should work.
12:23
This is what you'll need to know about YAML
12:25
though, in order to interact with the YAML system in various places
12:29
that you'll see it in the context of Drupal 8.

An Introduction to YAML

12 minutes 35 seconds // Drupal 9, Drupal 8 // HDCC //

YAML, which stands for YAML Ain't Markup Language, is a human-readable data serialization format that's been widely adopted in a variety of use cases in Drupal. Anyone wanting to write modules, or themes, for Drupal will need to understand YAML syntax. Even site builders are likely to encounter YAML at least in passing as YAML is the data-serialization format of choice for Drupal's configuration management system. Good thing it's pretty easy to learn even with the most basic of programming backgrounds.

This tutorial will look at the YAML data format and provide examples of how to write and read YAML. Starting with an introduction to the language's syntax and some of the strengths of YAML. Then looking at the difference between scalar data types like strings and integers, and collection data types like lists and associative arrays.

Since YAML in the Drupal world is read into PHP and ultimately becomes a PHP data structure that we can use in our own code we'll also look at how the YAML we write in a .yml file is represented in PHP data types. To do this we'll use the YAML Sandbox module that provides a handy textarea into which we can type YAML and have it parsed into PHP data structures.

Learning objectives

Explain what YAML is and its strengths as a data serialization format
Create scalar key/value pairs in YAML
Create lists, and associative arrays using YAML collections
Understand how the YAML you write is represented in PHP

Tips

In Drupal, use the .yml extension and not .yaml
Ensure your code editing application is configured to use spaces (preferably 2 spaces, as per Drupal coding standards), not the tab character when the TAB key is pressed. If you have tab characters in a YAML file within a Drupal environment, a fatal PHP error will be thrown and you'll see a White Screen of Death (WSOD).
Copy and paste from an existing YAML file to ensure the formatting is correct, and edit from there.

Additional resources:

http://www.yaml.org
YAML Sandbox module
Find other tutorials and external resources related to YAML on our YAML topic page (Drupalize.Me)