feature #14006 [VarDumper] with-er interface for Cloner\Data (nicolas-grekas)

This PR was merged into the 2.7 branch.

Discussion
----------

[VarDumper] with-er interface for Cloner\Data

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | yes
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | symfony/symfony-docs#5106

I should have this idea earlier... :)

Commits
-------

2462c5b [VarDumper] with-er interface for Cloner\Data

src/Symfony/Component/HttpKernel/DataCollector/DumpDataCollector.php

@@ -168,7 +168,12 @@ class DumpDataCollector extends DataCollector implements DataDumperInterface
         $dumps = array();
 
         foreach ($this->data as $dump) {
-            $dumper->dump($dump['data']->getLimitedClone($maxDepthLimit, $maxItemsPerDepth));
+            if (method_exists($dump['data'], 'withMaxDepth')) {
+                $dumper->dump($dump['data']->withMaxDepth($maxDepthLimit)->withMaxItemsPerDepth($maxItemsPerDepth));
+            } else {
+                // getLimitedClone is @deprecated, to be removed in 3.0
+                $dumper->dump($dump['data']->getLimitedClone($maxDepthLimit, $maxItemsPerDepth));
+            }
             rewind($data);
             $dump['data'] = stream_get_contents($data);
             ftruncate($data, 0);

src/Symfony/Component/VarDumper/Cloner/Data.php

@@ -37,6 +37,51 @@ class Data
         return $this->data;
     }
 
+    /**
+     * Returns a depth limited clone of $this.
+     *
+     * @param int $maxDepth The max dumped depth level.
+     *
+     * @return self A clone of $this.
+     */
+    public function withMaxDepth($maxDepth)
+    {
+        $data = clone $this;
+        $data->maxDepth = (int) $maxDepth;
+
+        return $data;
+    }
+
+    /**
+     * Limits the numbers of elements per depth level.
+     *
+     * @param int $maxItemsPerDepth The max number of items dumped per depth level.
+     *
+     * @return self A clone of $this.
+     */
+    public function withMaxItemsPerDepth($maxItemsPerDepth)
+    {
+        $data = clone $this;
+        $data->maxItemsPerDepth = (int) $maxItemsPerDepth;
+
+        return $data;
+    }
+
+    /**
+     * Enables/disables objects' identifiers tracking.
+     *
+     * @param bool $useRefHandles False to hide global ref. handles.
+     *
+     * @return self A clone of $this.
+     */
+    public function withRefHandles($useRefHandles)
+    {
+        $data = clone $this;
+        $data->useRefHandles = $useRefHandles ? -1 : 0;
+
+        return $data;
+    }
+
     /**
      * Returns a depth limited clone of $this.
      *
@@ -45,9 +90,13 @@ class Data
      * @param bool $useRefHandles    False to hide ref. handles.
      *
      * @return self A depth limited clone of $this.
+     *
+     * @deprecated since Symfony 2.7, to be removed in 3.0. Use withMaxDepth, withMaxItemsPerDepth or withRefHandles instead.
      */
     public function getLimitedClone($maxDepth, $maxItemsPerDepth, $useRefHandles = true)
     {
+        trigger_error('The '.__METHOD__.' method is deprecated since Symfony 2.7 and will be removed in 3.0. Use withMaxDepth, withMaxItemsPerDepth or withRefHandles methods instead.', E_USER_DEPRECATED);
+
         $data = clone $this;
         $data->maxDepth = (int) $maxDepth;
         $data->maxItemsPerDepth = (int) $maxItemsPerDepth;

src/Symfony/Component/VarDumper/Tests/CliDumperTest.php

@@ -245,7 +245,7 @@ EOTXT
         $dumper->setColors(false);
         $cloner = new VarCloner();
 
-        $data = $cloner->cloneVar($var)->getLimitedClone(3, -1);
+        $data = $cloner->cloneVar($var)->withMaxDepth(3);
         $out = '';
         $dumper->dump($data, function ($line, $depth) use (&$out) {
             if ($depth >= 0) {