Download

DotApp Configuration

This section guides you through configuring the DotApp PHP Framework. Discover how to set up session drivers, databases (PDO, MySQLi), and the Config class to tailor your web applications with ease and precision.

Config Class Overview

The Config class, located at /app/Config.php, provides the core configuration settings required to run a DotApp application. It includes default settings that ensure the framework operates smoothly, but users typically need to customize only a few key parameters, such as the database, application name, and encryption key.

Important: The encryption key (c_enc_key) is used for securing passwords and sensitive data. Once set, it should not be changed, as doing so would require resetting all encrypted data, such as user passwords.

Basic Settings

To run a DotApp application, you must define the root directory in index.php if the application is hosted in a subdirectory. Otherwise, the current directory is used by default. 


define('__ROOTDIR__', "path/to/your/application"); // Set this only if the application runs in a subdirectory

Custom configuration settings are defined in /app/config.php. This file allows you to override default settings and tailor the framework to your needs.

Session Configuration

DotApp provides a robust session management system with customizable settings. Below are the default session configuration options defined in /app/config.php: 


'session' => [
    'driver' => 'default', // Default session driver
    'lifetime' => 3600, // Session expiration in seconds
    'rm_always_use' => false, // Always use "Remember Me" functionality?
    'rm_autologin' => false, // Enable automatic autologin?
    'rm_lifetime' => 2592000, // Remember Me lifetime (30 days)
    'cookie_name' => 'dotapp_session', // Session cookie name
    'path' => '/', // Cookie path
    'secure' => false, // Restrict to HTTPS
    'httponly' => true, // Prevent XSS attacks
    'samesite' => 'Strict', // Prevent CSRF attacks
    'database_use' => false, // Use database for session storage?
    'database_table' => 'users_sessions', // Table for database sessions
    'redis_host' => '127.0.0.1', // Redis host
    'redis_port' => 6379, // Redis port
    'redis_timeout' => 2, // Redis connection timeout
    'redis_password' => '', // Redis password
    'redis_persistent' => false, // Persistent Redis connection
    'redis_database' => 0, // Redis database number
    'redis_prefix' => 'session:', // Redis session prefix
    'file_driver_dir' => '/app/runtime/SessionDriverFile', // Directory for SessionDriverFile
    'file_driver_dir2' => '/app/runtime/SessionDriverFile2', // Directory for SessionDriverFile2
]

To customize session settings, use the Config::session method. For example: 


Config::session("lifetime", 30 * 24 * 3600); // Set session lifetime to 30 days
Config::session("rm_autologin", true); // Enable automatic autologin

Session Drivers

DotApp supports multiple session drivers, allowing you to choose the storage mechanism that best suits your application. Importantly, session settings must be configured before defining the driver, as the driver uses these settings upon initialization.

Available Drivers

  • Default Driver (SessionDriverDefault): Uses PHP’s built-in $_SESSION mechanism.
  • File Driver (SessionDriverFile): Stores sessions in files, using the directory specified in file_driver_dir. Requires a CRON job for garbage collection.
  • File Driver 2 (SessionDriverFile2): Similar to SessionDriverFile, but stores each cookie in separate files, ideal for handling many cookies. Uses file_driver_dir2. Requires a CRON job for garbage collection.
  • Database Driver (SessionDriverDB): Stores sessions in a database, ideal for load-balanced environments. Uses the <prefix>users_sessions table (default prefix: dotapp_).
  • Redis Driver (SessionDriverRedis): Uses Redis for fast, centralized session storage, suitable for load-balanced setups.

To set a driver, use the Config::sessionDriver method after configuring session settings: 


Config::sessionDriver("default", SessionDriverDefault::driver()); // Default $_SESSION driver
Config::sessionDriver("default", SessionDriverFile::driver()); // File-based driver
Config::sessionDriver("default", SessionDriverFile2::driver()); // File-based driver with multiple files
Config::sessionDriver("default", SessionDriverDB::driver()); // Database driver
Config::sessionDriver("default", SessionDriverRedis::driver()); // Redis driver

Database Driver Setup

For the database driver, you must create the <prefix>users_sessions table. Below is the SQL to create it: 


