The VarDumper Component ¶

Installation ¶

1

$ composer require --dev symfony/var-dumper

The dump() Function ¶

The VarDumper component creates a global dump() function that you can use instead of e.g. var_dump. By using it, you'll gain:

• Per object and resource types specialized view to e.g. filter out Doctrine internals while dumping a single proxy entity, or get more insight on opened files with stream_get_meta_data;
  オブジェクトとリソースの種類ごとに特化したビューなど。単一のプロキシ エンティティをダンプする際に Doctrine の内部を除外するか、stream_get_meta_data で開いているファイルについてより多くの洞察を得ます。
• Configurable output formats: HTML or colored command line output;
  構成可能な出力形式: HTML または色付きのコマンド ライン出力。
• Ability to dump internal references, either soft ones (objects or resources) or hard ones (=& on arrays or objects properties). Repeated occurrences of the same object/array/resource won't appear again and again anymore. Moreover, you'll be able to inspect the reference structure of your data;
• Ability to operate in the context of an output buffering handler.
  出力バッファリング ハンドラのコンテキストで操作する機能。

For example:

1
2
3
4
5
6
7
8
9

require __DIR__.'/vendor/autoload.php';

// create a variable, which could be anything!
$someVar = ...;

dump($someVar);

// dump() returns the passed value, so you can dump an object and keep using it
dump($someObject)->someMethod();

By default, the output format and destination are selected based on your current PHP SAPI:

• On the command line (CLI SAPI), the output is written on STDOUT. This can be surprising to some because this bypasses PHP's output buffering mechanism;
  コマンドライン (CLI SAPI) では、出力は STDOUT に書き込まれます。これは、PHP の出力バッファリング メカニズムをバイパスするため、驚く人もいます。
• On other SAPIs, dumps are written as HTML in the regular output.
  他の SAPI では、ダンプは通常の出力で HTML として書き込まれます。

The Dump Server ¶

The dump() function outputs its contents in the same browser window or console terminal as your own application. Sometimes mixing the real output with the debug output can be confusing. That's why this component provides a server to collect all the dumped data.

Start the server with the server:dump command and whenever you call to dump(), the dumped data won't be displayed in the output but sent to that server, which outputs it to its own console or to an HTML file:

1
2
3
4
5
6

# displays the dumped data in the console:
$ php bin/console server:dump
  [OK] Server listening on tcp://0.0.0.0:9912

# stores the dumped data in a file using the HTML format:
$ php bin/console server:dump --format=html > dump.html

Inside a Symfony application, the output of the dump server is configured with the dump_destination option of the debug package:

1
2
3

# config/packages/debug.yaml
debug:
   dump_destination: "tcp://%env(VAR_DUMPER_SERVER)%"

1
2
3
4
5
6
7
8
9
10
11
12

<!-- config/packages/debug.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:debug="http://symfony.com/schema/dic/debug"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/debug
        https://symfony.com/schema/dic/debug/debug-1.0.xsd"
>
    <debug:config dump-destination="tcp://%env(VAR_DUMPER_SERVER)%"/>
</container>

1
2
3
4
5
6
7
8

// config/packages/debug.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return static function (ContainerConfigurator $container) {
    $container->extension('debug', [
        'dump_destination' => 'tcp://%env(VAR_DUMPER_SERVER)%',
    ]);
};

Outside a Symfony application, use the ServerDumper class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

require __DIR__.'/vendor/autoload.php';

use Symfony\Component\VarDumper\Cloner\VarCloner;
use Symfony\Component\VarDumper\Dumper\CliDumper;
use Symfony\Component\VarDumper\Dumper\ContextProvider\CliContextProvider;
use Symfony\Component\VarDumper\Dumper\ContextProvider\SourceContextProvider;
use Symfony\Component\VarDumper\Dumper\HtmlDumper;
use Symfony\Component\VarDumper\Dumper\ServerDumper;
use Symfony\Component\VarDumper\VarDumper;

$cloner = new VarCloner();
$fallbackDumper = \in_array(\PHP_SAPI, ['cli', 'phpdbg']) ? new CliDumper() : new HtmlDumper();
$dumper = new ServerDumper('tcp://127.0.0.1:9912', $fallbackDumper, [
    'cli' => new CliContextProvider(),
    'source' => new SourceContextProvider(),
]);

VarDumper::setHandler(function ($var) use ($cloner, $dumper) {
    $dumper->dump($cloner->cloneVar($var));
});

Then you can use the following command to start a server out-of-the-box:

1
2

$ ./vendor/bin/var-dump-server
  [OK] Server listening on tcp://127.0.0.1:9912

1

$ ./vendor/bin/var-dump-server

1

$ VAR_DUMPER_FORMAT=server [your-cli-command]

DebugBundle and Twig Integration ¶

The DebugBundle allows greater integration of this component into Symfony applications.

Since generating (even debug) output in the controller or in the model of your application may just break it by e.g. sending HTTP headers or corrupting your view, the bundle configures the dump() function so that variables are dumped in the web debug toolbar.

But if the toolbar cannot be displayed because you e.g. called die()/exit()/dd() or a fatal error occurred, then dumps are written on the regular output.

In a Twig template, two constructs are available for dumping a variable. Choosing between both is mostly a matter of personal taste, still:

• {% dump foo.bar %} is the way to go when the original template output shall not be modified: variables are not dumped inline, but in the web debug toolbar;
  {% dump foo.bar %} は、元のテンプレート出力が変更されない場合の方法です。変数はインラインではなく、webdebug ツールバーにダンプされます。
