Luminova Framework

PHP Luminova: Global Utility & Compatibility Functions

Last updated: 2026-08-29 15:55:40

Built-in global helper functions for common tasks and compatibility with the minimum supported PHP version.

Luminova provides a collection of built-in Global Functions for common tasks and compatibility with PHP features that may not be available in the minimum supported PHP version. These functions are available throughout the application and help simplify development without requiring repetitive compatibility checks namespace import or implementations.

These functions are available everywhere in your application because they are defined in the global scope and loaded automatically at runtime—no namespace required.

For user-defined helpers, see User Defined Functions.


Namespaced Functions

Luminova also provides namespaced helper functions for more advanced operations.

These functions are still globally accessible, but must be imported using use function before use.

Example:

use function Luminova\Funcs\root;

root('app.name');

For a full list, see Namespaced Global Functions.


Usage Rules

Global functions:

  • Do not use a namespace
  • Can be called directly from anywhere

Correct:

env('app.name');

Incorrect:

Luminova\Funcs\env('app.name'); // function does not exist

Key Difference:

  • Global functions → no namespace, direct access
  • Namespaced functions → require use function import

Environment Functions

env

Retrieve an environment variable value.

Retrieve environment variable values from the registered environment. The value is automatically normalized to its corresponding PHP type, including booleans, numbers, null, and arrays. Returns $default if the (trimmed) $name is empty or the key is not found.

function env(string $name, mixed $default = null): mixed

Parameters:

ParameterTypeDescription
$namestringThe environment variable name.
$defaultmixedThe value to return when the key is not found.

Return Value:

mixed — The resolved environment value, or $default if not found.

See Also: Luminova\Config\Env::get(), Luminova\Config\Env::value() to retrieve the raw value.

Example:

$appName = env('app.name', 'Luminova'); // returns 'Luminova' if key is missing

If a variable is stored as foo = [1, 2, 4] in .env, env('foo') will return it as an array.

See Also: Environment Variables


setenv

Sets an environment variable, optionally saving it to the .env file.

function setenv(string $name, array|string|float|bool|int|null $value, bool $persist = false): bool

Parameters:

ParameterTypeDescription
$namestringThe environment variable name/key.
$valuearray|string|float|bool|int|nullThe value to set for the environment variable.
$persistboolWhether to store/update the variable in the .env file (default: false).

Return Value:

bool — Returns true on success, false on failure (including when $name is empty after trimming).

See Also: Luminova\Config\Env::set() for more details on how the variable is stored and persisted.

Examples:

// Set for current runtime only
setenv('FOO_KEY', 'foo value');

// Set and persist to .env file
setenv('FOO_KEY', 'foo value', true);

// Add/update disabled entry (prefixed with ;)
setenv(';FOO_KEY', 'foo value', true);

By default, setenv only affects the current runtime.To permanently save the value in your .env file, pass true as the third argument.A more efficient way is to use the NovaKit Command:

php novakit env:add --key="my_new_key" --value="my key value"

General Utility Functions

tap

Execute a callback with the given value and return the original value.

This is useful when an object needs to be modified or inspected before being returned, without changing the value returned by the operation.

function tap(mixed $value, callable $callback): mixed

Parameters:

ParameterTypeDescription
$valuemixedThe value to pass to the callback.
$callbackcallableThe callback to execute, receives $value, return is ignored.

Return Value:

mixed — Returns the original $value, unchanged.

Example:

$user = tap(new User(100), function (User $user): void {
    $user->setName('Peter');
    $user->setActive(true);
});

uwait

Pause execution for a specified duration with microsecond precision.

Supports fractional seconds by converting the duration to microseconds before calling PHP's usleep(). If the resolved duration is 0 or less, the function returns immediately without sleeping.

function uwait(float|int $seconds, float|int|null $max = null): void

Parameters:

ParameterTypeDescription
$secondsfloat|intDuration to wait in seconds. Supports fractions, e.g. 0.5 for 500 milliseconds.
$maxfloat|int|nullMaximum wait duration in seconds, or null for no limit (default: null).

Return Value:

void

Example:

uwait(1);     // 1 second
uwait(2.4);   // 2 seconds (rounded)
uwait(2.6);   // 3 seconds (rounded)

uwait(0.5);    // 500 milliseconds
uwait(0.25);   // 250 milliseconds
uwait(1.75);   // 1.75 seconds

uwait(10_000);    // 10,000 seconds
uwait(0.01);      // 10 milliseconds
uwait(0.00001);   // 10 microseconds

// Cap a large duration to a maximum of 5 seconds
uwait(30, 5);

to_numeric

Convert a numeric string into its appropriate numeric type.

