PHP Luminova: Environment Variable Management and Formatting

The environment configuration file (.env) controls how your application behaves. It is used by both core Luminova modules and your application. The file stores key settings that allow you to run the app differently in development, staging, or production environments without changing the code.

By default, Luminova uses lowercase variable names with dot notation (e.g., app.name) for core settings. These core variable names cannot be changed. You can, however, define custom variables in any case or format you prefer, as long as the core variable names remain unchanged.

Managing Environment Variables

Luminova makes it easy to read and write values in the .env file.

Setting Variables

Set an environment variable at runtime onlyThis sets the value temporarily for the current script execution and does not override the default value in the .env file.

setenv('MY_FOO', 'foo value');

Set and save a variable permanentlyPass true as the third argument to override the default value in the .env file or create a new variable if it does not exist.

setenv('MY_FOO', 'foo value', true);

Reading Variables

Get a value from the environment

echo env('foo.bar');

Get a value with a fallback

If my.bar is missing, the second argument is returned instead.

echo env('my.bar', 'default value');

Using NovaKit Commands

These command provide an efficient way to manage your environment configurations with ease.

Add or update an environment variable

php novakit env:add --key=MY_FOO --value="foo value"

Remove an environment variable

php novakit env:remove --key=MY_FOO

Set an environment variables by context

php novakit env:setup --target=telegram

Variables Formatting

Environment variables can store different kinds of values. Luminova reads these values and converts them into the right PHP types when you call env().

Boolean Values

The boolean value can be either true sames as enable or false same as disable.Use boolean values when you want to turn a feature on or off.

Examples

In Environment File

# /.env

FEATURE_X=true # Same as enable

FEATURE_Y=disable # Same as false

Accessing Value

$featureX = env('FEATURE_X');   // true
$featureY = env('FEATURE_Y');   // false

Null Values

Use null when the key should exist but have no value.

In Environment File

# /.env

OPTIONAL_VALUE=null

Accessing Value

$value = env('OPTIONAL_VALUE');   // null

Blank Values

Use blank or an empty string '' when the key needs to be present but return an empty string.

In Environment File

# /.env

EMPTY_FIELD=blank

Accessing Value

$value = env('EMPTY_FIELD');    // ''

Array Values

Use array formatting when you want multiple values stored under one key.

In Environment File

# /.env

MY_LIST=['foo', 'bar', 'baz']
NUMBERS=[1,2,3]

Accessing Value

$list = env('MY_LIST');     // ['foo', 'bar', 'baz']
$nums = env('NUMBERS');     // [1, 2, 3]

Application Variables

Application Name

app.name (string)Specifies the name of your application. Used for identification, display, and internal reference.

Examples

# /.env

app.name=LuminovaApp

Application Hostname

app.hostname (string)Defines the hostname where your application is served. Required for network-related configuration such as generating URLs.

Examples

# /.env

app.hostname=example.com

Application Timezone

app.timezone (string)Sets the timezone used by the application. This affects timestamps, logs, scheduled tasks, and all date/time functions.

Examples

# /.env

app.timezone=Asia/Kuala_Lumpur

Application Locale

app.locale (string)Specifies the default locale. Controls language settings, formatting rules, numbers, dates, and other locale-driven output.

Examples

# /.env

app.locale=en

HTML Output Charset

app.charset (string)Defines the output charset for HTML templates, HTTP headers and other output layers. Important for correct text rendering.

Examples

# /.env

app.charset=utf-8

HTML Charset

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.

Examples

# /.env

app.mb.encoding=UTF-8

Application Version

app.version (string)Indicates the current version of the application. Used internally when generating static page caches and other internal reference.

Examples

# /.env

app.version=1.0.0

Useful 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.

Examples

# /.env

app.file.version=1.0.0

Application 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.

Examples

# /.env

app.key=your-secret-key

Note: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:key or by setting the key manually.

Application Environment Mode

