Luminova Framework

PHP Luminova: Luminova Framework Class

Last updated: 2026-10-27 15:55:35

Luminova built-in development server, leveraging PHP's development server functionality. This is useful for development and testing your application in a controlled environment.

The Luminova class is the central utility hub for the Luminova framework. It provides framework-level constants and static helper methods to simplify common tasks, work with application paths and URLs, terminate requests, and retrieve metadata about the framework.

All methods are static. The class is final and has a private constructor, so it cannot be instantiated.


Usage Examples

Get Framework Version

use Luminova\Luminova;

echo Luminova::version();     // 3.9.0
echo Luminova::version(true); // 390

Build Application Paths

$file = Luminova::root('writeable/logs', 'debug.log');
// /var/www/app/writeable/logs/debug.log

Build Application URLs

$url = Luminova::toBaseUrl('about');
$relative = Luminova::toBaseUrl('about', true);

Resolve a Kernel Service

use App\Kernel;

$application = Kernel::resolve(Kernel::SERVICE_APPLICATION);

Get Base Class Name

$base = Luminova::getClassBasename('\App\Controllers\HomeController'); 
// Returns: HomeController

Masking System Path

$path = Luminova::toDisplayPath('/var/www/project/app/Controllers/Http/Home.php');
// Returns: app/Controllers/Http/Home.php

Class Definition

  • Full namespace: \Luminova\Luminova
  • This class is a Final class

Constants

ConstantTypeDescription
VERSIONstringThe current Luminova framework version.
VERSION_NAMEstringThe codename associated with the current Luminova version.
MIN_PHP_VERSIONstringThe minimum PHP version required to run Luminova.
NOVAKIT_VERSIONstringThe version of the built-in CLI Novakit.
SYSTEM_PATHSarrayKnown application system directories.

SYSTEM_PATHS

Known application system directories used to identify and mask filesystempaths (see toDisplayPath()). The first matching directory in this listdetermines where a path is truncated.

public const SYSTEM_PATHS

Type: array<int,string>

Default Value:

[
    'public', 'node', 'bin', 'system', 'bootstrap',
    'resources', 'writeable', 'libraries', 'routes', 'builds', 'app'
]

Methods

version

Get the framework version name or code.

When $integer is true, the dots are removed from the version string and theresult is cast to an integer (for example, 3.9.0 becomes 390).

final public static version(bool $integer = false): string|int

Parameters:

ParameterTypeDescription
$integerboolReturn the version as an integer code instead of the version string (default: false).

Return Value:

string|int - Return the version string, or the integer version code.


root

Build an absolute path from the application root directory.

Generates a normalized path based on the application root, with an optionalsubdirectory and filename appended. Input separators (\ and /) aresanitized, and the path is not checked for existence.

When $path is already prefixed with the application root, it is treated as an absolute path instead of being appended again. When a $path is given, the result ends with a trailing / unless a $filename is appended.

public static root(
    ?string $path = null, 
    ?string $filename = null, 
    bool $normalize = false
): string

Parameters:

ParameterTypeDescription
$pathstring|nullOptional subdirectory relative to the application root (e.g., writeable/logs).
$filenamestring|nullOptional filename to append to the path (e.g., debug.log).
$normalizeboolConvert the result to the operating system directory separator for filesystem usage (default: false, uses /).

Return Value:

string - Return the absolute path based on the application root.

Examples:

$file = Luminova::root('writeable/logs', 'debug.log');

// Output:
// /var/www/app/writeable/logs/debug.log
$file = Luminova::root('writeable/logs', 'debug.log', true);

// Linux:   /var/www/app/writeable/logs/debug.log
// Windows: C:\wamp64\www\app\writeable\logs\debug.log

Use $normalize = true only for direct filesystem access.


appRoot

Get the application project root filesystem path.

The project root contains the application source code and configuration,including the public document root. Starting from APP_BASE_PATH, the methodwalks up the directory tree until it finds a .env file, a .dev.env file, orsystem/Boot.php. If none is found, APP_BASE_PATH is used. The result uses the operating system directoryseparator, ends with a trailing separator, and is cached after the first call.

public static appRoot(): string

Return Value:

string - Return the absolute filesystem path to the application project root.


documentRoot

Get the application document root filesystem path.

The document root is the public directory exposed by the web server.

public static documentRoot(): string

