Stacktrace arguments

When an error occurs in your application, Flare will send the stacktrace of the error to Flare. This stacktrace contains the file and line number where the error occurred and the argument values passed to the function or method that caused the error.

Flare shows the arguments on the frame that makes the call. So for each frame, you see the values used in the call on that line. When a parameter falls back to its default value, Flare shows that default. Variadic arguments are shown too, marked with ….

These argument values have been significantly reduced to make them easier to read and reduce the amount of data sent to Flare, which means that the arguments are not always complete. To see the full arguments, you can always use a glow to send the whole parameter to Flare.

For example, let's say you have the following DateTime object:

new DateTime('2020-05-16 14:00:00', new DateTimeZone('Europe/Brussels'))

Flare will automatically reduce this to the following:

16 May 2020 14:00:00 Europe/Brussels

To stop sending stack frame arguments to Flare, ignore the StackFrameArguments collect in config/flare.php:

use Spatie\FlareClient\Enums\CollectType;

'collects' => FlareConfig::defaultCollects(
    ignore: [CollectType::StackFrameArguments],
),

When Flare reduces arguments, the stacktrace should contain the arguments used with each frame. This is on some Linux versions of PHP not enabled by default, so Flare automatically sets the zend.exception_ignore_args ini setting to 0.

To keep your own value for zend.exception_ignore_args, set force_php_ini_setting to false. Flare then does not change the ini setting. When PHP ignores arguments, Flare receives no arguments:

'collects' => FlareConfig::defaultCollects(
    extra: [
        CollectType::StackFrameArguments->value => [
            'force_php_ini_setting' => false,
        ]
    ],
),

It is possible to configure how these arguments are reduced. You can even implement your own reducers. By default, the following reducers are used:

• BaseTypeArgumentReducer
• ArrayArgumentReducer
• StdClassArgumentReducer
• EnumArgumentReducer
• ClosureArgumentReducer
• DateTimeArgumentReducer
• DateTimeZoneArgumentReducer
• SymphonyRequestArgumentReducer
• ModelArgumentReducer
• CollectionArgumentReducer
• ViewArgumentReducer

You can use your own set of reducers as such:

'collects' => FlareConfig::defaultCollects(
    extra: [
        CollectType::StackFrameArguments->value => [
            'argument_reducers' => [
                MyCustomArgumentReducer::class,
            ],
        ]
    ],
),

When you want to extend the default set of reducers, you can do the following:

'collects' => FlareConfig::defaultCollects(
    extra: [
        CollectType::StackFrameArguments->value => [
            'argument_reducers' => [
                ...FlareConfig::defaultArgumentReducers(),
                MyCustomArgumentReducer::class,
            ],
        ]
    ],
),

Implementing your reducer

Each reducer implements Spatie\Backtrace\Arguments\Reducers\ArgumentReducer. This interface contains a single method, execute, which provides the original argument value:

interface ArgumentReducer
{
    public function execute(mixed $argument): ReducedArgumentContract;
}

In the end, three types of values can be returned:

When the reducer could not reduce this type of argument value:

return UnReducedArgument::create();

When the reducer could reduce the argument value, but a part was truncated due to the size:

return new TruncatedReducedArgument(
    array_slice($argument, 0, 25), // The reduced value
    'array' // The original type of the argument
);

When the reducer could reduce the full argument value:

return new ReducedArgument(
    $argument, // The reduced value
    'array' // The original type of the argument
);

For example, the DateTimeArgumentReducer from the example above looks like this:

class DateTimeArgumentReducer implements ArgumentReducer
{
    public function execute(mixed $argument): ReducedArgumentContract
    {
        if (! $argument instanceof \DateTimeInterface) {
            return UnReducedArgument::create();
        }
        
        return new ReducedArgument(
            $argument->format('d M Y H:i:s e'),
            get_class($argument),
        );
    }
}