[VarDumper] Add support of named arguments to `dd()` and `dump()` to display a label #48432

alexandre-daubois · 2022-12-01T17:40:37Z

Q	A
Branch?	6.3
Bug fix?	no
New feature?	yes
Deprecations?	no
Tickets	N/A
License	MIT
Doc PR	Todo

Following an idea from @nicolas-grekas, the goal here is to ease debugging with dd() and dump() by supporting named arguments passed to them. This will display a label, helping understand the goal/meaning of a dump.

Example in web browser:

Example in CLI:

The above example is clickable and points to file:///home/alexandredaubois/PhpstormProjects/dummy_project/src/Command/TestCommand.php#L15.

No more dd("First one", $var1, "Second var", $var2);!

nicolas-grekas

Send screenshots! We want to make the buzz around this ;)

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

src/Symfony/Component/VarDumper/CHANGELOG.md

nicolas-grekas · 2022-12-01T18:00:51Z

src/Symfony/Component/VarDumper/VarDumper.php

@@ -37,13 +37,13 @@ class VarDumper
     */
    private static $handler;

-    public static function dump(mixed $var)
+    public static function dump(mixed $var, string $sectionName = null)


$label
adding a new argument should be done in a BC way

This is a static method, so I don't think we have a BC issue here

I would call it $name (for argument name) or $key (for array key)
Like this.

Suggested change

public static function dump(mixed $var, string $sectionName = null)

/**

* @param string|null $name

*/

public static function dump(mixed $var, /*string $name = null*/)

I think I would go for $label which is clearer and more suitable to the context of "displaying an information".

I'll do the change for the BC promise, as I didn't find any exception mentioning static methods in the prohibition to add an extra parameter to a public method. 👍

it's a BC break @stof, see https://3v4l.org/2cUek

GromNaN

Very nice little feature.

I find the term "section" confusing. A section normally groups several things together. Here, there is only one variable for each name.

src/Symfony/Component/VarDumper/CHANGELOG.md

GromNaN · 2022-12-02T08:24:09Z

src/Symfony/Component/VarDumper/VarDumper.php

@@ -37,13 +37,13 @@ class VarDumper
     */
    private static $handler;

-    public static function dump(mixed $var)
+    public static function dump(mixed $var, string $sectionName = null)


I would call it $name (for argument name) or $key (for array key)
Like this.

Suggested change

public static function dump(mixed $var, string $sectionName = null)

/**

* @param string|null $name

*/

public static function dump(mixed $var, /*string $name = null*/)

src/Symfony/Component/VarDumper/Resources/functions/dump.php

stof · 2022-12-01T18:13:22Z

src/Symfony/Component/VarDumper/VarDumper.php

@@ -37,13 +37,13 @@ class VarDumper
     */
    private static $handler;

-    public static function dump(mixed $var)
+    public static function dump(mixed $var, string $sectionName = null)


This is a static method, so I don't think we have a BC issue here

lyrixx · 2022-12-02T11:34:49Z

Oh, I like this so much. Can we leverage this, to be able to configuration the dumper? (may be in another PR). I would love to do something like

dd($value, max_depth: 4);

to automatically expand the 4 depth level

alexandre-daubois · 2022-12-02T12:28:08Z

Big yes to me, @lyrixx! When talking about this idea, Nicolas seemed to have a few other ones that could definitely fit with this evolution in future PRs. A set of "reserved" named parameters to tweak dump() and dd() behaviours sounds great!

azjezz · 2022-12-02T16:13:18Z

src/Symfony/Component/VarDumper/Resources/functions/dump.php

+        foreach ($vars as $key => $v) {
+            VarDumper::dump($v, is_numeric($key) ? null : $key);
        }


wouldn't be better to dump argument index as well here?

Suggested change

foreach ($vars as $key => $v) {

VarDumper::dump($v, is_numeric($key) ? null : $key);

}

$i = 0;

foreach ($vars as $key => $v) {

VarDumper::dump($v, is_numeric($key) ? "$i" : "$key@$i");

$i++;

}

When there is only one argument, I wouldn't dump the index as label. But when there are more, it might be nice to dump the index+1 even when it's numeric (+1 to start from 1, and the index should be the key, no need for $i)
(same for dump() of course)

I was 👍 on this proposition, but:

$argc = count($vars); foreach ($vars as $key => $v) { $displayLabel = 1 < $argc || !is_numeric($key); $label = is_numeric($key) ? $key+1 : $key; VarDumper::dump($v, $displayLabel ? $label : null); }