Return Value:

string - Return the absolute filesystem path to the application document root.


documentRootUri

Get the application document root URI.

The URI is derived from SCRIPT_NAME by removing the entry script nameand normalizing path separators to forward slashes. The returned URIalways ends with /. The result is cached after the first call.

public static documentRootUri(): string

Return Value:

string - Return the application document root URI, such as / or /admin/.


entryScript

Get the application entry script path or URI.

public static entryScript(bool $uri = true): string

Parameters:

ParameterTypeDescription
$uriboolWhether to return the web URI instead of the filesystem path (default: true).

Return Value:

string - Return the application entry script URI or absolute filesystem path.

Example:

Luminova::entryScript();       // e.g. /index.php
Luminova::entryScript(false);  // e.g. /var/www/project/public/index.php

toBaseUrl

Build a URL relative to the application base path.

Generates an absolute or relative URL using the application base path orfront controller directory. Useful for generating links to routes, assets,and internal pages.

  • In development, the front controller path is included.
  • In production, URLs are resolved from the application root (APP_URL).
  • Host and port are preserved when available.
public static toBaseUrl(?string $route = null, bool $relative = false): string

Parameters:

ParameterTypeDescription
$routestring|nullOptional route path to append.
$relativeboolWhether to return a relative URL (default: false).

Return Value:

string - Return the constructed application URL.

Example:

Assuming your application path is like /Some/Path/To/htdocs/my-project-path/public/:

echo Luminova::toBaseUrl('about');

It returns, depending on your development environment:

On Development:

  • http://localhost:8080/about
  • http://localhost/my-project-path/public/about
  • http://localhost/public/about

In Production:

  • http://example.com:8080/about
  • http://example.com/about

Relative URL Example:

echo Luminova::toBaseUrl('about', true); 
// /my-project-path/public/about
// /about

toAbsoluteUrl

Convert an application path to a fully qualified URL.

Normalizes the path by removing the application directory prefix and theleading public/ segment as needed, then resolves it with toBaseUrl().

public static toAbsoluteUrl(string $path): string

Parameters:

ParameterTypeDescription
$pathstringThe application-relative file or route path.

Return Value:

string - Return the fully qualified URL.

Examples:

Luminova::toAbsoluteUrl('public/images/logo.png');

// Development:
// http://localhost/my-project/public/images/logo.png

// Production:
// https://example.com/images/logo.png
Luminova::toAbsoluteUrl('about');

// Development:
// http://localhost/my-project/public/about

// Production:
// https://example.com/about

apiPrefix

Get the API route prefix.

Reads the app.api.prefix configuration once and caches the result forsubsequent calls to avoid repeated environment lookups. Falls back to'api' if the value is not defined or empty.

public static apiPrefix(): string

Return Value:

string - Return the default application API prefix used for routing.


toDisplayPath

Convert a file path to a display-friendly path.

Removes the leading path up to the first known application directory(from Luminova::SYSTEM_PATHS, such as app or system), to avoidexposing the full server filesystem path in errors, logs, and debug output.Backslashes are normalized to forward slashes.

If no known directory is found, the normalized original path is returned.

public static toDisplayPath(string $path): string

Parameters:

ParameterTypeDescription
$pathstringThe file path to convert.

Return Value:

string - Return the display path starting at the matched application directory, or the normalized original path when no match is found.

Example:

Luminova::toDisplayPath('/var/www/project/app/Controllers/Home.php');
// app/Controllers/Home.php

terminate

Terminates the current request with a formatted response.

In HTTP context, the output format is taken from the LMV_SENT_CONTENT_TYPE request header, falling back to $httpOutput:

  • json: JSON. A message that is already valid JSON is sent as is, otherwise it is wrapped as {status, error, message}.
  • html: a minimal HTML page.
  • xml: an XML document.
  • otherwise plain text, formatted as (status) [title] message.