This method detects whether the given string represents a floating-point number or an integer.If the string contains a decimal point (.) or scientific notation (e), it is converted to a float; otherwise, it is converted to an int.

function to_numeric(string $value, bool $toLowercase = false): float|int

Parameters:

ParameterTypeDescription
$valuestringThe numeric string to convert.
$toLowercaseboolWhether to convert the string to lowercase before processing.
Useful when checking for scientific notation (e.g., 1E3).

Return Value:

float|int — Returns the numeric value as int or float depending on the input. Returns 0 if the (trimmed) string is empty or not numeric.

Example:

to_numeric('42');        // int(42)
to_numeric('42.5');      // float(42.5)
to_numeric('1E3', true); // float(1000)
to_numeric('abc');       // int(0)

Debugging Functions

dump

Dumps one or more values for debugging.

Uses var_dump() to output each value. Execution continues after the values are dumped. In non-CLI (HTTP) contexts, output is wrapped in an output buffer and flushed after all values are dumped; in CLI, values are dumped directly.

function dump(mixed ...$vars): void

Parameters:

ParameterTypeDescription
...$varsmixedValues to dump.

Return Value:

void

See Also: dd() — Dump Die, ddd() — Discard Dump Die

Example:

dump($user, $request->all());

dd

Dumps one or more values for debugging and terminates execution.

Uses the framework's debugger tracer (Luminova\Debugger\Tracer) when available; otherwise, falls back to dump(). Always terminates the script with exit status 1.

function dd(mixed ...$vars): never

Parameters:

ParameterTypeDescription
...$varsmixedValues to dump.

Return Value:

never — Always terminates execution with exit status 1.

See Also: ddd() — Discard Dump Die, dump() — Dump

Example:

dd($user, $errors);

ddd

Discards all active output buffers, dumps one or more values, and terminates execution.

Unlike dd(), this function removes all previously buffered output before displaying the debug output.

function ddd(mixed ...$vars): never

Parameters:

ParameterTypeDescription
...$varsmixedValues to dump.

Return Value:

never — Always terminates execution with exit status 1.

See Also: dd() — Dump Die, dump() — Dump

Example:

ddd($user, $errors);

Path Functions

root_dir

Get the application root directory.

Searches upward from the current directory for a .env or .dev.env file and returns the directory containing it. Falls back to the parent directory when no environment file is found. The resolved path is cached statically after the first call.

function root_dir(): string

Return Value:

string — The application root directory with a trailing separator.

Example:

$root = root_dir(); // e.g. '/var/www/my-app/'

Compatibility Polyfills

The following functions are conditionally declared with function_exists() guards. They provide the same behavior as their native PHP counterparts on installations running a PHP version that does not yet include them, and are otherwise skipped in favor of the native implementation.

json_validate

Check if the input is a valid JSON string.

Polyfill for PHP's native json_validate() function. Returns false immediately for any non-string input, without attempting to decode it.

function json_validate(mixed $input, int $depth = 512, int $flags = 0): bool

Parameters:

ParameterTypeDescription
$inputmixedThe input to check.
$depthintMaximum nesting depth of the structure being decoded (default: 512).
$flagsintOptional json_decode() flags (default: 0).

Return Value:

bool — Returns true if the input is a valid JSON string; false otherwise (including when $input is not a string).

Example:

json_validate('{"foo":"bar"}');  // true
json_validate('{invalid}');      // false
json_validate(['foo' => 'bar']); // false (not a string)

array_is_list

Check if array is list.

Polyfill for PHP's native array_is_list() function.

function array_is_list(array $array): bool

Parameters:

ParameterTypeDescription
$arrayarrayThe array to check.

Return Value:

bool — Returns true if array is sequential (zero-indexed, in order), false otherwise.

Example:

array_is_list([1, 2, 3]);            // true
array_is_list([1 => 'a', 0 => 'b']); // false
array_is_list(['a' => 1]);           // false

array_first

Get the first element of an array.

Returns null if the array is empty. Works for both indexed and associative arrays.

function array_first(array $array): mixed

Parameters:

ParameterTypeDescription
$arrayarrayThe array to get the first element from.

Return Value:

mixed|null — Returns the first element of the array, or null if empty.

Example:

array_first([10, 20, 30]);          // 10
array_first(['b' => 2, 'a' => 1]);  // 2
array_first([]);                    // null

array_last

Get the last element of an array.

Returns null if the array is empty. Works for both indexed and associative arrays.

function array_last(array $array): mixed

Parameters:

ParameterTypeDescription
$arrayarrayThe array to get the last element from.

Return Value:

mixed|null — Returns the last element of the array, or null if empty.

Example:

array_last([10, 20, 30]);          // 30
array_last(['b' => 2, 'a' => 1]);  // 1
array_last([]);                    // null