minor #9205 Documented the missing YAML flags (javiereguiluz)

javiereguiluz · javiereguiluz · commit 3137a7340259 · 2018-02-07T09:10:07.000+01:00
This PR was squashed before being merged into the 3.4 branch (closes #9205). Discussion ---------- Documented the missing YAML flags This finishes #6226. Commits ------- 6ecf051 Documented the missing YAML flags
diff --git a/components/yaml.rst b/components/yaml.rst
@@ -267,6 +267,30 @@ representation of the object.
     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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 3.2
+    Support for parsing and dumping objects as maps was introduced in Symfony 3.2.
+
+You can dump objects as Yaml maps by using the ``DUMP_OBJECT_AS_MAP`` flag::
+
+    $object = new \stdClass();
+    $object->foo = 'bar';
+
+    $dumped = Yaml::dump(array('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::
+
+    $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.
+
 .. _invalid-types-and-object-serialization:
 
 Handling Invalid Types
@@ -333,6 +357,26 @@ syntax to parse them as proper PHP constants::
     $parameters = Yaml::parse($yaml, Yaml::PARSE_CONSTANT);
     // $parameters = array('foo' => 'PHP_INT_SIZE', 'bar' => 8);
 
+Parsing and Dumping of Binary Data
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 3.2
+    Support for parsing and dumping binary data was introduced in Symfony 3.2.
+
+You can dump binary data by using the ``DUMP_BASE64_BINARY_DATA`` flag::
+
+    $imageContents = file_get_contents(__DIR__.'/images/logo.png');
+
+    $dumped = Yaml::dump(array('logo' => $imageContents), 2, 4, Yaml::DUMP_BASE64_BINARY_DATA);
+    // logo: !!binary iVBORw0KGgoAAAANSUhEUgAAA6oAAADqCAY...
+
+Binary data is automatically parsed if they include the ``!!binary`` YAML tag
+(there's no need to pass any flag to the Yaml parser)::
+
+    $dumped = 'logo: !!binary iVBORw0KGgoAAAANSUhEUgAAA6oAAADqCAY...';
+    $parsed = Yaml::parse($dumped);
+    $imageContents = $parsed['logo'];
+
 Syntax Validation
 ~~~~~~~~~~~~~~~~~
 
