README

记录异常（高级）

Clarity Context 收集并管理您添加到代码中的上下文细节。

当发生异常时，它会构建一个 CodeDistortion\ClarityContext\Context 对象，该对象可以被进行记录的代码使用。这个 Context 对象包含您添加的详细信息（当时在调用栈中存在的）。

如果您想自己处理记录，或者正在构建一个用于此目的的包，则需要更新 Laravel 的 异常处理器 app/Exceptions/Handler.php 以使用这些 Context 值。

本节解释如何使用这个Context类。

获取上下文对象

使用Clarity::getExceptionContext($e)来访问为该异常构建的CodeDistortion\ClarityContext\Context对象。

然后您可以根据Context对象中的内容选择如何记录异常。

// 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
        });
    }
}

上下文对象

Context对象包含有关异常的各种详细信息，包括

• 调用栈/堆栈跟踪（基于$e->getTrace()，但文件/行号向上一帧偏移，因此它们更有意义），
• 异常发生时的上下文详细信息，
• 异常抛出和捕获的位置引用。

$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

堆栈跟踪/调用栈，以及帧

您可以使用$context->getStackTrace()或$context->getCallStack()检索有关调用栈帧的详细信息。它们包含表示每个帧的对象。

getStackTrace()按照从最近到最远的顺序包含帧。getCallStack()与之相同，只是顺序从最远到最近。

它们还包含以下方法来帮助您找到特定的帧和元信息。

$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

它们是可迭代的，因此可以遍历。

您可以从以下Frame对象中检索以下详细信息

$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?
}

注意：一些方法如getFunction()、getClass()、getObject()并不总是返回值。这取决于具体情况。有关更多详细信息，请参阅PHP的debug_backtrace方法。

元对象

有5种类型的元对象

• ContextMeta - 当应用程序调用Clarity::context(…)添加上下文详细信息时，
• CallMeta - 当控制包为应用程序运行一些代码时（例如使用Control::run()），
• LastApplicationFrameMeta - 最后一个应用程序（即非供应商）帧的位置，
• ExceptionThrownMeta - 异常被抛出的位置，
• ExceptionCaughtMeta - 异常被捕获的位置。

您可以从元对象中检索以下详细信息

// 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

有几种方法可以检索元对象

$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)

这些方法中的每一个都接受一个元类字符串，或者多个它们，这限制了结果。例如。

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

元组对象

在报告异常详细信息时，将元对象分组在一起非常有用。MetaGroup对象提供了一种以逻辑方式分组元对象的方法。

组内的元对象相关联，即在同一个帧和附近行。

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

每个MetaGroup包含与Frame对象相似的详细信息。

$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 = Clarity::buildContextHere();