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

Application Runtime Bootstrap

The Application Runtime Bootstrap is the final stage of the APPNETOS system bootstrap sequence. It provides an optional entry point for applications that require their own startup and request-processing logic.

Purpose and execution

The SystemBootstrap invokes the Core Bootstrap first and the Application Runtime Bootstrap afterward. This is a sequential call, not a conditional check for an application-specific configuration. However, standard Core processing may already have sent a response and terminated execution before the Application Runtime is reached.

In the standard URI pipeline, a mapped URI Collection enables document-based routing and response handling. If no URI Collection is mapped, Core\Uri skips document-based resolution without rendering a response. Provided no other Core component terminates execution, control continues to the Application Runtime Bootstrap.

A mapped URI Collection with no matching document is a different case: the standard URI controller invokes its not-found fallback rather than handing the unresolved request to the Application Runtime.

Configuration file resolution

The Application Runtime Bootstrap reads an optional application-specific PHP configuration:

platform/bootstrap/<application>.php
platform/bootstrap/<application>.<environment>.php

If an environment-specific file exists, it replaces the default configuration in full; the two arrays are not merged. If neither file exists, no application bootstrap classes are executed. This configuration is optional.

Configuration example

<?php

return [
    'application' => 'example-application',
    'contexts' => [
        'shared' => [
            \ExampleApplication\Shared\Bootstrap::class,
        ],
        'app' => [
            \ExampleApplication\App\Bootstrap::class,
        ],
        'admin' => [
            \ExampleApplication\Admin\Bootstrap::class,
        ],
        'worker' => [
            \ExampleApplication\Worker\Bootstrap::class,
        ],
    ],
];

The application value must match the active application. Bootstrap class names must be autoloadable. Each configured class is instantiated through Registry::getNew() and its public, non-static boot() method is invoked. The method must not require arguments.

Context selection and execution order

Classes in contexts.shared execute first. Classes for the exact runtime context execute afterward. For HTTP requests only, when the exact runtime context is not defined, the base context may be used as a fallback. Process contexts do not use this base-context fallback. An explicitly configured empty runtime-context array prevents fallback to the base context.

Within the selected groups, classes execute in their configured order. Duplicate class entries across the active groups are rejected rather than executed twice. Invalid configuration structures and invalid bootstrap class contracts raise errors.

Example bootstrap class

<?php

declare(strict_types=1);

namespace ExampleApplication\App;

class Bootstrap
{
    public function boot(): void
    {
        // Initialize application-specific services.
        // Execute custom routing or request handling.
        // Produce a response when appropriate.
    }
}

Unlike the Core Bootstrap definition, the Application Runtime configuration does not provide separate classes, init, and run phases. Developers organize their own initialization steps within the configured boot() methods.

Advanced customization options

Developers are not limited to disabling document-based URI routing. Class Mapping can select an alternative Core Bootstrap implementation with a different set or order of Core components. Where supported, the APPNETOS Class Extension system can modify a Core Bootstrap implementation through its recursive inheritance chain. These mechanisms operate at different levels from the optional Application Runtime configuration; the protected System Bootstrap itself is not a general-purpose extension target.

Core components initialized before the Application Runtime remain available and can be reused by custom application logic.

Recommendation: Prefer the Standard Core Runtime

APPNETOS provides a fully prepared Core runtime that already covers the requirements of most applications, including URI resolution, routing, rendering, response handling, and other essential infrastructure.

For standard application development, using the existing Core Bootstrap is strongly recommended.

Developers should build on the available Core components and use Class Mapping or Class Extension for targeted customization when necessary. There is generally no need to implement a separate application runtime or replace the standard initialization process.

The Application Runtime Bootstrap is primarily intended for advanced use cases where developers deliberately require fundamentally different application behavior, such as custom routing systems, independent request processing, or entirely customized runtime initialization.

Replacing or bypassing the standard Core runtime should be considered an exceptional architectural decision, not a regular development pattern.

Before implementing a custom runtime, developers should evaluate whether the required functionality can already be achieved using the existing APPNETOS Core components and customization mechanisms.

Next Steps

Previous

Core

Explore Core

Next

Process Bootstrap

Explore Process Bootstrap