Skip to content

Commit 13993af

Browse files
james-johnston-thumbtackbarryvdh
james-johnston-thumbtack
authored and
barryvdh
committed
Introduce DebugBarVarDumper for HTML variable dumping (php-debugbar#344)
The Symfony VarDumper component includes an HtmlDumper that dumps variables in a rich HTML format that allows for expanding and collapsing individual tree nodes in the dumped variable. This makes it much more practical to navigate large/deep variables that have been dumped. DebugBarVarDumper provides a Debug Bar-friendly wrapper around the VarDumper component. It’s intended as a better alternative to DataFormatter::formatVar. It provides for: * Debug Bar-friendly styles for the VarDumper HTML. * Implements AssetProvider for returning VarDumper static assets (requires users of JavascriptRenderer to support inline assets). * Simplifies VarCloner and HtmlDumper function calls for cloning and dumping variables in a Debug Bar environment. VarDumper was originally written/targeted to be a replacement for var_dump, so the default behavior of HtmlDumper echoing static assets and variable dumps directly to the page output isn’t really appropriate. Furthermore, we must contend with several different Symfony versions going back to v2.6.0. This class provides a friendly wrapper. I have tested this with these Symfony versions: * v2.6.0 * v2.7.0 * v2.8.0 * v3.0.0 * v3.1.0 * v3.2.0 * v3.3.0 All seem to work fine, with graceful degradation as needed. Furthermore, the class is ready to take advantage of new features that I added and are upcoming in Symfony v3.4: * setMinDepth: symfony/symfony#23515 This feature will be valuable for the upcoming BacktraceCollector.
1 parent 22cb245 commit 13993af

File tree

5 files changed

+840
-4
lines changed

5 files changed

+840
-4
lines changed

‎docs/data_formatter.md‎

Lines changed: 101 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,108 @@
11
# Data Formatter
22

3+
## HTML variable formatting
4+
5+
PHP Debug Bar integrates with Symfony's
6+
[VarDumper](https://symfony.com/doc/current/components/var_dumper.html) component to provide
7+
interactive HTML-based variable dumps. This is accomplished via the
8+
`DebugBar\DataFormatter\DebugBarVarDumper` class, which wraps VarDumper functionality for use by the
9+
debug bar.
10+
11+
Debug bar users who wish to take advantage of this feature must ensure that they properly render
12+
[inline assets](rendering.html#assets) when rendering the debug bar. That's because collectors
13+
using the variable dumper return the static assets of the HTML variable dumper, which includes
14+
inline assets.
15+
16+
By default, collectors inheriting from `DebugBar\DataCollector\DataCollector` will use the
17+
`DebugBarVarDumper` instance specified by the static `DataCollector::setDefaultVarDumper` function.
18+
This can be overridden on a per-collector basis by the non-static `DataCollector::setVarDumper`
19+
function.
20+
21+
// Modify default options used globally by all collectors
22+
DataCollector::getDefaultVarDumper()->mergeClonerOptions(array(
23+
'max_items' => 50,
24+
));
25+
26+
// Modify options for a specific collector
27+
$varDumper = new DebugBarVarDumper();
28+
$varDumper->mergeDumperOptions(array(
29+
'max_string' => 100,
30+
));
31+
$collector->setVarDumper($varDumper);
32+
33+
VarDumper has two key classes that are used by `DebugBarVarDumper`. The options can be set using
34+
the `mergeClonerOptions`, `resetClonerOptions`, `mergeDumperOptions`, and `resetDumperOptions`
35+
methods on `DebugBarVarDumper`.
36+
37+
- `VarCloner`: Cloners copy the contents of a variable into a serializable format. They are
38+
intended to run as fast as possible; advanced rendering/formatting is saved for the dumper.
39+
Classes known as casters control how particular data types are serialized; if no caster exists,
40+
then a generic serialization is done. You can specify custom casters using the
41+
`additional_casters` option; the default list of casters can be overridden with the `casters`
42+
option. Finally, the number of items and maximum string length to clone can be controlled via the
43+
`max_items`, `min_depth`, and `max_string` options; consult the
44+
[VarDumper documentation](https://symfony.com/doc/current/components/var_dumper/advanced.html)
45+
for more information on these options, which have a considerable performance impact. Note that
46+
the `min_depth` option requires VarDumper 3.4 or newer.
47+
- `HtmlDumper`: Dumpers format cloned data for a particular destination, such as command-line or
48+
HTML. `DebugBarVarDumper` only uses the `HtmlDumper`. Custom styles can be specified via the
49+
`styles` option, but this is not generally needed. If using VarDumper 3.2 or newer, you may also
50+
specify the `expanded_depth`, `max_string`, and `file_link_format` options. `expanded_depth`
51+
controls the tree depth that should be expanded by default upon initial rendering. `max_string`
52+
can be used to truncate strings beyond the initial truncation done by the cloner.
53+
`file_link_format` is a format string used to generate links to source code files.
54+
55+
A collector wishing to take advantage of this feature must call the `renderVar()` function and
56+
return the HTML result as part of the request dataset:
57+
58+
public function collectVariable($v)
59+
{
60+
// This will clone and then dump the variable in one operation:
61+
$this->variableHtml = $this->getVarDumper()->renderVar($v);
62+
}
63+
64+
public function collect()
65+
{
66+
return array('variableHtml' => $this->variableHtml);
67+
}
68+
69+
The collector may then render the raw HTML in a Javascript widget:
70+
71+
if (value.variableHtml) {
72+
var val = $('<span />').html(value.variableHtml).appendTo(otherElement);
73+
}
74+
75+
If the collector takes advantage of the variable dumper, as shown above, then it must also
76+
implement the `AssetProvider` interface and include the assets of the variable dumper. This does
77+
not take place by default, because not all collectors will use the variable dumper.
78+
79+
class MyCollector extends DataCollector implements Renderable, AssetProvider
80+
{
81+
public function getAssets() {
82+
return $this->getVarDumper()->getAssets();
83+
}
84+
}
85+
86+
You might want to clone a variable initially, and only dump it at a later time. This is supported by
87+
the `captureVar()` and `renderCapturedVar()` functions. It's also possible to render only portions
88+
of a cloned variable at a time.
89+
90+
$testData = array('one', 'two', 'three');
91+
$cloned_variable = $this->getVarDumper()->captureVar($testData);
92+
93+
// Later, when you want to render it. Note the second parameter is $seekPath; here we specify
94+
// to only render the second array element (index 1). $html will therefore only contain 'two'.
95+
$html = $this->getVarDumper()->renderCapturedVar($cloned_variable, array(1));
96+
97+
## Text formatting
98+
399
An instance of `DebugBar\DataFormatter\DataFormatterInterface` is used by collectors to
4-
format data.
100+
format variables into a text-only format.
5101

6102
The default instance is `DebugBar\DataFormatter\DataFormatter`. This can be modified
7103
using `DebugBar\DataCollector\DataCollector::setDefaultDataFormatter()`.
8104

9-
You can use a custom formater for each collector using `DataCollector::setDataFormatter()`.
105+
You can use a custom formatter for each collector using `DataCollector::setDataFormatter()`.
106+
107+
For general-purpose variable formatting, it's recommended to use the HTML variable dumper, described
108+
earlier.

‎src/DebugBar/DataCollector/DataCollector.php‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,18 @@
1212

1313
use DebugBar\DataFormatter\DataFormatter;
1414
use DebugBar\DataFormatter\DataFormatterInterface;
15+
use DebugBar\DataFormatter\DebugBarVarDumper;
1516

1617
/**
1718
* Abstract class for data collectors
1819
*/
1920
abstract class DataCollector implements DataCollectorInterface
2021
{
2122
private static $defaultDataFormatter;
23+
private static $defaultVarDumper;
2224

2325
protected $dataFormater;
26+
protected $varDumper;
2427

2528
/**
2629
* Sets the default data formater instance used by all collectors subclassing this class
@@ -68,6 +71,55 @@ public function getDataFormatter()
6871
return $this->dataFormater;
6972
}
7073

74+
/**
75+
* Sets the default variable dumper used by all collectors subclassing this class
76+
*
77+
* @param DebugBarVarDumper $varDumper
78+
*/
79+
public static function setDefaultVarDumper(DebugBarVarDumper $varDumper)
80+
{
81+
self::$defaultVarDumper = $varDumper;
82+
}
83+
84+
/**
85+
* Returns the default variable dumper
86+
*
87+
* @return DebugBarVarDumper
88+
*/
89+
public static function getDefaultVarDumper()
90+
{
91+
if (self::$defaultVarDumper === null) {
92+
self::$defaultVarDumper = new DebugBarVarDumper();
93+
}
94+
return self::$defaultVarDumper;
95+
}
96+
97+
/**
98+
* Sets the variable dumper instance used by this collector
99+
*
100+
* @param DebugBarVarDumper $varDumper
101+
* @return $this
102+
*/
103+
public function setVarDumper(DebugBarVarDumper $varDumper)
104+
{
105+
$this->varDumper = $varDumper;
106+
return $this;
107+
}
108+
109+
/**
110+
* Gets the variable dumper instance used by this collector; note that collectors using this
111+
* instance need to be sure to return the static assets provided by the variable dumper.
112+
*
113+
* @return DebugBarVarDumper
114+
*/
115+
public function getVarDumper()
116+
{
117+
if ($this->varDumper === null) {
118+
$this->varDumper = self::getDefaultVarDumper();
119+
}
120+
return $this->varDumper;
121+
}
122+
71123
/**
72124
* @deprecated
73125
*/

0 commit comments

Comments
 (0)