[Yaml] dump customization option with dumper flags

UPGRADE-3.1.md

@@ -33,5 +33,18 @@ Serializer
 Yaml
 ----
 
+ * Deprecated support for passing `true`/`false` as the third argument to the `dump()` methods to toggle object support.
+
+   Before:
+
+   ```php
+   Yaml::dump(array('foo' => new A(), 'bar' => 1), 0, 0, false, true);
+   ```
+
+   After:
+
+   ```php
+   Yaml::dump(array('foo' => new A(), 'bar' => 1), 0, 0, false, Yaml::DUMP_OBJECT);
+
  * The `!!php/object` tag to indicate dumped PHP objects has been deprecated
    and will be removed in Symfony 4.0. Use the `!php/object` tag instead.

UPGRADE-4.0.md

@@ -24,5 +24,19 @@ Serializer
 Yaml
 ----
 
+ * Removed support for passing `true`/`false` as the third argument to the `dump()` methods to toggle object support.
+
+   Before:
+
+   ```php
+   Yaml::dump(array('foo' => new A(), 'bar' => 1), 0, 0, false, true);
+   ```
+
+   After:
+
+   ```php
+   Yaml::dump(array('foo' => new A(), 'bar' => 1), 0, 0, false, Yaml::DUMP_OBJECT);
+   ```
+
  * The `!!php/object` tag to indicate dumped PHP objects was removed in favor of
    the `!php/object` tag.

src/Symfony/Component/Yaml/CHANGELOG.md

@@ -1,6 +1,15 @@
 CHANGELOG
 =========
 
+3.1.0
+-----
+
+ * Added support for customizing the dumped YAML string through an optional bit field:
+
+   ```php
+   Yaml::dump(array('foo' => new A(), 'bar' => 1), 0, 0, false, Yaml::DUMP_OBJECT);
+   ```
+
 3.0.0
 -----
 

src/Symfony/Component/Yaml/Dumper.php

@@ -42,17 +42,23 @@ class Dumper
      * @param int   $inline                 The level where you switch to inline YAML
      * @param int   $indent                 The level of indentation (used internally)
      * @param bool  $exceptionOnInvalidType true if an exception must be thrown on invalid types (a PHP resource or object), false otherwise
-     * @param bool  $objectSupport          true if object support is enabled, false otherwise
+     * @param int   $flags                  A bit field of Yaml::DUMP_* constants to customize the dumped YAML string
      *
      * @return string The YAML representation of the PHP value
      */
-    public function dump($input, $inline = 0, $indent = 0, $exceptionOnInvalidType = false, $objectSupport = false)
+    public function dump($input, $inline = 0, $indent = 0, $exceptionOnInvalidType = false, $flags = 0)
     {
+        if (is_bool($flags)) {
+            @trigger_error('Passing a boolean flag to toggle object support is deprecated since version 3.1 and will be removed in 4.0. Use the Yaml::DUMP_OBJECT flag instead.', E_USER_DEPRECATED);
+
+            $flags = (int) $flags;
+        }
+
         $output = '';
         $prefix = $indent ? str_repeat(' ', $indent) : '';
 
         if ($inline <= 0 || !is_array($input) || empty($input)) {
-            $output .= $prefix.Inline::dump($input, $exceptionOnInvalidType, $objectSupport);
+            $output .= $prefix.Inline::dump($input, $exceptionOnInvalidType, $flags);
         } else {
             $isAHash = array_keys($input) !== range(0, count($input) - 1);
 
@@ -61,9 +67,9 @@ class Dumper
 
                 $output .= sprintf('%s%s%s%s',
                     $prefix,
-                    $isAHash ? Inline::dump($key, $exceptionOnInvalidType, $objectSupport).':' : '-',
+                    $isAHash ? Inline::dump($key, $exceptionOnInvalidType, $flags).':' : '-',
                     $willBeInlined ? ' ' : "\n",
-                    $this->dump($value, $inline - 1, $willBeInlined ? 0 : $indent + $this->indentation, $exceptionOnInvalidType, $objectSupport)
+                    $this->dump($value, $inline - 1, $willBeInlined ? 0 : $indent + $this->indentation, $exceptionOnInvalidType, $flags)
                 ).($willBeInlined ? "\n" : '');
             }
         }

src/Symfony/Component/Yaml/Inline.php

@@ -88,14 +88,20 @@ class Inline
      *
      * @param mixed $value                  The PHP variable to convert
      * @param bool  $exceptionOnInvalidType true if an exception must be thrown on invalid types (a PHP resource or object), false otherwise
-     * @param bool  $objectSupport          true if object support is enabled, false otherwise
+     * @param int   $flags                  A bit field of Yaml::DUMP_* constants to customize the dumped YAML string
      *
      * @return string The YAML string representing the PHP array
      *
      * @throws DumpException When trying to dump PHP resource
      */
-    public static function dump($value, $exceptionOnInvalidType = false, $objectSupport = false)
+    public static function dump($value, $exceptionOnInvalidType = false, $flags = 0)
     {
+        if (is_bool($flags)) {
+            @trigger_error('Passing a boolean flag to toggle object support is deprecated since version 3.1 and will be removed in 4.0. Use the Yaml::DUMP_OBJECT flag instead.', E_USER_DEPRECATED);
+
+            $flags = (int) $flags;
+        }
+
         switch (true) {
             case is_resource($value):
                 if ($exceptionOnInvalidType) {
@@ -104,7 +110,7 @@ class Inline
 
                 return 'null';
             case is_object($value):
-                if ($objectSupport) {
+                if (Yaml::DUMP_OBJECT & $flags) {
                     return '!php/object:'.serialize($value);
                 }
 
@@ -114,7 +120,7 @@ class Inline
 
                 return 'null';
             case is_array($value):
-                return self::dumpArray($value, $exceptionOnInvalidType, $objectSupport);
+                return self::dumpArray($value, $exceptionOnInvalidType, $flags);
             case null === $value:
                 return 'null';
             case true === $value:

src/Symfony/Component/Yaml/Tests/DumperTest.php

@@ -13,6 +13,7 @@ namespace Symfony\Component\Yaml\Tests;
 
 use Symfony\Component\Yaml\Parser;
 use Symfony\Component\Yaml\Dumper;
+use Symfony\Component\Yaml\Yaml;
 
 class DumperTest extends \PHPUnit_Framework_TestCase
 {
@@ -177,6 +178,16 @@ EOF;
     }
 
     public function testObjectSupportEnabled()
+    {
+        $dump = $this->dumper->dump(array('foo' => new A(), 'bar' => 1), 0, 0, false, Yaml::DUMP_OBJECT);
+
+        $this->assertEquals('{ foo: !php/object:O:30:"Symfony\Component\Yaml\Tests\A":1:{s:1:"a";s:3:"foo";}, bar: 1 }', $dump, '->dump() is able to dump objects');
+    }
+
+    /**
+     * @group legacy
+     */
+    public function testObjectSupportEnabledPassingTrue()
     {
         $dump = $this->dumper->dump(array('foo' => new A(), 'bar' => 1), 0, 0, false, true);
 
@@ -195,7 +206,7 @@ EOF;
      */
     public function testObjectSupportDisabledWithExceptions()
     {
-        $this->dumper->dump(array('foo' => new A(), 'bar' => 1), 0, 0, true, false);
+        $this->dumper->dump(array('foo' => new A(), 'bar' => 1), 0, 0, true);
     }
 
     /**

src/Symfony/Component/Yaml/Yaml.php

@@ -20,6 +20,8 @@ use Symfony\Component\Yaml\Exception\ParseException;
  */
 class Yaml
 {
+    const DUMP_OBJECT = 1;
+
     /**
      * Parses YAML into a PHP array.
      *
@@ -58,15 +60,21 @@ class Yaml
      * @param int   $inline                 The level where you switch to inline YAML
      * @param int   $indent                 The amount of spaces to use for indentation of nested nodes.
      * @param bool  $exceptionOnInvalidType true if an exception must be thrown on invalid types (a PHP resource or object), false otherwise
-     * @param bool  $objectSupport          true if object support is enabled, false otherwise
+     * @param int   $flags                  A bit field of DUMP_* constants to customize the dumped YAML string
      *
      * @return string A YAML string representing the original PHP array
      */
-    public static function dump($array, $inline = 2, $indent = 4, $exceptionOnInvalidType = false, $objectSupport = false)
+    public static function dump($array, $inline = 2, $indent = 4, $exceptionOnInvalidType = false, $flags = 0)
     {
+        if (is_bool($flags)) {
+            @trigger_error('Passing a boolean flag to toggle object support is deprecated since version 3.1 and will be removed in 4.0. Use the DUMP_OBJECT flag instead.', E_USER_DEPRECATED);
+
+            $flags = (int) $flags;
+        }
+
         $yaml = new Dumper();
         $yaml->setIndentation($indent);
 
-        return $yaml->dump($array, $inline, 0, $exceptionOnInvalidType, $objectSupport);
+        return $yaml->dump($array, $inline, 0, $exceptionOnInvalidType, $flags);
     }
 }