This seems a bit complicated logic for the actual gain, what do you think?

Like this?

if (isset($vars[0]) && 1 === count($vars)) { VarDumper::dump($vars[0]); } else { // loop }

Yes, thank you!

drupol · 2022-12-02T22:44:16Z

Nice feature !

nicolas-grekas

Thanks for working on this. Here are some comments.

I like the idea of using special names to configure the dump.

I'm keeping a branch from 2016 with all possible options.
Here is what I collected back then:

dump_destination
format (cli, html, txt, default)
max_items
max_depth
max_items_per_depth
max_string_length
max_string_width
collapse_depth
collapse_length
use_ref_handles
casters
replace_casters
filter
light_array
string_length
charset
trace
src_context
trace_args

We could even have an option builder:

$options = VarDumper::options()->trace()->maxDepth(4)->toArray();
dump($var, ...$options);

As a convention, it might be worth prefixing all options by an underscore?

Anyway, I'd just suggest considering this in a follow up PR to keep this one focused.

src/Symfony/Component/VarDumper/Tests/Dumper/FunctionsTest.php

src/Symfony/Component/VarDumper/VarDumper.php

nicolas-grekas · 2022-12-04T15:52:01Z

src/Symfony/Component/VarDumper/Resources/functions/dump.php

+        foreach ($vars as $key => $v) {
+            VarDumper::dump($v, is_numeric($key) ? null : $key);
        }


When there is only one argument, I wouldn't dump the index as label. But when there are more, it might be nice to dump the index+1 even when it's numeric (+1 to start from 1, and the index should be the key, no need for $i)
(same for dump() of course)

src/Symfony/Component/VarDumper/Resources/functions/dump.php

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

GromNaN · 2022-12-04T23:42:38Z

I like the idea of using special names to configure the dump.
…
Anyway, I'd just suggest considering this in a follow up PR to keep this one focused.

Let's discuss this other feature in #48474

nicolas-grekas

I only have minor CS suggestions. Thanks!

src/Symfony/Component/VarDumper/Resources/functions/dump.php

src/Symfony/Component/VarDumper/VarDumper.php

alexandre-daubois · 2022-12-15T16:23:33Z

Everything has been updated according to your feedback. Thanks!

GromNaN · 2022-12-15T16:39:40Z

Names starting with _ should be forbidden and reserved to the futur options.

nicolas-grekas

Names starting with _ should be forbidden and reserved to the futur options.

let's do this in the PR that will follow up the issue you opened (same for the "no-args" behavior that needs to be adjusted if we follow your idea of a builder)

…display the argument name

nicolas-grekas · 2022-12-15T17:12:26Z

Thank you @alexandre-daubois.

drupol · 2022-12-15T17:13:40Z

src/Symfony/Component/VarDumper/Resources/functions/dump.php

        }

