Error Handling

Error and exception handling are already configured for you when you create a new OstroJS project. All exceptions raised by your application are logged and subsequently presented to the user in the app/exceptions/handler class. Throughout this explanation, we'll go further into this class.

The debug option in your config/app.js configuration file controls how much error information is presented to the user. This option is set by default to respect the value of the APP_DEBUG environment variable saved in your.env file.

Set the APP_DEBUG environment variable to true during local development. This value should always be false in your production environment. You risk exposing sensitive configuration variables to your application's end users if the value is set to true in production.

The app/exceptions/handler class handles all exceptions. Custom exception reporting and rendering callbacks may be registered using the register method in this class. We'll go through each of these ideas in depth. Exception reporting is used to log or send exceptions to a third-party service such as Flare, Bugsnag, or Sentry. Exceptions are logged by default based on your logging setup. You are, however, allowed to track exceptions in whatever way you like.

If you need to report multiple sorts of exceptions in different ways, for example, you may use the reportable method to register a closure that will be invoked when an exception of a certain type has to be reported. By looking at the type-hint of the closure, OstroJS can figure out what kind of exception it's reporting:

It's possible that you'll need to report an exception while continuing to handle the current request. You may use the report helper method to rapidly report an exception to the exception handler without having to show the user an error page:

isValid($value) {
    try {
        // Validate the value...
    } catch (Throwable $e) {
        app('@ostro/contracts/exception/handler').report($e);
        return false;
    }
}

There will be certain exceptions in your application that you just wish to ignore and never report. The $dontReport property in your application's exception handler is set to an empty array by default. Any classes you add to this property will not be reported, but they may have their own rendering logic:

$dontReport = [
    InvalidOrderException,
];

The render method is in charge of translating a specified exception into an HTTP response that should be returned to the browser. The exception is forwarded to the base class by default, which creates a response for you. You may, however, check the exception type or respond with your own custom response:

render(request, response, $exception){
    if ($exception instanceof CustomException) {
        return response.view('errors.custom', {}, 500);
    }

    return super.render($request, $exception);
}

You can specify report and render methods directly on your custom exceptions instead of type-checking them in the exception handler's register method. The framework will automatically call these methods if they exist:

const Exception = require('./handler')
class InvalidOrderException extends Exception {
    /**
     * Report the exception.
     *
     */
    report() {
        //
    }

    /**
     * Render the exception into an HTTP response.
     *

     */
    render(request, response, $e) {
        return response.send($e);
    }
}

Some exceptions describe HTTP error codes from the server. For example, this may be a "page not found" error (404), an "unauthorized error" (401) or even a developer generated 500 error. In order to generate such a response from anywhere in your application, you may use the response.abort(404) :

response.abort(404)

Custom error pages for various HTTP status codes are simple to show with OstroJS. Create a resources/views/errors/404.html view template, for example, to modify the error page for 404 HTTP status codes. This view will be displayed on any 404 errors that your application generates. The names of the views in this directory should correspond to the HTTP status codes that they relate to. The abort method will issue a @ostro/support/exceptions/httpException object, which will be sent to the view as a helpers.exception variable:

<h2><%- helpers.exception.getMessage() %></h2>