Symfony 4 was released on November 30th.
Update now to the best Symfony ever!

New in Symfony 3.1: Customizable YAML parsing and dumping

YAML is one of the most popular formats to define the configuration of Symfony applications. Besides, the YAML Component is our second most popular component, with tens of millions of downloads and thousands of PHP projects depending on it.

In previous Symfony versions, the behavior of the parse() and dump() methods were partially configurable. For example, the parse() method defined a boolean argument to configure the behavior of object maps and you could also toggle object support with the fifth parameter of the dump() method:

1
2
3
use Symfony\Component\Yaml\Yaml;

Yaml::dump(array('foo' => new A(), 'bar' => 1), 0, 4, false, true);

However, these features had some drawbacks. First, boolean arguments (also called "flag arguments") are usually not recommended. Second, this doesn't scale well because it forces you to define new method arguments for the new features.

Introducing configuration flags

In Symfony 3.1, to avoid all the issues mentioned above and to keep adding new features, we decided to introduce configuration flags for the YAML component. These flags are constants defined in the Symfony\Component\Yaml\Yaml class. For example, to enable the object support for the dump() method, use the Yaml::DUMP_OBJECT constant:

1
2
3
use Symfony\Component\Yaml\Yaml;

Yaml::dump(array('foo' => new A(), 'bar' => 1), 0, 4, Yaml::DUMP_OBJECT);

Thanks to this flag-based configuration mechanism, we've started adding lots of new features to the YAML component. Keep reading to learn about some of those features.

Parsing and dumping DateTime objects

If the content of a YAML string can be interpreted as a valid DateTime value, use the new Yaml::PARSE_DATETIME to transform those strings into proper \DateTime PHP objects:

1
2
3
4
5
6
$date = Yaml::parse('2001-12-15 21:59:43.10 -5', Yaml::PARSE_DATETIME);
// $date = DateTime {
//     "date": "2001-12-15 21:59:43.100000"
//      "timezone_type": 1
//      "timezone": "-05:00"
//  }

In addition, the \DateTime and \DateTimeImmutable objects are now dumped as YAML timestamps:

1
2
3
$date = new \DateTime('2001-07-15 21:59:43', new \DateTimeZone('Europe/Berlin'));
$timestamp = Yaml::dump(array('date' => $date));
// $timestamp = 'date: 2001-07-15T21:59:43+02:00'

Showing exceptions on invalid types

The new Yaml::DUMP_EXCEPTION_ON_INVALID_TYPE flag replaces the fourth argument of the dump() method and it makes the application to trigger exceptions when an invalid type is passed (for example when dumping PHP resources):

1
Yaml::dump(array('foo' => new A(), 'bar' => 1), 0, 4, Yaml::DUMP_EXCEPTION_ON_INVALID_TYPE);

Dumping objects as maps

Consider the following PHP object:

1
2
3
$object = new \stdClass();
$object->foo = 'foo';
$object->bar = new \StdClass();

The regular dump() method won't provide the results you may expect, but the new Yaml::DUMP_OBJECT_AS_MAP flag will dump the object as expected:

1
2
3
4
5
$dumpedObject = Yaml::dump($object, 0, 4);
// $dumpedObject = "{ object: null }"

Yaml::dump($object, 0, 4, Yaml::DUMP_OBJECT_AS_MAP);
// $dumpedObject = "{ object: { foo: foo, bar: {  } } }"

Dumping multi-line strings as scalar blocks

This was one of the most requested features by Symfony developers. Consider the following content where the string includes \n characters:

1
2
3
$data = array(
    'content' => "Lorem ipsum dolor sit amet\nconsectetur adipisicing\nelit sed do eiusmod",
);

Thanks to the new Yaml::DUMP_MULTI_LINE_LITERAL_BLOCK flag, you can tell YAML to consider those \n characters to create a scalar block:

1
$dumpedData = Yaml::dump($data, 2, 4, Yaml::DUMP_MULTI_LINE_LITERAL_BLOCK);

In this example, the second argument of dump() is set to 2 to avoid inlining the first two levels YAML of indentation. The result is the following content:

1
2
3
4
content: |
    Lorem ipsum dolor sit amet
    consectetur adipisicing
    elit sed do eiusmod

If you set a lower indentation level or don't use the Yaml::DUMP_MULTI_LINE_LITERAL_BLOCK flag, you'll get the following result:

1
content: "Lorem ipsum dolor sit amet\nconsectetur adipisicing\nelit sed do eiusmod"

Comments

What is an "OPJECT"? :-)

It's in and above your 2nd code snippet.
@Thomas it's fixed now. Thanks for reporting it.

Comments are closed.

To ensure that comments stay relevant, they are closed for old posts.