The YAML Component
Edit this pageWarning: You are browsing the documentation for Symfony 2.1, which is no longer maintained.
Read the updated version of this page for Symfony 7.0 (the current stable version).
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.
Tip
Learn more about the Yaml component in the The YAML Format article.
Installation
You can install the component in 2 different ways:
- Use the official Git repository (https://github.com/symfony/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 (Parser), and the other dumps a PHP array to a YAML string (Dumper).
On top of these two classes, the Yaml class acts as a thin wrapper that simplifies common uses.
Reading YAML Files
The parse() method parses a YAML string and converts it to a PHP array:
1 2 3 4 5
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 ParseException exception indicating the error type and the line in the original YAML string where the error occurred:
1 2 3 4 5 6 7
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 parse() wrapper method:
1 2 3
use Symfony\Component\Yaml\Yaml;
$yaml = Yaml::parse('/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.
Executing PHP Inside YAML Files
2.1
The Yaml::enablePhpParsing()
method is new to Symfony 2.1. Prior to 2.1,
PHP was always executed when calling the parse()
function.
By default, if you include PHP inside a YAML file, it will not be parsed.
If you do want PHP to be parsed, you must call Yaml::enablePhpParsing()
before parsing the file to activate this mode. If you only want to allow
PHP code for a single YAML file, be sure to disable PHP parsing after parsing
the single file by calling Yaml::$enablePhpParsing = false;
($enablePhpParsing
is a public property).
Writing YAML Files
The dump() method dumps any PHP array to its YAML representation:
1 2 3 4 5 6 7 8 9 10 11 12
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 DumpException exception.
If you only need to dump one array, you can use the dump() static method shortcut:
1 2 3
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:
1
{ 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:
1
echo $dumper->dump($array, 1);
1 2
foo: bar
bar: { foo: bar, bar: baz }
1
echo $dumper->dump($array, 2);
1 2 3 4
foo: bar
bar:
foo: bar
bar: baz