-        if (1 < func_num_args()) {
-            return func_get_args();
+        if (isset($vars[0]) && 1 === count($vars)) {


count($vars) is called twice, maybe use an intermediary var to avoid doing the job twice?

carsonbot added Status: Needs Review Feature VarDumper labels Dec 1, 2022

carsonbot added this to the 6.3 milestone Dec 1, 2022

alexandre-daubois force-pushed the feat/dd-section-name branch from 7afb2b1 to f148793 Compare December 1, 2022 17:43

nicolas-grekas reviewed Dec 1, 2022

View reviewed changes

GromNaN reviewed Dec 2, 2022

View reviewed changes

stof reviewed Dec 2, 2022

View reviewed changes

alexandre-daubois changed the title ~~[VarDumper] Add support of named arguments to dd() and dump() to display a "section name"~~ [VarDumper] Add support of named arguments to dd() and dump() to display a label Dec 2, 2022

alexandre-daubois force-pushed the feat/dd-section-name branch from f148793 to 984aceb Compare December 2, 2022 11:02

azjezz reviewed Dec 2, 2022

View reviewed changes

nicolas-grekas reviewed Dec 4, 2022

View reviewed changes

GromNaN mentioned this pull request Dec 4, 2022

Add options to dump function #48474

Open

alexandre-daubois force-pushed the feat/dd-section-name branch 5 times, most recently from 7dbba29 to b1e4214 Compare December 11, 2022 11:13

nicolas-grekas approved these changes Dec 15, 2022

View reviewed changes

carsonbot added Status: Reviewed and removed Status: Needs Review labels Dec 15, 2022

alexandre-daubois force-pushed the feat/dd-section-name branch 2 times, most recently from 00fc4ba to 3da860c Compare December 15, 2022 16:21

nicolas-grekas approved these changes Dec 15, 2022

View reviewed changes

nicolas-grekas force-pushed the feat/dd-section-name branch from 3da860c to b08b677 Compare December 15, 2022 17:10

[VarDumper] Add support of named arguments to dd() and dump() to …

2519c5c

…display the argument name

nicolas-grekas force-pushed the feat/dd-section-name branch from b08b677 to 2519c5c Compare December 15, 2022 17:11

nicolas-grekas merged commit d8d93c6 into symfony:6.3 Dec 15, 2022

nicolas-grekas mentioned this pull request Dec 15, 2022

[VarDumper] Add support of named arguments to dd() and dump() to di… symfony/symfony-docs#17568

Closed

drupol reviewed Dec 15, 2022

View reviewed changes

alexandre-daubois mentioned this pull request Dec 15, 2022

[VarDumper] Add an options builder to configure VarDumper's behavior at runtime #48667

Open

fabpot mentioned this pull request May 1, 2023

Release v6.3.0-BETA1 #50199

Merged

gharlan mentioned this pull request Aug 30, 2023

PHPStan\dumpType could support dumping more than one thing phpstan/phpstan#6419

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[VarDumper] Add support of named arguments to `dd()` and `dump()` to display a label #48432

[VarDumper] Add support of named arguments to `dd()` and `dump()` to display a label #48432

alexandre-daubois commented Dec 1, 2022 •

edited

nicolas-grekas left a comment •

edited

nicolas-grekas Dec 1, 2022

stof Dec 1, 2022

GromNaN Dec 2, 2022

alexandre-daubois Dec 2, 2022 •

edited

nicolas-grekas Dec 2, 2022 •

edited

GromNaN left a comment

GromNaN Dec 2, 2022

stof Dec 1, 2022

lyrixx commented Dec 2, 2022

alexandre-daubois commented Dec 2, 2022

azjezz Dec 2, 2022

nicolas-grekas Dec 4, 2022

alexandre-daubois Dec 6, 2022 •

edited

GromNaN Dec 6, 2022 •

edited

alexandre-daubois Dec 6, 2022

drupol commented Dec 2, 2022

nicolas-grekas left a comment •

edited

nicolas-grekas Dec 4, 2022

GromNaN commented Dec 4, 2022

nicolas-grekas left a comment

alexandre-daubois commented Dec 15, 2022 •

edited

GromNaN commented Dec 15, 2022

nicolas-grekas left a comment •

edited

nicolas-grekas commented Dec 15, 2022

drupol Dec 15, 2022

-    public static function dump(mixed $var, string $sectionName = null)
+    /**
+     * @param string|null $name
+     */
+    public static function dump(mixed $var, /*string $name = null*/)

[VarDumper] Add support of named arguments to dd() and dump() to display a label #48432

[VarDumper] Add support of named arguments to dd() and dump() to display a label #48432

Conversation

alexandre-daubois commented Dec 1, 2022 • edited

nicolas-grekas left a comment • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexandre-daubois Dec 2, 2022 • edited

Choose a reason for hiding this comment

nicolas-grekas Dec 2, 2022 • edited

Choose a reason for hiding this comment

GromNaN left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lyrixx commented Dec 2, 2022

alexandre-daubois commented Dec 2, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexandre-daubois Dec 6, 2022 • edited

Choose a reason for hiding this comment

GromNaN Dec 6, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

drupol commented Dec 2, 2022

nicolas-grekas left a comment • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

GromNaN commented Dec 4, 2022

nicolas-grekas left a comment

Choose a reason for hiding this comment

alexandre-daubois commented Dec 15, 2022 • edited

GromNaN commented Dec 15, 2022

nicolas-grekas left a comment • edited

Choose a reason for hiding this comment

nicolas-grekas commented Dec 15, 2022

Choose a reason for hiding this comment

[VarDumper] Add support of named arguments to `dd()` and `dump()` to display a label #48432

[VarDumper] Add support of named arguments to `dd()` and `dump()` to display a label #48432

alexandre-daubois commented Dec 1, 2022 •

edited

nicolas-grekas left a comment •

edited

alexandre-daubois Dec 2, 2022 •

edited

nicolas-grekas Dec 2, 2022 •

edited

alexandre-daubois Dec 6, 2022 •

edited

GromNaN Dec 6, 2022 •

edited

nicolas-grekas left a comment •

edited

alexandre-daubois commented Dec 15, 2022 •

edited

nicolas-grekas left a comment •

edited