CREATE TABLE IF NOT EXISTS `dotapp_users_sessions` (
  `session_id` varchar(64) NOT NULL,
  `sessname` varchar(255) NOT NULL,
  `values` longtext NOT NULL,
  `variables` longtext NOT NULL,
  `expiry` bigint NOT NULL,
  `created_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `updated_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`session_id`,`sessname`),
  KEY `idx_expiry` (`expiry`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;

To change the table prefix: 


Config::db("prefix", "your_prefix_");

Redis Driver Configuration

To configure the Redis driver, update the relevant settings using Config::session. For example: 


Config::session("redis_host", "your IP"); // Redis host
Config::session("redis_port", 6379); // Redis port
Config::session("redis_timeout", 2); // Redis connection timeout
Config::session("redis_password", "your_password"); // Redis password
Config::session("redis_persistent", false); // Persistent Redis connection
Config::session("redis_database", 0); // Redis database number
Config::session("redis_prefix", "session:"); // Redis session prefix

Application Configuration

DotApp allows you to configure core application settings, such as the application name, encryption key, and version. Below are the default settings: 


'app' => [
    'name' => 'dotApp123456',
    'name_hash' => '', // Do not modify directly
    'c_enc_key' => 'K9xP7mW3qT2rY6vL8cF4hD5aE0zJ1nB2X7bP9qRtY2mW4kZjN6vL8cF3hD5aE0xQ', // Encryption key
    'version' => '1.0',
]

To customize these settings, use the Config::app method: 


Config::app("name", "Your Application Name"); // Set application name
Config::app("c_enc_key", "YourStrongEncryptionKey"); // Set a strong encryption key
Config::app("version", "0.1 alpha"); // Set application version

Important: The encryption key (c_enc_key) must be strong and secure, as it is used for encrypting sensitive data. Avoid changing it after initial setup to prevent issues with existing encrypted data.

Database Configuration

DotApp supports multiple database drivers (PDO and MySQLi) and allows you to configure multiple databases. To add a database, use the Config::addDatabase method: 


Config::addDatabase("main", "127.0.0.1", "dotsystems", "dotsystems", "dotsystems", "UTF8", "MYSQL", "pdo");

This configures a database named main using the PDO driver with MySQL. Supported PDO database types include mysql, pgsql, sqlite, oci, and sqlsrv.

Default database settings: 


'db' => [
    'prefix' => 'dotapp_', // Database table prefix
    'driver' => 'pdo', // Default driver
    'maindb' => 'main' // Default database name
]

The main database is used by default across the application unless another database is specified. To switch the default database for all modules: 


Config::db("maindb", "anotherdb");
Config::addDatabase("anotherdb", "127.0.0.1", "dotsystems2", "dotsystems2", "dotsystems2", "UTF8", "MYSQL", "pdo");

To change the default driver: 


Config::db("driver", "mysqli");

Important: Each driver maintains its own database credentials. A database configured for PDO cannot be used with MySQLi unless reconfigured. For example: 


// Incorrect: Mixing PDO database with MySQLi driver
Config::db("driver", "mysqli");
Config::db("maindb", "anotherdb");
Config::addDatabase("anotherdb", "127.0.0.1", "dotsystems2", "dotsystems2", "dotsystems2", "UTF8", "MYSQL", "pdo");

// Correct: Matching driver and database
Config::db("driver", "mysqli");
Config::db("maindb", "anotherdb");
Config::addDatabase("anotherdb", "127.0.0.1", "dotsystems2", "dotsystems2", "dotsystems2", "UTF8", "MYSQL", "mysqli");

Warning: While you can define multiple databases with different drivers (e.g., PDO for one, MySQLi for another), this is not recommended for universal, shareable modules. For example: 


Config::addDatabase("eshop1", "127.0.0.1", "dotsystems2", "dotsystems2", "dotsystems2", "UTF8", "MYSQL", "mysqli");
DotApp::DotApp()->DB->driver('mysqli')->selectDb('eshop1')->q(...)->execute();
Config::addDatabase("eshop2", "127.0.0.1", "dotsystems", "dotsystems", "dotsystems", "UTF8", "MYSQL", "pdo");
DotApp::DotApp()->DB->driver('pdo')->selectDb('eshop2')->q(...)->execute();

This approach works but makes modules non-portable. For shareable and maintainable modules, always use the default database (maindb) and driver: 


DB::module()->q(...)->execute(); // Automatically uses Config::db('driver') and Config::db('maindb')

Following DotApp’s philosophy ensures modules are portable and easy to maintain across applications.

Module Configuration

DotApp allows module-specific configuration using the Config::module method, which provides getter and setter functionality for module settings.

Example of setting and getting module configuration: 


Config::module("crm", "title", "CRM PAGE TITLE"); // Set module configuration
$title = Config::module("crm", "title"); // Get module configuration

This allows module developers to provide customizable settings for users while keeping configurations organized and module-specific.

Two-Factor Authentication (2FA)

DotApp supports two-factor authentication (2FA) with TOTP (Time-based One-Time Password). The default settings are: 


'totp' => [
    'issuer' => 'DotApp',
    'algorithm' => 'SHA256',
    'digits' => 6,
    'period' => 30,
]

To customize the 2FA issuer (e.g., for display in authenticator apps): 


Config::totp("issuer", "MyApp");

Other settings (algorithm, digits, period) should typically remain unchanged. 2FA configuration is only necessary if your application uses two-factor authentication for login.

Configuration Examples

To see practical examples of configuring DotApp, including session drivers, database setup, and module configuration, visit the Examples section. These examples demonstrate how to apply the configurations discussed here in real-world scenarios.