Add options to dump function

[GromNaN]

Description

Following #48432 (review)

It would be helpful to pass options to the dump() and dd() functions.

1. @nicolas-grekas propose to use named arguments, and an option builder.

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

// or

dump($var, _trace: true, _max_depth: 4);

The underscore prefix is required to prevent conflict with named arguments that could be dynamically set.

2. In addition, I propose to return the options builder and actually display the dump in a __destruct. So that it is more fluent.

dump($var)->trace()->maxDepth(4);

A last method can be added in case the __destruct would not be called (return value affected to a variable).

dump($var)->trace()->maxDepth(4)->render();

---

To be complete, we need the same capability for the dump helper in Twig.

Example

No response

[derrabus]

2. In addition, I propose to return the options builder and actually display the dump in a __destruct. So that it is more fluent.

dump($var)->trace()->maxDepth(4);

👎🏻

Right now, dump() returns the dumped value(s). The reason for that is that you can hook dump() into an assignment or a chained function call:

some_function(
    another_function(
        dump(yet_another_function())
    )
);

$foo = dump(fetch_data());

I would like to keep that behavior.

[alexandre-daubois]

Thank you very much for opening this issue @GromNaN! If that's okay, I would love to work on this and give it a try really soon, now that #48432 is being polished and finalized. Something like a first PR with the options model, and 1 or 2 options that have been mentioned in #48432. 👍

To be noted, this syntax:

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

will only work if there are no named arguments. dump(myVar: $var, ...$options); will result of an error, as $options is considered as a positional argument and can't be placed after a named argument. The only solution that comes to my mind right now would be to actually not pass options to dump() and register these options statically.

VarDumper::options() could be static, and act just like VarDumper::$handler. Two things to be aware of:

• It registers global options to dump vars. That's cool!
• But, do we really want to globally register those options?

[GromNaN]

If we are to use the VarDumper class, we should not use the dump function shortcut.

The dumped variable could be the last function call.

VarDumper::options()->trace()->maxDepth(4)->dump($var);
VarDumper::options()->trace()->maxDepth(4)->dd($var);
VarDumper::options()->trace()->maxDepth(4)->die()->dump($var);

Brainstorming alternatives: the function could return an option builder when no argument are passed.

dump()->trace()->maxDepth(4)->values($var);
dd()->trace()->maxDepth(4)->values($var);

[alexandre-daubois]

I really like both ideas!

I am definitely convinced by the first one. The second one gives the feeling it is like a major change. Curious to hear opinions on it!

[GromNaN]

We are adding a new behavior:

the current signature make it impossible to call the function without any argument

https://github.com/symfony/symfony/pull/48432/files#r1037426040

The return type will be:

function dump(): mixed|VarDumperOptions

[alexandre-daubois]

I gave it a try. Here is a draft/WIP PR I came up with: alexandre-daubois#2

I tried an approach with options built before calling VarDumper. It uses a special named argument called _options. It looks like this:

public function __invoke(): Response
{
    $options = (new VarDumperOptions())
        ->format('html')
        ->trace()
        ->traceLimit(null)
    ;

    dump(var: 123, _options: $options);
    dd(test: 'test');

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

[alexandre-daubois]

Thank you for your feedback on my branch @GromNaN!

I added a few other methods to build options, here is how this looks like now:

I'm discovering a lot of features of the VarDumper while doing this. This reinforce my feeling that this feature is definitely a good idea, so everybody can easily manipulate VarDumper capabilities.

[carsonbot]

Thank you for this suggestion.
There has not been a lot of activity here for a while. Would you still like to see this feature?

[alexandre-daubois]

I guess yes! The PR is actually nearly done (a test has to be fixed). But otherwise, I think it is ready for one more review. However, I'm not 100% sure about the dump()->trace(2)->dump($values); syntax to dump somes values, I find it a bit ugly 🤔