app.environment.mood (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.mood=development

API Prefix

app.api.prefix (string)

Sets the URI prefix used for all application APIs. This prefix allows Luminova to correctly identify and validate internal API requests. Methods like Luminova\Luminova::isApiPrefix() rely on this value to decide whether the incoming request is an API call or a normal HTTP request.The default prefix is api.

ExampleIf your API endpoint is https://example.com/api/user/{id}, then the prefix is api.

# /.env

app.api.prefix=api

CLI

CLI Mode

cli.environment.mood (string)Defines the mood of the CLI environment, which affects how commands are executed and logged based on the environment. Typical values are production, development, or testing.

Examples

# /.env

cli.environment.mood=development

CLI 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

Examples

# /.env

throw.cli.exceptions=true

Page Caching

default.cache.control (string)Configures cache control directives for HTTP headers. This determines how browsers and intermediate caches handle your content. Example values:

Examples

# /.env

default.cache.control=no-store, max-age=0, no-cache

• no-store - do not cache
• max-age=0 - cached content expires immediately
• no-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 pages are stored and served directly, improving performance by reducing repeated processing and database queries.

Examples

# /.env

page.caching=true

Static 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.

Examples

# /.env

page.cache.expiry=3600

Note:Cache expiration can also be overridden before rendering a template in controllers ($this->tpl->cache(...)) or globally via the application’s $this->view->cache(...) class using the Luminova\Template\View->cache(expiration: ...) 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.

Make sure there are no spaces around the pipe symbol.

# /.env
page.caching.statics=html|json

By 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=true

Note:The immutable cache option can be overridden before rendering a template in controllers ($this->tpl->cache()) for a specific template, or globally via the application’s $this->view->cache() class using the Luminova\Template\View->cache(immutable: ...) 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

This ensures older cached pages are reused only if they match one of the specified versions, maintaining compatibility with legacy content.

# /.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.

Examples

# /.env

page.caching.uri.query=true

Recommended false:Unless your responses change based on query parameters (e.g., pagination, filters).

Memcached

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.

Examples

# /.env

memcached.persistent.id=my_app_memcache

Memcached 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.

Examples

# /.env

memcached.key.prefix=myapp_

Memcached Hostname

memcached.host (string)The hostname or IP address of the Memcached server.

• Default: localhost (server running on the same machine).

Examples

# /.env

memcached.host=127.0.0.1

Memcached Port

memcached.port (int)The port number on which the Memcached server listens.

• Default: 11211, the standard Memcached port.

Examples

# /.env

memcached.port=11211

Memcached 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).

Examples

# /.env

memcached.server.weight=1

Optimization

Template Content Minification

page.minification (bool)Enables or disables global HTML page content minification, including inline CSS and JavaScript. Minification reduces file size, improving page load times and overall performance.

Example

# /.env

page.minification=true

Note:HTML content minification can also be configured before rendering a template in controllers ($this->tpl->minify()) for a specific template, or globally via the application’s $this->view->minify() class using the Luminova\Template\View->minify(...) method.

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.

Examples

# /.env

script.execution.limit=30

Script 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.

Examples

# /.env

script.ignore.abort=true

Output Compression Handler

script.output.handler (string|null)Defines a custom output compression handler for script output.

• Example: ob_gzhandler compresses data sent to clients.
• Set to null to disable compression.

Examples

# /.env

script.output.handler=ob_gzhandler

Content Output Encoding

enable.encoding (bool)Enables or disables content encoding and compression for views. When enabled, output is compressed to reduce data size and improve transmission efficiency.

Examples

# /.env

enable.encoding=true

Output Compression Handler

compression.encoding (string|bool)Specifies the compression method for output, such as gzip or deflate. Setting it to false disables compression entirely. Adjusts how content is compressed for optimized delivery.

Examples

# /.env

compression.encoding=gzip

Output Compression Level

compression.level (int)Sets the compression level, usually from 1 (lowest) to 9 (highest). Higher levels compress content more but may increase CPU usage and processing time.

Examples

# /.env

compression.level=5

Login 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 a login session, the session is invalidated, and the user must log in again. This improves security by binding sessions to a specific IP.

Examples

# /.env

session.strict.ip=true

Debugging

Maintenance Mode

app.maintenance.mood (bool)Enables or disables maintenance mode. When enabled, users may see a maintenance page while internal tasks continue running.

Examples

# /.env

app.maintenance.mood=true

Maintenance 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.

Examples

# /.env

app.maintenance.retry=3600

Show 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.

Examples

# /.env

debug.show.tracer=true

Note: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=true

Note: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.

Examples

# /.env

debug.display.errors=true

Performance Monitoring

debug.show.performance.profiling (bool)Displays performance profiling information at the bottom of each page or after CLI routable command is execution. Includes execution time, memory usage, and files loaded. Only visible in development mode to help identify performance bottlenecks.

Examples

# /.env

debug.show.performance.profiling=true

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 in /writeable/logs/metrics.json for analysis.

