The Yaml Component

Fast¶

One of the goals of Symfony Yaml is to find the right balance between speed and features. It supports just the needed features to handle configuration files. Notable lacking features are: document directives, multi-line quoted messages, compact block collections and multi-document 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.

Reading YAML Files¶

The parse() method parses a YAML string and converts it to a PHP array:

use SymfonyComponentYamlParser;

$yaml = new Parser();

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

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

use SymfonyComponentYamlExceptionParseException;

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

It may also be convenient to use the parse() wrapper method:

use SymfonyComponentYamlYaml;

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

The parse() static method takes a YAML string or a file containing YAML. Internally, it calls the parse() method, but enhances the error if something goes wrong by adding the filename to the message.

Writing YAML Files¶

The dump() method dumps any PHP array to its YAML representation:

use SymfonyComponentYamlDumper;

$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);

If an error occurs during the dump, the parser throws a DumpException exception.

If you only need to dump one array, you can use the dump() static method shortcut:

use SymfonyComponentYamlYaml;

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