Stars: 270
Forks: 17
Pull Requests: 17
Issues: 0
Watchers: 8
Last Updated: 2023-09-04 20:10:20
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
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.
You can install the package via composer:
composer require spatie/backtrace
This is how you can create a backtrace instance:
$backtrace = Spatie\Backtrace\Backtrace::create();
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 filelineNumber
: the line numberarguments
: 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 frameapplicationFrame
: contains true
is this frame belongs to your application, and false
if it belongs to a file in
the vendor directoryFor performance reasons, the frames of the back trace will not contain the arguments of the called functions. If you
want to add those use the withArguments
method.
$backtrace = Spatie\Backtrace\Backtrace::create()->withArguments();
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.
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());
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();
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();
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 the throwable, the frames will always contain the arguments used.
composer test
Please see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.
Please review our security policy on how to report security vulnerabilities.
The MIT License (MIT). Please see License File for more information.