PHP Luminova: Luminova Runtime 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 Runtime class is the central utility hub for the Luminova framework and application runtime. It provides framework-level static helper methods to simplify common runtime, environment, and platform checks, along with a lightweight in-memory shared storage registry that can be accessed across the application codebase.
All methods are static, so there's no need to instantiate the class.
NoteThe shared storage provided by this class is runtime-only, comparable in concept to Swift's
UserDefaultsor Android/JavaSharedPreferences, but not persistent:
- Data is lost at the end of each request.
- Values are not shared across processes or workers.
- Nothing is written to disk.
Usage Examples
use Luminova\Runtime;
Runtime::set('THEME', true);
$context = Runtime::get('THEME', false);
if (Runtime::has('THEME')) {
// Key exists...
}
Runtime::remove('THEME');
Runtime::clear();Class Definition
- Full namespace:
\Luminova\Runtime - This class is a Final class
Constants
| Constant | Value | Description |
|---|---|---|
QUERY_DEBUG | luminova.b.query.debug | Enable or store query debug information. |
ALTER_DROP_COLUMNS | luminova.b.db.alter_drop_columns | Allow dropping columns during table alteration. |
CHECK_ALTER_TABLE | luminova.b.db.check_alter_table | Enable validation before running ALTER TABLE operations. |
MIGRATION_SUCCESS | luminova.b.migration.success | Flag indicating a successful migration execution. |
ALTER_SUCCESS | luminova.b.alter.success | Flag indicating a successful table alteration. |
DROP_TRANSACTION | luminova.O.db.transaction | Store database transaction object. |
QUERY_PROFILING | luminova.a.db.query.profiling | Store query execution profiling data. |
CLASS_METADATA | luminova.a.class.metadata | Store routed class metadata used during runtime. |
TEMPLATE_CONTEXT | luminova.s.template.context | Store rendered template context ID. |
Methods
isEnv
Determine whether the application is running in the specified runtime.
The comparison is case-insensitive.
public static isEnv(string $runtime): boolParameters:
| Parameter | Type | Description |
|---|---|---|
$runtime | string | Runtime name to check. |
Return Value:
bool - Return true if the current runtime matches, otherwise false.
Example:
if (Runtime::isEnv('docker')) {
// Running inside a Docker container.
}isLocal
Determine whether the current request is from a local environment.
This is a heuristic check based on:
- Local hostnames (
localhost,127.0.0.1,::1). - Private / loopback IP ranges (e.g.,
127.x.x.x,10.x.x.x,192.168.x.x,172.16.x.xto172.31.x.x).
The result is cached after the first call.
public static isLocal(): boolReturn Value:
bool - Return true if the request appears to originate from a local environment.
Note:This does NOT guarantee environment type (dev/prod). It only detects local network characteristics.
Example:
if (Runtime::isLocal()) {
// Skip strict CORS checks for local development.
}isDocker
Determine whether the application is running in a Docker environment.
This is a convenience wrapper around self::isContainer() that checks specifically for the Docker runtime.
public static isDocker(): boolReturn Value:
bool - Return true if Docker is detected, otherwise false.
Example:
if (Runtime::isDocker()) {
// Use container-friendly file paths.
}isContainer
Determine whether the application is running in a supported runtime environment.
When no runtime is specified, checks whether any supported runtime is detected. When a runtime is specified, checks only that runtime. The php alias is treated as novakit.
Supported runtimes include docker, kubernetes, containerd, podman, and novakit.
public static isContainer(?string $runtime = null): boolParameters:
| Parameter | Type | Description |
|---|---|---|
$runtime | string|null | Runtime name to check, or null to check for any supported runtime. |
Return Value:
bool - Return true if the requested runtime is detected, otherwise false.
Example:
if (Runtime::isContainer('kubernetes')) {
// Running inside a Kubernetes pod.
}
if (Runtime::isContainer()) {
// Running inside any supported container runtime.
}isOutsideContainer
Determine whether the application is running outside a detected runtime environment.
Checks if any supported container or runtime environment is detected.
public static isOutsideContainer(): boolReturn Value:
bool - Return true if no supported runtime is detected, otherwise false.
Example:
if (Runtime::isOutsideContainer()) {
// Running directly on bare metal or a VM.
}name
Get the name of the current runtime environment.
The runtime name is resolved from the RUNTIME_ENV environment variable. This allows the runtime to be explicitly identified when automatic container detection cannot determine the environment.
public static name(): ?stringReturn Value:
string|null - Return the runtime name, or null if none is defined.
Example:
$runtime = Runtime::name();
// e.g., "docker", "podman", "kubernetes", or nullThe value may be set through any container configuration mechanism that exposes environment variables to the application, including Docker, Docker Compose, Podman, Kubernetes, or a container orchestration platform.
Setting the runtime name:
Docker:
ENV RUNTIME_ENV=dockerDocker Compose:
services:
app:
environment:
RUNTIME_ENV: dockerPodman:
podman run -e RUNTIME_ENV=podman my-appKubernetes:
env:
- name: RUNTIME_ENV
value: kubernetesAny container configuration that exposes RUNTIME_ENV to PHP can be used:
RUNTIME_ENV=<runtime-name>For example:
RUNTIME_ENV=docker
RUNTIME_ENV=podman
RUNTIME_ENV=kubernetes
RUNTIME_ENV=ecs
RUNTIME_ENV=custom-runtimeThis is useful when the runtime cannot be reliably detected from container-specific files or
/proc/1/cgroup.
isCommand
Determine whether the application is running in CLI (Command-Line Interface) mode.
Uses the PHP SAPI and common CLI indicators to distinguish command-line execution from web requests.
public static isCommand(): boolReturn Value:
bool - Return true if running in CLI mode, otherwise false.
Example:
if (Runtime::isCommand()) {
// Running via CLI/novakit.
}isHmvc
Determine whether HMVC mode is enabled.
The env(feature.app.hmvc) configuration value is read once and cached for subsequent calls.
public static isHmvc(): boolReturn Value:
bool - Return true if HMVC mode is enabled, otherwise false.
Example:
if (Runtime::isHmvc()) {
// Resolve controllers using the HMVC module structure.
}isPlatform
Determine whether the application is running on a specific platform.
Supports common operating system families, BSD variants, Solaris, and common AWS and Azure runtime environments. Custom platform names are matched against the operating system name returned by php_uname().
Supported Platform Values:
mac— macOS.windows— Windows.linux— Linux.freebsd— FreeBSD.openbsd— OpenBSD.bsd— Any BSD-based operating system.solaris— Solaris.aws— AWS runtime environment.azure— Azure runtime environment.
Custom platform names are also supported and are matched case-insensitively against the current operating system name.
public static isPlatform(string $name): boolParameters:
| Parameter | Type | Description |
|---|---|---|
$name | string | Platform name to check, such as windows, linux, mac, aws, or azure. |
Return Value:
bool - Return true if the current platform matches the specified name, otherwise false.
Example:
Runtime::isPlatform('windows');
Runtime::isPlatform('linux');
Runtime::isPlatform('mac');
Runtime::isPlatform('aws');
Runtime::isPlatform('azure');isFunctionDisabled
Check whether a PHP function is disabled by the server configuration.
Reads the configured disabled function list and checks if the specified function is unavailable due to PHP's disable_functions setting.
public static isFunctionDisabled(string $function): boolParameters:
| Parameter | Type | Description |
|---|---|---|
$function | string | The PHP function name to check. |
Return Value:
bool - Return true if the function is disabled, otherwise false.
Example:
if (Runtime::isFunctionDisabled('exec')) {
// Fall back to an alternative implementation.
}disabledFunctions
Returns the list of disabled PHP functions (via the disable_functions directive).
The list can be returned as a simple array of function names, or as an associative array with function names as keys and true as values.
public static disabledFunctions(bool $flip = false): arrayParameters:
| Parameter | Type | Description |
|---|---|---|
$flip | bool | If true, returns an associative array with function names as keys and true as values. |
Return Value:
string[]|array<string,true> - Return an array of disabled function names, or an associative array if $flip is true.
Example:
$disabled = Runtime::disabledFunctions(true);
if (isset($disabled['exec'])) {
// "exec" is disabled on this server.
}tryFunction
Call a PHP function if it exists and is not disabled.
Returns null when the function is unavailable due to being undefined or disabled by PHP configuration.
public static tryFunction(string $function, mixed ...$arguments): mixedParameters:
| Parameter | Type | Description |
|---|---|---|
$function | string | Function name to call. |
$arguments | mixed | Arguments passed to the function. |
Return Value:
mixed - Return the function result, or null if the function is unavailable.
Example:
$result = Runtime::tryFunction('set_time_limit', 300);
if ($result === null) {
echo 'Function is unavailable.';
}isCallable
Check whether the given value is callable or represents a callable reference.
In addition to standard PHP callables, two-element arrays are accepted as callable references even when the target cannot currently be called. When $strict is enabled, the referenced class and method must exist.
public static isCallable(mixed $input, bool $strict = false): boolParameters:
| Parameter | Type | Description |
|---|---|---|
$input | mixed | The value to check (string, array, closure, object, etc.). |
$strict | bool | If true, array callables are valid only if the referenced class exists. |
Return Value:
bool - Return true if the value is callable or a valid callable reference, otherwise false.
setEncoding
Set the internal multibyte encoding.
On success, the applied encoding is also stored under the app.mb.encoding environment key.
public static setEncoding(string $encoding): boolParameters:
| Parameter | Type | Description |
|---|---|---|
$encoding | string | The default internal encoding. |
Return Value:
bool - Return false if encoding is empty or mb_internal_encoding is unavailable, otherwise true.
Example:
Runtime::setEncoding('UTF-8');permission
Check whether a file or directory has the required access permissions.
Checks each requested permission and returns true only when allpermissions are available. When a permission check fails, this methodreturns false by default. If $silent is false, it logs the failurein production and throws a FileException.
Permissions may be specified using shorthand (r, w, x) or readablenames (read, write, execute). Multiple permissions can be combinedusing underscores, plus signs, or commas, and their order is not significant.
public static permission(
string $permission = 'rw',
?string $file = null,
bool $silent = true
): boolParameters:
| Parameter | Type | Description |
|---|---|---|
$permission | string | The access permission or combination of permissions to check.. |
$file | string|null | The file or directory path to check. If null, defaults to the application's writeable directory. |
$silent | bool | Whether to suppress the exception and return false when a required permission is unavailable. (default: true). |
Return Value:
bool - Return true if all required permissions are available, otherwise false.
Throws:
- \Luminova\Exceptions\FileException - If the file does not have the required permissions,
$silentis false, and the failure could not be logged (i.e. not in production, or logging failed to dispatch).
hasPermission
Check whether a file or directory has the specified access permissions.
Supports read, write, and execute permissions individually or in combination. Permissions can be specified using shorthand (r, w, x) or readable names (read, write, execute). Multiple permissions may be separated by underscores, plus signs, or commas, and their order is not significant. Unlike self::permission(), this method never throws and simply returns the check result.
Supported permissions:
rorread- Read access.worwrite- Write access.xorexecute- Execute access.rworread_write- Read and write access.rxorread_execute- Read and execute access.wxorwrite_execute- Write and execute access.rwxorread_write_execute- Read, write, and execute access.
public static hasPermission(
string $permission,
string $file
): boolParameters:
| Parameter | Type | Description |
|---|---|---|
$permission | string | The access permission or combination of permissions to check. |
$file | string | The file or directory path to check. |
Return Value:
bool - Return true if all requested permissions are available, otherwise false.
Example:
Runtime::hasPermission('read', $file);
Runtime::hasPermission('read_write', $file);
Runtime::hasPermission('write+read', $file);
Runtime::hasPermission('execute,read,write', $file);
Runtime::hasPermission('rwx', $file);setTimezone
Sets the default PHP timezone.
If the specified timezone is already active, no changes are made and true is returned. The timezone may be provided as a DateTimeZone instance or a valid timezone identifier. On success, the applied timezone is also stored under the app.timezone environment key.
public static setTimezone(DateTimeZone|string $timezone): boolParameters:
| Parameter | Type | Description |
|---|---|---|
$timezone | \DateTimeZone|string | The timezone to set. |
Return Value:
bool - Return true on success, or false if the timezone is empty, invalid, or date_default_timezone_set() is unavailable.
Example:
$timezone = 'UTC';
Runtime::setTimezone($timezone);
echo date_default_timezone_get(); // UTC
// Optionally read back the applied value from env
echo env('app.timezone'); // UTCsetExecutionTime
Set the max script execution time, in seconds.
Updates the limit only when increasing it or disabling it (0). Has no effect on Windows. On success, the applied value is also stored under the script.execution.limit environment key.
public static setExecutionTime(int $seconds): boolParameters:
| Parameter | Type | Description |
|---|---|---|
$seconds | int | Time limit in seconds (0 = unlimited). |
Return Value:
bool - Return true on success, false otherwise.
Example:
Runtime::setExecutionTime(300);setIgnoreUserAbort
Set whether the script should continue running after the client disconnects.
On success, the applied flag is also stored under the script.ignore.abort environment key.
public static setIgnoreUserAbort(bool $ignore): boolParameters:
| Parameter | Type | Description |
|---|---|---|
$ignore | bool | Whether to ignore or continue on client disconnect. |
Return Value:
bool - Return true on success, or false if ignore_user_abort() is unavailable.
Example:
Runtime::setIgnoreUserAbort(true);setLocale
Set the default locale for all or specific locale categories.
On success, when $category is LC_ALL, the applied locale is also stored under the app.locale environment key.
public static setLocale(string $locale, int $category = LC_ALL): boolParameters:
| Parameter | Type | Description |
|---|---|---|
$locale | string | The default application locale to set. |
$category | int | The category affected by the locale setting (e.g., LC_*). |
Return Value:
bool - Return true if the locale was applied, false if $locale is empty or invalid.
Example:
Runtime::setLocale('en_US.UTF-8');
Runtime::setLocale('en_US.UTF-8', LC_TIME);getCacheId
Generate a cache identifier for the current request.
Creates a normalized cache key using the request method and URI. The URI may optionally include query parameters and can be normalized by removing known static file extensions (as configured via page.caching.statics) to prevent duplicate cache entries for the same resource. The generated identifier can be returned as either a raw key or an XXH3 hash.
public static getCacheId(
?string $prefix = null,
?bool $withUriQuery = null,
bool $hashValue = true
): stringParameters:
| Parameter | Type | Description |
|---|---|---|
$prefix | string|null | Optional prefix to prepend to the generated key. |
$withUriQuery | bool|null | Whether to include query parameters in the key. When null, the value is determined by env('page.cache.query.params', false). |
$hashValue | bool | Whether to return the generated key as an XXH3 hash (falls back to md5 if unavailable). |
Return Value:
string - Return the generated cache identifier or its XXH3 hash.
Example:
$cacheId = Runtime::getCacheId();
$cacheIdWithoutQuery = Runtime::getCacheId(
withUriQuery: false
);
$rawCacheId = Runtime::getCacheId(
hashValue: false
);
$userCacheId = Runtime::getCacheId(
prefix: 'user-1',
hashValue: true
);Runtime Cache
set
Store a shared value by key.
Saves a value in the shared storage. If both the existing value and the new value are arrays, they are merged using array_replace, with the new values overriding existing ones.
public static set(string $key, mixed $value): mixedParameters:
| Parameter | Type | Description |
|---|---|---|
$key | string | The storage key. |
$value | mixed | The value to store. |
Return Value:
mixed - Return the stored value.
Example:
use Luminova\Runtime;
Runtime::set('theme', 'dark');
Runtime::set('config', ['debug' => true]);
Runtime::set('config', ['cache' => false]); // merges with existing arrayadd
Add a value to a shared array entry.
Ensures the storage key exists as an array, then assigns the value at the given index.
public static add(string $key, string|int $index, mixed $value): mixedParameters:
| Parameter | Type | Description |
|---|---|---|
$key | string | The storage key. |
$index | string|int | The array index to add the value to. |
$value | mixed | The value to store. |
Return Value:
mixed - Return the stored value.
Example:
use Luminova\Runtime;
Runtime::add('routes', 'home', '/');
Runtime::add('routes', 'login', '/login');get
Get a shared value.
Retrieves a value stored under the specified key. Returns null if the key does not exist.
public static get(string $key): mixedParameters:
| Parameter | Type | Description |
|---|---|---|
$key | string | The key to retrieve. |
Return Value:
mixed - Return the stored value or null if not found.
Example:
use Luminova\Runtime;
$theme = Runtime::get('theme') ?? 'light';has
Check if a key exists in the shared storage.
public static has(string $key): boolParameters:
| Parameter | Type | Description |
|---|---|---|
$key | string | The key to check. |
Return Value:
bool - Return true if the key exists, false otherwise.
Example:
use Luminova\Runtime;
if (Runtime::has('theme')) { ... }remove
Remove a value from the shared storage.
By default, this method protects Luminova internal keys (see ALL_KEYS) and will not remove framework-owned storage entries. To force removal of a core key, explicitly set $userDefined to false.
public static remove(string $key, bool $userDefined = true): voidParameters:
| Parameter | Type | Description |
|---|---|---|
$key | string | The storage key to remove. |
$userDefined | bool | Whether to enforce protection for core keys. |
Return Value:
void
Example:
use Luminova\Runtime;
// Remove a user-defined key
Runtime::remove('theme');
// Force removal of a core key (not recommended)
Runtime::remove(Runtime::CLASS_METADATA, false);clear
Clear all user-defined values from the shared storage.
Core Luminova keys (see ALL_KEYS) are preserved and cannot be removed by this method. This makes the operation safe to use in long-running processes and framework-level code.
public static clear(): voidReturn Value:
void
Example:
use Luminova\Runtime;
Runtime::clear();count
Count the number of keys currently stored.
public static count(): intReturn Value:
int - Return the number of stored keys.
Example:
use Luminova\Runtime;
$count = Runtime::count();