Application Bootstrap
The fourth bootstrap step loads installed application configurations, validates their contexts and routes, and resolves the application and context for the current HTTP request or process execution.
Purpose and Execution
Bootstrap\Application\ApplicationBootstrap executes after
Runtime
Bootstrap
and before CORS Bootstrap. It operates on the existing RuntimeState instance.
public function boot(): void
{
$applications = $this->validateApplications($this->loadApplications());
$this->runtimeState->setApplications($applications);
$this->runtimeState->setApplicationSlugs(
$this->collectApplicationSlugs($applications),
);
if ($this->isCoreCommandRuntime()) {
$this->applyCoreProcessContext();
return;
}
if ($this->runtimeState->getProcess()) {
$this->resolveProcessApplication($applications);
return;
}
$this->resolveRuntimeApplication($applications);
}
Application discovery and validation happen before the runtime branches into core commands, application processes, or HTTP routing. This step does not load application PHP classes or copy installation templates.
Complete Application Configuration
Installed application configurations reside in platform/application/. The following example
is based on the appnetos-docs application:
<?php
declare(strict_types=1);
return [
'application' => 'appnetos-docs',
'active' => true,
'contexts' => [
'app',
],
'default_context' => 'app',
'base_contexts' => [
'app' => 'app',
],
'routes' => [
'app' => [
'slug' => 'docs',
'hosts' => [],
],
],
];
| Key | Type | Required | Purpose |
|---|---|---|---|
application |
string |
Yes | Application identifier; matches the configuration filename. |
active |
bool |
No | Enables runtime resolution; defaults to true. |
contexts |
array |
Yes | Declares available application contexts. |
default_context |
string |
Yes | Declares a default context that belongs to contexts. |
base_contexts |
array |
Yes | Maps each context to the APPNETOS app or admin base. |
routes |
array |
Yes | HTTP routes for all non-process contexts. |
routes.<context>.slug |
string |
Conditional | First URI segment; an empty string defines a root route. |
routes.<context>.hosts |
array |
No | Optional explicit host scope; normalized during validation. |
A route requires a string slug or a
non-empty hosts
array. A host-only route may omit slug.
Application Identity and Activation
application
'application' => 'appnetos-docs',
The identifier must exactly match the configuration basename, excluding an optional environment suffix.
For example, appnetos-docs.php and appnetos-docs.docker.php both describe
appnetos-docs when APPNETOS_ENVIRONMENT is docker.
active
'active' => false, // Do not resolve this application at runtime.
This key is optional and defaults to true. Inactive applications are still
loaded and structurally validated, but their routes are excluded from HTTP matching and an attempt
to execute one as a process application is rejected.
Runtime Contexts
contexts
'contexts' => [
'app',
'admin',
'rest',
'admin-rest',
'cmd',
'worker',
],
The array must be non-empty and contain unique, supported context names. The bootstrap currently accepts
app, admin, rest, admin-rest,
api, admin-api, cmd, and worker.
The api and admin-api contexts are reserved for planned functionality;
listing them here does not imply their complete runtime implementations are available.
default_context
'default_context' => 'app',
This value is mandatory and must name a context declared in contexts. It is part of the
validated application definition; HTTP route selection still follows the explicit host and slug rules,
rather than automatically selecting this value for every unmatched request.
base_contexts
'base_contexts' => [
'app' => 'app',
'admin' => 'admin',
'rest' => 'app',
'admin-rest' => 'admin',
'cmd' => 'admin',
'worker' => 'admin',
],
Every declared context requires exactly one mapping to an APPNETOS base context: app or
admin. Unknown context keys in the mapping are invalid. Both process contexts,
cmd and worker, must map to admin.
These mappings determine which base-context resources subsequent bootstrap layers use.
cmd and worker must not have entries in routes.
Every other declared context must have an HTTP route.
HTTP Route Configuration
Routes are keyed by their declared runtime context. Each HTTP route specifies a slug, a host scope, or both. The examples below illustrate different configurations; they are not intended to be combined verbatim.
Slug-based routing
'routes' => [
'app' => [
'slug' => 'docs',
'hosts' => [],
],
],
The first request path segment docs selects this context on an unreserved host.
An empty hosts array does not override routes that explicitly reserve the
current host.
Host-based root routing
'routes' => [
'app' => [
'slug' => '',
'hosts' => [
'docs.appnetos.com',
],
],
],
An empty slug defines the root route for its host scope, including application-internal paths.
A host-only route may omit slug; the bootstrap treats it as empty during resolution.
Multiple contexts on one host
'contexts' => ['app', 'admin', 'admin-rest'],
'default_context' => 'app',
'base_contexts' => [
'app' => 'app',
'admin' => 'admin',
'admin-rest' => 'admin',
],
'routes' => [
'app' => [
'slug' => '',
'hosts' => ['example.com'],
],
'admin' => [
'slug' => 'admin',
'hosts' => ['example.com'],
],
'admin-rest' => [
'slug' => 'rest',
'hosts' => ['example.com'],
],
],
Within the same eligible host scope, matching non-empty slugs take priority over an empty root slug.
Thus /admin and /rest select their respective contexts, while other paths
can be handled by the root application route.
hosts normalization and ports
'hosts' => [
'docs.appnetos.com',
'localhost:20000',
],
Host names are normalized to lowercase and duplicates are rejected. Bare hosts match any port;
a configured host:port requires the corresponding port. The validator also accepts
http:// or https:// URLs, converting them into normalized host and port
values.
For reverse-proxy deployments, bare host names are generally preferable when the external protocol
is managed by the proxy. Paths, query strings, fragments, and user credentials are not valid route
hosts.
HTTP Resolution Order and Conflicts
| Priority | Behavior |
|---|---|
| 1. Active applications | Only active application routes are eligible for matching. |
| 2. Explicit host scope | Routes registered for the current host are considered first. Their presence reserves that host. |
| 3. Non-empty slug | A matching first URI segment wins within the eligible scope. |
| 4. Empty slug | The root route handles the request when no non-empty slug matches in that scope. |
| 5. Unreserved hosts | Only when the current host has no explicit host routes may routes with hosts:
[] be considered.
|
| 6. Core fallback | When no application route matches, APPNETOS uses the Core app context; later
handling may produce a 404.
|
Two active routes cannot register the same slug in overlapping explicit host scopes, or both register the same slug without hosts. The same slug is permitted on disjoint host scopes. An explicitly reserved host excludes hostless routes even when none of its configured slugs matches the request.
After modifying hosts or context slugs, regenerate OpenAPI files for the affected REST contexts. Generated API server URLs do not update automatically. Cross-origin browser testing also requires the target REST context to permit the calling origin through its CORS configuration; CORS does not replace authentication.
Environment-Specific Application Configuration
The bootstrap discovers PHP configuration files exclusively in APPNETOS_PLATFORM/application
and selects the file matching APPNETOS_ENVIRONMENT when available.
platform/application/
├── appnetos-docs.php
├── appnetos-docs.docker.php
├── appnetos-dns-control.php
└── appnetos-dns-control.production.php
// Environment Bootstrap has already defined:
APPNETOS_ENVIRONMENT === 'docker';
// Application Bootstrap selects:
// platform/application/appnetos-docs.docker.php
// instead of platform/application/appnetos-docs.php
| Files available | Environment | Selected file |
|---|---|---|
| Default + matching environment file | docker |
appnetos-docs.docker.php |
| Default only | docker |
appnetos-docs.php |
| Matching environment file only | docker |
appnetos-docs.docker.php |
| Default + non-matching environment file | docker |
appnetos-dns-control.php |
The environment-specific PHP file supplies the entire application configuration. It must contain all required keys, contexts, base-context mappings, and routes. No values are inherited from the default file.
Process and Core Command Resolution
For application commands and workers, RuntimeBootstrap has already populated the requested application
and process context. ApplicationBootstrap verifies that the application exists, is active, declares
the requested cmd or worker context, and maps that context to the
admin base context.
'contexts' => ['app', 'cmd', 'worker'],
'default_context' => 'app',
'base_contexts' => [
'app' => 'app',
'cmd' => 'admin',
'worker' => 'admin',
],
'routes' => [
'app' => [
'slug' => 'example',
'hosts' => [],
],
// No HTTP routes for cmd or worker.
],
APPNETOS Core commands have a separate process branch. They execute without a selected
application and use the Core admin base context. Application-specific commands must
resolve an installed, active application.
RuntimeState Integration and Validation
The bootstrap stores the validated application registry and reserved non-empty route slugs in
RuntimeState. Successful resolution then sets the active application, context,
base context, and HTTP context slug as appropriate. Subsequent bootstrap steps use this state;
the application configuration is not rediscovered by each later component.
Invalid configuration structures stop startup with an exception. Examples include an identifier that
differs from its filename, unsupported or duplicate contexts, missing mappings, process contexts
mapped to app, missing HTTP routes, invalid hosts, and conflicting active route slugs.
Application Customization and Update Safety
Do not place custom configuration files or custom modifications inside the original
application
directory. In particular, never edit the application-supplied configuration templates in
<application>/.files/. These files belong to the distributable application and
may be overwritten or replaced during an update, causing changes to be lost.
Maintain application customizations in the designated ./custom/ directory using
the APPNETOS customization mechanism. Installation-time customization and CMD workflows are
documented separately under Application Customization and Custom Installation.
This distinction does not change the bootstrap lookup location:
ApplicationBootstrap reads the installed runtime configuration from
platform/application/; it does not load installation templates from ./custom/
or <application>/.files/ during this step.