PHP Luminova: Framework Boot and Module Autoloading
Learn how Luminova initializes the framework, loads core modules, resolves files, caches boot configuration, and manages PHPVCI autoloading.
The autoloader class Luminova\Boot initializes the framework, loads the modules required by the application, and prepares the runtime for HTTP requests or CLI commands. It loads Composer's autoloader, registers environment settings, and can enable optional application features.
Including
system/Boot.phpautomatically starts the warmup phase. Call the appropriate public method to complete bootstrapping for your application context.
PHPVCI Autoloading
Luminova *PHPVCI allows applications to use a shared framework installation. When PHPVCI is enabled, Boot resolves system and bootstrap modules from the configured target directory instead of the local application directories.
Example:
Boot reads .phpvci.php from application root:
<?php
return [
'enabled' => true,
'version' => '^1.0.0',
'paths' => [
'target' => '/var/www/phpvci.packages',
],
];See Luminova PHPVCI Autoloading or https://github.com/phpvci/phpvci for more details.
Quick Start
Composer Autoloading
Luminova requires Composer for autoloading through system/plugins/autoload.php. The Composer autoload file is required even when PHPVCI is enabled.
If the file is missing, Boot stops and reports an autoload error. In development, the error includes the checked file path. In production, the path is omitted.
Initialize in HTTP
Luminova uses Boot::http() in an HTTP entry point (public/index.php) to initialize the framework and retrieve the application instance.
// /public/index.php
use Luminova\Boot;
require_once '/path/to/system/Boot.php';
Boot::http()->router->context(...)->run();Boot::http() calls Boot::init(), checks the environment mode, and returns the application instance resolved from App\Kernel.
Initialize in CLI
Luminova uses Boot::cli() in novakit command-line entry point.
#!/usr/bin/env php
<?php
use Luminova\Boot;
require '/path/to/system/Boot.php';
Boot::cli();
// novakit command.Initialize without retrieving the application
Boot::init() performs the HTTP boot process and registers the framework error handlers, but does not return the application instance or check the environment mode.
use Luminova\Boot;
require_once '/path/to/system/Boot.php';
Boot::init();Load framework modules only
Boot::autoload() runs warmup and finish without registering error handlers or configuring CLI-specific settings.
use Luminova\Boot;
require_once '/path/to/system/Boot.php';
Boot::autoload();Boot Lifecycle
Boot has two main phases: warmup and finish. The public methods add context-specific behavior around these phases.
| Method | Behavior |
|---|---|
Boot::http() | Runs init(), checks the environment mode, and returns the application instance. |
Boot::init() | Runs warmup, registers error handlers, and runs finish. |
Boot::cli() | Checks the PHP SAPI, runs warmup, applies CLI settings, defines standard streams, and runs finish. |
Boot::autoload() | Runs warmup and finish without registering error handlers or applying CLI settings. |
Warmup
Warmup runs automatically when system/Boot.php is included. The BOOT_WARMUP_STARTED constant prevents the full sequence from running more than once in the same PHP process.
On the first run, Boot:
- Defines
APP_BASE_PATHif it is not already defined. It uses theAPP_BASE_PATHprocess environment variable, then$_ENV['APP_BASE_PATH'], and otherwise the parent directory ofsystem/. Trailing slash and backslash characters are removed. - Reads the
.phpvci.phpconfiguration. - Loads the local Composer autoloader from
system/plugins/autoload.php. - Loads
bootstrap/polyfills.php, followed bysystem/Luminova.php,system/Runtime.php, andsystem/Config/Env.php. PHPVCI may change the source directory forsystemandbootstrapmodules if configured and enabled. - Registers environment values through
Env::register(). - Loads
bootstrap/constants.phpand applies the HTTP method override when supported. - Loads
bootstrap/Funcs/functions.php,bootstrap/Funcs/strings.php, andbootstrap/Funcs/arrays.php. - Applies PHP runtime settings from the environment configuration.
- Defines
BOOT_WARMUP_STARTEDand starts performance profiling. Profiling records data only when its environment settings allow it.
On subsequent calls, warmup reapplies the HTTP method override and returns without loading the modules again.
Context-specific initialization
init(),http(),cli()registers framework error handlers withError::register()after warmup.cli()accepts thecliandphpdbgSAPIs. It enables CLI error reporting, definesCLI_ENVIRONMENTif needed, and initializesSTDIN,STDOUT, andSTDERRthroughRuntime::defineStandardStreams().http()callsinit(). If the environment is neither production nor staging and the request is not from localhost, it exits with an environment mode error. Otherwise, it returns the application instance fromApp\Kernel.autoload()adds no context-specific initialization between warmup and finish.
Finish
Finish runs whenever http(), init(), cli(), or autoload() is called. It:
- Checks PHPVCI version compatibility when PHPVCI autoloading is active.
- Registers optional application features on the first finish only.
- Defines
APP_BOOTED. - Enters maintenance mode and exits if
MAINTENANCEis enabled. - Otherwise, for non-command requests, checks whether it can serve a static cached page. If a cached page is served, the script exits with
STATUS_SUCCESS.
Optional feature registration is skipped after APP_BOOTED is defined. The PHPVCI version check and maintenance or static-cache checks are still reached on each finish call.
Constants
These constants are defined during boot.
| Constant | When it is defined |
|---|---|
APP_BASE_PATH | During warmup, if not already defined. |
BOOT_WARMUP_STARTED | At the end of the first warmup. |
APP_BOOTED | During finish, after optional feature registration. |
CLI_ENVIRONMENT | During Boot::cli(), if not already defined. |
USER_DEFINED_GLOBAL_HELPER | After developer helper functions are loaded. |
USER_MODULE_AUTOLOAD | After at least one class alias is registered. |
Boot also reads constants such as PRODUCTION, STAGING, MAINTENANCE, STATUS_SUCCESS, and STATUS_ERROR; it does not define those constants itself.
Public Methods
http
Initializes the framework for HTTP requests and returns the application instance.
public static function http(): ApplicationReturns:
Luminova\Foundation\Core\Application, the application instance resolved from App\Kernel.
If the environment is neither production nor staging and the request is not from localhost, the method exits with an environment mode error.
cli
Initializes the framework for CLI commands.
public static function cli(): voidThe method sets display_errors, display_startup_errors, and log_errors to 1, sets html_errors to 0, and sets error_reporting to E_ALL. It defines CLI_ENVIRONMENT from cli.environment.mode, which defaults to testing, if the constant is not already defined. It also defines standard CLI streams when they are missing.
init
Initializes the framework and registers error handlers without returning the application instance.
public static function init(): voidUnlike http(), it does not perform the environment mode check.
autoload
Loads the framework modules and completes bootstrapping without registering error handlers or configuring CLI settings.
public static function autoload(): voidisPhpVciAutoload
Checks whether PHPVCI autoloading can be used with the loaded configuration.
public static function isPhpVciAutoload(): boolReturns:
true when the configuration has a non-empty version and paths.target, or when its internal status is 2. Otherwise, returns false.
resolveFilepath
Resolves an existing file path from the selected framework directory.
public static function resolveFilepath(string $file, string $from = 'system'): ?string| Parameter | Type | Description |
|---|---|---|
$file | string | Relative file path. Leading forward slashes are removed. |
$from | 'system'|'bootstrap'|'plugins' | Source directory, defaulting to system. |
Returns:
string|null - Return the resolved file path if the file exists, or null for an empty file path, unsupported source, or missing file.
PHPVCI is considered for system and bootstrap paths, but not for plugins or the exact system/Boot.php path.
use Luminova\Boot;
$luminova = Boot::resolveFilepath('Luminova.php');
$autoload = Boot::resolveFilepath('autoload.php', 'plugins');
$constants = Boot::resolveFilepath('constants.php', 'bootstrap');
if ($luminova === null) {
// The file was not found in the resolved directory.
}File Resolution Rules
Boot resolves modules from the following directories:
| Source | Local resolution | PHPVCI resolution |
|---|---|---|
system | Directory containing local Boot.php | {target}/system/ |
bootstrap | APP_BASE_PATH/bootstrap/ | {target}/bootstrap/ |
plugins | Local system/plugins/ | Not used |
app | APP_BASE_PATH/app/ | Not used |
Key rules:
system/Boot.phpis loaded locally. PHPVCI does not replace the boot file that starts the process.system/plugins/*, includingsystem/plugins/autoload.php, always uses the local installation.- PHPVCI can resolve other
system/*files andbootstrap/*files when the configuration has a non-empty version and target. - Application files, including module configuration, developer helper functions, and the maintenance page, are loaded from
app/. - If PHPVCI is disabled or its required values are missing, public path resolution and internal module imports use the local directories.
For example, with paths.target set to /var/www/phpvci.packages:
Boot::resolveFilepath('Luminova.php');
// /var/www/phpvci.packages/system/Luminova.php
Boot::resolveFilepath('constants.php', 'bootstrap');
// /var/www/phpvci.packages/bootstrap/constants.php
Boot::resolveFilepath('Boot.php');
// The local system/Boot.php
Boot::resolveFilepath('autoload.php', 'plugins');
// The local system/plugins/autoload.phpFeatures
Optional application features
During the first finish, Boot checks these environment settings. Each feature is enabled only when its setting is truthy.
| Setting | Action |
|---|---|
feature.app.dev.functions | Loads app/Utils/Global.php and defines USER_DEFINED_GLOBAL_HELPER. |
feature.app.autoload.psr4 | Registers the application PSR-4 autoloader with Autoloader::register(). |
feature.app.services | Registers application services with Factory::register(). |
feature.app.class.alias | Reads app/Config/Modules.php and registers its alias entries with class_alias(). |
All four settings default to false when not configured.
The app/Config/Modules.php file can return aliases as alias => class name pairs:
return [
'alias' => [
'Helper' => \App\Utils\Helper::class,
],
];If an alias cannot be registered, Boot logs a warning and continues. USER_MODULE_AUTOLOAD is defined only when at least one alias is successfully registered.
HTTP Method Override
Outside production and outside the CLI SAPI, Boot can override a POST request method. It checks $_POST['_METHOD'], then $_POST['_method'], then $_GET['_method']. Values are trimmed and converted to uppercase. Only PUT, DELETE, PATCH, and OPTIONS are accepted, and the selected value is stored in $_SERVER['HTTP_X_HTTP_METHOD_OVERRIDE'].
Static Page Cache
During finish, Boot checks for a static cached response when page.caching is enabled and the request URI ends with one of the configured static extensions returned by Runtime::getStaticCacheTypes().
If a valid cache is found, Boot serves it and exits with STATUS_SUCCESS. If no usable cache is found for a matching extension, the extension is removed from the URI so the request can continue through normal routing.
Maintenance Mode
If MAINTENANCE is enabled, Boot stops normal request processing.
- CLI: Prints a maintenance error and exits with
STATUS_ERROR. - HTTP: Sends a non-cacheable
503 Service Unavailableresponse, usesapp.maintenance.retry(default3600) for the retry value, and loadsapp/Errors/Defaults/maintenance.php. If that file cannot be loaded, Boot sends a generic service-unavailable response. The script then exits.
Runtime and Environment Settings
During warmup, Boot applies these settings from the environment configuration:
| Setting | Behavior |
|---|---|
| Error reporting | For non-CLI requests, production outside staging excludes notices and deprecations. Other modes use E_ALL. |
debug.display.errors | Controls browser error display outside CLI. It is honored in staging or non-production mode. |
| Error output wrapper | Non-CLI PHP errors are wrapped in <span class="php-core-error">. |
zend.exception_ignore_args | Set to 1 in production outside staging, otherwise 0. |
script.execution.limit | Passed to Runtime::setExecutionTime() when configured. |
app.timezone | Passed to Runtime::setTimezone() when non-empty. |
app.mb.encoding | Passed to Runtime::setEncoding() when non-empty. |
script.ignore.abort | Passed to Runtime::setIgnoreUserAbort() when configured. |
Runtime::profiling('start') is called at the end of warmup. Profiling only records data when the relevant profiling environment settings allow it.