README

To get the backtrace in PHP you can use the debug_backtrace function. By default, it can be hard to work with. The reported function name for a frame is skewed: it belongs to the previous frame. Also, options need to be passed using a bitmask.

This package provides a better way than debug_backtrace to work with a back trace. Here's an example:

// returns an array with `Spatie\Backtrace\Frame` instances
$frames = Spatie\Backtrace\Backtrace::create()->frames(); 

$firstFrame = $frames[0];

$firstFrame->file; // returns the file name
$firstFrame->lineNumber; // returns the line number
$firstFrame->class; // returns the class name

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Installation

You can install the package via composer:

composer require spatie/backtrace

Usage

This is how you can create a backtrace instance:

$backtrace = Spatie\Backtrace\Backtrace::create();

Getting the frames

To get all the frames you can call frames.

$frames = $backtrace->frames(); // contains an array with `Spatie\Backtrace\Frame` instances

A Spatie\Backtrace\Frame has these properties:

file: the name of the file
lineNumber: the line number
arguments: the arguments used for this frame. Will be null if withArguments was not used.
class: the class name for this frame. Will be null if the frame concerns a function.
method: the method used in this frame
object: the object when the frame is in an object context (method call, closure bound to object, arrow function which captured $this, etc.). Will be null if withObject was not used.
applicationFrame: contains true is this frame belongs to your application, and false if it belongs to a file in the vendor directory. A couple edge cases exist, see "application frames" below.

Collecting arguments and objects

For performance reasons, the frames of the back trace will not contain the arguments of the called functions and the object. If you want to add those, use the withArguments and withObject methods.

$backtrace = Spatie\Backtrace\Backtrace::create()->withArguments()->withObject();

Reducing arguments

For viewing purposes, arguments can be reduced to a string:

$backtrace = Spatie\Backtrace\Backtrace::create()->withArguments()->reduceArguments();

By default, some typical types will be reduced to a string. You can define your own reduction algorithm per type by implementing an ArgumentReducer:

class DateTimeWithOtherFormatArgumentReducer implements ArgumentReducer
{
    public function execute($argument): ReducedArgumentContract
    {
        if (! $argument instanceof DateTimeInterface) {
            return UnReducedArgument::create();
        }

        return new ReducedArgument(
            $argument->format('d/m/y H:i'),
            get_class($argument),
        );
    }
}

This is a copy of the built-in argument reducer for DateTimeInterface where we've updated the format. An UnReducedArgument object is returned when the argument is not of the expected type. A ReducedArgument object is returned with the reduced value of the argument and the original type of the argument.

The reducer can be used as such:

$backtrace = Spatie\Backtrace\Backtrace::create()->withArguments()->reduceArguments(
    Spatie\Backtrace\Arguments\ArgumentReducers::default([
        new DateTimeWithOtherFormatArgumentReducer()
    ])
);

Which will first execute the new reducer and then the default ones.

Setting the application path

You can use the applicationPath to pass the base path of your app. This value will be used to determine whether a frame is an application frame, or a vendor frame. Here's an example using a Laravel specific function.

$backtrace = Spatie\Backtrace\Backtrace::create()->applicationPath(base_path());

Removing the application path from the file name

You can use trimFilePaths to remove the base path of your app from the file. This will only work if you use it in conjunction with the applicationPath method re above. Here's an example using a Laravel specific function. This will ensure the Frame has the trimmedFilePath property set.

$backtrace = Backtrace::create()->applicationPath(base_path())->trimFilePaths());

Application frames

By default, a frame is considered an application frame when the file of the frame is not in the vendor directory. The following edge cases apply:

Laravel's artisan CLI file (generally found in the root of the project) is considered a vendor file and frame
Statamic's please CLI file (generally found in the root of the project) is considered a vendor file and frame

Getting a certain part of a trace

If you only want to have the frames starting from a particular frame in the backtrace you can use the startingFromFrame method:

use Spatie\Backtrace\Backtrace;
use Spatie\Backtrace\Frame;

$frames = Backtrace::create()
    ->startingFromFrame(function (Frame $frame) {
        return $frame->class === MyClass::class;
    })
    ->frames();

With this code, all frames before the frame that concerns MyClass will have been filtered out.

Alternatively, you can use the offset method, which will skip the given number of frames. In this example the first 2 frames will not end up in $frames.

$frames = Spatie\Backtrace\Backtrace::create()
    ->offset(2)
    ->frames();

Limiting the number of frames

To only get a specific number of frames use the limit function. In this example, we'll only get the first two frames.

$frames = Spatie\Backtrace\Backtrace::create()
    ->limit(2)
    ->frames();

Getting a backtrace for a throwable

Here's how you can get a backtrace for a throwable.

$frames = Spatie\Backtrace\Backtrace::createForThrowable($throwable)

Because we will use the backtrace that is already available in the throwable, the frames will contain the arguments used in the backtrace as long as the zend.exception_ignore_args INI option is disabled (set to 0) before the throwable is thrown. On the other hand, objects will never be included in the backtrace. More information.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

spatie / backtrace

Maintainers

Details