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

alexandre-daubois · 2022-12-15T18:02:53Z

Q	A
Branch?	6.3
Bug fix?	no
New feature?	yes
Deprecations?	no
Tickets	Fix #48474
License	MIT
Doc PR	Todo

Following up #48432, this PR brings an options builder to configure VarDumper's behavior thanks to a special _options named argument. Here is a snippet of it in action and a screenshot of the result. Feedbacks on UI are really welcomed, especially about the debug backtrace!

#[AsController]
#[Route('/')]
class FooController
{
    public function __invoke(): Response
    {
        $options = (new VarDumperOptions())
            ->trace()
            ->stringLength()
        ;

        dump(var: ['Hi', 'Greetings' => 'Good morning, Symfony!'], _options: $options);
        dump('Classic dump');
        dd(['Options are cloned!'], named: 'This is named', _options: (clone $options)->lightArray()->traceLimit(2));

        throw new \LogicException('This code should never be reached!');
    }
}

nicolas-grekas

Thanks for tackling this, that's a complex feature because the matrix of possibilities is huge.

Here are some random thoughts:

I like the style proposed in the issue: dump()->trace()->maxDepth(4)->values($var);. I'm just wondering if values() shouldn't be named dump() or var() or ?
I also like the dump($var, _trace: true) style, which could work well with autocompletion if we describe the options as virtual arguments on the function? array{_trace: bool, ...}
instead of trace_limit, what about trace: bool|int?
have a look at FrameStub/TraceStub for dumping traces
we might want to provide a way to define the default options on the VarDumper class?

lyrixx · 2022-12-16T15:23:03Z

I like the style proposed in the issue: dump()->trace()->maxDepth(4)->values($var);. I'm just wondering if values() shouldn't be named dump() or var() or ?

As states by @derrabus, this cannot work

I don't really like the current object API:

$options = (new VarDumperOptions())
    ->trace()
    ->stringLength()
;

it's too long to type. We should not forgot we are a in debug context. So we want to be able to get a result ASAP. that's why we have the function dd(). As short as possible.

That's why I prefer the second bullet point of @nicolas-grekas comment:

dd($this, _trace: true, _maxDepth: 4);

nicolas-grekas · 2022-12-16T15:25:20Z

#48474 (comment), this cannot work

yes it can, see #48474 (comment) ;)

lyrixx · 2022-12-16T15:33:52Z

This is ugly :) I really don't like it. And it's too slow to type.

ro0NL · 2022-12-16T15:53:55Z

how is a fully autodiscoverable dump()->... too slow to type?

lyrixx · 2022-12-16T15:56:50Z

@ro0NL I mixed my thought :/ I was talking about:

$options = (new VarDumperOptions())
    ->trace()
    ->stringLength()
;

dump($this, _options: $options);

ro0NL · 2022-12-16T16:19:48Z

I'm just wondering if values() shouldn't be named dump() or var() or ?

maybe __invoke works, IIUC we could do

dump(1,2,3);
dump()(1,2,3)->trace();
dump()->trace()(1,2,3);

alexandre-daubois · 2022-12-16T16:53:07Z

I agree the current object API is a bit much to type. I am 👍 to find a better solution.

Should I try to implement both @GromNaN solution (dump returning mixed|VarDumperOptions) and @nicolas-grekas' one, together? I wonder if it would be a bit disturbing to have both ways available, and I don't have, yet, a strong opinion for one solution over the other.

Also, I really like the solution proposed by @ro0NL. If I may find a drawback, I'm afraid this syntax could be difficult to be "discovered" by yourself without reading the documentation.

GromNaN · 2022-12-16T18:17:29Z

The syntax that don't work is the one that rely on __destruct.
The last suggestion mentioned by @nicolas-grekas is dump()->trace()->maxDepth(4)->dump($var) which returns the $var as expected.

alexandre-daubois · 2022-12-17T11:54:56Z

I updated the feature. The new version allows you to do both ways:

// Passing options as named parameters
dump('Values', _trace: 5, _flags: AbstractDumper::DUMP_STRING_LENGTH);

