Dreamfork
Errors
Introduction
Upon initiating a new Dreamfork project, error and exception handling come pre-configured for your convenience. The App\Exceptions\Handler class serves as the central location where all exceptions thrown by your application are logged and subsequently presented to the user. Further exploration of this class will be covered in more detail throughout this documentation.
Configuration
The debug option in your config/app.php configuration file dictates the level of error information displayed to the user. By default, this option is configured to respect the value of the APP_DEBUG environment variable, which is stored in your .env file.
For local development, it is recommended to set the APP_DEBUG environment variable to true. However, in a production environment, this value should always be set to false. Setting the value to true in a production environment poses a risk of exposing sensitive configuration values to your application's end users.
The Exception Handler
Reporting Exceptions
All exceptions in the application are handled by the App\Exceptions\Handler class, which, in turn, inherits from the main Exception Handler. This class contains the register method responsible for capturing all unhandled exceptions in the application and forwarding them to the main handler. If you feel the need to handle exceptions in a custom way, you can handle the exception within the register method instead of passing it to the reportable method. Alternatively, you can perform specific actions before forwarding the exception to reportable.
// App\Exceptions\Handler.php
public function register(\Throwable $e): void
{
// Performing own actions on exception before passing it to main handler.
// ...
$this->reportable($e);
}
Ignoring Exceptions
Handler also allows you to define exceptions that should be muted and not reported further. To achieve this, assign an array of such exceptions to the $dontReport variable.
// App\Exceptions\Handler.php
protected $dontReport = [
\Exception::class
];
public function register(\Throwable $e): void
{
$this->reportable($e);
}
Hiding Exceptions
Handler also offers the ability to hide exception details when the application is not in debug mode. By default, details related to database handling exceptions are hidden. However, you can customize this behavior by extending the list of exceptions to be hidden. To achieve this, assign an array of specific exceptions to the $dontFlash variable.
// App\Exceptions\Handler.php
protected $dontFlash = [
Framework\Exceptions\Database\QueryExecutionError::class
App\Exceptions\MyError::class
];
public function register(\Throwable $e): void
{
$this->reportable($e);
}
When customizing the
$dontFlasharray, includeQueryExecutionError, as shown above, to maintain default database exception handling. Omitting this will impact database-related exceptions.
Global Log Context
When possible, DreamFork automatically includes the ID of the currently authorized user as contextual data for each exception. It is also possible to define custom global contextual data by implementing the context method on the Handler:
// App\Exceptions\Handler.php
public function context(): array
{
return array_merge(parent::context(), [ 'foo' => 'bar', ]);
}
Exception Log Context
While including context in every log message can be beneficial, there are instances where a specific exception may require unique context for enhanced logging. By defining a context method within one of your application's exceptions, you can specify any data pertinent to that exception, which will be added to the exception's log entry:
<?php
namespace App\Exceptions;
class CustomException extends \Exception
{
public function context() {
return ['custom' => 'my_custom_value'];
}
}
Exception Log Levels
All application logs resulting from the handling of a caught exception are recorded with a specified log level indicating the importance of the message being logged. If you wish to associate a particular type of exception with a specific log level, you can define the $levels property. This property should contain an array of exception types and their corresponding log levels, following the PSR-3 standard:
// App\Exceptions\Handler.php
use Framework\Log\LogLevel;
protected $levels = [
\PDOException::class => LogLevel::CRITICAL
];
Rendering Exceptions
DreamFork converts caught exceptions into responses based on the utilized interface. For example, when using the API interface and the request includes the header Accept: application/json, the Handler will return a JsonResponse with an appropriate structure. Otherwise, it will return an HTTP response with a rendered view describing the caught exception.
Exception Response Configuration
Returned responses contain varying levels of feedback information based on the debug configuration. When the debug mode is enabled, the application provides expanded data, assisting developers in pinpointing the cause of an exception. In cases where the debug mode is disabled, the application returns minimal data to prevent potential leakage of inappropriate information when users encounter errors in the application.
HTTP Exceptions
DreamFork by default provides two types of rendered views for exceptions. The developer view, available when the debug mode is enabled, displays comprehensive information about the caught exception. The user view, applicable when the debug mode is disabled, presents a general error message along with the status code.
Custom HTTP Error Pages
The previously described views are available in the directory /resources/views/exceptions. Feel free to customize them as needed.
If you intend to make significant modifications to these views, you may need to edit the exception renderer located in the
/framework/Exceptions/ExceptionRenderer.phpdirectory.
Logging
As previously mentioned, DreamFork logs caught exceptions by recording them in the event log. This log is located in the /storage/logs/dreamfork.log directory and contains simplified entries regarding the caught exceptions.