• on the contrary, {{ dump(foo.bar) }} dumps inline and thus may or not be suited to your use case (e.g. you shouldn't use it in an HTML attribute or a <script> tag).
  逆に、 {{ dump(foo.bar) }} はインラインでダンプするため、ユースケースに適している場合と適していない場合があります (たとえば、HTML 属性または atag では使用しないでください)。

This behavior can be changed by configuring the debug.dump_destination option. Read more about this and other options in the DebugBundle configuration reference.

Using the VarDumper Component in your PHPUnit Test Suite ¶

The VarDumper component provides a trait that can help writing some of your tests for PHPUnit.

This will provide you with two new assertions:

assertDumpEquals()

verifies that the dump of the variable given as the second argument matches the expected dump provided as the first argument.

2 番目の引数として指定された変数のダンプが、最初の引数として指定された予想されるダンプと一致することを確認します。

assertDumpMatchesFormat()

is like the previous method but accepts placeholders in the expected dump, based on the assertStringMatchesFormat() method provided by PHPUnit.

前のメソッドと似ていますが、PHPUnit が提供する assertStringMatchesFormat() メソッドに基づいて、予想されるダンプでプレースホルダーを受け入れます。

The VarDumperTestTrait also includes these other methods:

setUpVarDumper()

is used to configure the available casters and their options, which is a way to only control the fields you're expecting and allows writing concise tests.

利用可能なキャスターとそのオプションを構成するために使用されます。これは、期待するフィールドのみを制御し、簡潔なテストを作成できるようにする方法です。

tearDownVarDumper()

is called automatically after each case to reset the custom configuration made in setUpVarDumper().

setUpVarDumper() で作成されたカスタム構成をリセットするために、各ケースの後に自動的に呼び出されます。

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

use PHPUnit\Framework\TestCase;
use Symfony\Component\VarDumper\Test\VarDumperTestTrait;

class ExampleTest extends TestCase
{
    use VarDumperTestTrait;

    protected function setUp()
    {
        $casters = [
            \DateTimeInterface::class => static function (\DateTimeInterface $date, array $a, Stub $stub): array {
                $stub->class = 'DateTime';
                return ['date' => $date->format('d/m/Y')];
            },
        ];

        $flags = CliDumper::DUMP_LIGHT_ARRAY | CliDumper::DUMP_COMMA_SEPARATOR;

        // this configures the casters & flags to use for all the tests in this class.
        // If you need custom configurations per test rather than for the whole class,
        // call this setUpVarDumper() method from those tests instead.
        $this->setUpVarDumper($casters, $flags);
    }

    public function testWithDumpEquals()
    {
        $testedVar = [123, 'foo'];

        // the expected dump contents don't have the default VarDumper structure
        // because of the custom casters and flags used in the test
        $expectedDump = <<<EOTXT
[
  123,
  "foo",
]
EOTXT;

        // if the first argument is a string, it must be the whole expected dump
        $this->assertDumpEquals($expectedDump, $testedVar);

        // if the first argument is not a string, assertDumpEquals() dumps it
        // and compares it with the dump of the second argument
        $this->assertDumpEquals($testedVar, $testedVar);
    }
}

Dump Examples and Output ¶

For simple variables, reading the output should be straightforward. Here are some examples showing first a variable defined in PHP, then its dump representation:

1
2
3
4
5
6
7
8

$var = [
    'a simple string' => "in an array of 5 elements",
    'a float' => 1.0,
    'an integer' => 1,
    'a boolean' => true,
    'an empty array' => [],
];
dump($var);

1
2
3
4
5
6
7

$var = "This is a multi-line string.\n";
$var .= "Hovering a string shows its length.\n";
$var .= "The length of UTF-8 strings is counted in terms of UTF-8 characters.\n";
$var .= "Non-UTF-8 strings length are counted in octet size.\n";
$var .= "Because of this `\xE9` octet (\\xE9),\n";
$var .= "this string is not UTF-8 valid, thus the `b` prefix.\n";
dump($var);

1
2
3
4
5
6
7
8
9

class PropertyExample
{
    public $publicProperty = 'The `+` prefix denotes public properties,';
    protected $protectedProperty = '`#` protected ones and `-` private ones.';
    private $privateProperty = 'Hovering a property shows a reminder.';
}

$var = new PropertyExample();
dump($var);

1
2
3
4
5
6
7
8

class DynamicPropertyExample
{
    public $declaredProperty = 'This property is declared in the class definition';
}

$var = new DynamicPropertyExample();
$var->undeclaredProperty = 'Runtime added dynamic properties have `"` around their name.';
dump($var);

1
2
3
4
5
6
7

class ReferenceExample
{
    public $info = "Circular and sibling references are displayed as `#number`.\nHovering them highlights all instances in the same dump.\n";
}
$var = new ReferenceExample();
$var->aCircularReference = $var;
dump($var);

1
2
3
4
5
6
7
8

$var = new \ErrorException(
    "For some objects, properties have special values\n"
    ."that are best represented as constants, like\n"
    ."`severity` below. Hovering displays the value (`2`).\n",
    0,
    E_WARNING
);
dump($var);

1
2
3
4
5
6
7
8

$var = [];
$var[0] = 1;
$var[1] =& $var[0];
$var[1] += 1;
$var[2] = ["Hard references (circular or sibling)"];
$var[3] =& $var[2];
$var[3][] = "are dumped using `&number` prefixes.";
dump($var);

1
2
3
4
5

$var = new \ArrayObject();
$var[] = "Some resources and special objects like the current";
$var[] = "one are sometimes best represented using virtual";
$var[] = "properties that describe their internal state.";
dump($var);

1
2
3
4
5
6
7
8

$var = new AcmeController(
    "When a dump goes over its maximum items limit,\n"
    ."or when some special objects are encountered,\n"
    ."children can be replaced by an ellipsis and\n"
    ."optionally followed by a number that says how\n"
    ."many have been removed; `9` in this case.\n"
);
dump($var);

Learn More ¶