Logging Exceptions (Advanced)

Clarity Context collects and manages the context details you've added to your code.

When an exception occurs, it builds a CodeDistortion\ClarityContext\Context object that can be used by the code doing the logging. This Context object contains the details you added (that were present in the call stack at the time).

If you'd like to handle the logging yourself, or are building a package to do so - this involves updating Laravel's exception handler app/Exceptions/Handler.php to use these Context values.

This section explains how to use this Context class.

Obtaining the Context Object

Use Clarity::getExceptionContext($e) to access the CodeDistortion\ClarityContext\Context object built for that exception.

Then you can choose how to log the exception based on what's inside the Context object.

// app/Exceptions/Handler.php

namespace App\Exceptions;

use CodeDistortion\ClarityContext\Clarity; // <<<
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Throwable;

class Handler extends ExceptionHandler
{
    …

    /**
     * Register the exception handling callbacks for the application.
     */
    public function register(): void
    {
        $this->reportable(function (Throwable $e) {

            $context = Clarity::getExceptionContext($e); // <<<
            // … perform formatting and logging here
        });
    }
}

The Context Object

The Context object includes a variety of details about the exception, including:

• the call stack / stack trace (based on $e->getTrace(), but with the file/line numbers shifted by one frame, so they make more sense),
• your context details, that were present in the call stack at the time the exception occurred,
• references to the location where the exception was thrown and caught.

$context->getException();           // the exception that was caught
$context->getChannels();            // the intended channels to log to
$context->getLevel();               // the intended reporting level (debug, … emergency)
$context->getDefault();             // the default value that will be returned
$context->getTraceIdentifiers();    // the trace identifiers
$context->getKnown();               // "known" issues associated with the exception
$context->hasKnown();               // whether the exception has "known" issues or not
$context->getReport();              // whether to trigger Laravel's report() method or not
$context->getRethrow();             // whether to rethrow, a closure to resolve it, or an exception itself to throw
$context->detailsAreWorthListing(); // whether details (other than those you can get by looking at the exception alone) are available

$stackTrace = $context->getStackTrace(); // the stack trace frames (most recent at the start)
$callStack = $context->getCallStack();   // the same as the stack trace, but in reverse

Stack Trace / Call Stack, and Frames

You can retrieve details about the call stack frames using $context->getStackTrace() or $context->getCallStack(). They contain objects representing each frame.

getStackTrace() contains the frames in order from most recent to oldest. getCallStack() is the same, except ordered from oldest to newest.

They also contain the following methods to help you find particular frames and meta information.

$stackTrace = $context->getStackTrace(); // or $context->getCallStack();

$stackTrace->getLastApplicationFrame();      // get the last application (i.e. non-vendor) frame
$stackTrace->getLastApplicationFrameIndex(); // get the index of the last application frame
$stackTrace->getExceptionThrownFrame();      // get the frame that threw the exception
$stackTrace->getExceptionThrownFrameIndex(); // get the index of the frame that threw the exception
$stackTrace->getExceptionCaughtFrame();      // get the frame that caught the exception
$stackTrace->getExceptionCaughtFrameIndex(); // get the index of the frame that caught the exception
$stackTrace->getMeta();                      // get the Meta objects - these represent the context details, amongst others
$stackTrace->getGroupedMeta();               // get the Meta objects grouped together in MetaGroups - see below

They are iterable, allowing them to be looped through.

You can retrieve the following details from the Frame objects inside:

$stackTrace = $context->getStackTrace(); // or $context->getCallStack();