Example

# /.env
debug.api.performance.profiling=true

Inline Error Detection

debug.catch.inline.errors (bool)Enables detection and handling of hidden errors in view content.When true, hidden errors trigger exceptions to ensure all errors are properly handled.

Examples

# /.env

debug.catch.inline.errors=true

Depreciated:This feature has been depreciated, it no longer serve the intended need.

Logging System

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 file
• false - clear the log file without creating a backup

Examples

# /.env

logger.create.backup=true

Maximum 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.backup is true, a backup is created.
  • If false, the log file is cleared.

Examples

# /.env

logger.max.size=10485760

Remote 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.
• Leave null or unset to disable remote logging.

Examples

# /.env

logger.remote.logs=https://example.com/log-endpoint

Email Logging

logger.mail.logs (string|null)Specifies an email address for sending error logs.

• When set, the logger will email errors automatically.
• Leave null or unset to disable email logging.

Examples

# /.env

[email protected]

Telegram Bot Logging Token

telegram.bot.token (string|null)The Telegram bot token used for API authentication.

• Obtain from BotFather.
• Required for sending Telegram notifications.
• Leave null or unset to disable Telegram features.

Examples

# /.env

telegram.bot.token=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

Telegram Bot Chat-ID

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 null or unset to disable messaging.

Examples

# /.env

telegram.bot.chat.id=987654321

Email SMTP

SMTP Authenticatable

smtp.use.credentials (bool)Specifies whether SMTP authentication requires credentials.

• true - SMTP username and password are required to send emails.
• false - credentials are not used.

Examples

# /.env

smtp.use.credentials=true

SMTP Password

smtp.use.password (bool)Indicates whether a password is required for SMTP authentication.

• true - a password must be provided if credentials are used.

Examples

# /.env

smtp.use.password=true

SMTP Debuggable

smtp.debug (bool)Enables or disables debugging information for SMTP communication.

• Useful for troubleshooting email sending issues, as it provides detailed logs.

Examples

# /.env

smtp.debug=true

SMTP Hostname

smtp.host (string)The hostname or IP address of the SMTP server that handles outgoing emails.

Examples

# /.env

smtp.host=smtp.example.com

Accessing 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.

Examples

# /.env

smtp.port=587

SMTP Username

smtp.username (string)The username for SMTP authentication.

• Required if smtp.use.credentials is enabled.

Examples

# /.env

smtp.username=your_username

SMTP Password

smtp.password (string)The password for SMTP authentication.

• Required if smtp.use.credentials is enabled.

Examples

# /.env

smtp.password=your_password

SMTP Sender Email

smtp.email.sender (string)The email address that appears as the sender ("From") in outgoing emails.

Examples

# /.env

[email protected]

SMTP Encryption Type

smtp.encryption (string)Specifies the encryption method for SMTP communication.

• Common values: tls or ssl
• Secures the connection between the email client and server.

Examples

# /.env

smtp.encryption=tls

SMTP Encoding

smtp.charset (string)Defines the character set used for encoding email content.

• Common value: UTF-8
• Ensures proper display of international characters.

Examples

# /.env

smtp.charset=UTF-8

Database Variables

These configuration variables are used to set up the default database connection. Variables with development in their names are specific to development environments, keeping development and production configurations separate.

Hostname

database.hostname (string)The hostname of your database server.

Examples

# /.env

database.hostname=localhost

DB Port

database.port (int)The port number for your database connection.

Examples

# /.env

database.port=3306

DB Encoding

database.charset (string)The character set used for the database connection.

Examples

# /.env

database.charset=utf8mb4

Database 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.

Examples

# /.env

database.connection.pool=true

Database Maximum Connections

database.max.connections (int)Specifies the maximum number of simultaneous database connections.

• Helps manage resource usage and prevent overloading the database server.

Examples

# /.env

database.max.connections=20

Database 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.

Examples

# /.env

database.connection.retry=3

Database Persistent Connection

database.persistent.connection (bool)Enables or disables persistent database connections.

• Persistent connections remain open across multiple requests, improving performance.
• Requires careful management to avoid stale connections.

Examples

# /.env

database.persistent.connection=true

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.

Examples

# /.env

database.emulate.prepares=true

Database Cache Driver

database.caching.driver (string)Specifies the cache driver for the database Luminova\Database\Builder class.

• Available drivers: memcached or filesystem

Examples

# /.env

database.caching.driver=memcached

Database Driver

