Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • SensioLabs Professional services to help you with Symfony
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by SensioLabs
  1. Home
  2. Documentation
  3. Components
  4. Yaml
  5. The YAML Format
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

Table of Contents

  • Scalars
    • Strings
    • Numbers
    • Nulls
    • Booleans
    • Dates
  • Collections
  • Comments

The YAML Format

Edit this page

Warning: You are browsing the documentation for Symfony 2.0, which is no longer maintained.

Read the updated version of this page for Symfony 6.2 (the current stable version).

The YAML Format

According to the official YAML website, YAML is "a human friendly data serialization standard for all programming languages".

Even if the YAML format can describe complex nested data structure, this chapter only describes the minimum set of features needed to use YAML as a configuration file format.

YAML is a simple language that describes data. As PHP, it has a syntax for simple types like strings, booleans, floats, or integers. But unlike PHP, it makes a difference between arrays (sequences) and hashes (mappings).

Scalars

The syntax for scalars is similar to the PHP syntax.

Strings

1
A string in YAML
1
'A singled-quoted string in YAML'

Tip

In a single quoted string, a single quote ' must be doubled:

1
'A single quote '' in a single-quoted string'
1
"A double-quoted string in YAML\n"

Quoted styles are useful when a string starts or ends with one or more relevant spaces.

Tip

The double-quoted style provides a way to express arbitrary strings, by using \ escape sequences. It is very useful when you need to embed a \n or a unicode character in a string.

When a string contains line breaks, you can use the literal style, indicated by the pipe (|), to indicate that the string will span several lines. In literals, newlines are preserved:

1
2
3
|
  \/ /| |\/| |
  / / | |  | |__

Alternatively, strings can be written with the folded style, denoted by >, where each line break is replaced by a space:

1
2
3
4
5
>
  This is a very long sentence
  that spans several lines in the YAML
  but which will be rendered as a string
  without carriage returns.

Note

Notice the two spaces before each line in the previous examples. They won't appear in the resulting PHP strings.

Numbers

1
2
# an integer
12
1
2
# an octal
014
1
2
# an hexadecimal
0xC
1
2
# a float
13.4
1
2
# an exponential number
1.2e+34
1
2
# infinity
.inf

Nulls

Nulls in YAML can be expressed with null or ~.

Booleans

Booleans in YAML are expressed with true and false.

Dates

YAML uses the ISO-8601 standard to express dates:

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. A collection can be a sequence or a mapping of elements. Both sequences and mappings are converted to PHP arrays.

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
array('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
array('PHP' => 5.2, 'MySQL' => 5.1, 'Apache' => '2.2.20');

Note

In a mapping, a key can be any valid scalar.

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 following YAML is equivalent to the following PHP code:

1
2
3
4
5
6
7
8
9
10
array(
  'symfony 1.0' => array(
    'PHP'    => 5.0,
    'Propel' => 1.2,
  ),
  'symfony 1.2' => array(
    '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 tabulations.

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 }

Note

Comments are simply ignored by the YAML parser and do not need to be indented according to the current level of nesting in a collection.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    We stand with Ukraine.
    Version:
    Measure & Improve Symfony Code Performance

    Measure & Improve Symfony Code Performance

    Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).

    Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).

    Symfony footer

    ↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

    Avatar of Mike Zukowsky, a Symfony contributor

    Thanks Mike Zukowsky for being a Symfony contributor

    1 commit • 6 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Deployed on

    Follow Symfony