Luminova Framework

PHP Luminova: Framework Boot and Module Autoloading

Last updated: 2026-10-27 22:52:16

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.php automatically 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.

MethodBehavior
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:

  1. Defines APP_BASE_PATH if it is not already defined. It uses the APP_BASE_PATH process environment variable, then $_ENV['APP_BASE_PATH'], and otherwise the parent directory of system/. Trailing slash and backslash characters are removed.
  2. Reads the .phpvci.php configuration.
  3. Loads the local Composer autoloader from system/plugins/autoload.php.
  4. Loads bootstrap/polyfills.php, followed by system/Luminova.php, system/Runtime.php, and system/Config/Env.php. PHPVCI may change the source directory for system and bootstrap modules if configured and enabled.
  5. Registers environment values through Env::register().
  6. Loads bootstrap/constants.php and applies the HTTP method override when supported.
  7. Loads bootstrap/Funcs/functions.php, bootstrap/Funcs/strings.php, and bootstrap/Funcs/arrays.php.
  8. Applies PHP runtime settings from the environment configuration.
  9. Defines BOOT_WARMUP_STARTED and 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 with Error::register() after warmup.
  • cli() accepts the cli and phpdbg SAPIs. It enables CLI error reporting, defines CLI_ENVIRONMENT if needed, and initializes STDIN, STDOUT, and STDERR through Runtime::defineStandardStreams().
  • http() calls init(). 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 from App\Kernel.
  • autoload() adds no context-specific initialization between warmup and finish.

Finish

Finish runs whenever http(), init(), cli(), or autoload() is called. It:

  1. Checks PHPVCI version compatibility when PHPVCI autoloading is active.
  2. Registers optional application features on the first finish only.
  3. Defines APP_BOOTED.
  4. Enters maintenance mode and exits if MAINTENANCE is enabled.
  5. 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.

ConstantWhen it is defined
APP_BASE_PATHDuring warmup, if not already defined.
BOOT_WARMUP_STARTEDAt the end of the first warmup.
APP_BOOTEDDuring finish, after optional feature registration.
CLI_ENVIRONMENTDuring Boot::cli(), if not already defined.
USER_DEFINED_GLOBAL_HELPERAfter developer helper functions are loaded.
USER_MODULE_AUTOLOADAfter 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(): Application

Returns:

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(): void

The 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(): void

Unlike 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(): void

isPhpVciAutoload

Checks whether PHPVCI autoloading can be used with the loaded configuration.

public static function isPhpVciAutoload(): bool

Returns:

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
ParameterTypeDescription
$filestringRelative 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:

SourceLocal resolutionPHPVCI resolution
systemDirectory containing local Boot.php{target}/system/
bootstrapAPP_BASE_PATH/bootstrap/{target}/bootstrap/
pluginsLocal system/plugins/Not used
appAPP_BASE_PATH/app/Not used

Key rules:

  • system/Boot.php is loaded locally. PHPVCI does not replace the boot file that starts the process.
  • system/plugins/*, including system/plugins/autoload.php, always uses the local installation.
  • PHPVCI can resolve other system/* files and bootstrap/* 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.php

Features

Optional application features

During the first finish, Boot checks these environment settings. Each feature is enabled only when its setting is truthy.

SettingAction
feature.app.dev.functionsLoads app/Utils/Global.php and defines USER_DEFINED_GLOBAL_HELPER.
feature.app.autoload.psr4Registers the application PSR-4 autoloader with Autoloader::register().
feature.app.servicesRegisters application services with Factory::register().
feature.app.class.aliasReads 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 Unavailable response, uses app.maintenance.retry (default 3600) for the retry value, and loads app/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:

SettingBehavior
Error reportingFor non-CLI requests, production outside staging excludes notices and deprecations. Other modes use E_ALL.
debug.display.errorsControls browser error display outside CLI. It is honored in staging or non-production mode.
Error output wrapperNon-CLI PHP errors are wrapped in <span class="php-core-error">.
zend.exception_ignore_argsSet to 1 in production outside staging, otherwise 0.
script.execution.limitPassed to Runtime::setExecutionTime() when configured.
app.timezonePassed to Runtime::setTimezone() when non-empty.
app.mb.encodingPassed to Runtime::setEncoding() when non-empty.
script.ignore.abortPassed 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.