PHP Luminova: Global Utility & Compatibility Functions
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 existKey Difference:
- Global functions → no namespace, direct access
- Namespaced functions → require
use functionimport
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): mixedParameters:
| Parameter | Type | Description |
|---|---|---|
$name | string | The environment variable name. |
$default | mixed | The 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 missingIf 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): boolParameters:
| Parameter | Type | Description |
|---|---|---|
$name | string | The environment variable name/key. |
$value | array|string|float|bool|int|null | The value to set for the environment variable. |
$persist | bool | Whether 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,
setenvonly affects the current runtime.To permanently save the value in your.envfile, passtrueas 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): mixedParameters:
| Parameter | Type | Description |
|---|---|---|
$value | mixed | The value to pass to the callback. |
$callback | callable | The 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): voidParameters:
| Parameter | Type | Description |
|---|---|---|
$seconds | float|int | Duration to wait in seconds. Supports fractions, e.g. 0.5 for 500 milliseconds. |
$max | float|int|null | Maximum 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|intParameters:
| Parameter | Type | Description |
|---|---|---|
$value | string | The numeric string to convert. |
$toLowercase | bool | Whether 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): voidParameters:
| Parameter | Type | Description |
|---|---|---|
...$vars | mixed | Values 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): neverParameters:
| Parameter | Type | Description |
|---|---|---|
...$vars | mixed | Values 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): neverParameters:
| Parameter | Type | Description |
|---|---|---|
...$vars | mixed | Values 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(): stringReturn 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): boolParameters:
| Parameter | Type | Description |
|---|---|---|
$input | mixed | The input to check. |
$depth | int | Maximum nesting depth of the structure being decoded (default: 512). |
$flags | int | Optional 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): boolParameters:
| Parameter | Type | Description |
|---|---|---|
$array | array | The 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]); // falsearray_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): mixedParameters:
| Parameter | Type | Description |
|---|---|---|
$array | array | The 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([]); // nullarray_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): mixedParameters:
| Parameter | Type | Description |
|---|---|---|
$array | array | The 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