Skip to content

slashtrace/slashtrace

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

27 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

SlashTrace - Awesome error handler

Build Status Code Coverage


Screenshot


SlashTrace is, at its core, an error and exception handler. You hook it into your error handling routine (or let it set itself up to catch all errors and exceptions), and it captures and displays a lot of nice information about your errors. It does this for normal browser requests, but also for AJAX, the CLI, and JSON APIs.

When you're done with local debugging, you can configure SlashTrace to send errors to dedicated error reporting services, like Sentry, Raygun, and Bugsnag.

Usage

  1. Install using Composer:

    composer require slashtrace/slashtrace
    
  2. Capture errors:

    use SlashTrace\SlashTrace;
    use SlashTrace\EventHandler\DebugHandler;
    
    $slashtrace = new SlashTrace();
    $slashtrace->addHandler(new DebugHandler());
    
    // Register the error and exception handlers
    $slashtrace->register();

    Alternatively, you can explicitly handle exceptions:

    try {
        // Your code
    } catch (Exception $exception) {
        $slashtrace->handleException($exception);
    }

Handlers

SlashTrace comes bundled with the DebugHandler used in the example above, but you will usually want to set it up to send errors to an error tracking service when running in production. Currently, there are handlers implemented for the following providers, and more are on the way. Click each link to view the usage documentation:

Capturing additional data

Besides the complex error information that SlashTrace captures out of the box, you can attach other types of data to each report. This is especially useful when using one of the external handlers above.

This way, SlashTrace acts like an abstraction layer between you and these providers, and normalizes the data that you provide into a single format. This helps you to avoid vendor lock-in and lets you switch error reporting providers simply by switching the handler.

Capturing user data

If you want to attach information about the affected user, you can do so like this:

use SlashTrace\Context\User;

$user = new User();
$user->setId(12345); 
$user->setEmail('[email protected]');
$user->setName('Philip J. Fry');

$slashtrace->addUser($user);

Note that a user needs at least an ID or an email. The name is completely optional.

This feature corresponds to the respective implementations in each error tracker:

Recording breadcrumbs

Sometimes a stack trace isn't enough to figure out what steps lead to an error. To this end, SlashTrace lets you record breadcrumbs during execution:

$slashtrace->recordBreadcrumb("Router loaded");
$slashtrace->recordBreadcrumb("Matched route", [
    "controller" => "orders",
    "action" => "confirm",
]);

Relevant tracker docs:

Tracking releases

Often, it's useful to know which release introduced a particular bug, or which release triggered a regression. Tagging events with a particular release or version number is very easy:

$slashtrace->setRelease("1.0.0"); // <- Your version number, commit hash, etc.

Tracker docs:

Debug renderers

When you use the bundled debug handler, it tries to choose an appropiate output renderer based on the environment in which it's running, like this:

Alternatively, you can force the debug handler to use a particular renderer:

use SlashTrace\EventHandler\DebugHandler;
use SlashTrace\DebugRenderer\DebugJsonRenderer;

$handler = new DebugHandler();
$handler->setRenderer(new DebugJsonRenderer());

$slashtrace->addHandler($handler);