Error Handling
Windwalker converts PHP errors and uncaught exceptions into a single handling pipeline. The ErrorService registers the PHP handlers, turns errors into ErrorException objects, and passes them to one or more ErrorHandler classes. Those handlers log the error, render an error page, or both.
Configuration
The error settings live in etc/conf/error.config.php. The most important keys are:
// etc/conf/error.config.php
return [
'ini' => [
'display_errors' => 'on',
'error_reporting' => $errorReporting,
],
'report_level' => env('ERROR_REPORT_LEVEL') ?? $errorReporting,
'restore' => false,
'register_shutdown' => true,
'log' => true,
'log_channel' => 'error',
'template' => 'layout.error.default',
'handlers' => [
// Handler definitions, see below
],
];iniwrites PHP INI values during boot.report_levelis the error mask thatErrorServiceconverts.logandlog_channelcontrol whether errors are written to logs.templateis the view used by the default error page.
TIP
Set ERROR_REPORT_LEVEL in .env to change the reporting level without editing the config file.
Default Error Logs
Errors are logged by default, even when debug mode is off, so you can investigate them later. Each kind of error goes to its own log channel.
- Web errors go to the
system/errorchannel. - Console errors go to the
system/console-errorchannel. - Deprecation notices go to the
system/deprecationschannel.
These channels are set in the factories section of etc/conf/error.config.php. Logging is controlled by error.log, which is enabled by default, so errors are recorded in production as well as in debug mode.
INFO
Deprecation logging uses the same error.log switch, and it has its own channel. Keep the channels configured and rotated in production.
Default Reporting Levels
Without changes, ErrorService::getReportLevel() returns E_ALL minus the low-severity levels: E_WARNING, E_NOTICE, E_DEPRECATED, and the E_USER_* equivalents.
etc/conf/error-reporting.config.php gives each level a boolean. Most of these default to env('APP_DEBUG'), so they are enabled only in debug mode. Override a single level with its ERROR_REPORT_* environment variable.
// .env
ERROR_REPORT_NOTICE=1ini.error_reporting and report_level
These two keys are different:
ini.error_reportingsets PHP's ownerror_reporting()level. PHP uses it to decide whether an error is raised at all.report_levelsets which levelsErrorServiceregisters and converts into exceptions.
If PHP suppresses an error at the INI level, the handler never sees it.
Dev and Debug Mode
The WINDWALKER_DEBUG constant switches ini.error_reporting to E_ALL, so every level reaches the handler. APP_DEBUG turns on the Whoops page, described in the Whoops section below.
WARNING
Do not enable APP_DEBUG or WINDWALKER_DEBUG on a public production server. Stack traces and environment details may be shown to visitors.
Changing Error Reporting in Code
Call PHP's error_reporting() or ini_set() at runtime to change the level for a block of code.
$old = error_reporting(E_ALL & ~E_DEPRECATED);
// Code that triggers known deprecations
legacyCall();
error_reporting($old);How Error Handling Works
ErrorService and ErrorHandler
ErrorService is the entry point. It is registered by ErrorHandlingProvider during boot. Each ErrorHandler receives an ErrorException or an uncaught Throwable, and decides how to handle it.
Registering the Error Handler
ErrorService::register() calls set_error_handler() and set_exception_handler(). When PHP raises an error that matches the reporting level, error() throws an ErrorException with code 500.
// ERROR: ErrorException: Undefined variable $name
echo $name;Deprecation notices are routed to handleDeprecation(), so they can be logged without stopping the request.
INFO
Handler registration happens only for web requests. The console registers ConsoleErrorEvent instead, with register(false, E_ALL, true).
Registering the Exception Handler
When an exception reaches the top level, exception() runs every configured handler, then calls exit(). The error status code is normalized: only 2xx and 3xx values are kept, and anything else becomes 500.
Adding More Handlers
Handlers are wired in three places in etc/conf/error.config.php:
handlers.<AppType>lists the handlers for each app type.factories.handlersdefines how each handler is built.deprecation_handlerslists handlers for deprecation notices.
// etc/conf/error.config.php
'handlers' => [
AppType::WEB->name => [
'default' => ref('error.factories.handlers.default'),
'log' => ref('error.factories.handlers.log'),
],
],
'factories' => [
'handlers' => [
'default' => static fn () => create(
SimpleErrorPageHandler::class,
),
],
],To add your own handler, define a factory and reference it.
ErrorHandlers
Each handler is an invokable class that implements ErrorHandlerInterface. Its __invoke(Throwable $e) method receives the exception. The built-in handlers include:
SimpleErrorPageHandler: renders the error page. Itsdebugflag comes fromsystem.debug.ErrorLogHandler: writes the error to a log channel.ErrorInlineHandler: shows the error inline in the page.
Writing Your Own Handler
Implement ErrorHandlerInterface and register the instance in handlers. The example below sends the error to an external service.
// App\Error\ReportErrorHandler.php
use Throwable;
use Windwalker\Core\Error\ErrorHandlerInterface;
class ReportErrorHandler implements ErrorHandlerInterface
{
public function __invoke(Throwable $e): void
{
// Send $e to an external tracking service.
}
}TIP
Keep handlers small and fast. A slow handler delays the response to every failing request.
Error Rendering
The default template (layout.error.default) renders the error page. Keep custom error views simple, so that a failure in the view does not cause a second error.
TIP
Pass plain values, such as a message and a status code, into the error view instead of relying on request or routing state.
Whoops in Debug Mode
WhoopsProvider registers the Whoops handler only when app.debug is true. It replaces the default handler, so you see a detailed error page with a stack trace and code frame.
Whoops configuration is in etc/conf/whoops.config.php.
Hiding Sensitive Values
The hidden_list key hides values from the environment and server arrays. Add keys that contain secrets to this list.
// etc/conf/whoops.config.php
'hidden_list' => [
'_ENV' => array_keys($_ENV ?? []),
'_SERVER' => array_merge(
['PATH', 'DOCUMENT_ROOT'],
array_keys($_ENV ?? []),
),
],WARNING
Whoops shows request data and server variables. Keep app.debug off in production, and hide any key that could contain a credential.
IDE Integration
Set editor to the IDE that should open file links. The default is phpstorm. Set WHOOPS_EDITOR in .env to change it.
// .env
WHOOPS_EDITOR=vscodeClicking a file link in the Whoops page then opens the failing line in that editor.