Luminova Framework

PHP Luminova: Luminova Runtime Class

Last updated: 2026-08-26 15:38:47

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 UserDefaults or Android/Java SharedPreferences, 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

ConstantValueDescription
QUERY_DEBUGluminova.b.query.debugEnable or store query debug information.
ALTER_DROP_COLUMNSluminova.b.db.alter_drop_columnsAllow dropping columns during table alteration.
CHECK_ALTER_TABLEluminova.b.db.check_alter_tableEnable validation before running ALTER TABLE operations.
MIGRATION_SUCCESSluminova.b.migration.successFlag indicating a successful migration execution.
ALTER_SUCCESSluminova.b.alter.successFlag indicating a successful table alteration.
DROP_TRANSACTIONluminova.O.db.transactionStore database transaction object.
QUERY_PROFILINGluminova.a.db.query.profilingStore query execution profiling data.
CLASS_METADATAluminova.a.class.metadataStore routed class metadata used during runtime.
TEMPLATE_CONTEXTluminova.s.template.contextStore 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): bool

Parameters:

ParameterTypeDescription
$runtimestringRuntime 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.x to 172.31.x.x).

The result is cached after the first call.

public static isLocal(): bool

Return 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(): bool

Return 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): bool

Parameters:

ParameterTypeDescription
$runtimestring|nullRuntime 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(): bool

Return 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(): ?string

Return Value:

string|null - Return the runtime name, or null if none is defined.

Example:

$runtime = Runtime::name();

// e.g., "docker", "podman", "kubernetes", or null

The 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=docker

Docker Compose:

services:
  app:
    environment:
      RUNTIME_ENV: docker

Podman:

podman run -e RUNTIME_ENV=podman my-app

Kubernetes:

env:
  - name: RUNTIME_ENV
    value: kubernetes

Any 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-runtime

This 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(): bool

Return 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(): bool

Return 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): bool

Parameters:

ParameterTypeDescription
$namestringPlatform 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): bool

Parameters:

ParameterTypeDescription
$functionstringThe 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): array

Parameters:

ParameterTypeDescription
$flipboolIf 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): mixed

Parameters:

ParameterTypeDescription
$functionstringFunction name to call.
$argumentsmixedArguments 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): bool

Parameters:

ParameterTypeDescription
$inputmixedThe value to check (string, array, closure, object, etc.).
$strictboolIf 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): bool

Parameters:

ParameterTypeDescription
$encodingstringThe 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
): bool

Parameters:

ParameterTypeDescription
$permissionstringThe access permission or combination of permissions to check..
$filestring|nullThe file or directory path to check. If null, defaults to the application's writeable directory.
$silentboolWhether 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, $silent is 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:

  • r or read - Read access.
  • w or write - Write access.
  • x or execute - Execute access.
  • rw or read_write - Read and write access.
  • rx or read_execute - Read and execute access.
  • wx or write_execute - Write and execute access.
  • rwx or read_write_execute - Read, write, and execute access.
public static hasPermission(
    string $permission,
    string $file
): bool

Parameters:

ParameterTypeDescription
$permissionstringThe access permission or combination of permissions to check.
$filestringThe 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): bool

Parameters:

ParameterTypeDescription
$timezone\DateTimeZone|stringThe 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'); // UTC

setExecutionTime

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): bool

Parameters:

ParameterTypeDescription
$secondsintTime 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): bool

Parameters:

ParameterTypeDescription
$ignoreboolWhether 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): bool

Parameters:

ParameterTypeDescription
$localestringThe default application locale to set.
$categoryintThe 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
): string

Parameters:

ParameterTypeDescription
$prefixstring|nullOptional prefix to prepend to the generated key.
$withUriQuerybool|nullWhether to include query parameters in the key. When null, the value is determined by env('page.cache.query.params', false).
$hashValueboolWhether 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): mixed

Parameters:

ParameterTypeDescription
$keystringThe storage key.
$valuemixedThe 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 array

add

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): mixed

Parameters:

ParameterTypeDescription
$keystringThe storage key.
$indexstring|intThe array index to add the value to.
$valuemixedThe 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): mixed

Parameters:

ParameterTypeDescription
$keystringThe 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): bool

Parameters:

ParameterTypeDescription
$keystringThe 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): void

Parameters:

ParameterTypeDescription
$keystringThe storage key to remove.
$userDefinedboolWhether 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(): void

Return Value:

void

Example:

use Luminova\Runtime;

Runtime::clear();

count

Count the number of keys currently stored.

public static count(): int

Return Value:

int - Return the number of stored keys.

Example:

use Luminova\Runtime;

$count = Runtime::count();