APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

Error Handling Bootstrap

The second system bootstrap step establishes independent, early error handling before the APPNETOS Core exception handler and application runtime are available.

Purpose and Execution

Bootstrap\ErrorHandling\ErrorHandlingBootstrap runs immediately after Environment Bootstrap. It relies on APPNETOS_VAR and APPNETOS_DEBUG, which are established in the preceding step. Its responsibility is to capture and report failures while the rest of the runtime is still being initialized.

public function boot(): void
{
    $this->logFile = APPNETOS_VAR . '/log/error.log';

    $this->initPhpSettings();
    $this->initLogDirectory();
    $this->registerHandlers();
}

This early layer intentionally does not depend on the Registry, Core exception handling, DebugBar, rendering, templates, or application services. It is part of the protected bootstrap chain and cannot be extended through the APPNETOS class extension system.

PHP Error Configuration

The early error handler has no dedicated configuration file. Its output behavior is controlled by APPNETOS_DEBUG, defined by the protected environment configuration. PHP error reporting and logging remain enabled in both modes.

PHP setting Debug enabled Debug disabled
error_reporting() E_ALL E_ALL
log_errors 1 1
display_errors 1 0
display_startup_errors 1 0
protected function initPhpSettings(): void
{
    error_reporting(E_ALL);

    ini_set('log_errors', '1');
    ini_set('display_errors', APPNETOS_DEBUG ? '1' : '0');
    ini_set('display_startup_errors', APPNETOS_DEBUG ? '1' : '0');
}

Applications cannot enable this global debug setting through their ordinary platform configuration. Change it in the trusted environment configuration before starting the runtime.

Early Error Handlers

Three PHP callbacks are registered during this step:

protected function registerHandlers(): void
{
    set_error_handler([$this, 'handleError']);
    set_exception_handler([$this, 'handleException']);
    register_shutdown_function([$this, 'handleShutdown']);
}
Handler Behavior
handleError() Logs PHP errors covered by the active error_reporting() mask. Returns false for masked errors and true for handled errors. In debug mode, it also renders diagnostics.
handleException() Logs an uncaught Throwable including its stack trace and produces a terminal debug or production response.
handleShutdown() Inspects error_get_last() for E_ERROR, E_PARSE, E_CORE_ERROR, or E_COMPILE_ERROR. It is skipped after a terminal early response or successful handover to Core.

The shutdown callback also tracks whether a terminal response has already been sent, preventing duplicate early fatal-error output for the same termination.

Early Error Logging

Early errors are appended to the installation's error log:

APPNETOS_VAR/log/error.log

If the log directory does not exist, the bootstrap attempts to create it recursively with permissions 0775. Log entries include a timestamp, error category, message, source file and line number. Uncaught exceptions also include their stack trace.

Log file creation and writing require appropriate filesystem permissions. This early layer writes directly to the filesystem; it does not use the later Core logging services.

Debug and Production Output

Situation Debug enabled Debug disabled
Handled PHP error Log entry and diagnostic output Log entry, without early-handler diagnostic output
Uncaught exception or fatal shutdown error Log entry and detailed output, including a stack trace for exceptions Log entry and generic message: An internal error occurred

For HTTP requests, terminal responses use status 500. Debug output is HTML-escaped inside a <pre> element. CLI execution uses plain-text output without HTTP status handling. A handled, nonfatal PHP error does not automatically terminate execution; in debug mode, its diagnostic output sets HTTP status 500 through the debug renderer.

Handover to Core Error Handling

The early handler remains available while subsequent bootstrap steps execute. Later, CoreBootstrap initializes the central Core exception handler and calls ErrorHandlingBootstrap::handoverToCore() after successful initialization.

protected function initExceptionHandler(): void
{
    try {
        Registry::get(Handler::class)->init();

        \Bootstrap\ErrorHandling\ErrorHandlingBootstrap::handoverToCore();
    } catch (Throwable $throwable) {
        error_log($throwable->getMessage());
    }
}

PHP does not allow a registered shutdown callback to be unregistered. Instead, the handover sets an internal flag so that the early shutdown callback returns without processing errors. If Core handler initialization fails before handover, this flag is not set and the early shutdown handler remains available.

Scope of the handover: handoverToCore() does not itself unregister the previously registered PHP error handler or exception handler. It specifically disables early shutdown processing; any other handler replacement depends on the Core handler initialization.

Limitations and Security

  • Failures before the early handlers have been registered cannot be captured by those handlers.
  • Errors outside the active error_reporting() mask are passed back to normal PHP handling.
  • The early handler is intentionally independent of Core services and application extensions.
  • Detailed output is intended for trusted development environments only.

Next Steps

Previous

Environment

Explore Environment

Next

Runtime

Explore Runtime