PHP Luminova: Environment Configuration Variables
The .env file centralizes configuration for Luminova, including custom and default variables, formatting rules, and controlling application behavior across development and production environments.
The .ENV file stores configuration settings that control how your application behaves. It is used by both core Luminova modules and application modules to manage application runtime behavior.
It allows your app to run differently in development and production environments without changing the code.
Variable Naming:
- The Core variables use lowercase names with dot notation (e.g.,
app.name) and cannot be renamed.- Custom variables can use any naming style, as long as core variable names remain unchanged.
Environment Configuration Files
Luminova supports multiple environment files for different environments:
- Production: strictly use
.env - Development: Uses
.dev.envif available, otherwise default to.env
During application boot, if in development mode, Luminova will look for .dev.env first. If not found, it falls back to .env.
Luminova calls Env::register() automatically during application bootstrap to parse the active environment file and load its values into runtime memory. In non-local environments, parsed values are cached to writeable/.env-cache.php and reused on subsequent requests to avoid re-parsing. You do not need to call Env::register() manually.
Note:
Place
.envor.dev.envin the project root (e.g.,/) not in the public folder (/public).Missing files will cause the framework to fail booting.
devConfigExists
Determine whether the development environment file (.dev.env) exists in the project root.
use Luminova\Config\Env;
if (Env::devConfigExists()) {
// .dev.env file exists
}file
Retrieve the active environment configuration file.
The development environment file is preferred in local mode when available. Otherwise, the production environment file is used.
use Luminova\Config\Env;
// Get the active env file path, creating it if missing
$path = Env::file();Returns
nullwhen neither.envnor.dev.envexists.
Constants
Env exposes the following file-path constants, all resolved relative to APP_ROOT:
| Constant | Value | Description |
|---|---|---|
Env::PRODUCTION_FILE | APP_ROOT . '.env' | Path to the production environment file. |
Env::DEVELOPMENT_FILE | APP_ROOT . '.dev.env' | Path to the development environment file. |
Env::CACHE_FILE | APP_ROOT . 'writeable/.env-cache.php' | Path to the generated environment cache file used in non-local environments. |
Managing Environment Variables
Luminova provides methods to read, set, and persist environment variables.
Setting Variables
Temporary (runtime only):
Sets the value only for the current script execution. Does not update the .env file.
use Luminova\Config\Env;
Env::set('APP_THEME', 'dark');
// Global helper function
setenv('APP_THEME', 'dark');Permanent:
Updates or creates the variable in the runtime .env file.
use Luminova\Config\Env;
Env::set('APP_THEME', 'dark', persist: true);
// Global helper function
setenv('APP_THEME', 'dark', persist: true);Array values passed to
set()must be simple (list) arrays; associative arrays are rejected and the call returnsfalse. Prefixing the key with;stores it as a disabled/commented entry when$persististrue.
Reading Variables
Get a value from the environment:
use Luminova\Config\Env;
$value = Env::get('app.name');
// Using global helper
$value = env('app.name');Get a value with a fallback:
Returns the fallback if the key is missing.
use Luminova\Config\Env;
$value = Env::get('APP_THEME', 'dark');
// Using global helper
$value = env('APP_THEME', 'dark');Helper Methods
remove
Remove an environment variable from runtime memory, the environment file, and the production environment cache.
By default, the variable is removed from all three locations. When $cacheOnly is true, the variable is removed only from runtime memory and the production environment cache, leaving the environment file unchanged.
use Luminova\Config\Env;
// Remove from the environment file, runtime, and cache
Env::remove('APP_THEME');
// Remove from runtime and cache while preserving the environment file
Env::remove('APP_THEME', cacheOnly: true);disable
Remove an environment variable from $_ENV, $_SERVER, and the process environment (runtime memory only). The environment file is left untouched.
use Luminova\Config\Env;
Env::disable('APP_THEME');comment
Comment out an environment variable in the environment file instead of removing it. The variable's current value is preserved and the entry is prefixed with ;. It is also removed from the current runtime.
use Luminova\Config\Env;
// Comment out in the env file and remove from runtime
Env::comment('APP_THEME');has
Check whether a variable exists in $_SERVER, $_ENV, or getenv(). A key is considered present even when its value is null, false, or otherwise falsy.
use Luminova\Config\Env;
Env::has('APP_THEME');raw
Retrieve an environment value without type normalization.
Values are checked in the following order:
$_SERVER$_ENVgetenv()
use Luminova\Config\Env;
$exists = false;
$theme = Env::raw('APP_THEME', $exists);
if($exists){
echo $theme;
}The
$existsparameter distinguishes a missing key from a value that is actuallyfalse,null, or otherwise falsy.
add
Add or update an environment variable in runtime memory only ($_SERVER, getenv(), and $_ENV when running locally). Unlike set(), this does not persist the value to the environment file.
Comment-prefixed keys (; or #) are not supported by add() directly; use set() or comment() to disable an entry.
use Luminova\Config\Env;
Env::add('APP_THEME', 'dark');Use
add()directly only when you want to update the runtime value without going throughset()'s validation and persistence logic.
cache
Add variables to environment configuration cache file.
use Luminova\Config\Env;
Env::cache([
'APP_THEME' => 'dark',
'APP_AUTO_THEME' => false
]);Cached env values improve performance in production by avoiding repeated parsing of the original env file. The array must be associative (keyed by variable name); passing a list array returns
false.
write
Write, update or comment an environment entry directly in the env file.
use Luminova\Config\Env;
Env::write('APP_THEME', 'dark');
Env::write(';APP_THEME', 'dark'); // CommentUnlike
set(),write()only modifies the physical env file and does not update runtime environment values.
deleteCache
Delete the environment variable cache.
This invalidates the entire cached environment file.
use Luminova\Config\Env;
Env::deleteCache();The cache will be rebuilt with the updated environment variables when the application initializes again.
isCached
Determine whether cached environment data is available. Checks both the in-memory cache and the physical cache file.
use Luminova\Config\Env;
if (Env::isCached()) {
// cache available
}Managing ENV with Novakit CLI
NovaKit offers commands to safely manage environment variables:
Add or update a variable:
php novakit env:add --key=APP_THEME --value="dark"Remove a variable:
php novakit env:remove --key=APP_THEMESet variables by context:
php novakit env:setup --target=telegramUsing Novakit avoids manually editing the
.envfile and ensures safe updates.
Variable Types & Formatting
Environment values can be:
int,float,bool,array<int,string|int|float|bool|null>,string, ornull- Luminova automatically converts values into the correct PHP type when calling
get().
Boolean Values
Boolean can be expressed as:
trueorenable→ truefalseordisable→ false
Example (.env):
# /.env
FEATURE_X=true # enable
FEATURE_Y=disable # falseAccess in PHP:
$featureX = env('FEATURE_X'); // true
$featureY = env('FEATURE_Y'); // falseNull Values
Use null when the key exists but has no value.
Example (.env):
# /.env
OPTIONAL_VALUE=nullAccess in PHP:
$value = env('OPTIONAL_VALUE'); // nullDefault values will override
nullif provided inenv().
Blank Values
Use blank or '' when the key should exist but return an empty string.
Example (.env):
# /.env
EMPTY_FIELD=''
; EMPTY_FIELD=blankAccess in PHP:
$value = env('EMPTY_FIELD'); // ''Array Values
Store multiple values under a single key:
# /.env
MY_LIST=['a','b','c']
NUMBERS=[1,2,3]Access in PHP:
$list = env('MY_LIST'); // ['a', 'b', 'c']
$nums = env('NUMBERS'); // [1, 2, 3]Notes:
- Only simple lists are supported.
- Associative arrays are not supported.
- Nested lists (e.g.
[1,2,[true,false]]) are supported and resolved recursively.- For complex structures, use JSON or config files.
Variable Interpolation
Luminova supports referencing other environment variables using ${}.
Example (.env):
# /.env
app.name = Example
app.version = 1.2
app.description = This is my ${app.name} app using version ${app.version}Access in PHP:
echo env('app.description');
// "This is my Example app using version 1.2"Helps avoid duplication and keeps configuration DRY.
Core Variables
Application Name
app.name (string)Specifies the name of your application. Used for identification, display, and internal reference.
Example:
# /.env
app.name = Example AppApplication Hostname
app.hostname (string)Defines the hostname where your application is served. Required for network-related configuration such as generating URLs.
Example:
# /.env
app.hostname=example.comApplication Timezone
app.timezone (string)Sets the timezone used by the application. This affects timestamps, logs, scheduled tasks, and all date/time functions.
Example:
# /.env
app.timezone=Asia/Kuala_LumpurApplication Locale
app.locale (string)Specifies the default locale. Controls language settings, formatting rules, numbers, dates, and other locale-driven output.
Example:
# /.env
app.locale=enHTML Output Charset
app.charset (string)Defines the output charset for HTML templates, HTTP headers and other output layers. Important for correct text rendering.
Example:
# /.env
app.charset=utf-8Multibyte Encoding
app.mb.encoding (string)
Set the internal encoding for multibyte string functions (mb_*) like mb_strlen(), mb_substr(), mb_strpos(), etc., ensuring PHP uses the correct encoding instead of guessing.
Example:
# /.env
app.mb.encoding=UTF-8Application Version
app.version (string)Indicates the current version of the application. Used internally when generating static page caches and other internal reference.
Example:
# /.env
app.version=1.0.0Useful for debugging, updates, asset tagging, and compatibility tracking.
Application File Version
app.file.version (string)Specifies the version for static files (e.g, assets). Often used for cache-busting assets without changing the main application version.
Example:
# /.env
app.file.version=1.0.0Application Encryption Key
app.key (string)The main encryption key used by the framework for hashing, encryption, and securing sensitive data. Must be a strong, random string.
Example:
# /.env
app.key=your-secret-keyNote:The application encryption key is created automatically when Luminova is installed for the first time.You can change this key at any time by running
php novakit generate:keyor by setting the key manually.
Application Environment Mode
app.environment.mode (string)Specifies the current runtime environment of the application. Determines how the application behaves, such as error reporting, caching, and debugging. Supported values:
production– Application is live and serving users.development– Application is in development mode, usually on localhost.staging– Application in pre-production mode (used for testing changes before going live)
Example:
# /.env
app.environment.mode=developmentAPI Prefix
app.api.prefix (string) (default: api)
Defines the URI prefix for all application API endpoints.
Luminova uses this prefix to identify and validate API requests.Methods like Luminova\Routing\Router::isApiPrefix() check this value to distinguish between API calls and normal HTTP requests.
Example:
For an API endpoint like https://example.com/api/user/{id}, the prefix is api.
# /.env
app.api.prefix = apiTreat AJAX Requests as API
app.validate.ajax.asapi (bool)
Define if AJAX request should be treated as API request.
- When set to
true, AJAX (XMLHttpRequest) requests are treated as API endpoints. - When set to
false– AJAX requests are treated like normal web requests unless explicitly marked as API.
Example:
# /.env
app.validate.ajax.asapi = falseThis affects the behavior of Luminova\Routing\Router::isApiPrefix() and related routing or response logic.
Disable Powered-By Header
x.powered (bool)
Enables or disables the X-Powered-By signature response header.
true– the header is sent (default).false– the header is suppressed.
Example:
# /.env
x.powered = falseCLI
CLI Mode
cli.environment.mode (string)Defines the mode of the CLI environment, which affects how commands are executed and logged based on the environment. Typical values are production, development, or testing.
Example:
# /.env
cli.environment.mode=developmentCLI Exception Debugging
throw.cli.exceptions (bool)Allows CLI commands to throw exceptions.
When disabled, uncaught exceptions are converted into a simple CLI-friendly error message.
- true – raw exceptions are thrown in CLI, useful during debugging
- false – exceptions are caught and replaced with a custom CLI error message
Example:
# /.env
throw.cli.exceptions=truePage Caching
default.cache.control (string)Configures cache control directives for HTTP headers. This determines how browsers and intermediate caches handle your content. Example values:
Example:
# /.env
default.cache.control=no-store, max-age=0, no-cacheno-store- do not cachemax-age=0- cached content expires immediatelyno-store, max-age=0, no-cache- combination of directives for strict caching control
Template View Cacheable
page.caching (bool)Enables or disables static page caching. When enabled, rendered template are stored and served directly, improving performance by reducing repeated processing and database queries.
Example:
# /.env
page.caching=trueStatic Cache Expiration
page.cache.expiry (int)Sets the default expiration time for static page caches.
Specifies how long cached pages remain valid, in seconds. For example, 3600 means pages are cached for one hour before they are refreshed or invalidated.
Example:
# /.env
page.cache.expiry=3600Note:
Cache expiration can also be overridden before rendering a template in controllers (
$this->tpl->cache(...)) method.
Static Cache Types
page.caching.statics (string)Specifies the template content types that should be served as cached static pages. Multiple types are separated by a pipe (|).
Example:
Setting: html|json ensures that static caching applies to both .html and .json contents.
# /.env
page.caching.statics=html|jsonBy setting this, URLs like http://example.com/blog can also be accessed as http://example.com/blog.html, ensuring faster responses compared to non-static URLs. This works because, with the extension appended to the view URI, Luminova checks the cache early in the boot process and serves the content directly, skipping routing and other modules.
Regular caching is passed through controllers, then handled by the Luminova\Template\View class, giving you control over when and how cached content is served.
Cache Immutable
page.caching.immutable (bool)Determines whether the cached page content is immutable.
true- cached content will not change and can be safely reused.false- content may update dynamically.
Examples:
# /.env
page.caching.immutable=trueNote:
The immutable cache option can be overridden before rendering a template in controllers (
$this->tpl->cache()) for a specific template, or globally viaonCreate()method.
Last Cached App Versions
page.cache.app.versions (array)An array of previous application versions considered when retrieving cached content.
Luminova’s static page cache stores cached pages in directories based on the current application version (env(app.version)). When the app version changes, the cache directory name changes accordingly. To allow Luminova to serve content from past versions, list all previous versions in this array.
Example:
# /.env
page.cache.app.versions=[1.0.2,3.2.6]Note:
The cache system always checks the current version first, then
env(page.cache.latest.content),and finally past versions.This approach is suitable only when URLs change between versions(e.g., versioned documentation where content is tied to a specific release).
Cache Latest URIs Prexies
page.cache.latest.content (array)An array of URI patterns or prefixes that should always use the latest cached content for the current application version.
Before caching, Luminova checks if the content already exists. If past versions are listed in env(page.cache.app.versions), the cache might exist for an older version but not the in latest yet. By defining URI patterns here, you ensure that critical pages always serve the latest content instead of older cached versions.
Example:
When a URI matches one of these patterns, caches from older versions are ignored. This ensures that frequently updated or critical pages—like landing pages or dashboards—always display fresh content.
# /.env
page.cache.latest.content=[/,users]Cache URI Queries
page.cache.query.params (bool)
Enable or disable, including the request's URI query string when generating cache keys.
true- different query strings produce different cache entries (useful if responses vary by query params).false- query parameters are ignored to increase cache hit rate when params don't affect response.
Example:
# /.env
page.cache.query.params=trueRecommended
false:Unless your responses change based on query parameters (e.g., pagination, filters).
Preferred Cache Driver
system.cache.driver (string) (default: filecache)
Specifies the preferred PSR-16 compatible cache driver implementation used across the framework's internal caching (page caching, and as a fallback for other components).
- Available drivers:
filecache,memcached,redis
Example:
# /.env
system.cache.driver=filecacheSystem Cache Persistent ID
system.cache.persistent.id (string)
Default cache persistent ID used as a fallback when no memcached.persistent.id or redis.persistent.id value is provided.
Example:
# /.env
system.cache.persistent.id=defaultCache Serializer
system.cache.encoding.serializer (int)
Controls how cached data is serialized before being stored.
0– auto (igbinaryif available, otherwiseserialize)1–serialize(PHP native serialization)2–igbinary(binary serializer, faster and smaller if the extension is available)3–json(portable, human-readable, but loses PHP type fidelity)4– none (allow the cache server to handle serialization)
Example:
# /.env
system.cache.encoding.serializer=0Cache Base64 Encoding
system.cache.encoding.base64 (bool)
Enables or disables base64 encoding for stored cache payloads. Useful for binary-safe storage (e.g., file systems, databases, text-only stores).
Example:
# /.env
system.cache.encoding.base64=falseMemcached
Memcached Persistent ID
memcached.persistent.id (string|null)Specifies the persistent connection ID for the Memcached server.
- If set to
null, a default ID is used. - Persistent IDs allow reusing the same connection across multiple requests, improving performance.
Example:
# /.env
memcached.persistent.id=my_app_memcacheMemcached Key Prefix
memcached.key.prefix (string|null)An optional prefix added to all cache keys.
- Helps avoid key collisions between different applications or environments.
- If set to
null, no prefix is applied.
Example:
# /.env
memcached.key.prefix=my_app_Memcached Hostname
memcached.host (string)The hostname or IP address of the Memcached server.
- Default:
localhost(server running on the same machine).
Example:
# /.env
memcached.host=127.0.0.1Memcached Port
memcached.port (int)The port number on which the Memcached server listens.
- Default:
11211, the standard Memcached port.
Example:
# /.env
memcached.port=11211Memcached Server
memcached.server.weight (int)Defines the weight of the Memcached server, affecting how cache requests are distributed among multiple servers.
- Higher weight → server handles more requests.
- Default:
0(weight not explicitly set).
Example:
# /.env
memcached.server.weight=1Optimization
HTML Minification
output.minify.html (bool)Minifies HTML before sending it to the client, removing unnecessary comments and whitespace to reduce file size and improve page load times.
Example:
# /.env
output.minify.html=trueNote:HTML content minification can also be configured before rendering a template in controllers (
$this->tpl->htmlMinification()) for a specific template, or globally viaonCreate(...)method.
Minification Preserved Tags
output.minify.preserve.tags (array)Specifies which HTML tags should be preserved (left untouched) during HTML minification.
Supported tags:
script–<script>style–<style>textarea–<textarea>math–<math>svg–<svg>pre–<pre>without a<code>childcode–<pre><code>pairs, with<code>as a child of<pre>
Example:
# /.env
output.minify.preserve.tags=['pre', 'code', 'textarea']Code Block Action Buttons
output.minify.codeblock.buttons (array)Adds action buttons to rendered code blocks.
Supported actions:
copy– Add copy button.ai– Add AI button.run– Add run button.
Example:
# /.env
output.minify.codeblock.buttons=['copy', 'ai', 'run']Script Execution Limit
script.execution.limit (int)Specifies the maximum execution time for scripts in seconds. This prevents scripts from running indefinitely and affecting server performance. Set to 0 to disable the time limit.
Example:
# /.env
script.execution.limit=30Script Abort Connection
script.ignore.abort (bool)Determines whether a script continues running even if the client disconnects or aborts the request. Useful for long-running processes where the task should finish regardless of the user connection.
Example:
# /.env
script.ignore.abort=trueEnable Output Compression
output.compression.enable (bool)
Enables or disables automatic HTTP response compression.
Example:
# /.env
output.compression.enable=trueOutput Compression Handler
output.compression.handler (string|null)Defines a custom PHP output buffer compression handler for script output.
- Example:
ob_gzhandlercompresses data sent to clients. - Leave empty when using manual compression via
output.compression.encoding.
Example:
# /.env
output.compression.handler=ob_gzhandlerMinimum Compression Length
output.compression.min.length (int)The minimum response body size, in bytes, before compression is attempted. Responses smaller than this value are sent uncompressed.
Example:
# /.env
output.compression.min.length=1024Compression Encoding Method
output.compression.encoding (string)Specifies the compression method for output.
- Supported:
auto,zstd,br,gzip,deflate,compress
Example:
# /.env
output.compression.encoding=gzipOutput Compression Level
output.compression.level (int)Sets the compression level. Higher levels compress content more but may increase CPU usage and processing time.
zstd: between1to22br: between0to11gzip/deflate/compress: between-1to9
Example:
# /.env
output.compression.level=6Login Session
Strict Login IP
session.strict.ip (bool)Enforces strict session login handling based on the user's IP address.If the user's IP changes during an active login session, the session is invalidated, and the user must log in again. This improves security by binding sessions to a specific IP.
Example:
# /.env
session.strict.ip=trueDebugging
Maintenance Mode
app.maintenance.mode (bool)Enables or disables maintenance mode. When enabled, users may see a maintenance page while internal tasks continue running.
Example:
# /.env
app.maintenance.mode=trueMaintenance Page:To customize the default maintenance page, edit the file at
/app/Errors/Defaults/maintenance.php.
Maintenance Retry Seconds
app.maintenance.retry (int)Number of seconds a client should wait before retrying access during maintenance. Default: 3600.
Example:
# /.env
app.maintenance.retry=3600Show Debug Tracing
debug.show.tracer (bool)Controls whether a debug trace is displayed. A debug trace shows detailed information about the execution flow, which helps track down issues.
Example:
# /.env
debug.show.tracer=trueNote:On production exception tracing arguments are ignored by default.
Debug Performance Tips
debug.alert.performance.tips (bool)Enables production log warnings when critical performance features are missing or not enabled.
Example:
# /.env
debug.alert.performance.tips=trueNote:Enabling this may produce large log entries. If these warnings are no longer needed in production, you can disable this setting.
Error Display Handler
debug.display.errors (bool)Enables or disables the display of error messages on the screen.
true- Errors are visible, useful for development.false- Errors are hidden, recommended for production, in development custom error details is shown.
Example:
# /.env
debug.display.errors=falsePerformance Monitoring
debug.show.performance.profiling (bool)Displays performance profiling information at the bottom of each page or after a CLI routable command execution. Includes execution time, memory usage, and files loaded.
Only visible in development mode to help identify performance bottlenecks.
Example:
# /.env
debug.show.performance.profiling=trueProduction Performance Monitoring
production.show.performance.profiling (bool)Enables performance profiling while the application is running in production. This acts as an explicit opt-in gate on top of debug.show.performance.profiling: profiling only runs in production when both values are enabled.
Example:
# /.env
production.show.performance.profiling=falseNote:Leave this disabled in production unless you are actively diagnosing a performance issue, since profiling adds overhead to every request.
- In development or staging, only
debug.show.performance.profilingneeds to betrue. - In production, both
debug.show.performance.profilingandproduction.show.performance.profilingmust betrue.
API Performance Profiling
debug.api.performance.profiling (bool)Enables performance profiling for API requests. Works together with debug.show.performance.profiling. When enabled, the performance metrics of the last API request are logged to /writeable/logs/metric.log for analysis.
Example:
# /.env
debug.api.performance.profiling=trueLogging System
Log Message Template Format
logger.log.format (string)
This allows you to fully control how log entries are written using a log message template.The template uses placeholders wrapped in {} which are replaced at runtime.
Example:
# /.env
logger.log.format = '[{time:Y-m-d H:i:s.uP}] {level} {name} {message} {context}'Available Placeholders:
| Placeholder | Description |
|---|---|
{level} | Log level name (INFO, ERROR, DEBUG, etc.). |
{name} | Logger channel name. |
{time} | Current timestamp. Supports date format: {time:Y-m-d H:i:s} |
{message} | Log message text. |
{context} | Context array rendered as string or JSON. |
{ipaddress} | Client IP address (HTTP only). |
{referer} | HTTP referer header if available. |
{useragent} | Client user agent string. |
Example Output:
[2026-01-17 23:41:18.382+08:00] ERROR AppLogger Database connection failed {"host":"127.0.0.1"}Log Backup
logger.create.backup (bool)Determines whether a backup of the log file should be created when the logger.max.size limit is reached.
true- automatically create a backup and clear the current log filefalse- clear the log file without creating a backup
Example:
# /.env
logger.create.backup=trueMaximum Log Size
logger.max.size (int)Specifies the maximum size (in bytes) for each log level. Example: 10485760 = 10 MB.
When this limit is reached:
- If
logger.create.backupistrue, a backup is created. - If
false, the log file is cleared.
- If
Example:
# /.env
logger.max.size=10485760Remote Logging
logger.remote.logs (string|null)Defines the endpoint URL for sending POST requests with error logs to a remote server in production.
- Set to a URL to enable remote logging (e.g
https://hooks.slack.com/your-key). - Leave
nullor unset to disable remote logging.
Example:
# /.env
logger.remote.logs=https://example.com/log-endpointRemote Log Signing Key
logger.remote.sign.key (string|null)Shared encryption key used to sign requests sent to the remote logging endpoint, allowing the receiving server to verify their authenticity.
- Format:
key:secret
Example:
# /.env
logger.remote.sign.key=key:secretInclude Context in Remote Logs
logger.remote.send.context (bool)Determines whether context data is included in remote log messages sent to Telegram or Slack.
Example:
# /.env
logger.remote.send.context=falseEmail Logging
logger.mail.logs (string|null)Specifies an email address for sending error logs.
- When set, the logger will email errors automatically.
- Leave
nullor unset to disable email logging.
Example:
# /.env
[email protected]Telegram Bot Logging Token
logger.telegram.bot.token (string|null)The Telegram bot token used for API authentication.
- Obtain from BotFather.
- Required for sending Telegram notifications.
- Leave
nullor unset to disable Telegram features.
Example:
# /.env
logger.telegram.bot.token=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11Telegram Bot Chat-ID
logger.telegram.bot.chat.id (string|int|null)Specifies the Telegram chat ID for sending notifications.
- Can be a user ID, group ID, or channel ID.
- Leave
nullor unset to disable messaging.
Example:
# /.env
logger.telegram.bot.chat.id=987654321Dispatch Log Levels
logger.dispatch.levels (string[])
Define which log levels are allowed to be sent to remote services such as HTTP, Email, or Telegram.This acts as a strict whitelist.
Example:
Override the default remote log levels (alert, exception, emergency, critical):
# /.env
logger.dispatch.levels = [critical, emergency, alert, exception]How it works
Only the levels listed above will be dispatched when:
Luminova\Logger\Logger::dispatch()is called- Or a fatal / critical error triggers automatic remote logging
- If a level is not listed, it will never be sent remotely.
- If remote logging is not configured, nothing is sent, even for critical levels.
use Luminova\Logger\Logger;
use Luminova\Logger\LogLevel;
Logger::dispatch(LogLevel::ERROR, 'Query failed'); // ❌ Not dispatched
Logger::dispatch(LogLevel::CRITICAL, 'DB is down'); // ✅ Sent to remote
Logger::dispatch(LogLevel::EXCEPTION, 'Throws an error'); // ✅ Sent to remote
// Use default remote config and CRITICAL level
Logger::dispatch(to: null, 'Fatal error'); // ✅ Sent to remote if configuredThis keeps bots quiet, inboxes clean, and your sanity intact.
Email SMTP
SMTP Authentication Enabled
smtp.auth.enabled (bool)Enables SMTP authentication.
true- the SMTP client authenticates usingsmtp.username(andsmtp.passwordwhen required).false- authentication is skipped.
Example:
# /.env
smtp.auth.enabled=trueSMTP Password Required
smtp.password.required (bool)Indicates whether a password is required for SMTP authentication.
true- a password must be provided whensmtp.auth.enabledistrue.
Example:
# /.env
smtp.password.required=trueSMTP Debuggable
smtp.debug (bool)Enables or disables debugging information for SMTP communication.
- Useful for troubleshooting email sending issues, as it provides detailed logs.
Example:
# /.env
smtp.debug=trueSMTP Hostname
smtp.host (string)The hostname or IP address of the SMTP server that handles outgoing emails.
Example:
# /.env
smtp.host=smtp.example.comAccessing Value
$host = env('smtp.host'); // 'smtp.example.com'SMTP Port
smtp.port (int)The port number used for SMTP communication.
- Common ports:
25,465,587 - Depends on the SMTP server and encryption method.
Example:
# /.env
smtp.port=587SMTP Username
smtp.username (string)The username for SMTP authentication.
- Required if
smtp.auth.enabledis enabled.
Example:
# /.env
smtp.username=your_usernameSMTP Password
smtp.password (string)The password for SMTP authentication.
- Required if
smtp.password.requiredis enabled.
Example:
# /.env
smtp.password=your_passwordSMTP Sender Email
smtp.sender.email (string)The email address that appears as the sender ("From") in outgoing emails.
Example:
# /.env
[email protected]SMTP Encryption Type
smtp.encryption (string)Specifies the encryption method for SMTP communication.
- Common values:
tlsorssl - Secures the connection between the email client and server.
Example:
# /.env
smtp.encryption=tlsSMTP Encoding
smtp.charset (string)Defines the character set used for encoding email content.
- Common value:
UTF-8 - Ensures proper display of international characters.
Example:
# /.env
smtp.charset=UTF-8Database Connection Variables
These variables configure the default database connection in Luminova.
Deprecated development-prefixed keys:
database.development.username,database.development.name,database.development.password,database.development.commands, anddatabase.development.sqlite.pathare deprecated. Use the standard keys below instead, even inside.dev.env.
Hostname
database.hostname (string)The hostname of your database server.
Example:
# /.env
database.hostname=localhostDB Port
database.port (int)The port number for your database connection.
Example:
# /.env
database.port=3306DB Encoding
database.charset (string)The character set used for the database connection.
Example:
# /.env
database.charset=utf8mb4Database Pool
database.connection.pool (bool)Enables or disables connection pooling.
- Connection pooling reuses existing database connections instead of creating a new one for each request.
- Improves performance and reduces overhead.
Example:
# /.env
database.connection.pool=trueDatabase Maximum Connections
database.max.connections (int)Specifies the maximum number of simultaneous database connections.
- Helps manage resource usage and prevent overloading the database server.
Example:
# /.env
database.max.connections=20Database Trying Attempts
database.connection.retry (int)The number of retry attempts for database connections if the initial attempt fails.
- Useful for handling transient issues like network glitches or temporary server unavailability.
Example:
# /.env
database.connection.retry = 3Database Persistent Connection
database.persistent.connection (bool)
Enable or disable persistent database connections.When enabled, Luminova keeps database connections open between requests instead of reconnecting every time.
Example:
# /.env
database.persistent.connection = falseImplementation depends on the driver:
| Driver | How it works |
|---|---|
| MySQLi | Prefixes the host with p: (e.g. p:localhost) |
| PDO | Sets PDO::ATTR_PERSISTENT = true |
Notes
Persistent connections reduce connection overhead and improve performance on busy systems, but they come with sharp edges:
Pros
- Faster request startup
- Lower connection cost under load
Cons
- Stale connections
- Leaked transactions
- Hard-to-debug “ghost bugs”
MySQL Buffered Queries
database.mysql.buffered.query (bool)
Enable or disable buffered queries for MySQL connections.
- When enabled (
true), MySQL will fetch the entire result set into memory before you start reading it. - When disabled (
false), rows are streamed one by one from the server.
Example:
# /.env
database.mysql.buffered.query = falseWhy this matters
| Mode | Behavior | When to use |
|---|---|---|
| true | Faster for small queries, higher memory usage | Dashboards, admin panels, small datasets |
| false | Low memory usage, safer for big tables | Imports, exports, reports, long-running jobs |
Database Parameter Prepares
database.emulate.prepares (bool)Enables or disables emulation of prepared statements.
true- allows using the same named parameter multiple times in a query (useful for MySQLi, which doesn’t natively support repeated named parameters).false- uses native prepared statement behavior; each placeholder must be unique.
Example:
# /.env
database.emulate.prepares=trueDatabase ORM Cache Driver
database.orm.cache.driver (string)Specifies the cache driver for the database ORM Luminova\Database\Builder class. Setting this overrides system.cache.driver for the builder specifically.
- Available drivers:
memcached,filecache,redis
Example:
# /.env
database.orm.cache.driver = memcachedDeprecated:
database.caching.driveris deprecated. Usedatabase.orm.cache.driverinstead.
Database ORM Cache Enable
database.orm.cache.enable (bool)Enables or disables global caching for the database ORM query builder. This can be overridden per query using $builder->cacheable(false).
Example:
# /.env
database.orm.cache.enable = falseDatabase Driver
database.connection (string)The database connection driver to use.
- Available drivers:
mysqliorpdo
Example:
# /.env
database.connection=pdoDatabase PDO Driver Version
database.pdo.driver (string)
When using the PDO driver, specify the PDO DBMS type (default: mysql).
- Available types:
mysql,sqlite,sqlsrv,pgsql,cubrid,dblib, oroci
Example:
# /.env
database.pdo.driver=mysqlThis is only applicable when
database.connectionispdo. Not required formysqli.
Database Socket Connection
database.socket.connection (bool)Use a Unix socket connection instead of TCP for the database connection.
true- forces socket connection instead of TCP/IP. Enable this when running CLI tasks or when a socket connection is required.
Example:
# /.env
database.socket.connection = trueDatabase Socket Path
database.socket.path (string)Path to the database Unix socket file.
- Required if
database.socket.connectionistrue. - Example:
/var/run/mysqld/mysqld.sock
Example:
# /.env
database.socket.path=/var/run/mysqld/mysqld.sockDatabase Initialization Commands
database.commands (string[])
Define SQL commands that are executed immediately after a database connection is created.
Examples:
These commands run once per connection and are used to prepare the session environment.
# /.env
database.commands = ["SET time_zone = '${app.timezone}'"]Database Username
database.username (string)The username used to connect to the database.
Example:
# /.env
database.username=rootDatabase Name
database.name (string)The name of the database name.
Examples:
# /.env
database.name = my_databaseDatabase Password
database.password (string)The password used to authenticate the database user.
Examples:
# /.env
database.password = my_db_secretLeave empty if no password is required
Sqlite Database Path
database.sqlite.path (string)The file path to the SQLite database.
- Store the file inside the
/writeable/database/directory. - You may choose any filename you prefer.
Example:
# /.env
database.sqlite.path = /writeable/database/production.sqlite
database.sqlite.path = /writeable/database/development.sqliteNote:
Ensure that sqlite database file is stored in the
/writeable/database/directory.While there is no strict naming convention for the database file, it should be named according to your preference.
Optional Luminova Features
These are Luminova features that are disabled by default.They can be enabled when needed to reduce unnecessary overhead and improve performance by only loading what your application uses.
Route Attributes
feature.route.attributes (bool)Enable defining routes using PHP attributes inside controller methods instead of manual registration.
Example:
# /.env
feature.route.attributes = trueRoute Attribute Caching
feature.route.cache.attributes (bool)Enable caching of parsed route attributes to avoid re-parsing on every request.
Example:
Recommended in production for faster route handling.
# /.env
feature.route.cache.attributes=trueNote:
When route attribute caching is enabled, any changes made to controller attributes in production will not take effect until the cached files are manually deleted from:
/writeable/caches/routes/*The cache has no expiration and remains on the filesystem indefinitely until removed.
Route Attribute Optimization
route.optimize.attributes (bool)When enabled, route attributes are scored and sorted according to their score for more efficient routing. This only runs once, when feature.route.cache.attributes is enabled.
Example:
# /.env
route.optimize.attributes=disableApplication Class Aliases
feature.app.class.alias (bool)Allows registering custom class aliases for your application, letting you reference classes using shorter or more meaningful names.
Example:
# /.env
feature.app.class.alias=trueApplication Services Loader
feature.app.services (bool)Enables automatic loading and management of your application's services.
Example:
# /.env
feature.app.services=truePSR-4 Autoloading
feature.app.autoload.psr4 (bool)Activates PSR-4 autoloading, allowing classes to be automatically loaded based on their namespaces and directory structure.
Example:
# /.env
feature.app.autoload.psr4=trueDeveloper Functions Loader
feature.app.dev.functions (bool)Loads procedural utility functions from app/Utils/Global.php.Useful for making custom global helper functions available across the app.
Example:
# /.env
feature.app.dev.functions=trueRoute Dependency Injection
feature.route.dependency.injection (bool)Enables type-hint-based dependency injection for routable controller methods, allowing cleaner and more testable code.
Example:
# /.env
feature.route.dependency.injection=trueHMVC Architecture
feature.app.hmvc (bool)Enable support for HMVC architecture to organize nested modules.
enable→ activate HMVCdisable→ revert to standard MVC
Example:
# /.env
feature.app.hmvc=enableApplication Start URL (Development Only)
dev.app.start.url (string)Specifies the starting URL of your project's front controller. This URL is used when generating sitemaps.Ensure it points directly to your front controller (e.g., http://localhost/public/, http://localhost/my-project/public/, or http://localhost:port/).
Example:
# /.env
dev.app.start.url=https://localhost/your-project-path/public/Note:This can also be set in
app/Config/Sitemap.phpor using--urloption in command