// Use the options builder syntax
dump()
    ->trace(5)
    ->stringLength()
    ->dd('Values') // or ->dump('Values')
;

Still investigating on how to use TraceStub. Otherwise, this works well! And it is so much cleaner and quicker to type.

Also, I made the choice to only have the options builder syntax on dump, not dd. I did this, because I think it is, in my opinion, a good thing to keep never return type on dd (because never|VarDumpOptions is obviously a forbidden return type). Of course, passing options as named parameters to dd also works!

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

ro0NL · 2022-12-17T16:52:50Z

src/Symfony/Component/VarDumper/VarDumper.php

    /**
     * @param string|null $label
+     * @param VarDumperOptions|iterable $options


s/iterable/array/

… at runtime

alexandre-daubois · 2022-12-19T13:04:32Z

I've been able to use TraceStub to display the backtrace. Here is the result:

nicolas-grekas

About the default options, I'd suggest configuring them via a VAR_DUMPER_OPTIONS env var. I'd go with a url-encoded string so that it's easy to turn into an options array

nicolas-grekas · 2022-12-22T17:06:18Z

src/Symfony/Bundle/DebugBundle/composer.json

    },
    "require-dev": {
        "symfony/config": "^5.4|^6.0",
        "symfony/web-profiler-bundle": "^5.4|^6.0"
    },
    "conflict": {
        "symfony/config": "<5.4",
-        "symfony/dependency-injection": "<5.4"
+        "symfony/dependency-injection": "<5.4",
+        "symfony/var-dumper": "<6.3"


nicolas-grekas · 2022-12-22T17:06:18Z

src/Symfony/Component/VarDumper/CHANGELOG.md

@@ -6,6 +6,7 @@ CHANGELOG

 * Add caster for `WeakMap`
 * Add support of named arguments to `dd()` and `dump()` to display the argument name
+ * Add support of dumper's behavior configuration with the special `_options` named argument for `dump` and `dd`


Let's keep thins simple, eg
Allowing configuring options when dumping

nicolas-grekas · 2022-12-22T17:06:18Z

src/Symfony/Component/VarDumper/Dumper/HtmlDumperTheme.php

+/**
+ * @author Alexandre Daubois <alex.daubois@gmail.com>
+ */
+enum HtmlDumperTheme: string


this should be removed as it closes the list of possible themes, while the list is open for extensibility

nicolas-grekas · 2022-12-22T17:06:18Z

src/Symfony/Component/VarDumper/Dumper/VarDumperOptions.php

+        $this->options = array_replace($this->options, \array_intersect_key($options, $this->options));
+    }
+
+    public function dump(mixed ...$vars): mixed


would also benefit from the generics annotation

nicolas-grekas · 2022-12-22T17:06:18Z

src/Symfony/Component/VarDumper/Dumper/VarDumperOptions.php

+            $vars = [new ScalarStub('🐛')];
+        }
+
+        return dump(...($vars + $this->options));


no need for the brackets

using dump() instead of VarDumper::dump() is adding one extra frame in the backtrace.
it might be better to skip this frame (same for dd() below

nicolas-grekas · 2022-12-22T17:06:18Z

src/Symfony/Component/VarDumper/Dumper/VarDumperOptions.php

+        return $this->options;
+    }
+
+    public function set(string $option, mixed $value): static


not needed I suppose

nicolas-grekas · 2022-12-22T17:06:18Z

src/Symfony/Component/VarDumper/Factory/VarClonerFactory.php

+ *
+ * @internal
+ */
+final class VarClonerFactory


I'd better not add this class, it adds indirection

nicolas-grekas · 2022-12-22T17:06:18Z

src/Symfony/Component/VarDumper/Dumper/VarDumperOptions.php

