Reporting of Exceptions can supply an identifier to present to the end user

[peterfox]

Proposal

When reporting an exception in the exception handler. The reporter callable could return a string designed to be a unique identifier for the error that occurred. This identifier could then be displayed to the end user as an error code in a view or API response to send to a company's technical support to help diagnose an issue.

Why

Services like Sentry automatically produce a unique event ID for every exception reported. It would be a neat feature of Laravel to be able to show error IDs out of the box when an event ID is set. The benefit would be that it's easier for companies to tie together application failures from the end user to diagnostic tools like Sentry.

It feels like this is a no-brainer for modern web applications to be able to provide feedback via a unique code to end users when an error occurs and something every production application could make use of.

Those working with the likes of SPAs will need to handle how to display the error from a JSON response.

Example Usage

The report callbacks would behave in the same similar way except that a string could be returned which would set the error ID to be displayed.

// app/Exceptions/Handler.php

/**
 * Register the exception handling callbacks for the application.
 */
public function register(): void
{
    $this->reportable(function (Throwable $e): string {
        // example with Sentry
        return (string) Integration::captureUnhandledException($e);
    });
}

Possible Implementation

The following covers the basics required. I've not included things like updating the 500 error view as such a change would be more design-focused.

// changes to src/Illuminate/Foundation/Exceptions/Handler.php

protected function reportThrowable(Throwable $e): void
{
    $this->reportedExceptionMap[$e] = true;

    if (Reflector::isCallable($reportCallable = [$e, 'report']) &&
        $this->container->call($reportCallable) !== false) {
        return;
    }

    foreach ($this->reportCallbacks as $reportCallback) {
        if ($reportCallback->handles($e) && $reportCallback($e) === false) {
            // After the callback is called we can check if an event occurred.
            // This could either stop further callbacks like the false value or could occur after the if statement
            if ($reportCallback->eventId()) {
                $this->eventId = $reportCallback->eventId();
            }

            return;
        }
    }

    try {
        $logger = $this->newLogger();
    } catch (Exception) {
        throw $e;
    }

    $level = Arr::first(
        $this->levels, fn ($level, $type) => $e instanceof $type, LogLevel::ERROR
    );

    $context = $this->buildExceptionContext($e);

    method_exists($logger, $level)
        ? $logger->{$level}($e->getMessage(), $context)
        : $logger->log($level, $e->getMessage(), $context);
}

protected function invalidJson($request, ValidationException $exception)
{
    return response()->json([
        'message' => $exception->getMessage(),
        'errors' => $exception->errors(),
        // if the eventId exists, include it as a field in the JSON response
        $this->eventId ? ['id' => $this->eventId] : []
    ], $exception->status);
}

protected function renderHttpException(HttpExceptionInterface $e)
{
    $this->registerErrorViewPaths();

    if ($view = $this->getHttpExceptionView($e)) {
        try {
            return response()->view($view, [
                'errors' => new ViewErrorBag,
                'exception' => $e,
                // if the eventId exists, include it as a field in the View response
                ...$this->eventId ? ['id' => $this->eventId] : []
            ], $e->getStatusCode(), $e->getHeaders());
        } catch (Throwable $t) {
            config('app.debug') && throw $t;

            $this->report($t);
        }
    }

    return $this->convertExceptionToResponse($e);
}

// Changes to /src/Illuminate/Foundation/Exceptions/ReportableHandler.php

public function __invoke(Throwable $e)
{
    $result = call_user_func($this->callback, $e);

    if ($result === false) {
        return false;
    }
    
    // store the ID created by the report
    if (is_string($result)) {
        $this->eventId = $result;
        return false;
    }

    return ! $this->shouldStop;
}

Notes

Shouldn't be a breaking change for most people in returning a string value but it is possible. The other alternative I can think of is passing a callable as a second parameter to the report callable that allows the user to specifically set properties to add to JSON or view responses and that way developers could extend the functionality in a way they felt fit and possibly have multiple reporters set different values into the response.

e.g.

// app/Exceptions/Handler.php

/**
 * Register the exception handling callbacks for the application.
 */
public function register(): void
{
    $this->reportable(function (Throwable $e, \Closure $setProperties): string {
        // Example with Sentry
        $id = (string) Integration::captureUnhandledException($e);
        $setProperties(json: ['error-id' => $id], view: ['errorId' => $id]);
    });
}

I'm happy to implement the feature, would just rather have the thumbs up that the idea is wanted before putting in the time for it. I could see this being added to Laravel 10 or 11 with minimal fuss.

Thanks for reading!

[martinbean]

I feel this could be better solved with say, an Identifiable interface that exceptions can implement:

interface Identifiable
{
    public function getErrorId(): string;
}

Exceptions can then implement this method. The exception handler then has an interface to look for rather than iterating over the debug backtrace and also changing the current behaviour of reportable callbacks to now start returning things, that the framework then has to check elsewhere, introducing branching logic.

[peterfox]

@martinbean I believe you've misunderstood the purpose of the idea. This isn't like a type ID for an exception. Services like Sentry generate unique Event ID when you send them an exception etc. You can then use this ID to search within Sentry's dashboard to find what exception was thrown and the stack trace etc. for that specific incident. This makes it easier to match up technical support problems a customer is having with the logs occurring within the backend because each exception instance will have a unique ID in the sentry dashboard, not just per exception.

What I think you're suggesting is that Exceptions implement their identifiable error code, which makes sense and is a neat idea but is a separate idea from what I'm suggesting.

[martinbean]

@peterfox I’m familiar with Sentry, have used it for years.

The problem is, that’s Sentry‘s identifier for an exception, and is generated after the exception is thrown and reported to Sentry. So yes, I think I may have misunderstood the purpose of your idea. How are you intending to:

1. Throw an exception
2. Send it to Sentry
3. Have Sentry generate an ID
4. Send that Sentry-generated ID back to your application that has blown up because an exception occurred?

[peterfox]

@martinbean I've ultimately built a demo project with the feature in question if you want to play around with it and understand the workflow/application benefit of what I'm proposing.

Now to respond to your points:

1. Throwing an exception isn't affected by the feature, exceptions are thrown as normal by the application and caught by the handler as it is.
2. When you set up reporting with sentry in Laravel's report callables for the exception handler, it generates an event ID. The event ID is generated like a UUID on the machine and is sent with the exception. Fact is Laravel by default could just generate a UUID to append to the logs or create a new file with the logs that's unique. This feature doesn't have to focused around Sentry, it's just a common example.

// app/Exceptions/Handler.php

/**
 * Register the exception handling callbacks for the application.
 */
public function register(): void
{
    $this->reportable(function (Throwable $e): string {
        // example with Sentry
        $eventId = (string) Integration::captureUnhandledException($e);
        dd($eventId); // shows you the unique event ID
    });
}

3. Sentry generates the ID on the machine locally for you, it's not created by the service. It's otherwise not the focus of the feature. See point 2 again.
4. My suggestion is that the feature I propose will make it easier to add the event ID to the 500.blade.php view to display and to the JSON body of an API responses.

For example, see the code in point 2. and compare with this new code:

// app/Exceptions/Handler.php

/**
 * Register the exception handling callbacks for the application.
 */
public function register(): void
{
    $this->reportable(function (Throwable $e, \Closure $setProperties): string {
        // Example with Sentry
        $id = (string) Integration::captureUnhandledException($e);
        $setProperties(json: ['error-id' => $id], view: ['errorId' => $id]);
    });
}