The YAML Format

Scalars

The syntax for scalars is similar to the PHP syntax.

1
2
3
4
5

A string in YAML

'A single-quoted string in YAML'

"A double-quoted string in YAML"

1

'A single quote '' inside a single-quoted string'

1

"A double-quoted string in YAML\n"

1
2
3

|
  \/ /| |\/| |
  / / | |  | |__

1
2
3
4
5
6
7
8
9
10
11
12
13

>
  This is a very long sentence
  that spans several lines in the YAML.

# This will be parsed as follows: (notice the trailing \n)
# "This is a very long sentence that spans several lines in the YAML.\n"

>-
  This is a very long sentence
  that spans several lines in the YAML.

# This will be parsed as follows: (without a trailing \n)
# "This is a very long sentence that spans several lines in the YAML."

1
2

# an integer
12

1
2

# an octal
0o14

1
2

# an hexadecimal
0xC

1
2

# a float
13.4

1
2

# an exponential number
1.2e+34

1
2

# infinity
.inf

1

2001-12-14T21:59:43.10-05:00

1
2

# simple date
2002-12-14

Collections

A YAML file is rarely used to describe a simple scalar. Most of the time, it describes a collection. YAML collections can be a sequence (indexed arrays in PHP) or a mapping of elements (associative arrays in PHP).

Sequences use a dash followed by a space:

1
2
3

- PHP
- Perl
- Python

The previous YAML file is equivalent to the following PHP code:

1

['PHP', 'Perl', 'Python'];

Mappings use a colon followed by a space (: ) to mark each key/value pair:

1
2
3

PHP: 5.2
MySQL: 5.1
Apache: 2.2.20

which is equivalent to this PHP code:

1

['PHP' => 5.2, 'MySQL' => 5.1, 'Apache' => '2.2.20'];

The number of spaces between the colon and the value does not matter:

1
2
3

PHP:    5.2
MySQL:  5.1
Apache: 2.2.20

YAML uses indentation with one or more spaces to describe nested collections:

1
2
3
4
5
6

'symfony 1.0':
  PHP:    5.0
  Propel: 1.2
'symfony 1.2':
  PHP:    5.2
  Propel: 1.3

The above YAML is equivalent to the following PHP code:

1
2
3
4
5
6
7
8
9
10

[
    'symfony 1.0' => [
        'PHP'    => 5.0,
        'Propel' => 1.2,
    ],
    'symfony 1.2' => [
        'PHP'    => 5.2,
        'Propel' => 1.3,
    ],
];

There is one important thing you need to remember when using indentation in a YAML file: Indentation must be done with one or more spaces, but never with tabulators.

You can nest sequences and mappings as you like:

1
2
3
4
5
6

'Chapter 1':
  - Introduction
  - Event Types
'Chapter 2':
  - Introduction
  - Helpers

YAML can also use flow styles for collections, using explicit indicators rather than indentation to denote scope.

A sequence can be written as a comma separated list within square brackets ([]):

1

[PHP, Perl, Python]

A mapping can be written as a comma separated list of key/values within curly braces ({}):

1

{ PHP: 5.2, MySQL: 5.1, Apache: 2.2.20 }

You can mix and match styles to achieve a better readability:

1
2

'Chapter 1': [Introduction, Event Types]
'Chapter 2': [Introduction, Helpers]

1
2

'symfony 1.0': { PHP: 5.0, Propel: 1.2 }
'symfony 1.2': { PHP: 5.2, Propel: 1.3 }

Comments

Comments can be added in YAML by prefixing them with a hash mark (#):

1
2
3

# Comment on a line
"symfony 1.0": { PHP: 5.0, Propel: 1.2 } # Comment at the end of a line
"symfony 1.2": { PHP: 5.2, Propel: 1.3 }

Explicit Typing

The YAML specification defines some tags to set the type of any data explicitly:

1
2
3
4
5
6
7
8
9
10
11
12
13

data:
    # this value is parsed as a string (it's not transformed into a DateTime)
    start_date: !!str 2002-12-14

    # this value is parsed as a float number (it will be 3.0 instead of 3)
    price: !!float 3

    # this value is parsed as binary data encoded in base64
    picture: !!binary |
        R0lGODlhDAAMAIQAAP//9/X
        17unp5WZmZgAAAOfn515eXv
        Pz7Y6OjuDg4J+fn5OTk6enp
        56enmleECcgggoBADs=

Symfony Specific Features

The Yaml component provides some additional features that are not part of the official YAML specification but are useful in Symfony applications:

• !php/const allows to get the value of a PHP constant. This tag takes the fully-qualified class name of the constant as its argument:

  1
  2

  data:
      page_limit: !php/const App\Pagination\Paginator::PAGE_LIMIT

• !php/object allows to pass the serialized representation of a PHP object (created with the serialize() function), which will be deserialized when parsing the YAML file:

  1
  2

  data:
      my_object: !php/object 'O:8:"stdClass":1:{s:3:"bar";i:2;}'

• !php/enum allows to use a PHP enum case. This tag takes the fully-qualified class name of the enum case as its argument:

  1
  2
  3
  4
  5

  data:
      # You can use the typed enum case...
      operator_type: !php/enum App\Operator\Enum\Type::Or
      # ... or you can also use "->value" to directly use the value of a BackedEnum case
      operator_type: !php/enum App\Operator\Enum\Type::Or->value

Unsupported YAML Features

The following YAML features are not supported by the Symfony Yaml component:

• Multi-documents (--- and ... markers);
• Complex mapping keys and complex values starting with ?;
• Tagged values as keys;
• The following tags and types: !!set, !!omap, !!pairs, !!seq, !!bool, !!int, !!merge, !!null, !!timestamp, !!value, !!yaml;
• Tags (TAG directive; example: %TAG ! tag:example.com,2000:app/) and tag references (example: !<tag:example.com,2000:app/foo>);
• Using sequence-like syntax for mapping elements (example: {foo, bar}; use {foo: ~, bar: ~} instead).