[VarDumper] Add support for options in `dump()`/`dd()` #48667

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

Q	A
Branch?	6.4
Bug fix?	no
New feature?	yes
Deprecations?	no
Tickets	Fix #48474
License	MIT

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!

<?php

use Symfony\Component\VarDumper\Dumper\CliDumper;

require 'vendor/autoload.php';

dump(
    var: ['Hi', 'Greetings' => 'Good morning, Symfony!'],
    _trace: true,
    _flags: CliDumper::DUMP_LIGHT_ARRAY | CliDumper::DUMP_STRING_LENGTH,
);

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.

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

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

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

dump($this, _options: $options);

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

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

src/Symfony/Bundle/DebugBundle/composer.json

src/Symfony/Component/VarDumper/CHANGELOG.md

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

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

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

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

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

nicolas-grekas · 2022-12-22T17:04:44Z

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.

requiresRegister helps on taking care of registering again the handler if dump/dd is not called with the exact same set of options as the previous call (this should work great with options defined in an env var!). So if you call the default dumper (I assume what you called "default dumper" is the one called without any special option? I may be wrong 😄), it should be registered again with its default options.

I struggled a bit on this part, only a few options need a full and new registration. I may be missing something?

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?

alexandre-daubois · 2022-12-23T06:58:53Z

@nicolas-grekas thank you for the review, I'll check this out! The env var is also a great idea too, in my opinion.
Edit: the env var mechanism is in!

@dunglas I really like your proposition! Giving the size of this PR, I think it would deserve a separate one. Definitely keeping your idea this in mind 👍

butschster · 2024-05-02T18:41:11Z

Hey @alexandre-daubois! We're currently working on Buggregator, and it can be used as a server for displaying dumps for the var-dumper component. I really like your PR with options. However, it would be great if you also provided the ability to add custom context as an array to a dump function.

$options = (new VarDumperOptions())
    ->withContext(['language' => 'php'])
;

dump($this, _options: $options);

This feature can be used in various scenarios, such as providing information about syntax highlighting for string dumps or offering details about the project to which a dump should be linked.

Would you kindly consider adding support for custom context in the dump function

Thanks for PR!

alexandre-daubois · 2024-05-03T07:45:59Z

Hey @butschster! Thank you for your interest in this PR! I kinda forgot about it, but I still think it is worth it to have this in the framework.

About the context feature you're talking about: while I understand it would help in your case, I find it weird to add some context here that won't be used apart from super precise use cases. Two solutions here:

If you have some strong reasons and use case, a complementary PR could be proposed ;
We may keep VarDumpOptions not final so you can extend it for all your needs. I think that's the quick win 😊

Anyway, I'll try finalize this PR. Thanks for digging it up!

nicolas-grekas

Coming back after a few months here, I'm wondering if this is worth the extra complexity...
We have an unresolved concern, which is that dump-handlers don't have to react to options, and we don't have an internal API to communicate those options to them. If we do want options, we need that API.

I'm wondering if we need this options class. We could instead document options using @param on the dump() function, so that using them would look like: dump($var, _max_depth: 3). That might be good enough in terms of DX.

src/Symfony/Component/VarDumper/Tests/Dumper/functions/dump_without_args.phpt

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

alexandre-daubois · 2024-08-19T12:09:11Z

I pushed a rebased, cleaner version. I removed the Options class and replaced it with an array, which seems enough. Tests are fixed.

We have an unresolved concern, which is that dump-handlers don't have to react to options, and we don't have an internal API to communicate those options to them. If we do want options, we need that API.

I wasn't exactly sure what you meant here. I updated VarDumper::dump() in order to pass options to the registered dump handler. This way, if one defines its own handler, options can either be handled or ignored. Is that what you had in mind?

nicolas-grekas · 2024-08-19T12:29:54Z

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


        if ($cursor->attr || '' !== $label) {
            $dumper->dumpScalar($cursor, 'label', $label);
        }
        $cursor->hashType = 0;
        $this->dumpItem($dumper, $cursor, $refs, $this->data[$this->position][$this->key]);
