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

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.

1
2
3
4

foo: bar
bar:
    foo: bar
    bar: baz

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

1
2

// uses 8 spaces for indentation
echo Yaml::dump($array, 2, 8);

1
2
3
4

foo: bar
bar:
        foo: bar
        bar: baz

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

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.

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

Scalars

The syntax for scalars is similar to the PHP syntax.

1
2
3
4
5

A string in YAML

'A single-quoted string in YAML'

"A double-quoted string in YAML"

1

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

1

"A double-quoted string in YAML\n"

1
2
3

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

1
2
3
4
5
6
7
8
9
10
11
12
13

>
  This is a very long sentence
  that spans several lines in the YAML.

# This will be parsed as follows: (notice the trailing \n)
# "This is a very long sentence that spans several lines in the YAML.\n"

>-
  This is a very long sentence
  that spans several lines in the YAML.

# This will be parsed as follows: (without a trailing \n)
# "This is a very long sentence that spans several lines in the YAML."

1
2

# an integer
12

1
2

# an octal
0o14

1
2

# an hexadecimal
0xC

1
2

# a float
13.4

1
2

# an exponential number
1.2e+34

1
2

# infinity
.inf

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. YAML collections can be a sequence (indexed arrays in PHP) or a mapping of elements (associative arrays in PHP).

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

['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

['PHP' => 5.2, 'MySQL' => 5.1, 'Apache' => '2.2.20'];

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

1
2
3
4
5
6
7
8
9
10

[
    'symfony 1.0' => [
        'PHP'    => 5.0,
        'Propel' => 1.2,
    ],
    'symfony 1.2' => [
        '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 tabulators.

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 }

Explicit Typing

The YAML specification defines some tags to set the type of any data explicitly:

1
2
3
4
5
6
7
8
9
10
11
12
13

data:
    # this value is parsed as a string (it's not transformed into a DateTime)
    start_date: !!str 2002-12-14

    # this value is parsed as a float number (it will be 3.0 instead of 3)
    price: !!float 3

    # this value is parsed as binary data encoded in base64
    picture: !!binary |
        R0lGODlhDAAMAIQAAP//9/X
        17unp5WZmZgAAAOfn515eXv
        Pz7Y6OjuDg4J+fn5OTk6enp
        56enmleECcgggoBADs=

Unsupported YAML Features

The following YAML features are not supported by the Symfony Yaml component:

• Multi-documents (--- and ... markers);
• Complex mapping keys and complex values starting with ?;
• Tagged values as keys;
• The following tags and types: !!set, !!omap, !!pairs, !!seq, !!bool, !!int, !!merge, !!null, !!timestamp, !!value, !!yaml;
• Tags (TAG directive; example: %TAG ! tag:example.com,2000:app/) and tag references (example: !<tag:example.com,2000:app/foo>);
• Using sequence-like syntax for mapping elements (example: {foo, bar}; use {foo: ~, bar: ~} instead).