PHP Luminova: Environment Variables and Managment

The environment configuration file controls how your application behaves. It stores key settings that help you run the app differently in development, staging, or production without changing the code.

Managing Environment Variables

Luminova makes it easy to read, set, and update values in your .env file.

Setting Variables

Set a variable for the current request only

This does not save anything to the .env file. It works only while the script is running.

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

Set and save a variable permanently

Pass true as the third argument to write the value into the .env file.If the key exists, it will be updated. If it doesn't, it will be created.

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

Reading Variables

Get a value from the environment

echo env('MY_FOO');

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. Useful for debugging, updates, asset tagging, and compatibility tracking.

Examples

# /.env

app.version=1.0.0

Application File Version

app.file.version (string)Specifies the version for static files. 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=base64:your-secret-key

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=production

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

API Prefix

app.api.prefix (string)Sets the URI prefix for API routes. Default is api. If changed, ensure Foundation::isApiContext() continues working with your prefix.

Examples

# /.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 exceptions in CLI commands to be caught or thrown outside of command controller classes.

• true - raw exceptions are thrown in CLI environments, useful for debugging scripts
• false - exceptions are handled silently

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 caching of entire pages. Enabling this improves performance by reducing repeated processing and database queries.

Examples

# /.env

page.caching=true

Static Cache Expiration

page.cache.expiry (int)Specifies how long cached pages remain valid, in seconds. For example, 3600 means cached pages are valid for one hour before being refreshed or invalidated.

Examples

# /.env

page.cache.expiry=3600

Static Cache Types

page.caching.statics (string)Specifies the types of content that should be served as static cached pages. Multiple types are separated by a pipe (|). Example: html|json ensures that static caching applies to both .html and .json pages. Make sure there are no spaces around the pipe symbol.

Examples

In Environment File

# /.env

page.caching.statics=html|json

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

In Environment File

# /.env

page.caching.immutable=true

Last Cached App Versions

page.cache.app.versions (array)An array of previous application versions considered when retrieving cached content.

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

Examples

# /.env

page.cache.app.versions=[1.0.2,3.2.6]

Cache Latest URIs Prexies

page.cache.latest.content (array)An array of URI patterns/prefix that should always use the latest cached content for the current application version.

When a URI matches one of these patterns, older version caches are ignored. This ensures critical or frequently updated pages, such as landing pages or dashboards, always display fresh content.

Examples

# /.env

page.cache.latest.content=[/,users]

Cache URI Queries

page.caching.uri.query (bool)Determines whether query parameters are included in cache keys.

• true - different query strings are treated as separate cache entries
• false - query parameters are ignored to reduce cache fragmentation

Examples

# /.env

page.caching.uri.query=true

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 minification of page content, including inline CSS and JavaScript. Minification reduces file size, which improves page loading times and overall performance.

Examples

# /.env

page.minification=true

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

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:If these warnings are unnecessary 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

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