PHP Luminova: User-Defined Global Helper Functions & Constants
User-defined global helpers let developers add reusable functions and constants to extend application behavior and reduce repetitive code.
User-Defined Helpers are procedural functions and constants defined by the developer in /app/Utils/Global.php. The file is loaded during the bootstrap process and is called during the framework's execution, making these helpers available throughout the application.
In addition to defining your own helpers, this file can also be used to overwrite core procedural functions, replacing the framework's default implementation with your own.
They are ideal for small, reusable logic that does not belong to a class.
Note:
The file should begins with
declare(strict_types=1);. It is recommended to keep this declaration in place to ensure strict typing is consistently enforced for your global helpers.
Enabling Custom Global Functions
For safety, custom global functions are disabled by default.
To enable them, add the following to your .env file:
feature.app.dev.functions = enableOnce enabled, define your functions and constants inside:
/app/Utils/Global.phpNote: This file is automatically loaded by the framework.The filename or location cannot be changed (strictly
Global.php)andenv(feature.app.dev.functions = enable)must be enabled to autoload it.
Global Check
You can check whether User Defined Global were loaded by testing the USER_DEFINED_GLOBAL_HELPER constant.
if (defined('USER_DEFINED_GLOBAL_HELPER')) {
echo 'Custom global helpers are loaded';
}If the constant is not defined
Something is wrong. Check the basics first:
- Make sure
feature.app.dev.functionsis enabled in your.envfile. - Confirm
/app/Utils/Global.phpfile exists and is in the correct location: - Check the error logs for syntax errors or duplicate function/constant definitions.
Tip:
Always guard critical logic with
defined()checks if your application depends on them.Alternatively, use
Luminova\Funcs\func()to call your function. It performs proper checks and will throw a runtime error ifthe function does not exist or is disabled—fail fast, fail loud, no silent bugs.
Using the Same Name as Core Procedural Functions
/app/Utils/Global.php can be used to define a custom helper with the same name as a core Luminova helper when your application requires different behavior.
This does not override or replace the core function. Both functions remain available under their respective namespaces, and you must explicitly call or import your application function.
Custom Behavior
// /app/Utils/Global.php
declare(strict_types=1);
namespace App\Utils\Global;
function root(string $path, string $filename): string
{
return $path . DIRECTORY_SEPARATOR . $filename;
}Usages:
Call your application helper explicitly:
echo App\Utils\Global\root('path/to/', 'file.txt');Instead of:
echo Luminova\Funcs\root('path/to/', 'file.txt');You can also import the function:
use function App\Utils\Global\root;
echo root('path/to/', 'file.txt');Note: Defining a helper with the same name does not affect Luminova's internal calls to
root(). It only allows your application to define and use a custom helper with the same function name.
Important Guidelines
To avoid conflicts and unexpected behavior:
- Always check if a function or constant already exists before defining it.
- Prefer prefixes or namespaces to reduce naming collisions.
- Keep global helpers small and simple — avoid complex logic.
Global scope is powerful. Use it carefully.
Examples
Simple Global Helpers
You can use Luminova\Funcs\function_exists_cache instead of function_exists to avoid repeated existence checks.
With Safety Checks:
// /app/Utils/Global.php
declare(strict_types=1);
// Define a constant safely
defined('APP_THEME') || define('APP_THEME', 'dark');
// Define a function safely
if (!function_exists('addition')) {
function addition(int $x, int $y): int
{
return $x + $y;
}
}Usage (anywhere in your application):
addition(1, 2); // 3
echo APP_THEME; // darkNote: Always wrap your override in a
function_exists()check. This avoids a fatal "cannot redeclare function" error if the same name is ever defined elsewhere in the request lifecycle.
Using a Custom Namespace
Namespacing provides the cleanest and safest approach by reducing naming conflicts and improve readability (Recommended).
// /app/Utils/Global.php
namespace App\Utils\Global;
// Namespaced constant
const APP_THEME = 'bar';
// Namespaced function
function addition(int $x, int $y): int
{
return $x + $y;
}Usage:
use const App\Utils\Global\APP_THEME;
use function App\Utils\Global\addition;
addition(1, 2); // 3
echo APP_THEME; // barThis apache reduce the need for calling
function_exists()checks for each functions.