+
+        if (false !== ($options['_trace'] ?? false) && $cursor->attr = $this->context[BacktraceContextProvider::class] ?? []) {


comparisons to boolean... you missed testing this is === true :P

Actually, _trace can be either a bool or a integer. false disables the trace. If it's an integer, we limit the trace size. Also, the limit is disabled if _trace is <= 0. That's why we can't use === true here 😄 But maybe limiting the stack trace isn't that useful and we may only accept a boolean for _trace?

ah, makes sense then, let's keep as is :)

OskarStark · 2024-08-20T21:47:28Z

PR title and header needs to be updated to reflect the content of this PR, thanks

alexandre-daubois · 2024-08-21T06:40:48Z

Should be better now @OskarStark

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 December 15, 2022 18:07

nicolas-grekas reviewed Dec 16, 2022

View reviewed changes

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

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

GromNaN reviewed Dec 17, 2022

View reviewed changes

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

alexandre-daubois force-pushed the feat/var-dumper-options branch 2 times, most recently from 1b933a2 to c8f0cd9 Compare December 19, 2022 13:00

nicolas-grekas reviewed Dec 22, 2022

View reviewed changes

alexandre-daubois force-pushed the feat/var-dumper-options branch 3 times, most recently from d3ccb34 to 1916b04 Compare December 27, 2022 19:27

alexandre-daubois force-pushed the feat/var-dumper-options branch from 1916b04 to a596b1c Compare January 1, 2023 19:09

nicolas-grekas mentioned this pull request Jan 19, 2023

FFICasterTest::testCastNonTrailingCharPointer() breaks PHPs community build #47668

Closed

alexandre-daubois mentioned this pull request Jan 22, 2023

[VarDumper] Add an options builder to configure VarDumper's behavior at runtime symfony/symfony-docs#17787

Open

alexandre-daubois force-pushed the feat/var-dumper-options branch 2 times, most recently from 229123d to 9be6dea Compare January 22, 2023 11:09

nicolas-grekas added this to the 7.1 milestone Nov 15, 2023

butschster mentioned this pull request May 2, 2024

Include Syntax Highlighting Language Option in Var-Dumper Dumps buggregator/server#164

Closed

alexandre-daubois force-pushed the feat/var-dumper-options branch from 74b5287 to 59db402 Compare May 3, 2024 07:26

alexandre-daubois force-pushed the feat/var-dumper-options branch from 59db402 to 32f4839 Compare May 3, 2024 07:47

xabbuh modified the milestones: 7.1, 7.2 May 15, 2024

alexandre-daubois mentioned this pull request Jun 3, 2024

[HtmlDumper] - Change $themes and $displayOptions to public static #57232

Open

nicolas-grekas reviewed Aug 12, 2024

View reviewed changes

src/Symfony/Component/VarDumper/Tests/Dumper/functions/dump_without_args.phpt Outdated Show resolved Hide resolved

src/Symfony/Component/VarDumper/Dumper/VarDumperOptions.php Outdated Show resolved Hide resolved

alexandre-daubois force-pushed the feat/var-dumper-options branch 5 times, most recently from a94b07a to df524cb Compare August 19, 2024 12:06

alexandre-daubois force-pushed the feat/var-dumper-options branch 2 times, most recently from b3bd92a to e1a90f4 Compare August 19, 2024 12:11

nicolas-grekas reviewed Aug 19, 2024

View reviewed changes

alexandre-daubois force-pushed the feat/var-dumper-options branch from e1a90f4 to b700997 Compare August 19, 2024 13:01

alexandre-daubois changed the title ~~[VarDumper] Add an options builder to configure VarDumper's behavior at runtime~~ [VarDumper] Add support for options in dump()/dd() Aug 21, 2024

alexandre-daubois force-pushed the feat/var-dumper-options branch from b700997 to b477b6a Compare August 21, 2024 06:35

[VarDumper] Add support for options in dump()/dd()

9077e4e

alexandre-daubois force-pushed the feat/var-dumper-options branch from b477b6a to 9077e4e Compare August 21, 2024 06:36

fabpot modified the milestones: 7.2, 7.3 Nov 20, 2024

fabpot modified the milestones: 7.3, 7.4 May 26, 2025

Uh oh!

[VarDumper] Add support for options in dump()/dd() #48667

Are you sure you want to change the base?

[VarDumper] Add support for options in dump()/dd() #48667

Uh oh!

Conversation

alexandre-daubois commented Dec 15, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nicolas-grekas left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lyrixx commented Dec 16, 2022

Uh oh!

nicolas-grekas commented Dec 16, 2022

Uh oh!

lyrixx commented Dec 16, 2022

Uh oh!

lyrixx commented Dec 16, 2022

Uh oh!

alexandre-daubois commented Dec 16, 2022

Uh oh!

GromNaN commented Dec 16, 2022

Uh oh!

alexandre-daubois commented Dec 17, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

alexandre-daubois commented Dec 19, 2022

Uh oh!

nicolas-grekas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nicolas-grekas Dec 22, 2022

Choose a reason for hiding this comment

Uh oh!

alexandre-daubois Jan 1, 2023

Choose a reason for hiding this comment

Uh oh!

dunglas commented Dec 22, 2022

Uh oh!

alexandre-daubois commented Dec 23, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

butschster commented May 2, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alexandre-daubois commented May 3, 2024

Uh oh!

nicolas-grekas left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

alexandre-daubois commented Aug 19, 2024

Uh oh!

nicolas-grekas Aug 19, 2024

Choose a reason for hiding this comment

Uh oh!

alexandre-daubois Aug 19, 2024

Choose a reason for hiding this comment

Uh oh!

nicolas-grekas Aug 19, 2024

Choose a reason for hiding this comment

Uh oh!

OskarStark commented Aug 20, 2024

Uh oh!

alexandre-daubois commented Aug 21, 2024

Uh oh!

[VarDumper] Add support for options in `dump()`/`dd()` #48667

[VarDumper] Add support for options in `dump()`/`dd()` #48667

alexandre-daubois commented Dec 15, 2022 •

edited

Loading

nicolas-grekas left a comment •

edited

Loading

alexandre-daubois commented Dec 17, 2022 •

edited

Loading

alexandre-daubois commented Dec 23, 2022 •

edited

Loading

butschster commented May 2, 2024 •

edited

Loading

nicolas-grekas left a comment •

edited

Loading