PHP Luminova: Luminova Framework Class
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); // 390Build Application Paths
$file = Luminova::root('writeable/logs', 'debug.log');
// /var/www/app/writeable/logs/debug.logBuild 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: HomeControllerMasking System Path
$path = Luminova::toDisplayPath('/var/www/project/app/Controllers/Http/Home.php');
// Returns: app/Controllers/Http/Home.phpClass Definition
- Full namespace:
\Luminova\Luminova - This class is a Final class
Constants
| Constant | Type | Description |
|---|---|---|
VERSION | string | The current Luminova framework version. |
VERSION_NAME | string | The codename associated with the current Luminova version. |
MIN_PHP_VERSION | string | The minimum PHP version required to run Luminova. |
NOVAKIT_VERSION | string | The version of the built-in CLI Novakit. |
SYSTEM_PATHS | array | Known 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_PATHSType: 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|intParameters:
| Parameter | Type | Description |
|---|---|---|
$integer | bool | Return 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
): stringParameters:
| Parameter | Type | Description |
|---|---|---|
$path | string|null | Optional subdirectory relative to the application root (e.g., writeable/logs). |
$filename | string|null | Optional filename to append to the path (e.g., debug.log). |
$normalize | bool | Convert 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.logUse $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(): stringReturn 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(): stringReturn 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(): stringReturn 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): stringParameters:
| Parameter | Type | Description |
|---|---|---|
$uri | bool | Whether 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.phptoBaseUrl
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): stringParameters:
| Parameter | Type | Description |
|---|---|---|
$route | string|null | Optional route path to append. |
$relative | bool | Whether 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
// /abouttoAbsoluteUrl
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): stringParameters:
| Parameter | Type | Description |
|---|---|---|
$path | string | The 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.pngLuminova::toAbsoluteUrl('about');
// Development:
// http://localhost/my-project/public/about
// Production:
// https://example.com/aboutapiPrefix
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(): stringReturn 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): stringParameters:
| Parameter | Type | Description |
|---|---|---|
$path | string | The 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.phpterminate
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
): neverParameters:
| Parameter | Type | Description |
|---|---|---|
$status | int | HTTP status code. |
$message | string | Termination message. |
$title | string|null | Optional response title (default: the HTTP status phrase). |
$retry | int | Cache retry duration in seconds (default: 3600). |
$httpOutput | null|'html'|'xml'|'json'|'plain' | Preferred HTTP output format when the request does not specify one (default: null). |
$hookOnTerminated | bool | Whether 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
): ?objectParameters:
| Parameter | Type | Description |
|---|---|---|
$class | string | Configuration basename or fully qualified class name under App\Config. |
$shared | bool | Whether to reuse a shared instance (default: true). |
$abstract | string|null | Optional 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:
- \Luminova\Exceptions\InvalidArgumentException - If the resolved instance does not extend or implement
$abstract. \Throwable- If the class cannot be instantiated.
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'); // nullimport
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:
| Scheme | Resolves to |
|---|---|
app | root/app/* |
package | root/system/plugins/* |
system | root/system/* |
public | root/public/* |
writeable | root/writeable/* |
libraries | root/libraries/* |
resources | root/resources/* |
routes | root/routes/* |
bootstrap | root/bootstrap/* |
builds | root/builds/* |
bin | root/bin/* |
node | root/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
): mixedParameters:
| Parameter | Type | Description |
|---|---|---|
$path | string | File path or scheme path to import. |
$throw | bool | Throw an exception when the file does not exist (default: true). |
$once | bool | Load the file only once using *_once (default: true). |
$useRequire | bool | Use require instead of include (default: false). |
$scope | array<string,mixed> | Variables to expose inside the imported file (default: []). |
$promise | bool | Return 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:
- \Luminova\Exceptions\RuntimeException - If the file does not exist and
$throwis enabled. - \Luminova\Exceptions\InvalidArgumentException - If
$scopeis a list array. \Throwable- Any error thrown by the imported file.
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 availablePromise 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'
): stringParameters:
| Parameter | Type | Description |
|---|---|---|
$algo | string | Preferred hashing algorithm. |
$data | string | Data to hash. |
$binary | bool | Whether to return raw binary output instead of hex (default: false). |
$options | array | Reserved options for future hash algorithm settings, passed to PHP hash() (default: []). |
$fallbackAlgo | string|null | Algorithm to use when the preferred one is unavailable (default: sha256). |
Return Value:
string - Return the generated hash output.
Throws:
- \Luminova\Exceptions\InvalidArgumentException - If neither the requested algorithm nor the fallback algorithm is supported.
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|stringParameters:
| Parameter | Type | Description |
|---|---|---|
$class | array<int,string>|string | One or more fully qualified class names. |
$validate | bool | Whether 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
): boolParameters:
| Parameter | Type | Description |
|---|---|---|
$objectOrClass | class-string|object | The class name or object to check. |
$property | string | The property name to check for. |
$staticOnly | bool | If 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