The YAML Component¶

The YAML Component loads and dumps YAML files.

What is it?¶

The Symfony2 YAML Component parses YAML strings to convert them to PHP arrays. It is also able to convert PHP arrays to YAML strings.

YAML, YAML Ain’t Markup Language, is a human friendly data serialization standard for all programming languages. YAML is a great format for your configuration files. YAML files are as expressive as XML files and as readable as INI files.

The Symfony2 YAML Component implements the YAML 1.2 version of the specification.

Installation¶

You can install the component in many different ways:

Use the official Git repository (https://github.com/symfony/Yaml);
Install it via PEAR ( pear.symfony.com/Yaml);
Install it via Composer (symfony/yaml on Packagist).

Why?¶

Fast¶

One of the goal of Symfony YAML is to find the right balance between speed and features. It supports just the needed feature to handle configuration files.

Real Parser¶

It sports a real parser and is able to parse a large subset of the YAML specification, for all your configuration needs. It also means that the parser is pretty robust, easy to understand, and simple enough to extend.

Clear error messages¶

Whenever you have a syntax problem with your YAML files, the library outputs a helpful message with the filename and the line number where the problem occurred. It eases the debugging a lot.

Dump support¶

It is also able to dump PHP arrays to YAML with object support, and inline level configuration for pretty outputs.

Types Support¶

It supports most of the YAML built-in types like dates, integers, octals, booleans, and much more...

Full merge key support¶

Full support for references, aliases, and full merge key. Don’t repeat yourself by referencing common configuration bits.

Using the Symfony2 YAML Component¶

The Symfony2 YAML Component is very simple and consists of two main classes: one parses YAML strings (Symfony\Component\Yaml\Parser), and the other dumps a PHP array to a YAML string (Symfony\Component\Yaml\Dumper).

On top of these two classes, the Symfony\Component\Yaml\Yaml class acts as a thin wrapper that simplifies common uses.

Reading YAML Files¶

The :method:`Symfony\\Component\\Yaml\\Parser::parse` method parses a YAML string and converts it to a PHP array:

use Symfony\Component\Yaml\Parser;

$yaml = new Parser();

$value = $yaml->parse(file_get_contents('/path/to/file.yml'));

If an error occurs during parsing, the parser throws a Symfony\Component\Yaml\Exception\ParseException exception indicating the error type and the line in the original YAML string where the error occurred:

use Symfony\Component\Yaml\Exception\ParseException;

try {
    $value = $yaml->parse(file_get_contents('/path/to/file.yml'));
} catch (ParseException $e) {
    printf("Unable to parse the YAML string: %s", $e->getMessage());
}

Tip

As the parser is re-entrant, you can use the same parser object to load different YAML strings.

When loading a YAML file, it is sometimes better to use the :method:`Symfony\\Component\\Yaml\\Yaml::parse` wrapper method:

use Symfony\Component\Yaml\Yaml;

$loader = Yaml::parse('/path/to/file.yml');

The :method:`Symfony\\Component\\Yaml\\Yaml::parse` static method takes a YAML string or a file containing YAML. Internally, it calls the :method:`Symfony\\Component\\Yaml\\Parser::parse` method, but with some added bonuses:

It executes the YAML file as if it was a PHP file, so that you can embed PHP commands in YAML files;
When a file cannot be parsed, it automatically adds the file name to the error message, simplifying debugging when your application is loading several YAML files.

Writing YAML Files¶

The :method:`Symfony\\Component\\Yaml\\Dumper::dump` method dumps any PHP array to its YAML representation:

use Symfony\Component\Yaml\Dumper;

$array = array('foo' => 'bar', 'bar' => array('foo' => 'bar', 'bar' => 'baz'));

$dumper = new Dumper();

$yaml = $dumper->dump($array);

file_put_contents('/path/to/file.yml', $yaml);

Note

Of course, the Symfony2 YAML dumper is not able to dump resources. Also, even if the dumper is able to dump PHP objects, it is considered to be a not supported feature.

If an error occurs during the dump, the parser throws a Symfony\Component\Yaml\Exception\DumpException exception.

If you only need to dump one array, you can use the :method:`Symfony\\Component\\Yaml\\Yaml::dump` static method shortcut:

use Symfony\Component\Yaml\Yaml;

$yaml = Yaml::dump($array, $inline);

The YAML format supports two kind of representation for arrays, the expanded one, and the inline one. By default, the dumper uses the inline representation:

{ foo: bar, bar: { foo: bar, bar: baz } }

The second argument of the :method:`Symfony\\Component\\Yaml\\Dumper::dump` method customizes the level at which the output switches from the expanded representation to the inline one:

echo $dumper->dump($array, 1);

foo: bar
bar: { foo: bar, bar: baz }

echo $dumper->dump($array, 2);

foo: bar
bar:
    foo: bar
    bar: baz

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¶

A string in YAML

'A singled-quoted string in YAML'

Tip

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

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

"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:

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

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

>
  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¶

# an integer
12

# an octal
014

# an hexadecimal
0xC

# a float
13.4

# an exponential number
1.2e+34

# 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:

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

# 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 (``- ``):

- PHP
- Perl
- Python

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

array('PHP', 'Perl', 'Python');

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

PHP: 5.2
MySQL: 5.1
Apache: 2.2.20

which is equivalent to this PHP code:

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:

PHP:    5.2
MySQL:  5.1
Apache: 2.2.20

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

"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:

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:

'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 ([]):

[PHP, Perl, Python]

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

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

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

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

"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 (#):

# 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.