foreach ($stackTrace as $frame) {
    $frame->getFile();                // the path to the file containing the code being run
    $frame->getProjectFile();         // the same file, but relative to the project-root's dir
    $frame->getLine();                // the relevant line number
    $frame->getFunction();            // the function or method being run at the time
    $frame->getClass();               // the class being used at the time
    $frame->getObject();              // the object instance being used at the time
    $frame->getType();                // the "type" ("::", "->")
    $frame->getArgs();                // the arguments the function or method was called with
    $frame->getMeta();                // retrieve the Meta objects, see below
    $frame->isApplicationFrame();     // is this an application (i.e. non-vendor) frame?
    $frame->isLastApplicationFrame(); // is this the last application frame (before the exception was thrown)?
    $frame->isVendorFrame();          // is this a vendor frame?
    $frame->isLastFrame();            // is this in the last frame in the (where the exception was thown)?
    $frame->exceptionWasThrownHere(); // was the exception thrown by this frame?
    $frame->exceptionWasCaughtHere(); // was the exception caught by this frame?
}

Note: Some of the methods like getFunction(), getClass(), getObject() won't always return a value. It depends on the circumstance. See PHP's debug_backtrace method for more details.

Meta Objects

There are 5 types of Meta objects:

• ContextMeta - when the application called Clarity::context(…) to add context details,
• CallMeta - when the Control package ran some code for the application (e.g. using Control::run()),
• LastApplicationFrameMeta - the location of the last application (i.e. non-vendor) frame,
• ExceptionThrownMeta - the location the exception was thrown,
• ExceptionCaughtMeta - the location the exception was caught.

You can retrieve the following details from the Meta objects:

// all Meta classes
$meta->getFile();        // the relevant file
$meta->getProjectFile(); // the same file, but relative to the project-root's dir
$meta->getLine();        // the relevant line number
$meta->getFunction();    // the function or method being run at the time
$meta->getClass();       // the class being used at the time
$meta->getType();        // the "type" ("::", "->")
// ContextMeta only
$meta->getContext();     // the context array or sentence
// CallMeta only
$meta->wasCaughtHere();  // whether the excepton was caught here or not
$meta->getKnown();       // the "known" issues associated to the exception

There are several ways of retrieving Meta objects:

$context->getStackTrace()->getMeta(); // all the Meta objects, in stack trace order
$context->getCallStack()->getMeta();  // all the Meta objects, in call stack order
$frame->getMeta();                    // the Meta objects present in a particular frame
$metaGroup->getMeta();                // related Meta objects, grouped togther (see below)

Each of these methods accepts a meta-class string, or several of them, which limit the result. e.g.

$context->getStackTrace()->getMeta(ContextMeta::class); // only ContextMeta objects will be returned

MetaGroup Objects

When reporting the exception details, it's useful to group the Meta objects together. MetaGroup objects provide a way of grouping the Meta objects in a logical way.

The Meta objects within are related, i.e. in the same frame and on near-by lines.

$context->getStackTrace()->getMetaGroups();
$context->getCallStack()->getMetaGroups();

Each MetaGroup contains similar details to the Frame object.

$metaGroup->getFile();                    // the path to the file containing the code being run
$metaGroup->getProjectFile();             // the same file, but relative to the project-root's dir
$metaGroup->getLine();                    // the relevant line number
$metaGroup->getFunction();                // the function or method being run at the time
$metaGroup->getClass();                   // the class being used at the time
$metaGroup->getType();                    // the "type" ("::", "->")
$metaGroup->getMeta();                    // the meta objects contained within
$metaGroup->isInApplicationFrame();       // is this in an application (i.e. non-vendor) frame?
$metaGroup->isInLastApplicationFrame();   // is this in the last application frame (before the exception was thrown)?
$metaGroup->isInVendorFrame();            // is this in a vendor frame?
$metaGroup->isInLastFrame();              // is this in the last frame (where the exception was thown)?
$metaGroup->exceptionThrownInThisFrame(); // is this in the frame the exception was thrown from?
$metaGroup->exceptionCaughtInThisFrame(); // is this in the frame the exception was caught in?

Context Objects Without an Exception

You can generate a Context object arbitrarily, without needing an exception.

The Context object returned will contain the current context details, like it normally would.

$context = Clarity::buildContextHere();