The Yaml Component
Warning: You are browsing the documentation for Symfony 6.2, which is no longer maintained.
Read the updated version of this page for Symfony 7.1 (the current stable version).
The Yaml Component
The Yaml component loads and dumps YAML files.
What is It?
The Symfony 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.
Tip
Learn more about YAML specifications.
Installation
1
$ composer require symfony/yaml
Note
If you install this component outside of a Symfony application, you must
require the vendor/autoload.php
file in your code to enable the class
autoloading mechanism provided by Composer. Read
this article for more details.
Why?
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 supports 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, octal numbers, 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 Symfony YAML Component
The Symfony Yaml component 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 Contents
The parse() method parses a YAML string and converts it to a PHP array:
1 2 3 4
use Symfony\Component\Yaml\Yaml;
$value = Yaml::parse("foo: bar");
// $value = ['foo' => 'bar']
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('...');
} catch (ParseException $exception) {
printf('Unable to parse the YAML string: %s', $exception->getMessage());
}
Reading YAML Files
The parseFile() method parses the YAML contents of the given file path and converts them to a PHP value:
1 2 3
use Symfony\Component\Yaml\Yaml;
$value = Yaml::parseFile('/path/to/file.yaml');
If an error occurs during parsing, the parser throws a ParseException
exception.
Writing YAML Files
The dump() method dumps any PHP array to its YAML representation:
1 2 3 4 5 6 7 8 9 10
use Symfony\Component\Yaml\Yaml;
$array = [
'foo' => 'bar',
'bar' => ['foo' => 'bar', 'bar' => 'baz'],
];
$yaml = Yaml::dump($array);
file_put_contents('/path/to/file.yaml', $yaml);
If an error occurs during the dump, the parser throws a DumpException exception.
Expanded and Inlined Arrays
The YAML format supports two kind of representation for arrays, the expanded one, and the inline one. By default, the dumper uses the expanded representation:
1 2 3 4
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 Yaml::dump($array, 1);
1 2
foo: bar
bar: { foo: bar, bar: baz }
1
echo Yaml::dump($array, 2);
1 2 3 4
foo: bar
bar:
foo: bar
bar: baz
Indentation
By default, the YAML component will use 4 spaces for indentation. This can be changed using the third argument as follows:
1 2
// uses 8 spaces for indentation
echo Yaml::dump($array, 2, 8);
1 2 3 4
foo: bar
bar:
foo: bar
bar: baz
Numeric Literals
Long numeric literals, being integer, float or hexadecimal, are known for their poor readability in code and configuration files. That's why YAML files allow to add underscores to improve their readability:
1 2 3 4 5
parameters:
credit_card_number: 1234_5678_9012_3456
long_number: 10_000_000_000
pi: 3.14159_26535_89793
hex_words: 0x_CAFE_F00D
During the parsing of the YAML contents, all the _
characters are removed
from the numeric literal contents, so there is not a limit in the number of
underscores you can include or the way you group contents.
Advanced Usage: Flags
Object Parsing and Dumping
You can dump objects by using the DUMP_OBJECT
flag:
1 2 3 4 5
$object = new \stdClass();
$object->foo = 'bar';
$dumped = Yaml::dump($object, 2, 4, Yaml::DUMP_OBJECT);
// !php/object 'O:8:"stdClass":1:{s:5:"foo";s:7:"bar";}'
And parse them by using the PARSE_OBJECT
flag:
1 2 3
$parsed = Yaml::parse($dumped, Yaml::PARSE_OBJECT);
var_dump(is_object($parsed)); // true
echo $parsed->foo; // bar
The YAML component uses PHP's serialize()
method to generate a string
representation of the object.
Caution
Object serialization is specific to this implementation, other PHP YAML
parsers will likely not recognize the php/object
tag and non-PHP
implementations certainly won't - use with discretion!
Parsing and Dumping Objects as Maps
You can dump objects as Yaml maps by using the DUMP_OBJECT_AS_MAP
flag:
1 2 3 4 5
$object = new \stdClass();
$object->foo = 'bar';
$dumped = Yaml::dump(['data' => $object], 2, 4, Yaml::DUMP_OBJECT_AS_MAP);
// $dumped = "data:\n foo: bar"
And parse them by using the PARSE_OBJECT_FOR_MAP
flag:
1 2 3 4
$parsed = Yaml::parse($dumped, Yaml::PARSE_OBJECT_FOR_MAP);
var_dump(is_object($parsed)); // true
var_dump(is_object($parsed->data)); // true
echo $parsed->data->foo; // bar
The YAML component uses PHP's (array)
casting to generate a string
representation of the object as a map.
Handling Invalid Types
By default, the parser will encode invalid types as null
. You can make the
parser throw exceptions by using the PARSE_EXCEPTION_ON_INVALID_TYPE
flag:
1 2
$yaml = '!php/object \'O:8:"stdClass":1:{s:5:"foo";s:7:"bar";}\'';
Yaml::parse($yaml, Yaml::PARSE_EXCEPTION_ON_INVALID_TYPE); // throws an exception
Similarly you can use DUMP_EXCEPTION_ON_INVALID_TYPE
when dumping:
1 2
$data = new \stdClass(); // by default objects are invalid.
Yaml::dump($data, 2, 4, Yaml::DUMP_EXCEPTION_ON_INVALID_TYPE); // throws an exception
Date Handling
By default, the YAML parser will convert unquoted strings which look like a
date or a date-time into a Unix timestamp; for example 2016-05-27
or
2016-05-27T02:59:43.1Z
(ISO-8601):
1
Yaml::parse('2016-05-27'); // 1464307200
You can make it convert to a DateTime
instance by using the PARSE_DATETIME
flag:
1 2
$date = Yaml::parse('2016-05-27', Yaml::PARSE_DATETIME);
var_dump(get_class($date)); // DateTime
Dumping Multi-line Literal Blocks
In YAML, multiple lines can be represented as literal blocks. By default, the dumper will encode multiple lines as an inline string:
1 2 3
$string = ["string" => "Multiple\nLine\nString"];
$yaml = Yaml::dump($string);
echo $yaml; // string: "Multiple\nLine\nString"
You can make it use a literal block with the DUMP_MULTI_LINE_LITERAL_BLOCK
flag:
1 2 3 4 5 6 7
$string = ["string" => "Multiple\nLine\nString"];
$yaml = Yaml::dump($string, 2, 4, Yaml::DUMP_MULTI_LINE_LITERAL_BLOCK);
echo $yaml;
// string: |
// Multiple
// Line
// String
Parsing PHP Constants
By default, the YAML parser treats the PHP constants included in the contents as
regular strings. Use the PARSE_CONSTANT
flag and the special !php/const
syntax to parse them as proper PHP constants:
1 2 3
$yaml = '{ foo: PHP_INT_SIZE, bar: !php/const PHP_INT_SIZE }';
$parameters = Yaml::parse($yaml, Yaml::PARSE_CONSTANT);
// $parameters = ['foo' => 'PHP_INT_SIZE', 'bar' => 8];
Parsing PHP Enumerations
The YAML parser supports PHP enumerations, both unit and backed enums.
By default, they are parsed as regular strings. Use the PARSE_CONSTANT
flag
and the special !php/enum
syntax to parse them as proper PHP enums:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
enum FooEnum: string
{
case Foo = 'foo';
case Bar = 'bar';
}
// ...
$yaml = '{ foo: FooEnum::Foo, bar: !php/enum FooEnum::Foo }';
$parameters = Yaml::parse($yaml, Yaml::PARSE_CONSTANT);
// the value of the 'foo' key is a string because it missed the `!php/enum` syntax
// $parameters = ['foo' => 'FooEnum::Foo', 'bar' => FooEnum::Foo];
$yaml = '{ foo: FooEnum::Foo, bar: !php/enum FooEnum::Foo->value }';
$parameters = Yaml::parse($yaml, Yaml::PARSE_CONSTANT);
// the value of the 'foo' key is a string because it missed the `!php/enum` syntax
// $parameters = ['foo' => 'FooEnum::Foo', 'bar' => 'foo'];
6.2
The support for PHP enumerations was introduced in Symfony 6.2.
Parsing and Dumping of Binary Data
Non UTF-8 encoded strings are dumped as base64 encoded data:
1 2 3 4
$imageContents = file_get_contents(__DIR__.'/images/logo.png');
$dumped = Yaml::dump(['logo' => $imageContents]);
// logo: !!binary iVBORw0KGgoAAAANSUhEUgAAA6oAAADqCAY...
Binary data is automatically parsed if they include the !!binary
YAML tag:
1 2 3
$dumped = 'logo: !!binary iVBORw0KGgoAAAANSUhEUgAAA6oAAADqCAY...';
$parsed = Yaml::parse($dumped);
$imageContents = $parsed['logo'];
Parsing and Dumping Custom Tags
In addition to the built-in support of tags like !php/const
and
!!binary
, you can define your own custom YAML tags and parse them with the
PARSE_CUSTOM_TAGS
flag:
1 2 3 4 5
$data = "!my_tag { foo: bar }";
$parsed = Yaml::parse($data, Yaml::PARSE_CUSTOM_TAGS);
// $parsed = Symfony\Component\Yaml\Tag\TaggedValue('my_tag', ['foo' => 'bar']);
$tagName = $parsed->getTag(); // $tagName = 'my_tag'
$tagValue = $parsed->getValue(); // $tagValue = ['foo' => 'bar']
If the contents to dump contain TaggedValue objects, they are automatically transformed into YAML tags:
1 2 3 4 5
use Symfony\Component\Yaml\Tag\TaggedValue;
$data = new TaggedValue('my_tag', ['foo' => 'bar']);
$dumped = Yaml::dump($data);
// $dumped = '!my_tag { foo: bar }'
Dumping Null Values
The official YAML specification uses both null
and ~
to represent null
values. This component uses null
by default when dumping null values but
you can dump them as ~
with the DUMP_NULL_AS_TILDE
flag:
1 2 3 4 5
$dumped = Yaml::dump(['foo' => null]);
// foo: null
$dumped = Yaml::dump(['foo' => null], 2, 4, Yaml::DUMP_NULL_AS_TILDE);
// foo: ~
Syntax Validation
The syntax of YAML contents can be validated through the CLI using the LintCommand command.
First, install the Console component:
1
$ composer require symfony/console
Create a console application with lint:yaml
as its only command:
1 2 3 4 5 6 7 8 9
// lint.php
use Symfony\Component\Console\Application;
use Symfony\Component\Yaml\Command\LintCommand;
(new Application('yaml/lint'))
->add(new LintCommand())
->getApplication()
->setDefaultCommand('lint:yaml', true)
->run();
Then, execute the script for validating contents:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
# validates a single file
$ php lint.php path/to/file.yaml
# or validates multiple files
$ php lint.php path/to/file1.yaml path/to/file2.yaml
# or all the files in a directory
$ php lint.php path/to/directory
# or all the files in multiple directories
$ php lint.php path/to/directory1 path/to/directory2
# or contents passed to STDIN
$ cat path/to/file.yaml | php lint.php
# you can also exclude one or more files from linting
$ php lint.php path/to/directory --exclude=path/to/directory/foo.yaml --exclude=path/to/directory/bar.yaml
The result is written to STDOUT and uses a plain text format by default.
Add the --format
option to get the output in JSON format:
1
$ php lint.php path/to/file.yaml --format json
Tip
The linting command will also report any deprecations in the checked YAML files. This may for example be useful for recognizing deprecations of contents of YAML files during automated tests.