Laravel's report helper: a must for error handling

For any application, handling errors gracefully is crucial for maintaining a smooth user experience. While PHP's try-catch statements are great at catching known exceptions and preventing them from crashing your application, they also make exceptions go unnoticed. What if you also want to log and report an exception without bringing your application to a screeching halt? That's where Laravel's report helper steps into the spotlight.

The Problem: Handling Known Failures

Let's start with a common scenario: making an API call to an unreliable service. You know the request might fail, but you don't want it to bring down your entire application. Here's how you might handle something like this:

function getData(): Response|null {
	try {
	    return Http::get('https://crowdstrike.com/unreliable-api');
	} catch (RequestException $exception) {
	    // We "gracefully" handle the error by returning null and not crashing
	    // but how do we let ourselves know this happened?
	    // Log the error? Send a notification to Slack? No, we'll use report!
	
	    return null;
	}
}

In this example, we're catching the exception and returning null to prevent the application from crashing. We'll then handle the null value by informing the end user that something went wrong. But how do we let ourselves, the developers, know? How do you keep track of handled exceptions?

Enter the report Helper

Before we dive into the report helper, it's helpful to understand Laravel's default error handling behavior. By default, Laravel automatically logs unhandled errors and exceptions. If you're using an error tracking solution like Flare, these errors will also get sent to Flare. However, when you handle an exception in a try-catch block, Laravel doesn't automatically log or report it – that's where the report helper comes in.

The report helper is Laravel's solution for sending an error or exception you've handled to your logs and error tracking service, without halting the execution. It's perfect for situations where you want to catch and handle an error but still want to be notified about it.

Here's how it works:

`report($exception);`

The beauty of report is that it doesn't throw the exception or stop your code - it simply reports it and moves on.

In Flare, these reported exceptions appear like any other exception, distinguished by a "handled" label. This label indicates the exception was handled without crashing the application.

Beyond Exceptions: Reporting Custom Messages

The report helper isn't limited to exceptions. You can also use it to report custom error messages:

report('API call failed: unable to fetch user data');

Behind the scenes, Laravel will automatically create and report an exception for this message. This handy shortcut allows you to quickly provide more context about the edge-case, making debugging easier down the line.

Conditional Reporting

Finally, it's worth mentioning that, in true Laravel fashion, two additional helpers exists for conditionally reporting an exception: report_if and report_unless.

A Real-World Example

Let's revisit our initial example and see how we can use these helpers to implement a strategy of graceful degradation:

function fetchUserData($userId)
{
    try {
        $response = Http::get("example.com/api/users/{$userId}");
        
        if ($response->successful()) {
            return $response->json();
        }

        report_unless($response->notFound(), "API returned unexpected status: {$response->status()}");
        
        return null;
    } catch (HttpException $exception) {
        report($exception);
        
        return null;
    }
}

In this enhanced version:

1. We're still catching and reporting any RequestException that might occur.
2. We're using report_unless to report unexpected status codes, but not 404s (which might be expected in some cases).
3. In both error cases, we're returning null, allowing the application to continue running without the user data.

This approach allows your application to continue functioning even when parts of it fail, while ensuring you're always informed about these failures.

Conclusion

Laravel's report helper and its variants are invaluable for error handling. They allow us to keep track of handled errors and edge cases in our applications without disrupting the user experience. Errors are always inevitable but with Laravel's reporting helpers and Flare, you're well-equipped to manage them effectively.