[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 ;)

nicolas-grekas · 2022-12-01T18:01:22Z

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

@@ -266,6 +271,11 @@ public function dump(DumperInterface $dumper)
        if ($cursor->attr = $this->context[SourceContextProvider::class] ?? []) {
            $cursor->attr['if_links'] = true;
            $cursor->hashType = -1;
+
+            if (null !== ($sectionName = $this->context['section_name'] ?? null)) {


no need for the extra brackets

nicolas-grekas · 2022-12-01T18:01:22Z

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

@@ -266,6 +271,11 @@ public function dump(DumperInterface $dumper)
        if ($cursor->attr = $this->context[SourceContextProvider::class] ?? []) {
            $cursor->attr['if_links'] = true;
            $cursor->hashType = -1;
+
+            if (null !== ($sectionName = $this->context['section_name'] ?? null)) {
+                $dumper->dumpScalar($cursor, 'default', $sectionName);


let's make a single call to dumpScalar for label + ^

nicolas-grekas · 2022-12-01T18:01:22Z

src/Symfony/Component/VarDumper/CHANGELOG.md

+6.3
+---
+
+ * Add support of named arguments to `dd()` and `dump()` to display a "section name"


The function can be named according to what it actually does.

Suggested change

* Add support of named arguments to `dd()` and `dump()` to display a "section name"

* Add support of named arguments to `dd()` and `dump()` to display the argument name.

nicolas-grekas · 2022-12-01T18:01: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)


$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.

GromNaN · 2022-12-02T08:30:16Z

src/Symfony/Component/VarDumper/CHANGELOG.md

+6.3
+---
+
+ * Add support of named arguments to `dd()` and `dump()` to display a "section name"


The function can be named according to what it actually does.

Suggested change

* Add support of named arguments to `dd()` and `dump()` to display a "section name"

* Add support of named arguments to `dd()` and `dump()` to display the argument name.

GromNaN · 2022-12-02T08:30:16Z

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*/)

stof · 2022-12-02T08:33:40Z

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

     */
-    function dump(mixed $var, mixed ...$moreVars): mixed
+    function dump(mixed ...$vars): mixed


the previous signature made it impossible to call the function without any argument. This is not the case anymore.

If we keep the same signature, we're not able to name the first argument. The following code doesn't work:

dump(first: 'Hello');

PHP will tell that $var parameter is missing. But we may throw a \LogicException if no argument is passed at all. Would that suit?

no exception please, not for a debugging tool
dump() could just output the ^?

It seems (unfortunately) tricky to me to display only the caret (or anything else "special"), because VarDumper:dump() must absolutely take an argument. Obviously we can't pass null to it.

Could dumping null when no argument is passed to dump() be acceptable?

We can pass a stub object, and with a custom stubcaster, display it as we want.

@alexandre-daubois I would not dump null, as that's a valid dump value as well

Yep, I definitely agree @stof! That was not a good idea.

Just learnt about StubCaster, it works great. Thanks for the hint @nicolas-grekas!

I updated the first screenshot of the description to reflect the changes

stof · 2022-12-02T08:33:40Z

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

…display the argument name

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:19Z

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++;

}

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

Nice feature !

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 Dec 1, 2022

nicolas-grekas reviewed Dec 1, 2022

View changes

GromNaN reviewed Dec 2, 2022

View changes

stof reviewed Dec 2, 2022

View 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

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

984aceb

…display the argument name

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

azjezz reviewed Dec 2, 2022

View changes

[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

nicolas-grekas Dec 1, 2022

nicolas-grekas Dec 1, 2022

GromNaN Dec 2, 2022

nicolas-grekas Dec 1, 2022

stof Dec 2, 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

GromNaN Dec 2, 2022

stof Dec 2, 2022

alexandre-daubois Dec 2, 2022

nicolas-grekas Dec 2, 2022

nicolas-grekas Dec 2, 2022

alexandre-daubois Dec 2, 2022

nicolas-grekas Dec 2, 2022

stof Dec 2, 2022

alexandre-daubois Dec 2, 2022 •

edited

stof Dec 2, 2022

lyrixx commented Dec 2, 2022

alexandre-daubois commented Dec 2, 2022

azjezz Dec 2, 2022

drupol commented Dec 2, 2022

	* Add support of named arguments to `dd()` and `dump()` to display a "section name"
	* Add support of named arguments to `dd()` and `dump()` to display the argument name.

-    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

Are you sure you want to change the base?

[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

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

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

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

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

drupol commented Dec 2, 2022

[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 2, 2022 •

edited