database.connection (string)The database connection driver to use.

• Available drivers: MYSQLI or PDO

Examples

# /.env

database.connection=PDO

Database PDO Driver Version

database.pdo.version (string)

When using PDO driver, specify the PDO DBMS type (default: mysql).

• Available types: mysql, sqlite, sqlsrv, pgsql, cubrid, dblib, or oci

Examples

# /.env

database.pdo.version=mysql

Database Socket Connection

database.mysql.socket (bool)Use a Unix socket for MySQL or MySQLi connections.

• true - forces socket connection instead of TCP/IP, improving performance for local servers.
• By default, Luminova may already use sockets for CLI connections; enabling ensures consistency across connection types.

Examples

# /.env

database.mysql.socket=true

Database Socket Path

database.mysql.socket.path (string)Path to the Unix socket file for MySQL/MySQLi connections.

• Required if database.mysql.socket is true.
• Example paths: /var/run/mysqld/mysqld.sock or /tmp/mysql.sock

Examples

# /.env

database.mysql.socket.path=/var/run/mysqld/mysqld.sock

Production Database Options

Luminova allows you to specify connectio details for production and development, without having to always change the connection details based on environment.

These settings define your production database credentials.

Production Database Username

database.username (string)The username used to connect to the production database.

Examples

# /.env

database.username=prod_user

Production Database Name

database.name (string)The name of the production database.

Examples

# /.env

database.name=prod_database

Production Database Password

database.password (string)The password used to authenticate the production database user.

Examples

# /.env

database.password=secret

Production Database Sqlite Path

database.sqlite.path (string)The file path to the SQLite database used in the production environment.

• Store the file inside the /writeable/database/ directory.
• You may choose any filename you prefer.

Examples

# /.env

database.sqlite.path=writeable/database/production.sqlite

Development Database Options

These settings define your development database credentials. Keeping them separate prevents accidental damage to production data.

Development Database Username

database.development.username (string)The username used to connect to the development database.

Examples

# /.env

database.development.username=dev_user

Development Database Name

database.development.name (string)The name of the development database.

Examples

# /.env

database.development.name=dev_database

Development Database Password

database.development.password (string)The password used to authenticate the development database user.

Examples

# /.env

database.development.password=dev_secret

Development Database Sqlite Path

database.development.sqlite.path (string)The file path to the SQLite database used in the development environment.

• Store the file inside the /writeable/database/ directory.
• Naming is optional and up to you.

Examples

# /.env

database.development.sqlite.path=writeable/database/development.sqlite

Note:

Ensure that both production or development 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 Features

Route Attributes

feature.route.attributes (bool)Enables route attribute definitions inside controller methods. When turned on, routes can be configured using PHP attributes instead of manual registration.

Examples

# /.env

feature.route.attributes=true

Route Attribute Cache

feature.route.cache.attributes (bool)Turns on caching for route attributes. When enabled, Luminova stores parsed route attributes so the framework doesn't re-parse them on every request. This reduces overhead and speeds up production environments where routes rarely change.

Examples

# /.env

feature.route.cache.attributes=enable

Application Class Aliases

feature.app.class.alias (bool)Allows registering custom class aliases for your application. This lets you reference classes using shorter or more meaningful names.

Examples

# /.env

feature.app.class.alias=true

Application Services Loader

feature.app.services (bool)Enables the service class loader. When active, Luminova automatically loads and manages services defined for your application.

Examples

# /.env

feature.app.services=true

PSR-4 Autoloading

feature.app.autoload.psr4 (bool)Activates PSR-4 autoloading for your application. When enabled, classes are automatically loaded based on their namespaces and directory structure.

Examples

# /.env

feature.app.autoload.psr4=true

Developers Functions Loader

feature.app.dev.functions (bool)Loads procedural utility functions from app/Utils/Global.php. Useful when you want custom global helper functions available across the app.

Examples

# /.env

feature.app.dev.functions=true

Route Dependency Injection

feature.route.dependency.injection (bool)Enables type-hint-based dependency injection for controller methods that are routable. This allows cleaner and more testable controllers.

Examples

# /.env

feature.route.dependency.injection=true

HMVC Architecture

feature.app.hmvc (bool)Controls support for the HMVC architecture.Set to enable to activate nested modules and improve code organization.Set to disable to revert to the default MVC structure.

Examples

# /.env

feature.app.hmvc=enable

Development Only

Scan Start URL

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.php or using --url option in command