Error Handling
PHP is an "exception-light" programming language, meaning that it doesn't throw exceptions for every little thing that goes wrong unlike other languages such as Python.
The chapter Errors and Exceptions from PHP The Right Way explains in great detail how PHP handles errors.
The following does not throw an exception but a warning
Warning: Undefined variable $foo and "Hello world" is still printed.
<?php
echo $foo;
echo 'Hello world';PHP categorizes errors into different levels of severity, with three primary types of
messages: errors, notices, and warnings.
Each type corresponds to a specific constant, namely E_ERROR, E_NOTICE, and E_WARNING.
The list of all error constants can be found here.
Errors with the severity E_ERROR are fatal and result in the termination of the script execution.
They occur when there is a critical error, for e.g. a syntax error or undefined function.
Notices (E_NOTICE) and warnings (E_WARNING) don't halt the script execution.
They produce a message and continue processing.
Notices are advisory messages that occur when PHP encounters something that might be an error, and warnings are non-fatal errors.
Displaying error details to the user exposes information about the structure of the application. In development, it's useful to see the errors to debug the application, but in production, it would present a security risk.
By default, errors are logged in the webserver error.log file.
Here is a summary of the error configuration options:
- error_reporting: What levels of errors get triggered.
- display_errors: Whether to show triggered errors in script output.
- display_startup_errors: Whether to show errors that were triggered during PHP's startup sequence.
- log_errors: Whether to write triggered errors to a log file.
error_reporting should always be set to E_ALL except if certain error severities should be
ignored.
To show every possible error during development, the php.ini file should be configured like this:
display_errors = On
display_startup_errors = On
error_reporting = E_ALL
log_errors = OnThis will show the error details to the user either by the default PHP error message, the framework default error handler, the debugging tool (an xdebug error looks like this) or a custom error handler.
In production, no error detail should ever be made visible to the user.
File: php.ini
display_errors = Off
display_startup_errors = Off
error_reporting = E_ALL
log_errors = OnThis will take into account the errors, log them and display a generic error page but not show the details.
The place where errors are logged, how they're logged, and the form in which development error details and production error pages are rendered can be customized with a custom error handler.
Slim already has an own error handler used by default. It logs the errors and displays the details in a page designed by the framework.
In my opinion, the slim error handler can be improved in a few ways. Symfony has a great error page that displays the error details in a clear and pretty format. Laravel uses the library whoops, which also displays error details very well.
The priority for me in an error details page is that the important and relevant bits are highlighted to be
seen clearly and recognized quickly. For example, the path to the file where the error occurred
doesn't need to have the same font-size as the file name and the line number. And the part before
src/ can be completely removed.
Or in the stack trace, the files located inside the src directory should stand out next to those
in the vendor directory.
Error details page for a warning:
With a custom error handler, it is important to note that errors that happen before the error handler is initialized or errors that happen inside the error handler will be handled by the server's default error handler.
This is why it is important to configure the php.ini file correctly even if the
custom error handler is configured separately.
The custom error handler uses the following configuration values.
They are initialized in defaults.php and should be changed in the environment specific config files.
File: config/defaults.php
// Error handler
$settings['error'] = [
// Should be set to false in production. When set to true, it will throw an ErrorException for notices and warnings.
'display_error_details' => false,
'log_errors' => true,
'log_error_details' => true,
];The Configuration chapter details how the different environments are specified loaded.
All errors, warnings and notices should be displayed in the browser while developing.
File: config/env/env.dev.php
// Display error details in browser and throw ErrorException for notices and warnings
$settings['error']['display_error_details'] = true;Errors, warnings and notices should be logged, but details shouldn't be shown to the client in production.
File: config/env/env.prod.php
// Display generic error page without details
$settings['error']['display_error_details'] = false;During testing, every notice and warning should bring the test to a halt, so
display_error_details should be true.
File: config/env/env.test.php
// Enable display_error_details for testing as this will throw an ErrorException for notices and warnings
$settings['error']['display_error_details'] = true;During development, notices and warnings should be addressed the same way as fatal errors.
The script should stop the execution, the error logged and an error details page with stack
trace displayed in the browser.
Symfony and Laravel are "exception-heavy" in debug mode for a long time already.
This means that notices and warnings are transformed into exceptions.
The slim error middleware then catches them, and the custom DefaultErrorHandler can display
the error details.
The middleware that is responsible for turning notices and warnings into fatal errors in development
is the NonFatalErrorHandlerMiddleware.
It does so by throwing an ErrorException (if display_error_details is true).
This middleware is also in charge of logging those non-fatal errors, as in production (when
display_error_details is false),
the ErrorException is not thrown for notices and warnings which means that
the DefaultErrorHandler will not be called and can't log them.
The PHP function set_error_handler enables the custom handling of the non-fatal errors.
File: src/Application/Middleware/NonFatalErrorHandlerMiddleware.php
<?php
namespace App\Application\Middleware;
use ErrorException;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;
use Psr\Log\LoggerInterface;
final class NonFatalErrorHandlerMiddleware implements MiddlewareInterface
{
private bool $displayErrorDetails;
private bool $logErrors;
public function __construct(bool $displayErrorDetails, bool $logErrors, private readonly LoggerInterface $logger)
{
$this->displayErrorDetails = $displayErrorDetails;
$this->logErrors = $logErrors;
}
public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
{
// set_error_handler only handles non-fatal errors. The function callback is not called by fatal errors.
set_error_handler(
function ($severity, $message, $file, $line) {
// Don't throw exception if error reporting is turned off.
// '&' checks if a particular error level is included in the result of error_reporting().
if (error_reporting() & $severity) {
// Log non fatal errors if logging is enabled
if ($this->logErrors) {
// If error is warning
if ($severity === E_WARNING | E_CORE_WARNING | E_COMPILE_WARNING | E_USER_WARNING) {
$this->logger->warning("Warning [$severity] $message on line $line in file $file");
} // If error is non-fatal and is not a warning
else {
$this->logger->notice("Notice [$severity] $message on line $line in file $file");
}
}
if ($this->displayErrorDetails === true) {
// Throw ErrorException to stop script execution and have access to more error details
// Logging for fatal errors happens in DefaultErrorHandler.php
throw new ErrorException($message, 0, $severity, $file, $line);
}
}
return true;
}
);
return $handler->handle($request);
}
}The NonFatalErrorHandlerMiddleware is instantiated in the
DI-container
with the display_error_details and log_errors config values as well as the logger instance.
File: config/container.php
use App\Application\Middleware\NonFatalErrorHandlerMiddleware;
use Psr\Container\ContainerInterface;
use Psr\Log\LoggerInterface;
return [
// ...
NonFatalErrorHandlerMiddleware::class => function (ContainerInterface $container) {
$config = $container->get('settings')['error'];
$logger = $container->get(LoggerInterface::class);
return new NonFatalErrorHandlerMiddleware(
(bool)$config['display_error_details'],
(bool)$config['log_errors'],
$logger,
);
},
];This middleware is the second last in the middleware stack.
File: config/middleware.php
use Slim\App;
use App\Application\Middleware\NonFatalErrorHandlerMiddleware;
return function (App $app) {
// ...
$app->add(NonFatalErrorHandlerMiddleware::class);
// ErrorMiddleware is the only middleware that comes after the NonFatalErrorHandlerMiddleware
};The error middleware is in charge of catching fatal errors and
if there is a Throwable, invoke the custom DefaultErrorHandler.php.
Slim has an inbuilt ErrorMiddleware which is designed call an error handler.
In order for the ErrorMiddleware to know that it should use our custom error handler,
it has to be configured in the container with the setDefaultErrorHandler method.
The ErrorMiddleware is instantiated with the config values and logger.
File: config/container.php
use App\Application\Handler\DefaultErrorHandler;
use App\Application\Middleware\ErrorHandlerMiddleware;
use Psr\Container\ContainerInterface;
use Slim\Middleware\ErrorMiddleware;
use Psr\Log\LoggerInterface;
use Slim\App;
return [
// ...
// Set error handler to custom DefaultErrorHandler
ErrorMiddleware::class => function (ContainerInterface $container) {
$config = $container->get('settings')['error'];
$app = $container->get(App::class);
$logger = $container->get(LoggerInterface::class);
$errorMiddleware = new ErrorMiddleware(
$app->getCallableResolver(),
$app->getResponseFactory(),
(bool)$config['display_error_details'],
(bool)$config['log_errors'],
(bool)$config['log_error_details'],
$logger
);
// Set the custom error handler
$errorMiddleware->setDefaultErrorHandler(
$container->get(\App\Application\ErrorHandler\DefaultErrorHandler::class)
);
return $errorMiddleware;
},
];The ErrorMiddleware is added at the end of the middleware stack.
It is important that it is the last middleware because, as explained in the
Routing and Middleware
chapter, that last middleware of the stack will be the first to be executed.
File: config/middleware.php
use Slim\App;
use App\Application\Middleware\ErrorHandlerMiddleware;
use Slim\Middleware\ErrorMiddleware;
return function (App $app) {
// ...
$app->add(NonFatalErrorHandlerMiddleware::class);
$app->add(ErrorMiddleware::class);
};It is essential that ErrorMiddleware is executed first because the goal is to cover as many errors as possible
with the custom error handler.
The process function of ErrorMiddleware contains a try catch block and if this middleware
is the last in the stack, meaning the first called, it will catch every error that might happen later.
Everything that happens before the process function of ErrorMiddleware will not be caught
and handled by the error handler set with slim. This is also not the case if there is faulty code in the
error handler itself.
File: vendor/slim/slim/Slim/Middleware/ErrorMiddleware.php
public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
{
try {
return $handler->handle($request);
} catch (Throwable $exception) {
return $this->handleException($request, $exception);
}
}If, for instance, an error occurs during
bootstrapping,
it falls back to the default error handler from the webserver
or debugging tool; errors logged in the default error.log from the webserver and the messages
in the browser will either be the default PHP error message or rendered by the debugging tool.
The custom error handler is in charge of logging the errors and rendering the error pages.
It is instantiated and then added to the ErrorMiddleware in the container
configuration via the setDefaultErrorHandler method.
It's called when a Throwable is caught in the ErrorMiddleware.
The error handler instance is called like a function in ErrorMiddleware with the required arguments.
This means the __invoke magic method
has to be implemented.
The first thing the DefaultErrorHandler does is log the error except if the exception is an
instance of ErrorException because that would mean it's a warning / notice, and they
were already logged in the NonFatalErrorHandlerMiddleware.
Then, it checks if the script is called via the command line. If that is the case, the script was probably run by the testing framework which has its own error handler that is more suitable for the console as it supports syntax highlighting and a stack trace with hyperlinks. Therefore, the exception that's caught is thrown so that the PHPUnit error handler can handle it. The logger should be disabled in the testing configuration, so the error is not logged.
After that, the response is created and rendered.
There are two ways the error can be displayed. Either with the error details in dev mode or a generic error page that keeps things vague.
This is determined by the display_error_details config value passed as an argument
to the __invoke method from the ErrorMiddleware.
If $displayErrorDetails is true, the DefaultErrorHandler builds
the attribute array containing the error details and then renders the page.
If $displayErrorDetails is false, a generic error page is rendered with the status code
and the reason phrase (e.g. 500 Internal Error or 404 Not found ).
If the exception is an instance of HttpException, the message of the exception is showed to the user.
File: src/Application/ErrorHandler/DefaultErrorHandler.php
<?php
namespace App\Application\ErrorHandler;
use App\Domain\Validation\ValidationException;
use Fig\Http\Message\StatusCodeInterface;
use Psr\Http\Message\ResponseFactoryInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Log\LoggerInterface;
use Selective\BasePath\BasePathDetector;
use Slim\Exception\HttpException;
use Slim\Views\PhpRenderer;
use Throwable;
readonly class DefaultErrorHandler
{
private string $fileSystemPath;
public function __construct(
private PhpRenderer $phpRenderer,
private ResponseFactoryInterface $responseFactory,
private LoggerInterface $logger,
) {
// The filesystem path to the project root folder will be removed in the error details page
$this->fileSystemPath = 'C:\xampp\htdocs\\';
}
/**
* @throws Throwable
* @throws \ErrorException
*/
public function __invoke(
ServerRequestInterface $request,
Throwable $exception,
bool $displayErrorDetails,
bool $logErrors,
bool $logErrorDetails
): ResponseInterface {
// Log error
// If exception is an instance of ErrorException it means that the NonFatalErrorHandlerMiddleware
// threw the exception for a warning or notice.
// That middleware already logged the message, so it doesn't have to be done here.
// The reason it is logged there is that if displayErrorDetails is false, ErrorException is not
// thrown and the warnings and notices still have to be logged in prod.
if ($logErrors && !$exception instanceof \ErrorException) {
// Error with no stack trace https://stackoverflow.com/a/2520056/9013718
$this->logger->error(
sprintf(
'Error: [%s] %s File %s:%s , Method: %s, Path: %s',
$exception->getCode(),
$exception->getMessage(),
$exception->getFile(),
$exception->getLine(),
$request->getMethod(),
$request->getUri()->getPath()
)
);
}
// Error output if script is called via cli (e.g. testing)
if (PHP_SAPI === 'cli') {
// If the column is not found and the request is coming from the command line, it probably means
// that the database schema.sql was not updated after a change.
if ($exception instanceof \PDOException && str_contains($exception->getMessage(), 'Column not found')) {
echo "Column not existing. Try running `composer schema:generate` in the console and run tests again. \n";
}
// The exception is thrown to have the standard behaviour (important for testing)
throw $exception;
}
// Create response
$response = $this->responseFactory->createResponse();
// Detect status code
$statusCode = $this->getHttpStatusCode($exception);
$response = $response->withStatus($statusCode);
// Reason phrase is the text that describes the status code e.g. 404 => Not found
$reasonPhrase = $response->getReasonPhrase();
$phpRendererAttributes['statusCode'] = $statusCode;
$phpRendererAttributes['reasonPhrase'] = $reasonPhrase;
// If $displayErrorDetails is true, display exception details
if ($displayErrorDetails === true) {
// Add exception details to template attributes
$phpRendererAttributes = array_merge(
$phpRendererAttributes,
$this->getExceptionDetailsAttributes($exception)
);
// The error-details template does not include the default layout,
// so the base path to the project root folder is required to load assets
$phpRendererAttributes['basePath'] = (new BasePathDetector($request->getServerParams()))->getBasePath();
// Render template if the template path fails, the default webserver exception is shown
return $this->phpRenderer->render($response, 'error/error-details.html.php', $phpRendererAttributes);
}
// Display generic error page
// If it's a HttpException it's safe to show the error message to the user
$exceptionMessage = $exception instanceof HttpException ? $exception->getMessage() : null;
$phpRendererAttributes['exceptionMessage'] = $exceptionMessage;
// Render template
return $this->phpRenderer->render($response, 'error/error-page.html.php', $phpRendererAttributes);
}
/**
* Determine http status code.
*
* @param Throwable $exception The exception
* @return int The http code
*/
private function getHttpStatusCode(Throwable $exception): int
{
// Default status code
$statusCode = StatusCodeInterface::STATUS_INTERNAL_SERVER_ERROR; // 500
// HttpExceptions have a status code
if ($exception instanceof HttpException) {
$statusCode = (int)$exception->getCode();
}
if ($exception instanceof ValidationException) {
$statusCode = StatusCodeInterface::STATUS_UNPROCESSABLE_ENTITY; // 422
}
$file = basename($exception->getFile());
if ($file === 'CallableResolver.php') {
$statusCode = StatusCodeInterface::STATUS_NOT_FOUND; // 404
}
return $statusCode;
}
/**
* Build the attribute array for the detailed error page.
*
* @param Throwable $exception
* @return array
*/
private function getExceptionDetailsAttributes(Throwable $exception): array
{
$file = $exception->getFile();
$lineNumber = $exception->getLine();
$exceptionMessage = $exception->getMessage();
$trace = $exception->getTrace();
// If the exception is ErrorException, the css class is warning, otherwise it's error
$severityCssClassName = $exception instanceof \ErrorException ? 'warning' : 'error';
// Remove the filesystem path and make the path to the file that had the error smaller to increase readability
$lastBackslash = strrpos($file, '\\');
$mainErrorFile = substr($file, $lastBackslash + 1);
$firstChunkFullPath = substr($file, 0, $lastBackslash + 1);
// remove C:\xampp\htdocs\ and project name to keep only part starting with src\
$firstChunkMinusFilesystem = str_replace($this->fileSystemPath, '', $firstChunkFullPath);
// locate project name because it is right before the first backslash (after removing filesystem)
$projectName = substr($firstChunkMinusFilesystem, 0, strpos($firstChunkMinusFilesystem, '\\') + 1);
// remove project name from first chunk
$pathToMainErrorFile = str_replace($projectName, '', $firstChunkMinusFilesystem);
$traceEntries = [];
foreach ($trace as $key => $t) {
// Sometimes class, type, file and line not set e.g. pdfRenderer when var undefined in template
$t['class'] = $t['class'] ?? '';
$t['type'] = $t['type'] ?? '';
$t['file'] = $t['file'] ?? '';
$t['line'] = $t['line'] ?? '';
// remove everything from file path before the last \
$fileWithoutPath = $this->removeEverythingBeforeLastBackslash($t['file']);
// remove everything from class before last \
$classWithoutPath = $this->removeEverythingBeforeLastBackslash($t['class']);
// if the file path doesn't contain "vendor", a css class is added to highlight it
$nonVendorFileClass = !str_contains($t['file'], 'vendor') ? 'non-vendor' : '';
// if file and class path don't contain vendor, add "non-vendor" css class to add highlight on class
$classIsVendor = str_contains($t['class'], 'vendor');
$nonVendorFunctionCallClass = !empty($nonVendorFileClass) && !$classIsVendor ? 'non-vendor' : '';
// Get function arguments
$args = [];
foreach ($t['args'] ?? [] as $argKey => $argument) {
// Get argument as string not longer than 15 characters
$args[$argKey]['truncated'] = $this->getTraceArgumentAsTruncatedString($argument);
// Get full length of argument as string
$fullArgument = $this->getTraceArgumentAsString($argument);
// Replace double backslash with single backslash
$args[$argKey]['detailed'] = str_replace('\\\\', '\\', $fullArgument);
}
$traceEntries[$key]['args'] = $args;
// If the file is outside vendor class, add "non-vendor" css class to highlight it
$traceEntries[$key]['nonVendorClass'] = $nonVendorFileClass;
// Function call happens in a class outside the vendor folder
// File may be non-vendor, but function call of the same trace entry is in a vendor class
$traceEntries[$key]['nonVendorFunctionCallClass'] = $nonVendorFunctionCallClass;
$traceEntries[$key]['classAndFunction'] = $classWithoutPath . $t['type'] . $t['function'];
$traceEntries[$key]['fileName'] = $fileWithoutPath;
$traceEntries[$key]['line'] = $t['line'];
}
return [
'severityCssClassName' => $severityCssClassName,
'exceptionClassName' => get_class($exception),
'exceptionMessage' => $exceptionMessage,
'pathToMainErrorFile' => $pathToMainErrorFile,
'mainErrorFile' => $mainErrorFile,
'errorLineNumber' => $lineNumber,
'traceEntries' => $traceEntries,
];
}
/**
* The stack trace contains the functions that are called during script execution with
* function arguments that can be any type (objects, arrays, strings or null).
* This function returns the argument as a string.
*
* @param mixed $argument
* @return string
*/
private function getTraceArgumentAsString(mixed $argument): string
{
// If the variable is an object, return its class name.
if (is_object($argument)) {
return get_class($argument);
}
// If the variable is an array, iterate over its elements
if (is_array($argument)) {
$result = [];
foreach ($argument as $key => $value) {
// if it's an object, get its class name if it's an array represent it as 'Array'
// otherwise, keep the original value.
if (is_object($value)) {
$result[$key] = get_class($value);
} elseif (is_array($value)) {
$result[$key] = 'Array';
} else {
$result[$key] = $value;
}
}
// Return the array converted to a string using var_export
return var_export($result, true);
}
// If the variable is not an object or an array, convert it to a string using var_export.
return var_export($argument, true);
}
/**
* Convert the given argument to a string not longer than 15 chars
* except if it's a file or a class name.
*
* @param mixed $argument The variable to be converted to a string.
* @return string The string representation of the variable.
*/
private function getTraceArgumentAsTruncatedString(mixed $argument): string
{
if ($argument === null) {
$formatted = 'NULL';
} elseif (is_string($argument)) {
// If string contains backslashes keep part after the last backslash, otherwise keep the first 15 chars
if (str_contains($argument, '\\')) {
$argument = $this->removeEverythingBeforeLastBackslash($argument);
} elseif (strlen($argument) > 15) {
$argument = substr($argument, 0, 15) . '...';
}
$formatted = '"' . $argument . '"';
} elseif (is_object($argument)) {
$formatted = get_class($argument);
// Only keep the last part of class string
if (strlen($formatted) > 15 && str_contains($formatted, '\\')) {
$formatted = $this->removeEverythingBeforeLastBackslash($formatted);
}
} elseif (is_array($argument)) {
// Convert each array element to string recursively
$elements = array_map(function ($element) {
return $this->getTraceArgumentAsTruncatedString($element);
}, $argument);
return '[' . implode(', ', $elements) . ']';
} else {
$formatted = (string)$argument;
}
return $formatted;
}
/**
* If a string is 'App\Domain\Example\Class', this function returns 'Class'.
*
* @param string $string
* @return string
*/
private function removeEverythingBeforeLastBackslash(string $string): string
{
return trim(substr($string, strrpos($string, '\\') + 1));
}
}The template error/error-details.html.php is rendered for the error details page.
It shows the error message and stack trace in a responsive table.
The function html() is used to escape
the values.
File: templates/error/error-details.html.php
<?php
/**
* @var string $basePath
* @var string $severityCssClassName 'error' fatal errors or 'warning' for notices and warnings
* @var int|null $statusCode http status code e.g. 404
* @var string|null $reasonPhrase http reason phrase e.g. 'Not Found'
* @var string|null $exceptionClassName e.g. 'HttpNotFoundException'
* @var string|null $exceptionMessage e.g. 'Page not found.'
* @var string|null $pathToMainErrorFile e.g. 'src\Application\Action\'
* @var string|null $mainErrorFile e.g. 'UserAction.php'
* @var int|null $errorLineNumber e.g. 123
* @var array $traceEntries contains keys 'args' (function arguments),
* 'nonVendorClass' (empty or 'non-vendor' to indicate that string should be highlighted),
* 'nonVendorFunctionCallClass' (empty or 'non-vendor' to indicate that string should be highlighted),
* 'classAndFunction' (class and function that was called in stack trace entry),
* 'fileName' (name of the file in the stack trace entry), 'line' (line number)
*/
// Remove layout if there was a default
$this->setLayout('');
?>
<!DOCTYPE html>
<html lang="en">
<head>
<base href="<?= $basePath ?>/"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" href="assets/error/error-details.css">
<title>Error</title>
</head>
<body class="<?= html($severityCssClassName) ?>">
<div id="title-div" class="<?= html($severityCssClassName) ?>">
<p><span><?= html($statusCode) ?> | <?= html($reasonPhrase) ?></span>
<span id="exception-name"><?= html($exceptionClassName) ?></span>
</p>
<h1><?= html($exceptionMessage) ?> in <span id="first-path-chunk"><?= html($pathToMainErrorFile) ?></span>
<?= html($mainErrorFile) ?>
on line <?= html($errorLineNumber) ?>.
</h1>
</div>
<div id="trace-div" class="<?= html($severityCssClassName) ?>">
<table>
<tr class="non-vendor">
<th id="num-th">#</th>
<th>Function</th>
<th>Location</th>
</tr>
<?php
foreach ($traceEntries as $key => $entry) { ?>
<tr>
<td class="<?= html($entry['nonVendorClass']) ?>"><?= html($key) ?></td>
<td class="function-td <?= html($entry['nonVendorFunctionCallClass']) ?>">
<?= html($entry['classAndFunction']) ?>(
<?php
foreach ($entry['args'] as $argument) { ?>
<span class="args-span" data-full-details="<?= html($argument['detailed']) ?>">
<?= html($argument['truncated']) ?></span>,
<?php
} ?>
)
</td>
<td class="stack-trace-file-name <?= html($entry['nonVendorClass']) ?>">
<?= html($entry['fileName']) ?>:<span class="lineSpan"><?= html($entry['line']) ?></span>
</td>
</tr>
<?php
}
?>
</table>
</div>
<script src="assets/error/error-details.js"></script>
</body>
</html>File: public/assets/error/error-details.css
@font-face {
font-family: Poppins;
src: url(Poppins-Regular.ttf);
font-weight: normal;
}
/* mobile first min-width sets base and content is adapted to computers. */
@media (min-width: 100px) {
* {
overflow-wrap: anywhere;
}
body {
margin: 0;
background: #ffd9d0;
font-family: Poppins, Geneva, AppleGothic, sans-serif;
}
body.warning {
background: #ffead0;
}
body.error {
background: #ffd9d0;
}
#title-div {
padding: 5px 10%;
color: black;
background: tomato;
border-radius: 0 35px;
box-shadow: 0 0 17px tomato;
box-sizing: border-box;
margin: 30px 0;
font-size: 0.8em;
}
#title-div h1 {
margin-top: 4px;
}
#title-div.warning {
background: orange;
box-shadow: 0 0 17px orange;
}
#title-div.error {
background: tomato;
box-shadow: 0 0 17px tomato;
}
#first-path-chunk {
font-size: 0.7em;
}
#trace-div {
font-size: 0.8em;
margin: auto auto 40px;
min-width: 350px;
padding: 20px;
background: #ff9e88;
border-radius: 0 35px;
box-shadow: 0 0 10px #ff856e;
width: 90%;
}
#trace-div.warning {
background: #ffc588;
box-shadow: 0 0 10px #ffad6e;
}
#trace-div.error {
background: #ff9e88;
box-shadow: 0 0 10px #ff856e;
}
#trace-div h2 {
margin-top: 0;
padding-top: 19px;
text-align: center;
}
#trace-div table {
border-collapse: collapse;
width: 100%;
overflow-x: auto;
}
#trace-div table td, #trace-div table th { /*border-top: 6px solid red;*/
padding: 8px;
text-align: left;
}
#trace-div table tr td:nth-child(3) {
min-width: 100px;
}
#num-th {
font-size: 2em;
color: #a46856;
margin-right: 50px;
}
.non-vendor {
font-weight: bold;
font-size: 1.2em;
}
.non-vendor .lineSpan {
font-weight: bold;
color: #b00000;
font-size: 1.1em;
}
.is-vendor {
font-weight: normal;
}
.args-span {
color: #395186;
cursor: pointer;
}
#exception-name {
float: right
}
.function-td {
font-size: 0.9em;
}
}
@media (min-width: 641px) {
#trace-div {
width: 80%;
}
}
@media (min-width: 810px) {
#title-div {
margin: 30px;
}
#trace-div table tr td:first-child, #trace-div table tr th:first-child {
padding-left: 20px;
}
#title-div {
font-size: 1em;
}
}
@media (min-width: 1000px) {
#trace-div {
font-size: 1em;
}
}The following script makes that the stack trace file names are camel-wrapped and that the full details of the function arguments are displayed when clicking on them.
File: public/assets/error/error-details.js
window.onload = function () {
// Camel-wrap all stack trace file names
let elements = document.querySelectorAll('.stack-trace-file-name');
elements.forEach(function (element) {
camelWrap(element);
});
// Show full details when clicking on an argument
// Select all spans with the class 'args-span'
var spans = document.querySelectorAll('.args-span');
// Add a click event listener to each span
spans.forEach(function (span) {
let spanExpanded = false;
let formatted;
span.addEventListener('click', function () {
// Get the full details from the data attribute
let fullDetails = this.getAttribute('data-full-details');
// Display the full details and store the formatted text
if (!spanExpanded) {
formatted = this.innerText;
span.innerText = fullDetails;
} else {
span.innerText = formatted;
}
spanExpanded = !spanExpanded;
});
});
}
/**
* This function is used to apply the camelWrapUnicode function to a given DOM node
* and then replace all zero-width spaces in the node's innerHTML with <wbr> elements.
* The <wbr> element represents a word break opportunity—a position within text where
* the browser may optionally break a line, though its line-breaking rules would not
* otherwise create a break at that location.
*
* @param {Node} node - The DOM node to which the camelWrapUnicode function should
* be applied and in whose innerHTML the zero-width spaces should be replaced
* with <wbr> elements.
*/
function camelWrap(node) {
camelWrapUnicode(node);
node.innerHTML = node.innerHTML.replace(/\u200B/g, "<wbr>");
}
/**
* This function is used to insert a zero-width space before each uppercase letter in
* a camelCase string.
* It does this by recursively traversing the DOM tree starting from the given node.
* For each text node it finds, it replaces the node's value with a new string where
* a zero-width space has been inserted before each uppercase letter.
*
* Source: http://heap.ch/blog/2016/01/19/camelwrap/
* @param {Node} node - The node from where to start the DOM traversal.
*/
function camelWrapUnicode(node) {
// Start from the first child of the given node and continue to the next sibling until there are no more siblings.
for (node = node.firstChild; node; node = node.nextSibling) {
// If the current node is a text node, replace its value.
if (node.nodeType === Node.TEXT_NODE) {
// Replace the node's value with a new string where a zero-width space has been inserted before each uppercase letter.
// This is done by first matching any word character or colon that is repeated 18 or more times, and for each match,
// a new string is returned where a zero-width space has been inserted before each uppercase letter.
// The same is done by matching any dot character, but without the repetition requirement.
node.nodeValue = node.nodeValue.replace(/[\w:]{18,}/g, function (str) {
return str.replace(/([a-z])([A-Z])/g, "$1\u200B$2");
});
} else {
// If the current node is not a text node, continue the traversal from this node.
camelWrapUnicode(node);
}
}
}The error page for a production environment displays the status code, the reason phrase,
an error message depending on the status code and optionally a server message.
There is also a button to report the issue with a partially pre-written email or go back home.
The navigation bar stays accessible for the user to navigate.
The default layout.html.php which contains the main HTML structure is loaded meaning only the relevant
HTML to this page is required in this template.
File: templates/error/error-page.html.php
<?php
/**
* @var \Slim\Interfaces\RouteParserInterface $route
* @var array $errorMessage containing (int) statusCode; (string) reasonPhrase; (string) exceptionMessage
* @var string|null $statusCode e.g. 403
* @var string|null $reasonPhrase e.g. Forbidden
* @var string|null $exceptionMessage e.g. You are not allowed to access this page.
* @var \Slim\Views\PhpRenderer $this
* @var array $config public config values
*/
$this->setLayout('layout.html.php');
?>
<?php
// Define assets that should be included
$this->addAttribute('css', ['assets/error/prod-error-page.css']);
$this->addAttribute('js', ['assets/error/prod-error-page.js']);
?>
<section id="error-inner-section">
<h1 id="error-status-code"><?= html($statusCode) ?></h1>
<section id="error-description-section">
<?php
switch ($statusCode) {
case 404:
$title = 'Page not found';
$message = __("Looks like you've ventured into uncharted territory. Please report the issue!");
break;
case 403:
$title = 'Access forbidden';
$message = __(
'You are not allowed to access this page. Please report the issue if you think this is
an error.'
);
break;
case 400:
$title = 'The request is invalid';
$message = __('There is something wrong with the request syntax. Please report the issue.');
break;
case 422:
$title = 'Validation failed.';
$message = __(
'The server could not interpret the data it received. Please try again with valid data and
report the issue if it persists.'
);
break;
case 500:
$title = 'Internal Server Error.';
$message = __(
'It\'s not your fault! The server has an internal error. <br> Please try again and
report the issue if the problem persists.'
);
break;
default:
$title = 'An error occurred.';
$message = __(
'While it\'s unfortunate that an error exists, the silver lining is that it can be rectified!
<br>Please try again and then contact us.'
);
break;
}
$emailSubject = strip_tags(str_replace('"', '', $exceptionMessage))
?? $statusCode . ' ' . $title;
$emailBody = __('This is what I did before the error happened:');
?>
<h2 id="error-reason-phrase">OOPS! <?= html($title) ?></h2>
<p id="error-message"><?= $message /* Not escape with html() because $message is safe and has html tags */ ?></p>
<?= $exceptionMessage !== null ?
'<p id="server-message">Server message: ' . html($exceptionMessage) . '</p>' : '' ?>
</section>
<section id="error-btn-section">
<a href="<?= $route?->urlFor('home-page') ?>" class="btn"><?= __('Go back home') ?></a>
<a href="mailto:<?= ($config['email']['main_contact_address'] ?? 'contact@samuel-gfeller.ch')
. '?subject=' . html($emailSubject) . '&body=' . html($emailBody) ?>" target="_blank" class="btn">
<?= __('Report the issue') ?></a>
</section>
</section>@font-face {
font-family: Poppins;
src: url(Poppins-Bold.ttf);
font-weight: 700;
}
@font-face {
font-family: Poppins;
src: url(Poppins-Regular.ttf);
}
:root {
--error-body-gradient-color-1: #49d2ff;
--error-body-gradient-color-2: #ea9bc2;
--error-inner-section-background: rgba(255, 255, 255, 0.4);
--error-reason-phrase-color: #535353;
--error-status-code-gradient-color-1: #00c1ff;
--error-status-code-gradient-color-2: #ff6bb4;
}
[data-theme="dark"] {
--error-body-gradient-color-1: rgb(102, 93, 182);
--error-body-gradient-color-2: rgb(64, 148, 157);
--error-inner-section-background: rgba(0, 0, 0, 0.4);
--error-reason-phrase-color: #a9a9a9;
}
@media (min-width: 100px) {
body {
background: linear-gradient(to bottom right, var(--error-body-gradient-color-1) 0%, var(--error-body-gradient-color-2) 100%);
}
main {
display: flex;
align-items: center;
justify-content: center;
/*background: lightblue;*/
margin-left: 0;
margin-top: 0;
border-radius: 0 0 0 0;
background: transparent;
}
footer {
background: var(--error-inner-section-background);
margin-top: 0;
/*border-radius: 0;*/
}
#error-inner-section {
width: fit-content;
max-width: 92%;
height: fit-content;
padding: 40px 30px;
/*border: 1px solid #ccc;*/
/*margin-left: 50px;*/
text-align: center;
border-radius: 30px;
background: var(--error-inner-section-background);
/*backdrop-filter: blur(50px);*/
box-shadow: 0 5px 10px rgba(0, 0, 0, 0.1);
}
/* #error-status-code */
#error-inner-section h1 {
font-size: clamp(100px, 18vw, 200px);
font-family: Poppins, Helvetica, sans-serif;
line-height: 1em;
margin-bottom: 0;
margin-top: 0px;
position: relative;
background: linear-gradient(to bottom right, var(--error-status-code-gradient-color-1) 0%,
var(--error-status-code-gradient-color-2) 100%);
-webkit-background-clip: text;
-webkit-text-fill-color: transparent;
}
#error-inner-section h2 {
text-transform: uppercase;
font-family: Poppins, Helvetica, sans-serif;
color: var(--error-reason-phrase-color);
/*font-family: SF-Pro Display, Helvetica, sans-serif;*/
}
#error-inner-section p {
font-family: Poppins, Helvetica, sans-serif;
font-weight: 400;
font-size: 1.2em;
}
p#server-message {
font-size: 1em;
}
#error-btn-section {
margin-top: 30px;
display: flex;
flex-wrap: wrap;
justify-content: space-evenly;
}
#error-btn-section .btn {
background: rgba(255, 255, 255, 0.4);
margin: 10px;
}
}
@media (min-width: 641px) {
#error-inner-section {
padding: 40px 50px;
max-width: 80%;
}
}
@media (min-width: 961px) {
#error-inner-section {
padding: 40px 100px;
}
}In an effort to make the error page a little less boring, the linear gradient direction of the status code follows the cursor.
File: public/assets/error/prod-error-page.js
const statusCode = document.getElementById('error-status-code');
// Make the linear gradient direction of the status code follow the cursor
document.documentElement.addEventListener("mousemove", function (event) {
// Retrieve the bounding rectangle of the "statusCode" element
const {left, top, width, height} = statusCode.getBoundingClientRect();
// Calculate the center coordinates of the "statusCode" element
const centerX = left + width / 2;
const centerY = top + height / 2;
// Calculate the angle (in radians) between the cursor position and the center of the element
const radians = Math.atan2(event.clientY - centerY, event.clientX - centerX);
// Convert the angle from radians to degrees
const degrees = radians * (180 / Math.PI);
// Add 90 degrees to shift the range from [-180, 180] to [0, 360] degrees
const gradientDirection = degrees + 90;
// Apply the linear gradient background to the "statusCode" element
const style = getComputedStyle(document.body);
const color1 = style.getPropertyValue('--error-status-code-gradient-color-1');
const color2 = style.getPropertyValue('--error-status-code-gradient-color-2');
setTimeout(() => {
statusCode.style.backgroundImage = `linear-gradient(${gradientDirection}deg, ${color1} 0%, ${color2} 100%)`;
}, 300
)
});