JSON is also used when the message starts with { or [, or when no format is given and the request is an API request. In CLI context, the message is written to the terminal instead (standard output for success or accepted statuses, standard error otherwise).

When $message is empty or the status has no content (for example 204), only the no-content headers are sent.

If $hookOnTerminated is enabled, the application onTerminated hook is triggered with the context (CLI or HTTP), status, message and title. Errors thrown by the hook are ignored. Calling this method a second time in the same request immediately exits with an error status without producing further output.

public static terminate(
    int $status,
    string $message,
    ?string $title = null,
    int $retry = 3600,
    ?string $httpOutput = null,
    bool $hookOnTerminated = true
): never

Parameters:

ParameterTypeDescription
$statusintHTTP status code.
$messagestringTermination message.
$titlestring|nullOptional response title (default: the HTTP status phrase).
$retryintCache retry duration in seconds (default: 3600).
$httpOutputnull|'html'|'xml'|'json'|'plain'Preferred HTTP output format when the request does not specify one (default: null).
$hookOnTerminatedboolWhether to trigger the onTerminated application hook (default: true).

Return Value:

never - This method always terminates the current process.

Example:

Luminova::terminate(503, 'Service is under maintenance.', httpOutput: 'json');

config

Resolve an application configuration class and return its instance.

Accepts a configuration name (e.g., session) or a fully qualified class name(e.g., App\Config\Session). A name without a namespace separator is resolvedrelative to the App\Config namespace, with the first letter capitalized(session becomes App\Config\Session). Only the first letter is changed, somulti-word names must be passed in their exact class casing (e.g., DatabaseConfig).

A name that contains a namespace separator must start with App\Config\, otherwise themethod returns null. Classes outside that namespace, such as those in Luminova\Config, cannot be resolved with this method.

When $shared is true, the instance is created once per class and reused on later calls. When false, a new instance is returned on every call and is not stored.

public static config(
    string $class, 
    bool $shared = true, 
    ?string $abstract = null
): ?object

Parameters:

ParameterTypeDescription
$classstringConfiguration basename or fully qualified class name under App\Config.
$sharedboolWhether to reuse a shared instance (default: true).
$abstractstring|nullOptional parent class or interface the instance must extend or implement (default: null).

Return Value:

object|null - Return the configuration instance, or null if $class is empty, is outside the App\Config namespace, or does not exist.

Throws:

Examples:

// Resolved as App\Config\Session
$session = Luminova::config('session');
// Using a fully qualified class name
$session = Luminova::config('App\Config\Session');
// Always create a fresh instance
$config = Luminova::config('session', shared: false);
// Require the configuration to satisfy a parent class or interface
$config = Luminova::config('session', abstract: MyConfigInterface::class);
// Missing or out of namespace classes return null
$missing = Luminova::config('DoesNotExist');   // null
$other = Luminova::config('Luminova\Config\Configuration'); // null

import

Import a PHP file using a physical path or a virtual path scheme.

A path written as scheme:path is resolved against the matching application directory. Any other path is used as is. By default the file is loaded once with include_once.

Supported schemes:

SchemeResolves to
approot/app/*
packageroot/system/plugins/*
systemroot/system/*
publicroot/public/*
writeableroot/writeable/*
librariesroot/libraries/*
resourcesroot/resources/*
routesroot/routes/*
bootstraproot/bootstrap/*
buildsroot/builds/*
binroot/bin/*
noderoot/node/*

packages and plugins are accepted as aliases of package. Scheme names are case-insensitive. Any other scheme is not resolved, so the file check fails for it.

The file is loaded with include_once by default. Set $once to false to use include, and $useRequire to true to use require or require_once.

Values in $scope are extracted as local variables inside the imported file. The array must be associative. Keys that clash with variables already defined by the loader (path, scope, once, require, promise) are skipped and not overwritten.

When $once is true and the file was already loaded, PHP returns true instead of the file's return value.

When $promise is true, the result is wrapped in a promise instead of being returned or thrown. A successful import returns a fulfilled promise holding the file's return value. A missing file, an invalid scope, or an error thrown by the imported file returns a rejected promise.

public static import(
    string $path,
    bool $throw = true,
    bool $once = true,
    bool $useRequire = false,
    array $scope = [],
    bool $promise = false
): mixed

Parameters:

ParameterTypeDescription
$pathstringFile path or scheme path to import.
$throwboolThrow an exception when the file does not exist (default: true).
$onceboolLoad the file only once using *_once (default: true).
$useRequireboolUse require instead of include (default: false).
$scopearray<string,mixed>Variables to expose inside the imported file (default: []).
$promiseboolReturn a promise instead of the raw value (default: false).

Return Value:

\Luminova\Interface\PromiseInterface|mixed|null - Return the value returned by the imported file, a promise when $promise is enabled, or null when the file does not exist and $throw is false.

When the file does not exist and $throw is false, null is returned even if $promise is enabled.

Throws:

When $promise is enabled, these are not thrown. They are returned as a rejected promise instead.

Examples:

$settings = Luminova::import('app:Config/settings.php');
// Using a direct path
Luminova::import(__DIR__ . '/app/Config/settings.php');
// Load a file from the plugins directory
Luminova::import('package:brick/math/src/BigNumber.php');
// Load on every call instead of once
Luminova::import('routes:api.php', once: false);
// Use require instead of include
Luminova::import('system:Bootstrap/init.php', useRequire: true);
// Return null instead of throwing when the file is missing
$file = Luminova::import('app:Config/optional.php', throw: false);
// Pass variables to the imported file
Luminova::import('app:Views/mail.php', scope: ['name' => 'Peter']);

// Inside mail.php, $name is available

Promise Example:

Luminova::import('app:Config/settings.php', promise: true)
    ->then(function (mixed $settings) {
        echo $settings['name'];
    })->catch(function (Throwable $e) {
        echo $e->getMessage();
    });

This method is also available as the global helper \Luminova\Funcs\import().


hash

Generate a hash using the requested algorithm with optional fallback support.

The method attempts to use the requested hashing algorithm. If the algorithmis unavailable in the current PHP environment, the fallback algorithm is usedinstead. This is useful when applications run across different environmentswhere optional hash algorithms may not be compiled or enabled. Algorithm names are case-insensitive.

public static hash(
    string $algo,
    string $data,
    bool $binary = false,
    array $options = [],
    ?string $fallbackAlgo = 'sha256'
): string

Parameters:

ParameterTypeDescription
$algostringPreferred hashing algorithm.
$datastringData to hash.
$binaryboolWhether to return raw binary output instead of hex (default: false).
$optionsarrayReserved options for future hash algorithm settings, passed to PHP hash() (default: []).
$fallbackAlgostring|nullAlgorithm to use when the preferred one is unavailable (default: sha256).

Return Value:

string - Return the generated hash output.

Throws:

Example:

$hash = Luminova::hash('sha3-256', 'my-data');

// If "sha3-256" isn't available in the current environment,
// it silently falls back to "sha256" instead of throwing.

getClassBasename

Get the base name from one or more fully qualified class names.

Accepts a single class name, a comma-separated list of class names, oran array of class names. The return format matches the input format. A comma-separated string is returned as a string joined with ,.

When $validate is enabled, each class name must refer to an alreadyloaded class and must not contain a static class member reference suchas ClassName::method(). Names that fail validation return an empty string.

public static getClassBasename(array|string $class, bool $validate = false): array|string

Parameters:

ParameterTypeDescription
$classarray<int,string>|stringOne or more fully qualified class names.
$validateboolWhether to validate that each class is already loaded (default: false).

Return Value:

string[]|string - Return the base class name(s), preserving the input format.

Examples:

Luminova::getClassBasename('\App\Controllers\HomeController');
// Returns: 'HomeController'
Luminova::getClassBasename('App\Models\User, App\Services\Log');
// Returns: 'User, Log'
Luminova::getClassBasename([
    'App\Models\User',
    'App\Services\Log',
]);
// Returns: ['User', 'Log']
Luminova::getClassBasename('App\Models\User', true);
// Returns: 'User' if the class is already loaded, otherwise ''.

isPropertyExists

Check whether a class or object has a property, with optional static-only filtering.

Uses ReflectionClass when $staticOnly is true to determine if a propertyis declared as static. In that mode, only public or protected static propertiesreturn true, and private static properties return false. For general use, itfalls back to property_exists() for better performance.

public static isPropertyExists(
    class-string|object $objectOrClass,
    string $property,
    bool $staticOnly = false
): bool

Parameters:

ParameterTypeDescription
$objectOrClassclass-string|objectThe class name or object to check.
$propertystringThe property name to check for.
$staticOnlyboolIf true, only returns true for public or protected static properties (default: false).

Return Value:

bool - Returns true if the property exists (and is a public or protected static property if required), false otherwise.

Example:

Luminova::isPropertyExists(MyClass::class, 'config', true); // true if static
Luminova::isPropertyExists(MyClass::class, 'config');       // true if static or non-static