+    }
+
+    /**
+     * Set flags manually. Valid flags are {@see AbstractDumper::DUMP_*} constants.


@param AbstractDumper::DUMP_* $flags

nicolas-grekas · 2022-12-22T17:06:18Z

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

-        if (!$vars) {
-            VarDumper::dump(new ScalarStub('🐛'));
+        $options = new VarDumperOptions($vars);
+        $vars = \array_diff_key($vars, $options->getOptions());


I'd rather ignore any arg that tarts with a _ in the foreach below

nicolas-grekas · 2022-12-22T17:06:18Z

src/Symfony/Component/VarDumper/VarDumper.php

+        }
+
+        if (self::requiresRegister($options)) {
+            self::register($options);


this will change the options of the default handler when any options changes?
this would be unexpected to me.

dunglas · 2022-12-22T17:26:47Z

When dumping large objects, it could be nice to be able to have the possibility to dump only one or several properties instead of the full object. Something like: _path: 'foo.bar' and _path: ['foo.bar', 'baz.bat'] maybe?

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

carsonbot added this to the 6.3 milestone Dec 15, 2022

alexandre-daubois force-pushed the feat/var-dumper-options branch from b90f2fc to 1a3ab94 Compare Dec 15, 2022

nicolas-grekas reviewed Dec 16, 2022

View changes

alexandre-daubois force-pushed the feat/var-dumper-options branch from 1a3ab94 to 90438de Compare Dec 17, 2022

alexandre-daubois force-pushed the feat/var-dumper-options branch from 90438de to 0b25f56 Compare Dec 17, 2022

GromNaN reviewed Dec 17, 2022

View changes

src/Symfony/Component/VarDumper/Resources/functions/dump.php Show resolved Hide resolved

ro0NL reviewed Dec 17, 2022

View changes

alexandre-daubois force-pushed the feat/var-dumper-options branch from 0b25f56 to 1b933a2 Compare Dec 18, 2022

[VarDumper] Add an options builder to configure VarDumper's behaviour…

c8f0cd9

… at runtime

alexandre-daubois force-pushed the feat/var-dumper-options branch from 1b933a2 to c8f0cd9 Compare Dec 19, 2022

nicolas-grekas reviewed Dec 22, 2022

View changes

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

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

alexandre-daubois commented Dec 15, 2022

nicolas-grekas left a comment •

edited

lyrixx commented Dec 16, 2022

nicolas-grekas commented Dec 16, 2022

lyrixx commented Dec 16, 2022

ro0NL commented Dec 16, 2022

lyrixx commented Dec 16, 2022

ro0NL commented Dec 16, 2022

alexandre-daubois commented Dec 16, 2022

GromNaN commented Dec 16, 2022

alexandre-daubois commented Dec 17, 2022 •

edited

ro0NL Dec 17, 2022

alexandre-daubois commented Dec 19, 2022

nicolas-grekas left a comment

nicolas-grekas Dec 22, 2022

nicolas-grekas Dec 22, 2022

nicolas-grekas Dec 22, 2022

nicolas-grekas Dec 22, 2022

nicolas-grekas Dec 22, 2022

nicolas-grekas Dec 22, 2022

nicolas-grekas Dec 22, 2022

nicolas-grekas Dec 22, 2022

nicolas-grekas Dec 22, 2022

nicolas-grekas Dec 22, 2022

dunglas commented Dec 22, 2022

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

Are you sure you want to change the base?

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

Conversation

alexandre-daubois commented Dec 15, 2022

nicolas-grekas left a comment • edited

lyrixx commented Dec 16, 2022

nicolas-grekas commented Dec 16, 2022

lyrixx commented Dec 16, 2022

ro0NL commented Dec 16, 2022

lyrixx commented Dec 16, 2022

ro0NL commented Dec 16, 2022

alexandre-daubois commented Dec 16, 2022

GromNaN commented Dec 16, 2022

alexandre-daubois commented Dec 17, 2022 • edited

Choose a reason for hiding this comment

alexandre-daubois commented Dec 19, 2022

nicolas-grekas 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

Choose a reason for hiding this comment

dunglas commented Dec 22, 2022

nicolas-grekas left a comment •

edited

alexandre-daubois commented Dec 17, 2022 •

edited