DEV Community: DotApp PHP Framework

How to Easily Create an MCP Server for Sending Emails with DotApp PHP Framework (Video Tutorial)

DotApp PHP Framework — Tue, 05 Aug 2025 19:24:18 +0000

This tutorial will guide you through using the DotApp PHP framework to build an MCP (Machine Control Protocol) server for sending emails. We'll cover setting up the framework, creating an MCP server module, and configuring it to handle email operations. A step-by-step video tutorial in English is also available to help you follow along!

What is DotApp?

DotApp is a lightweight, modular PHP framework designed for rapid development of web applications and APIs. It emphasizes simplicity, flexibility, and developer productivity, making it an excellent choice for building custom solutions like an MCP server for AI-driven tasks.

In this article, we'll create an MCP server that allows an AI agent to send emails using the DotApp framework. Let's dive in!

Step 1: Installing the DotApp PHP Framework

To get started, we need to install the DotApp framework using the dotapper.php installer.

Download the Installer:
- Visit https://install.dotapp.dev/dotapper.php.
- On Linux, use:
```
 wget https://install.dotapp.dev/dotapper.php
```
Install and Update DotApp:
Run the following commands to install and update the framework:

   php dotapper.php --install
   php dotapper.php --update

Alternative Installation Methods:

Using Composer:

 composer create-project dotsystems/dotapp ./

Using Git:

 git clone https://github.com/dotsystems-sk/dotapp.git ./

This sets up the DotApp framework in your project directory.

Step 2: Creating the MCP Module and Controller

Next, we'll create a module named MCPtest and a controller MCP to handle MCP server logic.

Run these commands:

php dotapper.php --create-module=MCPtest
php dotapper.php --module=MCPtest --create-controller=MCP

This creates:

A module named MCPtest.
A controller named MCP within app/modules/MCPtest/Controllers/MCP.php.

Step 3: Configuring Email Settings

In the configuration file app/config.php, add the email settings for SMTP and IMAP. The passwords here are placeholders (already changed for security).

Config::email("testAcc", "smtp", [
    "host" => "server1.dotsystems.sk",
    "port" => 587,
    "timeout" => 30,
    "secure" => "tls",
    "username" => "testsender@858.eu",
    "password" => "U4jNaM7H",
    "from" => "testsender@858.eu"
]);

Config::email("testAcc", "imap", [
    "host" => "server1.dotsystems.sk",
    "port" => 993,
    "timeout" => 30,
    "secure" => "ssl",
    "username" => "testsender@858.eu",
    "password" => "U4jNaM7H"
]);

These settings configure the email account testAcc for sending and receiving emails.

Step 4: Implementing the MCP Controller

Edit the controller file app/modules/MCPtest/Controllers/MCP.php to handle MCP requests and email sending functionality.

<?php
namespace Dotsystems\App\Modules\MCPtest\Controllers;
use Dotsystems\App\DotApp;
use Dotsystems\App\Parts\Middleware;
use Dotsystems\App\Parts\Response;
use Dotsystems\App\Parts\Renderer;
use Dotsystems\App\Parts\Router;
use Dotsystems\App\Parts\Email;
use Dotsystems\App\Parts\MCP as DotAppMCP;

class MCP extends \Dotsystems\App\Parts\Controller {
    public static function runMCP($request) {
        return json_encode(DotAppMCP::execute($request));
    }

    public static function addTools() {
        DotAppMCP::addTool(
            'send_email',
            'Send an email to a specified recipient',
            [
                "to_email" => ["type" => 'string', "description" => "Recipient email address"],
                "subject" => ["type" => 'string', "description" => "Email subject"],
                "body" => ["type" => 'string', "description" => "HTML BODY of email"],
                "save" => ["type" => 'boolean', "description" => "Save to Sent folder? If user do not specify, use default: false"],
            ],
            function($params) {
                self::sendEmail($params['to_email'], $params['subject'], $params['body'], $params['save']);
            }
        );
    }

    public static function sendEmail($to, $subject, $body, $save) {
        DotApp::DotApp()->unprotect($to);
        DotApp::DotApp()->unprotect($subject);
        DotApp::DotApp()->unprotect($body);
        if ($save === false) {
            $result = Email::send("testAcc", $to, $subject, $body, null);
        }
        if ($save === true) {
            $result = Email::sendAndSave("Sent", "testAcc", $to, $subject, $body, null);
        }
        if ($result === true) {
            return [
                "status" => "success",
                "message" => "Email sent to " . $to
            ];
        } else {
            throw new \Exception("Email was not sent: " . implode(",", $result));
        }
    }
}

This code:

Defines an MCP tool send_email with parameters for recipient, subject, body, and a save option.
Implements the sendEmail method to send emails using the configured testAcc account.
Uses runMCP to process MCP requests and return JSON responses.

Step 5: Setting Up Routes

In app/modules/MCPtest/module.init.php, initialize the module, add the MCP tools, and define a route to handle MCP requests.

<?php
namespace Dotsystems\App\Modules\MCPtest;
use \Dotsystems\App\DotApp;
use \Dotsystems\App\Parts\Router;
use \Dotsystems\App\Parts\Middleware;
use \Dotsystems\App\Parts\Request;
use \Dotsystems\App\Parts\Response;
use \Dotsystems\App\Parts\Input;
use \Dotsystems\App\Parts\DB;
use \Dotsystems\App\Parts\Renderer;

class Module extends \Dotsystems\App\Parts\Module {
    public function initialize($dotApp) {
        Controllers\MCP::addTools();
        Router::post("/", 'MCPtest:MCP@runMCP', Router::STATIC_ROUTE);
    }

    public function initializeRoutes() {
        return ['/'];
    }

    public function initializeCondition($routeMatch) {
        return $routeMatch;
    }
}
new Module($dotApp);

This sets up a POST route (/) that directs all MCP requests to the runMCP method in the MCP controller.

Step 6: Testing the MCP Server

To test the MCP server, you can use the following PHP agent script that interacts with an AI (e.g., ChatGPT) to send MCP requests. The script includes an HTML form for user interaction and requires an OpenAI API key, which users can provide via environment variables.

<?php
// Set script execution time limit to 120 seconds
set_time_limit(120);

// Define OpenAI API key and endpoint (use environment variables in production)
define('OPENAI_API_KEY', getenv('OPENAI_API_KEY') ?: '');
define('API_URL', 'https://api.openai.com/v1/chat/completions');

// Check if a string is valid JSON
function isJson($string) {
    json_decode($string);
    return json_last_error() === JSON_ERROR_NONE;
}

// Extract JSON from a string that may contain text
function extractJsonFromResponse($response) {
    // Try to parse as JSON directly
    if (isJson($response)) {
        return json_decode($response, true);
    }
    // Extract JSON from text using regex
    $pattern = '/\{[\s\S]*?\}(?=\s*$|\s*[^[{])/';
    if (preg_match($pattern, $response, $matches)) {
        $jsonString = $matches[0];
        if (isJson($jsonString)) {
            return json_decode($jsonString, true);
        }
    }
    return null;
}

// Make a cURL request (GET or POST)
function makeCurlRequest($url, $postData = null) {
    try {
        $ch = curl_init($url);
        $headers = [
            'User-Agent: Mozilla/5.0 (compatible; CustomBot/1.0)',
            'Content-Type: application/json'
        ];
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
        curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
        if ($postData) {
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($postData));
        }
        $response = curl_exec($ch);
        if (curl_errno($ch)) {
            $error = curl_error($ch);
            curl_close($ch);
            return ['error' => "cURL error: $error"];
        }
        curl_close($ch);
        return ['content' => trim(preg_replace('/\s+/', ' ', $response))];
    } catch (Exception $e) {
        return ['error' => "Error making cURL request: " . $e->getMessage()];
    }
}

// Fetch content from a URL (GET or POST)
function fetchUrlContent($url, $postData = null) {
    $result = makeCurlRequest($url, $postData);
    if (isset($result['error'])) {
        return ['error' => "Failed to fetch content from URL: $url - {$result['error']}"];
    }
    $content = $result['content'];
    if (isJson($content)) {
        $jsonData = json_decode($content, true);
        if (isset($jsonData['error'])) {
            return ['error' => "JSON-RPC error: {$jsonData['error']['message']} (code: {$jsonData['error']['code']})"];
        }
        return ['content' => $jsonData];
    }
    return ['content' => $content];
}

// Send request to ChatGPT API
function callChatGpt($prompt, $conversation = []) {
    $ch = curl_init(API_URL);
    $headers = [
        'Content-Type: application/json',
        'Authorization: Bearer ' . OPENAI_API_KEY
    ];
    // System prompt for MCP handshake and JSON-RPC requests
    $systemPrompt = 'You reply in the language the user starts communicating with you in the first message. You are a friendly and conversational AI assistant designed to assist users with general questions and tasks. Your primary role is to engage in natural conversation, answer questions to the best of your knowledge, and provide helpful responses without assuming any specific tools or external services unless explicitly requested by the user.
**Detection and Storage**: Search the entire conversation history for an MCP server URL in any message. Look for patterns such as "use mcp server at <url>", "mcp at <url>", "use <url>", "Pouzi mcp server: <url>", or any URL containing "mcp" in the domain (e.g., https://mcp.dotapp.dev). Use robust matching to recognize variations in language and format (e.g., case-insensitive, with or without colons, spaces, or "at"). Once an MCP server URL is found, store it for the entire conversation and reuse it for all subsequent tasks requiring an MCP server, unless the user explicitly provides a new MCP server URL. Validate the URL to ensure it is a valid HTTPS URL before storing it. If no MCP server URL is found in the history, return: {"error": "I cannot perform this task without an MCP server. Please provide an MCP server URL (e.g., \'use mcp server at https://mcp.example.com\')"}
If the user requests a task that requires external data or services (e.g., checking the weather, sending an email), or mentions an MCP server (e.g., "use mcp server at <url>", "mcp at <url>", or a URL containing "mcp"), follow these rules:
1. **MCP Server Detection and Tool Discovery**: If the user provides an MCP server URL (e.g., "use mcp server at https://mcp.example.com" or mentions a URL containing "mcp"), immediately extract the MCP server URL from the input. Generate a JSON-RPC 2.0 request for the `initialize` method to negotiate protocol version and capabilities, followed by a `tools/list` request to retrieve the list of available tools from the MCP server. Store the list of tools and their parameters for use in subsequent interactions. Ensure that the `data` parameter in any `tools/call` request is always set (use an empty string if no data is required). Return **only** pure, valid JSON without any additional text, comments, markdown, or code fences for these requests. Example for `initialize`:
   {"action": "fetch", "url": "<mcp_server_url>", "data": {"jsonrpc": "2.0", "id": "<unique_id>", "method": "initialize", "params": {"clientInfo": {"name": "mcp-client", "version": "1.0"}, "protocolVersion": "2025-06-18", "capabilities": {"tools": {"list": true, "call": true}, "resources": {"list": true, "read": true}, "prompts": {"list": true, "get": true}}}}}
   Example for `tools/list`:
   {"action": "fetch", "url": "<mcp_server_url>", "data": {"jsonrpc": "2.0", "id": "<unique_id>", "method": "tools/list", "params": {}}}
   So once you run initialize method, then you must also run tools/list or tools/call method to get the list of available tools - based on last reply from the initialize method.
2. **Tool Usage**: After retrieving the list of available tools, use them automatically for tasks that match their capabilities (e.g., if the user asks to "fetch a web page" and the MCP server supports a `fetch_url` tool, use it). Ensure all required parameters for the tool are provided, and the `data` parameter is always set (use an empty string if optional and not provided). Generate a JSON-RPC 2.0 request for `tools/call` with appropriate parameters. Example:
   {"action": "fetch", "url": "<mcp_server_url>", "data": {"jsonrpc": "2.0", "id": "<unique_id>", "method": "tools/call", "params": {"name": "fetch_url", "arguments": {"url": "<target_url>", "method": "GET", "data": ""}}}}
3. **Verification of Capabilities**: If the user asks whether a specific task can be performed using an MCP server (e.g., "Can you send an email using https://mcp.example.com?"), check the stored list of tools from the `tools/list` response to determine if the requested capability is supported. Return a conversational response indicating whether the task is supported (e.g., "Yes, the MCP server at https://mcp.example.com supports sending emails" or "No, the MCP server at https://mcp.example.com does not support sending emails"). Do not execute any actions (e.g., `tools/call`) unless explicitly instructed by the user.
4. **Action Execution**: Execute an action (e.g., `tools/call`, `resources/read`, or `prompts/get`) **only** if the user explicitly requests a specific task using the MCP server. Use the stored tool information to validate parameters and ensure the `data` parameter is always set (use an empty string if optional and not provided). Return **only** pure, valid JSON without any additional text or markdown for these requests. Example:
   {"action": "fetch", "url": "<mcp_server_url>", "data": {"jsonrpc": "2.0", "id": "<unique_id>", "method": "tools/call", "params": {"name": "tool_name", "arguments": {}}}}
5. **Error Handling**: If a JSON-RPC response contains an `error` field (e.g., code -32600, -32601, -32602), return **only** a JSON with the error: {"error": "<error_message> (code: <error_code>)"}. If no MCP server is provided for a task requiring external data, return: {"error": "I cannot perform this task without an MCP server. Please provide an MCP server URL (e.g., \'use mcp server at https://mcp.example.com\')."} Do not add any additional text or markdown.
6. **Non-MCP Tasks**: For tasks that do not require an MCP server or external data (e.g., general knowledge questions, casual conversation), respond directly with natural, conversational text. Do not assume any MCP server or external tools unless explicitly mentioned by the user.
**Important**: Never assume a default MCP server URL. Always extract the MCP server URL from the user input, if not found extract it from history. Never use GET for MCP requests; always use POST with JSON-RPC 2.0 format. Never execute any actions on an MCP server (e.g., `tools/call`) unless the user explicitly requests the action. Ensure all MCP-related responses are **pure, valid JSON** without any additional text, comments, markdown, or code fences (e.g., ```

json). Ensure all requests include `jsonrpc: "2.0"`, a unique `id`, and correct `method` and `params`.
**JSON Validity for FETCH Actions**: When generating JSON for `fetch` actions, ensure the JSON is valid ! You must always use VALID JSON syntax. Force to check JSON syntax before returning the response.';
    $messages = [
        ['role' => 'system', 'content' => $systemPrompt]
    ];
    // Add conversation history
    foreach ($conversation as $msg) {
        $messages[] = [
            'role' => $msg['role'],
            'content' => $msg['content']
        ];
    }
    // Add current user prompt
    $messages[] = ['role' => 'user', 'content' => $prompt];
    $data = [
        'model' => 'gpt-4.1-mini',
        'messages' => $messages,
        'temperature' => 0.7
    ];
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
    $response = curl_exec($ch);
    if (curl_errno($ch)) {
        curl_close($ch);
        return ['error' => 'cURL error: ' . curl_error($ch)];
    }
    curl_close($ch);
    $responseData = json_decode($response, true);
    if (isset($responseData['error'])) {
        return ['error' => 'API error: ' . $responseData['error']['message']];
    }
    return [
        'content' => $responseData['choices'][0]['message']['content'],
        'role' => 'assistant'
    ];
}
// Initialize conversation history
$conversation = [];
$finalResponse = '';
// Load conversation history from hidden input (if exists)
if ($_SERVER['REQUEST_METHOD'] === 'POST' && isset($_POST['conversation_history'])) {
    $historyJson = $_POST['conversation_history'];
    if (isJson($historyJson)) {
        $conversation = json_decode($historyJson, true);
        // Validate conversation structure
        if (!is_array($conversation)) {
            $conversation = [];
            $finalResponse = "<p class='text-red-500'>Invalid conversation history format.</p>";
        } else {
            // Ensure all messages have required fields
            foreach ($conversation as &$msg) {
                if (!isset($msg['role']) || !isset($msg['content']) || !isset($msg['display'])) {
                    $conversation = [];
                    $finalResponse = "<p class='text-red-500'>Corrupted conversation history.</p>";
                    break;
                }
            }
        }
    } else {
        $finalResponse = "<p class='text-red-500'>Invalid conversation history JSON.</p>";
    }
}
// Main script logic
if ($_SERVER['REQUEST_METHOD'] === 'POST' && isset($_POST['prompt'])) {
    $userInput = trim($_POST['prompt']);
    if (!empty($userInput)) {
        $currentPrompt = $userInput;
        // Add user input to conversation
        $conversation[] = ['role' => 'user', 'content' => $userInput, 'display' => true];
        while (true) {
            // Send current prompt to the assistant
            $response = callChatGpt($currentPrompt, $conversation);
            if (isset($response['error'])) {
                $finalResponse = $response['error'];
                $conversation[] = ['role' => 'assistant', 'content' => $finalResponse, 'display' => true];
                break;
            }
            $assistantResponse = $response['content'];
            // Try to extract JSON from response
            $jsonResponse = extractJsonFromResponse($assistantResponse);
            if ($jsonResponse !== null) {
                if (isset($jsonResponse['error'])) {
                    $finalResponse = $jsonResponse['error'];
                    $conversation[] = ['role' => 'assistant', 'content' => $finalResponse, 'display' => true];
                    break;
                }
                if (isset($jsonResponse['action']) && $jsonResponse['action'] === 'fetch') {
                    $url = $jsonResponse['url'];
                    $postData = isset($jsonResponse['data']) ? $jsonResponse['data'] : null;
                    // Validate JSON-RPC structure
                    if ($postData && (!isset($postData['jsonrpc']) || $postData['jsonrpc'] !== '2.0' ||
                        !isset($postData['id']) || !isset($postData['method']) || !isset($postData['params']))) {
                        $finalResponse = "Invalid JSON-RPC request generated by assistant";
                        $conversation[] = ['role' => 'assistant', 'content' => $finalResponse, 'display' => true];
                        break;
                    }
                    // Fetch URL content
                    $urlContent = fetchUrlContent($url, $postData);
                    if (isset($urlContent['error'])) {
                        $finalResponse = $urlContent['error'];
                        $conversation[] = ['role' => 'assistant', 'content' => $finalResponse, 'display' => true];
                        break;
                    }
                    // Add fetch response to conversation history (hidden from UI)
                    $conversation[] = ['role' => 'assistant', 'content' => $assistantResponse, 'display' => false];
                    // Add fetched content as a hidden user prompt
                    $currentPrompt = "You have sent action:fetch request JSON to load external url. Here is reply:\n" . json_encode($urlContent['content']);
                    $conversation[] = ['role' => 'user', 'content' => $currentPrompt, 'display' => false];
                    continue; // Continue loop with new prompt
                }
            }
            // If response is not a valid JSON, treat as final response
            $finalResponse = $assistantResponse;
            $conversation[] = ['role' => 'assistant', 'content' => $assistantResponse, 'display' => true];
            break;
        }
    } else {
        $finalResponse = "<p class='text-red-500'>Please enter a valid input.</p>";
    }
}
?>
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>ChatGPT with MCP and JSON-RPC Processing</title>
    <script src="https://cdn.tailwindcss.com"></script>
</head>
<body class="bg-gray-100 min-h-screen flex items-center justify-center">
    <div class="max-w-2xl w-full mx-auto p-6 bg-white rounded-lg shadow-lg">
        <h1 class="text-2xl font-bold text-gray-800 mb-6 text-center">ChatGPT 4.1 Mini</h1>
        <form method="post" class="space-y-4">
            <textarea
                name="prompt"
                rows="5"
                class="w-full p-3 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500 resize-y"
                placeholder="Enter your question or MCP request (e.g., 'Use mcp server at https://mcp.example.com to get weather for London')..."
            ></textarea>
            <input
                type="hidden"
                name="conversation_history"
                value="<?php echo htmlspecialchars(json_encode($conversation, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE), ENT_QUOTES, 'UTF-8'); ?>"
            >
            <button
                type="submit"
                class="w-full bg-blue-600 text-white py-2 px-4 rounded-lg hover:bg-blue-700 transition-colors duration-200"
            >
                Submit
            </button>
        </form>
        <?php if (!empty($conversation)): ?>
            <div class="mt-6 space-y-4">
                <h2 class="text-lg font-semibold text-gray-800">Conversation:</h2>
                <?php foreach (array_reverse($conversation) as $msg): ?>
                    <?php if ($msg['display']): ?>
                        <div class="p-4 rounded-lg <?php echo $msg['role'] === 'user' ? 'bg-blue-100' : 'bg-gray-200'; ?>">
                            <p class="font-semibold"><?php echo $msg['role'] === 'user' ? 'You' : 'Assistant'; ?>:</p>
                            <p><?php echo nl2br(htmlspecialchars($msg['content'], ENT_QUOTES, 'UTF-8')); ?></p>
                        </div>
                    <?php endif; ?>
                <?php endforeach; ?>
            </div>
        <?php endif; ?>
        <?php if (!empty($finalResponse) && empty($conversation)): ?>
            <div class="mt-6">
                <?php echo $finalResponse; ?>
            </div>
        <?php endif; ?>
    </div>
</body>
</html>

Testing the MCP Server

Set Up the API Key

Configure the OPENAI_API_KEY environment variable with your OpenAI API key.

Run the Agent

Execute the script and interact with the AI assistant via the provided HTML form.

Example Commands

Send an Email

To send an email, use the command:

"Using the MCP server at https://your-mcp-server-url, send an email to the address xyz@domain.com with the text AAABBB."

The assistant will prompt for the MCP server URL if not provided, or you can include it directly:

"Use the MCP server at https://your-mcp-server-url."

List Available Tools

To display the available tools of the MCP server, use:

"Display the available tools of the MCP server at https://your-mcp-server-url."

This will show the tools available, such as send_email.

Watch the Video Tutorial

For a complete, step-by-step guide in English, including how to install the DotApp PHP framework and set up the MCP server, check out this YouTube video tutorial: https://youtu.be/ED6ubqbJZ3c.

Conclusion

With the DotApp PHP framework, creating an MCP server for AI-driven email sending is straightforward. By following these steps, you can set up a robust server, define custom tools, and integrate with AI agents seamlessly. The modular design of DotApp allows you to extend the MCP server with additional tools as needed.

Try it out, and let me know in the comments how it worked for you! For more details on DotApp, visit https://dotapp.dev.

Happy coding!

Why Try DotApp PHP Framework When Laravel and Symfony Dominate?

DotApp PHP Framework — Mon, 16 Jun 2025 14:14:28 +0000

Why DotApp Framework Is More Than Just Another PHP Framework

In the crowded world of PHP frameworks, names like Laravel, Symfony, Nette, and CodeIgniter often steal the spotlight. But what about DotApp Framework? You might not have heard of it yet, but rest assured, DotApp is no second-rate tool. Built on years of real-world web development experience, DotApp started as a micro-framework in 2014 and evolved into a powerful, developer-friendly ecosystem. In 2024, after a major refactor to polish its code and introduce cleaner facades, it was released to the public. In this article, we’ll show you why DotApp isn’t just another framework—it’s a game-changer that can truly simplify and supercharge your development process.

More Than a Backend Framework

At first glance, DotApp might look like a typical backend framework, offering routing, templating, and database management. But it’s much more than that. DotApp is a comprehensive ecosystem that seamlessly connects PHP and JavaScript, streamlines development, and provides tools that save time while boosting efficiency. Whether you’re a beginner aiming to build a functional app quickly or a seasoned developer seeking a robust, scalable solution, DotApp is designed to make your work easier.

Its core philosophy? Quick setup, maximum flexibility. DotApp lets you dive in with minimal configuration while equipping you with the tools to build even the most complex applications. Optimized for performance and security, it frees you to focus on creating rather than wrestling with technical minutiae.

What DotApp Brings to the Table

DotApp isn’t just about delivering the standard features you’d expect from a modern PHP framework. It offers a unique set of tools that set it apart from other solutions. Here’s a quick rundown of its core features, followed by a deeper look at what makes it truly special:

Lightning-Fast Router: Handles high request volumes with minimal overhead, supporting both static and dynamic routes.
DotApp Bridge: A secure system for PHP-to-JavaScript communication via AJAX, complete with encryption, rate limiting, and built-in security so developers don’t have to worry about it.
Dependency Injection: An intuitive system for managing dependencies, simplifying development.
Middleware: Built-in before and after middleware for flexible request processing.
Hooks: Core hook system with on, off, and trigger functions for extensible logic.
Modular Templating System: A robust templating engine with support for custom renderers, allowing developers to extend functionality easily. All renderer instances share a common utility layer, ensuring universal access.
DotApp CLI: The dotapper tool for managing projects, installing dependencies, updating, creating controllers, or optimizing modules—all from the command line.

These features are just the foundation. What makes DotApp truly unique are its innovative capabilities that other frameworks often lack out of the box.

Key Advantages That Set DotApp Apart

DotApp delivers on its promises of modularity, simplicity, and extensibility in ways that are unmatched. Here are four standout features that make it a must-try for developers:

1. Driver-Based Services for Ultimate Flexibility

DotApp’s services—like DSM (DotApp Session Manager), cache, Databaser (supporting MySQLi, PDO, RAW, and ORM outputs), FastSearch (MeiliSearch, Elasticsearch, OpenSearch, Algolia, Typesense), SMS providers, and more—are built on a driver-based architecture. Each service comes with pre-built drivers for various environments (e.g., Redis, file-based, or database drivers). This unified interface means any module can work with any driver without code changes—no refactoring required.

For example, if your module uses the default $_SESSION driver but your app grows and needs better performance, you can switch to a Redis driver. Your module will work seamlessly without a single code tweak. Developers can even create custom drivers for future engines, ensuring compatibility with existing code. DotApp is built to adapt to future changes, making your applications future-proof.

2. Portable Modularity: Copy and Run

Modularity is a common promise, but many frameworks require complex module customization, configuration, or environment-specific tweaks. DotApp takes a different approach. Its modules are truly portable—copy them (Ctrl+C, Ctrl+V), and they work instantly in any project. Plus, modules use lazy loading, meaning they’re only loaded when needed, saving resources and boosting performance.

Want to add a newsletter system? Copy the module, integrate it into your app, and you’re done. No messy installations or dependency conflicts. Each module is a self-contained unit, including its CSS, JavaScript, templates, and backend logic—no need to scatter assets across your project. This level of portability is something other frameworks rarely offer natively.

3. Effortless Module Optimization

Imagine creating an installation module that downloads a ZIP file, extracts it to /app/modules/, and integrates it into your app. If you’ve optimized your modules, the new module won’t load until it’s registered in /app/modules/modulesAutoLoader.php. Typically, optimization requires running the DotApp CLI command php dotapper.php --optimize-modules. But DotApp goes further—you can optimize modules directly from your app without touching the CLI.

Your installer module can unzip the file and call Module::Optimize() to register the module and optimize performance. This eliminates the need for command-line access, enabling robust, user-friendly module installation interfaces. Unlike other frameworks, DotApp ensures only necessary modules are loaded, keeping your app fast and efficient. This flexibility lets you build applications of any scale—from simple sites to complex SaaS platforms—with ease, much like WordPress’s plugin system.

4. Seamless PHP-JavaScript Integration with DotApp.js

DotApp’s Bridge is a powerhouse, enabling secure and efficient PHP function calls from JavaScript via AJAX. It includes built-in rate limiting, encryption, CSRF protection via FormName, and automatic CRC checks for every request. Unlike other frameworks that require manual API creation or third-party libraries, DotApp provides a native, secure solution straight out of the box.

The DotApp.js frontend library simplifies this further by automatically handling encryption keys from the backend, so developers can focus on building features without worrying about security. Like jQuery, DotApp.js is easily extensible, allowing you to register custom functions. It comes packed with commonly used web app utilities, giving developers a robust toolkit right from the start.

With Bridge and DotApp.js, you can create interactive applications where frontend and backend work in perfect harmony, ideal for modern web apps requiring seamless server-client communication.

Who Is DotApp For?

DotApp is built for developers seeking a balance of simplicity and power. It’s perfect for:

Beginners who want to create functional apps quickly with an easy-to-learn framework, even without prior experience.
Experienced developers needing scalable, secure solutions with ample customization options.
Teams working on multiple projects who want to reuse modules across applications without rewriting code. DotApp’s modularity shines in team settings, as developers can work on separate modules without overwriting each other’s code, keeping projects clean and organized.

Whether you’re building a landing page, an e-commerce platform, or a complex SaaS app, DotApp delivers the tools you need without unnecessary overhead. Need a CMS like Joomla or WordPress? Create a user management module, an installer module for ZIP-based packages, and you’ve got a fully extensible system. Reuse these modules across projects, like invoicing or content management, to save time. For example, if two clients need login and invoicing but one requires scheduling and the other content management, you don’t build two apps—just copy the relevant modules. Updates to core modules or the framework apply seamlessly without affecting custom modules, simplifying maintenance.

Imagine a massive app with 20,000 routes. Split it into 50 modules, and you get clean, maintainable code. Updates target only the necessary parts, and instead of processing 20,000 routes, DotApp handles just 50 module entry filters, keeping performance razor-sharp.

What’s Next for DotApp?

DotApp Framework isn’t standing still. We have exciting plans to make it even more powerful:

dotHUB Module: A fully customizable user management module with login, registration, and a complete admin interface, available for free.
Package Installer Module: A module for installing packages with a central dotHUB repository. Developers can publish modules to dotHUB, and users can install them with a click, WordPress-style, also free.

These upcoming modules will let you build tailored applications by mixing and matching packages from dotHUB, streamlining development further. Share your own modules on dotHUB to contribute to the community. Stay tuned for more updates, as we have plenty in store!

Conclusion: Why Choose DotApp?

DotApp Framework isn’t your average PHP framework. It’s a tool that blends simplicity, innovation, and performance to empower developers. Its portable, lazy-loaded modules, driver-based services, easy optimization via Module::Optimize(), and seamless PHP-JavaScript integration with DotApp.js make it a standout. If you’re looking to accelerate development without sacrificing quality, DotApp is the answer.

Ready to dive in? Visit dotapp.dev or check out the GitHub repository at github.com/dotsystems-sk/DotApp. Join the DotApp community, try it out, and stay tuned for game-changing updates!

Connector Extension for the Frontend Part of DotApp PHP framework (dotapp.js): Seamlessly Connect Nodes in Just a Few Steps

DotApp PHP Framework — Thu, 05 Jun 2025 16:38:18 +0000

Better to see it once than hear about it a hundred times. Here's the video:

This article assumes you are already familiar with the DotApp framework. If not, you can explore it at https://dotapp.dev, where you'll find documentation and usage examples. To avoid explaining the framework setup in every article, I’ll assume you’ve checked it out. So, let’s dive right in.

Since I assume you’ve already worked with the framework, all these concepts should be familiar. Let’s get started. Create a new module—name it whatever you like. Then, create a controller.

In the module’s init file, add a route that points to your controller and a method, let’s say index(). In this method, use the renderer to create a view in your module’s /view/ folder, for example, index.view.php. Render this view in the index() method.

Here’s an example:

public static function index($request, Renderer $renderer) {
    return $renderer->module(self::modulename())->setView("index")->renderView();
}

Now, here comes the magic.

The core frontend library is built into the framework and accessible via .htaccess at:

<script src="/assets/dotapp/dotapp.js"></script>

The connector is available at:

<script src="/assets/dotapp/connector.js"></script>

Once the connector is successfully registered, it triggers the dotapp-connector event. This ensures no issues arise if a user incorrectly orders scripts or if a script loads slowly.

Now, a bit of theory on how to load libraries robustly, preparing for potential errors:

<script>
    (function() {
        function runMe($dotapp) {
            // Your code here
        }

        if (window.$dotapp && window.$dotapp().isSet(window.$dotapp().connector)) {
            runMe(window.$dotapp);
        } else {
            window.addEventListener('dotapp-connector', function() {
                runMe(window.$dotapp);
            }, { once: true });
        }
    })();
</script>

As you can see, the runMe function only runs if dotapp is loaded and the connector extension is initialized. If not, it sets a listener to wait for initialization. This is a good practice I recommend following when working with the connector. If you only need the dotapp library, replace the listener with the dotapp event.

That’s enough on best practices. Now, the exciting part. Copy the following code into the index view of your module. This is the code shown in the video demonstrating how it works.

Here’s the code:

<!DOCTYPE html>
<html lang="sk">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Drag-and-Drop Connectable Elements with Multiple Ports</title>
  <style>
    #vysledok {
        color:rgb(72, 255, 0);
        font-size: 2rem;
    }

    :root {
      --primary-color: #6B48FF;
      --secondary-color: #00DDEB;
      --background-color: #1A1A2E;
      --node-bg: rgba(255, 255, 255, 0.1);
      --node-border: rgba(255, 255, 255, 0.2);
      --port-color: #00DDEB;
      --port-hover: #FF6B6B;
      --connection-color: #FFFFFF;
      --temp-connection-color: rgba(255, 255, 255, 0.5);
      --text-color: #E0E0E0;
      --shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
      --glow: 0 0 10px rgba(107, 72, 255, 0.5);
    }

    body {
      background: linear-gradient(135deg, #1A1A2E 0%, #16213E 100%);
      font-family: 'Inter', sans-serif;
      color: var(--text-color);
      margin: 0;
      padding: 20px;
      display: flex;
      flex-direction: row;
      gap: 20px;
      min-height: 100vh;
    }

    #container {
      display: flex;
      flex-direction: row;
      gap: 20px;
      width: 100%;
      /*max-width: 1200px;*/
    }

    #sidebar .node {
      position: relative;
      width: 20%;
      height: 130px;
      margin: 10px auto;
      cursor: grab;
      background: var(--node-bg);
      border: 1px solid var(--node-border);
      border-radius: 12px;
      backdrop-filter: blur(8px);
      box-shadow: var(--shadow);
      transition: transform 0.3s ease, box-shadow 0.3s ease, opacity 0.3s ease;
    }

    #sidebar .node:active {
      cursor: grabbing;
    }

    #sidebar .node:hover {
      transform: translateY(-4px);
      box-shadow: var(--shadow), var(--glow);
      opacity: 1;
    }

    #canvas {
      position: relative;
      width: 78%;
      height: 600px;
      background: rgba(255, 255, 255, 0.05);
      border: 1px solid var(--node-border);
      border-radius: 16px;
      overflow: auto;
      resize: both;
      min-width: 400px;
      min-height: 300px;
      box-shadow: var(--shadow);
      backdrop-filter: blur(10px);
      transition: all 0.3s ease;
    }

    #canvas:hover {
      box-shadow: 0 12px 48px rgba(0, 0, 0, 0.4);
    }

    .node {
      position: absolute;
      width: 160px;
      height: 130px;
      background: var(--node-bg);
      border: 1px solid var(--node-border);
      border-radius: 12px;
      backdrop-filter: blur(8px);
      user-select: none;
      padding: 0;
      box-shadow: var(--shadow);
      transition: transform 0.3s ease, box-shadow 0.3s ease;
    }

    .node:hover {
      transform: translateY(-4px);
      box-shadow: var(--shadow), var(--glow);
    }

    .node-header {
      background: linear-gradient(90deg, var(--primary-color), var(--secondary-color));
      color: var(--text-color);
      padding: 10px;
      font-weight: 600;
      border-top-left-radius: 12px;
      border-top-right-radius: 12px;
      cursor: move;
      text-align: center;
      font-size: 14px;
      letter-spacing: 0.5px;
      text-transform: uppercase;
    }

    .content {
      padding: 12px;
      font-size: 12px;
      color: var(--text-color);
      overflow: auto;
      height: calc(100% - 34px);
      display: flex;
      flex-direction: column;
      gap: 8px;
    }

    .content input,
    .content select,
    .content button {
      background: rgba(255, 255, 255, 0.1);
      border: 1px solid var(--node-border);
      border-radius: 8px;
      color: var(--text-color);
      padding: 6px;
      font-size: 12px;
      transition: all 0.3s ease;
    }

    .content input:focus,
    .content select:focus,
    .content button:hover {
      background: rgba(255, 255, 255, 0.2);
      border-color: var(--secondary-color);
      outline: none;
    }

    .port {
      position: absolute;
      width: 14px;
      height: 14px;
      background: var(--port-color);
      border-radius: 50%;
      cursor: pointer;
      transition: transform 0.3s ease, background 0.3s ease;
      box-shadow: 0 0 8px rgba(0, 221, 235, 0.5);
    }

    .port:hover {
      background: var(--port-hover);
      transform: scale(1.3);
      box-shadow: 0 0 12px rgba(255, 107, 107, 0.7);
    }

    .port.input {
      left: -7px;
      transform: translateY(-50%);
    }

    .port.output {
      right: -7px;
      transform: translateY(-50%);
    }

    svg {
      position: absolute;
      top: 0;
      left: 0;
      width: 100%;
      height: 100%;
      pointer-events: none;
    }

    .connection {
      stroke: var(--connection-color);
      stroke-width: 3;
      fill: none;
      stroke-linecap: round;
      transition: stroke 0.3s ease;
    }

    .connection:hover {
      stroke: var(--secondary-color);
    }

    .temp-connection {
      stroke: var(--temp-connection-color);
      stroke-width: 3;
      stroke-dasharray: 6, 6;
      fill: none;
      stroke-linecap: round;
    }

    button {
      margin: 12px;
      padding: 10px 20px;
      background: linear-gradient(90deg, var(--primary-color), var(--secondary-color));
      color: var(--text-color);
      border: none;
      border-radius: 8px;
      cursor: pointer;
      font-weight: 600;
      text-transform: uppercase;
      letter-spacing: 0.5px;
      transitions: all 0.3s ease;
      box-shadow: var(--shadow);
    }

    button:hover {
      background: linear-gradient(90deg, var(--secondary-color), var(--primary-color));
      transform: translateY(-2px);
      box-shadow: var(--shadow), var(--glow);
    }

    button:active {
      transform: translateY(0);
      box-shadow: var(--shadow);
    }

    #output {
      margin: 12px;
      padding: 12px;
      background: rgba(255, 255, 255, 0.1);
      border: 1px solid var(--node-border);
      border-radius: 8px;
      max-height: 200px;
      overflow: auto;
      color: var(--text-color);
      font-size: 12px;
      line-height: 1.5;
      backdrop-filter: blur(8px);
      box-shadow: var(--shadow);
    }

    #sidebar {
      width: 200px;
      background: rgba(255, 255, 255, 0.05);
      border: 1px solid var(--node-border);
      border-radius: 16px;
      padding: 10px;
      box-shadow: var(--shadow);
      backdrop-filter: blur(10px);
      overflow-y: auto;
      display: flex;
      flex-direction: column;
      gap: 10px;
    }

    #sidebar .node {
      width: 160px;
      height: 130px;
      margin: 10px auto;
      cursor: grab;
      background: var(--node-bg);
      border: 1px solid var(--node-border);
      border-radius: 12px;
      backdrop-filter: blur(8px);
      box-shadow: var(--shadow);
      transition: transform 0.3s ease, box-shadow 0.3s ease, opacity 0.3s ease;
      position: relative;
    }

    #sidebar .node:active {
      cursor: grabbing;
    }

    #sidebar .node:hover {
      transform: translateY(-4px);
      box-shadow: var(--shadow), var(--glow);
      opacity: 1;
    }

    .close-button {
      position: absolute;
      right: 8px;
      top: 8px;
      cursor: pointer;
      font-size: 16px;
      color: var(--port-hover);
      transition: transform 0.3s ease, color 0.3s ease;
    }

    .close-button:hover {
      transform: scale(1.2);
      color: var(--secondary-color);
    }

    #grid {
        opacity: 1;
        transition: opacity 0.3s ease-in-out;
        pointer-events: none;
    }

    #grid.hidden {
        opacity: 0;
    }
  </style>
</head>
<body>
  <div id="container">
    <div id="sidebar"></div>
    <div id="canvas"></div>
  </div>
  <script src="/assets/dotapp/dotapp.js"></script>
  <script src="/assets/dotapp/connector.js"></script>
  <script>
    (function() {
        function runMe($dotapp) {
            const connector = $dotapp('#canvas').connector({
                grid: true,
                gridX: 20,
                gridY: 20
                /*rules: {
                    'out-number-1': ['in-sum-1', 'in-sum-2', 'in-sum-3', 'in-sum2-1', 'in-sum2-2', 'in-sum2-3'],
                    'out-number-2': ['in-sum-1', 'in-sum-2', 'in-sum-3', 'in-sum2-1', 'in-sum2-2', 'in-sum2-3'],
                    'out-number-3': ['in-sum-1', 'in-sum-2', 'in-sum-3', 'in-sum2-1', 'in-sum2-2', 'in-sum2-3'],
                    'out-sum-1': ['in-display-1','in-sum2-1', 'in-sum2-2', 'in-sum2-3']
                }*/
            });

            const predefinedNodes = [
                {
                    title: 'Number 1',
                    id: 'node-number-1',
                    content: 'Output: 5',
                    inputs: [],
                    outputs: [{ id: 'out-number-1' }],
                    callback: (inputs, outputId) => {
                        console.log('Number 1:', inputs, outputId);
                        return 5;
                    }
                },
                {
                    title: 'Number 2',
                    id: 'node-number-2',
                    content: 'Output: 6',
                    inputs: [],
                    outputs: [{ id: 'out-number-2' }],
                    callback: (inputs, outputId) => {
                        console.log('Number 2:', inputs, outputId);
                        return 6;
                    }
                },
                {
                    title: 'Number 3',
                    id: 'node-number-3',
                    content: 'Output: 10',
                    inputs: [],
                    outputs: [{ id: 'out-number-3' }],
                    callback: (inputs, outputId) => {
                        console.log('Number 3:', inputs, outputId);
                        return 10;
                    }
                },
                {
                    title: 'Number 4',
                    id: 'node-number-4',
                    content: '<input type="text" value="8">',
                    inputs: [],
                    outputs: [{ id: 'out-number-4' }],
                    callback: (inputs, outputId) => {
                        const input = $dotapp("#node-number-4 INPUT");
                        const element = $dotapp(input).first(false);
                        if (!element.__listenerAdded) {
                            element.__listenerAdded = true;
                            $dotapp(input).on("change", function() {
                                connector.trigger("connectionchange", {});
                            });
                        }                        
                        const result = input.val();
                        if (result === "" || result === null || result === undefined) {
                            return connector.halt('Empty input');
                        }

                        // Verify if the result is a valid number (integer or decimal)
                        const isValidNumber = !isNaN(result) && /^-?\d*\.?\d+$/.test(result);
                        if (!isValidNumber) {
                            return connector.halt('Invalid number or contains letters');
                        }
                        return parseFloat(result);
                    }
                },
                {
                    title: 'Adder',
                    id: 'node-sum',
                    content: 'Adds inputs',
                    inputs: [
                        { id: 'in-sum-1', required: true },
                        { id: 'in-sum-2', required: true },
                        { id: 'in-sum-3', required: false }
                    ],
                    outputs: [{ id: 'out-sum-1' }],
                    callback: (inputs, outputId) => {
                        console.log('Adder:', inputs, outputId);
                        // Check if any required inputs (in-sum-1, in-sum-2) are missing or halted
                        const requiredInputs = inputs.slice(0, 2); // First two inputs are required
                        if (requiredInputs.some(input => input.value === null || connector.isConnectorHalt(input.value))) {
                            return connector.halt('missing_required_input');
                        }
                        // Sum all provided inputs (including optional in-sum-3 if connected)
                        const validInputs = inputs.filter(input => input.value !== null && !connector.isConnectorHalt(input.value));
                        return validInputs.reduce((sum, input) => sum + input.value, 0);
                    }
                },
                {
                    title: 'Adder2',
                    id: 'node-sum2',
                    content: 'Adds inputs',
                    inputs: [
                        { id: 'in-sum2-1', required: true },
                        { id: 'in-sum2-2', required: true },
                        { id: 'in-sum2-3', required: false }
                    ],
                    outputs: [{ id: 'out-sum2-1' }],
                    callback: (inputs, outputId) => {
                        console.log('Adder:', inputs, outputId);
                        // Check if any required inputs (in-sum-1, in-sum-2) are missing or halted
                        const requiredInputs = inputs.slice(0, 2); // First two inputs are required
                        if (requiredInputs.some(input => input.value === null || connector.isHalted(input.value))) {
                            return connector.halt('missing_required_input');
                        }
                        // Sum all provided inputs (including optional in-sum-3 if connected)
                        const validInputs = inputs.filter(input => input.value !== null && !connector.isConnectorHalt(input.value));
                        return validInputs.reduce((sum, input) => sum + input.value, 0);
                    }
                },
                {
                    title: 'Multiplier',
                    id: 'node-adder',
                    content: 'Multiplies inputs',
                    inputs: [
                        { id: 'in-adder-1', required: true },
                        { id: 'in-adder-2', required: true }
                    ],
                    outputs: [{ id: 'out-adder-1' }],
                    callback: (inputs, outputId) => {
                        console.log('Multiplier:', inputs, outputId);
                        // Check if any required inputs (in-multiplier-1, in-multiplier-2) are missing or halted
                        const requiredInputs = inputs.slice(0, 2); // First two inputs are required
                        if (requiredInputs.some(input => input.value === null || connector.isHalted(input.value))) {
                            return connector.halt('missing_required_input');
                        }
                        // Multiply all provided inputs
                        const validInputs = inputs.filter(input => input.value !== null && !connector.isConnectorHalt(input.value));
                        return validInputs.reduce((product, input) => product * input.value, 1);
                    }
                },
                {
                    title: 'Display LIVE',
                    id: 'node-display2',
                    content: 'Result: <b id="vysledok">X</b>',
                    inputs: [{ id: 'in-display-2', required: true }],
                    outputs: [],
                    callback: (inputs, outputId) => {
                        if (inputs[0].value === null || connector.isHalted(inputs[0].value)) {
                            $dotapp('#node-display2 #vysledok').html("X");
                            return connector.halt('missing_required_input');
                        }
                        if (inputs[0].value === null) inputs[0].value = "X";
                        $dotapp('#node-display2 #vysledok').html(inputs[0].value);
                        return inputs[0].value;
                    }
                }
            ];

            connector.nodes({
                sidebar: '#sidebar',
                nodes: predefinedNodes,
                autoLoad: false // Changed to false to prevent auto-loading nodes onto canvas
            });

            // Example of how to store state
            function saveState() {
                const state = connector.save();
                document.getElementById('output').textContent = JSON.stringify(state, null, 2);
                localStorage.setItem('connectorState', JSON.stringify(state));
            }

            // Example of how to laod saved state
            function loadState() {
                const savedState = localStorage.getItem('connectorState');
                let state;
                if (savedState) {
                    state = JSON.parse(savedState);
                } 
                state.nodes.forEach(node => {
                    node.callback = predefinedNodes.find(n => n.id === node.originalConfig.id)?.callback || (() => null);
                });
                connector.load(state);
                document.getElementById('output').textContent = 'State loaded';
            }

            // Example of how to get route if you want somehow store it or pass it to backend for further processing
            function getRoute() {
                console.log('Connections:', connector.getConnections());
                console.log('Nodes:', connector.getNodes());
                const result = connector.route('node-display');
                document.getElementById('output').textContent = result ? JSON.stringify(result.path, null, 2) : 'Route does not exist';
            }

            // Example of how to run route in this example it is route of node-display2 
            function runRoute() {
                console.log('Running route...');
                const result = connector.route('node-display2');
                if (result) {
                    const output = result.run();
                    console.log('Route output:', output);
                    document.getElementById('output').textContent = connector.isConnectorHalt(output) ? `Halted: ${output.reason}` : `Result: ${output}`;
                } else {
                    document.getElementById('output').textContent = 'Route does not exist';
                }
            }

            // Example of how to make autocalculation on routes changes
            connector.on("connectionchange", (detail) => {
                console.log('SPUSTENY CONNECTION CHANGE:', detail);
                const result = connector.route('node-display2');
                if (result) {
                    const output = result.run();
                }
            });
        }

        if (window.$dotapp && window.$dotapp().isSet(window.$dotapp().connector)) {
            runMe(window.$dotapp);
        } else {
            window.addEventListener('dotapp-connector', function() {
                runMe(window.$dotapp);
            }, { once: true });
        }
    })();
</script>
</body>
</html>

The code provides enough examples to understand how to create nodes, their types, and how to define them easily. Experiment with this code and modify it to better understand how it works.

That’s all for today’s article, aimed at advanced users already familiar with the DotApp framework.

Previous Articles on the DotApp PHP Framework:

As you can see, the DotApp Framework is a truly high-quality, secure, and robust framework, easily extensible and built on the philosophy of modularity—create once, reuse in any DotApp project.

How to Send Emails and Save Them in the Sent Folder with DotApp PHP Framework

DotApp PHP Framework — Tue, 03 Jun 2025 09:42:42 +0000

Intro

This article assumes you're familiar with the DotApp PHP framework. If not, visit https://dotapp.dev for documentation and examples. To keep things concise, I’ll assume you’ve reviewed the setup and basics. Let’s dive in.

Sending emails is a common requirement in web applications. PHP has built-in libraries for this, but what if you need to save emails to the Sent folder for tracking? In this tutorial, we’ll explore how to send emails (with or without attachments) and save them using the DotApp PHP framework, leveraging its Emailer library and Email facade.

Setting Up the EmailTest Module

Create a new module called EmailTest by running:

php dotapper.php --create-module=EmailTest

Configuring SMTP and IMAP

In the app/config.php file, add the SMTP and IMAP configurations for email functionality:

// SMTP configuration for sending emails
Config::email("testAcc", "smtp", [
    "host" => "your.mail-server.com",
    "port" => 587,
    "timeout" => 30,
    "secure" => "tls",
    "username" => "no-reply@dotapp.dev",
    "password" => "password",
    "from" => "no-reply@dotapp.dev" // Email sender address
]);

// IMAP configuration for saving emails to the Sent folder (optional)
Config::email("testAcc", "imap", [
    "host" => "your.mail-server.com",
    "port" => 993,
    "timeout" => 30,
    "secure" => "ssl",
    "username" => "no-reply@dotapp.dev",
    "password" => "password"
]);

The testAcc is the account name for this configuration. You could use no-reply@dotapp.dev, but I chose testAcc for clarity.

Adding Email Routes

Open the /app/modules/EmailTest/module.init.php file and add the following import:

use Dotsystems\App\Parts\Email;

Then, inside the initialize function, add these routes to handle email sending:

Router::get("/testemail/send", function($request, $response) {
    $subject = 'DotApp Emailer';
    $body = '<h1>Hello!</h1><p>This is an <b>HTML</b> email sent using the Emailer library.</p>';
    $result = Email::send('testAcc', 'info@dotsystems.sk', $subject, $body);
    return print_r($result, true);
}, Router::STATIC_ROUTE);

Router::get("/testemail/send-attachment", function($request, $response) {
    $subject = 'DotApp Emailer';
    $body = '<h1>Hello!</h1><p>This is an <b>HTML</b> email sent using the Emailer library.</p>';
    $attachments = [__ROOTDIR__ . '/favicon.ico'];
    $result = Email::send('testAcc', 'info@dotsystems.sk', $subject, $body, null, $attachments);
    return print_r($result, true);
}, Router::STATIC_ROUTE);

Router::get("/testemail/send-save", function($request, $response) {
    $subject = 'DotApp Emailer';
    $body = '<h1>Hello!</h1><p>This is an <b>HTML</b> email sent using the Emailer library.</p>';
    $attachments = [__ROOTDIR__ . '/favicon.ico'];
    $result = Email::sendAndSave('Sent', 'testAcc', 'info@dotsystems.sk', $subject, $body, null, $attachments);
    return print_r($result, true);
}, Router::STATIC_ROUTE);

Understanding the Email Functions

The Email facade provides two key functions:

send($account, $to, $subject, $body, $contentType = null, $attachments = [], $cc = [], $bcc = [])
sendAndSave($folder, $account, $to, $subject, $body, $contentType = null, $attachments = [], $cc = [], $bcc = [])

Parameters:

$account: The account name, e.g., testAcc.
$to: The recipient(s). Can be a single email, a comma-separated string (e.g., "email1@email.com,email2@email.com"), or an array (e.g., ['email1@email.com', 'email2@email.com']).
$subject: The email subject.
$body: The email body content.
$contentType: Defaults to text/html if null.
$attachments: An array of file paths for attachments.
$cc: An array of email addresses for carbon copy recipients.
$bcc: An array of email addresses for blind carbon copy recipients.
$folder (for sendAndSave): The folder where the email will be saved, e.g., "Sent".

Testing the Routes

Visit these URLs in your browser to test the functionality:

/testemail/send: Sends a basic email.
/testemail/send-attachment: Sends an email with an attachment.
/testemail/send-save: Sends an email with an attachment and saves it to the Sent folder.

Building a Reusable Users Module with DotApp PHP Framework ( + 2FA )

DotApp PHP Framework — Mon, 02 Jun 2025 15:17:37 +0000

dotApp PHP framework

DotApp PHP framework project web: https://dotapp.dev
DotApp PHP Framework download at: https://github.com/dotsystems-sk/DotApp

Users Module Example

This advanced example demonstrates how to create a portable Users module in the DotApp PHP framework, implementing user registration, login, and two-factor authentication (2FA) with QR codes and email verification codes. The module integrates with databases, uses middleware for authentication checks, and employs secure form handling with dotapp.js. Designed for reusability, the module can be copied to any DotApp project, saving significant development time for administrative authentication systems. This aligns with DotApp’s philosophy: build a robust module once and reuse it across projects, streamlining development and ensuring consistency.

Prerequisites

Important: This example builds on the secure forms example, which introduces basic form handling in DotApp. To understand the context and setup, please review the following documentation before proceeding:

Secure Forms with dotapp.js

The secure forms example covers foundational concepts like form creation and dotapp.js usage, which are assumed here. You should follow the examples in order, starting from the first, to grasp the full context.

Module Creation

Unlike previous examples that used the Examples module, this example creates a standalone Users module to ensure portability across projects. The module includes its own controllers, middleware, views, and assets, making it independent of user configurations.

Create the module and its components using the DotApper CLI:

php dotapper.php --create-module=Users
php dotapper.php --module=Users --create-controller=CreateUser
php dotapper.php --module=Users --create-controller=Login
php dotapper.php --module=Users --create-middleware=AuthTest

These commands generate:

A Users module at /app/modules/Users.
A CreateUser controller at /app/modules/Users/Controllers/CreateUser.php for registration.
A Login controller at /app/modules/Users/Controllers/Login.php for login and 2FA.
An AuthTest middleware at /app/modules/Users/Middleware/AuthTest.php for authentication checks.

Database Setup

The Users module requires database tables for user management. Since users can configure custom database prefixes in DotApp, a universal SQL file cannot be provided. Instead, use the DotApper CLI to generate a tailored SQL file:

php dotapper.php --prepare-database

This command creates an SQL file with tables using the user’s configured prefix. Currently, DotApper does not automatically import the file into the database (a feature planned for the future), so you must manually import it into your database to create the necessary tables.

Configuration

Configure the database connection in /app/config.php to ensure the module can interact with the database:

Config::db("driver", "pdo");
Config::addDatabase("main", "127.0.0.1", "Username", "Password", "DBNAME", "UTF8", "MYSQL", "pdo");

Replace Username, Password, and DBNAME with your database credentials. This sets up a PDO driver connection to the database named "main" with UTF-8 encoding.

The Users module is highly configurable via Config::module in /app/config.php, keeping settings external for portability. Here’s how to set all options:

// Enable/disable autologin (Remember me)
Config::module("Users", "autologin", true);

// Default URL for the logged-in dashboard
Config::module("Users", "defaultUrl", "/users");

// Enable/disable user registration
Config::module("Users", "allowRegistration", true);

// Registration URL
Config::module("Users", "registerUrl", "/users/register");

// Enable/disable login functionality
Config::module("Users", "allowLogin", true);

// Login URL
Config::module("Users", "loginUrl", "/users/login");

// 2FA verification URL
Config::module("Users", "loginUrl2fa", "/users/login/2fa");

// Logout URL
Config::module("Users", "logoutUrl", "/users/logout");

// Email-based 2FA URL
Config::module("Users", "loginUrl2faEmail", "/users/login/2fa-email");

These settings let you:

Toggle registration (allowRegistration) and login (allowLogin).
Customize URLs (defaultUrl, registerUrl, etc.).
Enable/disable autologin (autologin).

Settings in /app/config.php persist during module updates.

Controllers

The Users module includes two controllers: CreateUser for registration and Login for login and 2FA processes. Below are the complete code listings for both controllers, along with descriptions of their methods.

CreateUser Controller

Located at /app/modules/Users/Controllers/CreateUser.php, this controller handles user registration.

<?php
namespace Dotsystems\App\Modules\Users\Controllers;
use Dotsystems\App\DotApp;
use Dotsystems\App\Parts\Middleware;
use Dotsystems\App\Parts\Response;
use Dotsystems\App\Parts\Renderer;
use Dotsystems\App\Parts\Router;
use Dotsystems\App\Parts\Validator;
use Dotsystems\App\Parts\TOTP;
use Dotsystems\App\Parts\Auth;
use Dotsystems\App\Modules\Users\Module;

class CreateUser extends \Dotsystems\App\Parts\Controller {

    private static function seoVar() {
        $seo = [];
        $seo['title'] = "DotApp Example: Advanced User Authentication with 2FA and QR Codes";
        $seo['description'] = "Explore how to build a secure user authentication module in the DotApp PHP framework, featuring registration, login, two-factor authentication (2FA) with QR codes and email, and a reusable module design for easy integration across projects.";
        $seo['keywords'] = "DotApp framework, user authentication, two-factor authentication, 2FA, QR codes, PHP module, reusable module, secure login, registration, middleware, DotApp philosophy";
        return $seo;
    }

    public static function url() {
        $url = [];
        $url['defaultUrl'] = Module::getStatic("defaultUrl");
        $url['loginUrl'] = Module::getStatic("loginUrl");
        $url['loginUrl2fa'] = Module::getStatic("loginUrl2fa");
        $url['loginUrl2faEmail'] = Module::getStatic("loginUrl2faEmail");
        $url['registerUrl'] = Module::getStatic("registerUrl");
        $url['logoutUrl'] = Module::getStatic("logoutUrl");
        return $url;
    }

    public static function register($request, Renderer $renderer) {
        $js = '<script src="/assets/modules/Users/users.js"></script>';
        $css = '<link rel="stylesheet" href="/assets/modules/Users/users.css">';
        $viewcode = $renderer->module(self::modulename())
                    ->setView("index")
                    ->setViewVar("seo",static::seoVar())
                    ->setViewVar("url",static::url())
                    ->setViewVar("js",$js)
                    ->setViewVar("css",$css)
                    ->setLayout("register")->renderView();
        return $viewcode;
    }

    public static function registerPost($request, Renderer $renderer) {
        if ($request->crcCheck()) {
            $answer = $request->form(['POST'],"CSRF", function($request) {
                // User registration logic
                $answer = [];
                $email = $request->data(true)['data']['email'];
                if (Validator::isEmail($email)) {
                    // $username is required, so even if we plan to use email for login, it must be filled.
                    $username = md5($email.bin2hex(random_bytes(16)));
                    $password = $request->data(true)['data']['password'];
                    if (Validator::isStrongPassword($password)) {
                        // Create the user
                        $userSettings = [];
                        $userSettings['tfa_email'] = 1; // Require 2FA, enable email method
                        $userSettings['tfa_auth'] = 1; // Require 2FA, enable authenticator app method
                        $userSettings['tfa_auth_secret'] = TOTP::newSecret(); // Generate new secret
                        $userSettings['tfa_auth_secret_confirmed'] = 0; // 2FA not yet confirmed
                        // Create the user
                        $user = Auth::createUser($username, $password, $email, $userSettings);
                        switch ($user['error']) {
                            case 0:
                                $answer['code'] = 200;
                                $body = [];
                                $body['status'] = 1;
                                $body['message'] = "User registered successfully! You can now log in using your email and password.";
                                $body['redirectTo'] = Module::getStatic("loginUrl");
                                $answer['body'] = $body;
                                break;
                            case 1:
                                $body = [];
                                $body['status'] = 0;
                                $body['error'] = 1;
                                $body['errorNo'] = 3;
                                $body['message'] = "Email already exists in the database!";
                                $answer['code'] = 200;
                                $answer['body'] = $body;
                                break;
                            case 99:
                                $body = [];
                                $body['status'] = 0;
                                $body['error'] = 1;
                                $body['errorNo'] = 4;
                                $body['message'] = "Unknown error, please try again later!";
                                $answer['code'] = 200;
                                $answer['body'] = $body;
                                break;
                        }
                    } else {
                        $body = [];
                        $body['status'] = 0;
                        $body['error'] = 1;
                        $body['errorNo'] = 2;
                        $body['message'] = "Please enter a strong password!";
                        $answer['code'] = 200;
                        $answer['body'] = $body;
                    }
                } else {
                    $body = [];
                    $body['status'] = 0;
                    $body['error'] = 1;
                    $body['errorNo'] = 1;
                    $body['message'] = "Please enter a valid email address!";
                    $answer['code'] = 200;
                    $answer['body'] = $body;
                }
                return $answer;
            }, function() {
                // CSRF check failed
                $body = [];
                $body['status'] = 0;
                $body['error'] = 1;
                $body['errorNo'] = 99;
                $body['message'] = "CSRF check failed!";
                $answer['code'] = 403;
                $answer['body'] = $body;
                return $answer;
            });
            return DotApp::DotApp()->ajaxReply($answer['body'], $answer['code']);
        }
    }

}
?>

Method Descriptions:

seoVar(): Defines SEO metadata for registration pages, tailored to reflect the module’s authentication and modularity focus.
url(): Returns an array of configurable URLs (e.g., login, registration, logout) from the module’s static settings, ensuring flexibility across projects.
register(): Renders the registration form using the index view and register layout, passing SEO, URLs, CSS, and JavaScript.
registerPost(): Handles form submission, validating email and password strength. It creates a user with 2FA settings (email and authenticator app enabled) and generates a TOTP secret. Error handling includes:
- Email already exists (errorNo: 3).
- Weak password (errorNo: 2).
- Invalid email (errorNo: 1).
- CSRF failure (errorNo: 99).

Login Controller

Located at /app/modules/Users/Controllers/Login.php, this controller manages login, 2FA, and logout.

<?php
namespace Dotsystems\App\Modules\Users\Controllers;
use Dotsystems\App\DotApp;
use Dotsystems\App\Parts\Middleware;
use Dotsystems\App\Parts\Response;
use Dotsystems\App\Parts\Renderer;
use Dotsystems\App\Parts\Router;
use Dotsystems\App\Parts\Validator;
use Dotsystems\App\Parts\TOTP;
use Dotsystems\App\Parts\QR;
use Dotsystems\App\Parts\Auth;
use Dotsystems\App\Parts\Config;
use Dotsystems\App\Parts\DB;
use Dotsystems\App\Modules\Users\Module;

class Login extends \Dotsystems\App\Parts\Controller {

    public static function drop($request, Renderer $renderer) {
        return false;
    }

    public static function index($request, Renderer $renderer) {
        $viewcode = $renderer->module(self::modulename())
                    ->setView("index")
                    ->setViewVar("seo",static::seoVar())
                    ->setViewVar("url",self::call("Users:CreateUser@url"))
                    ->setViewVar("email",Auth::attributes()['email'])
                    ->setLayout("index.logged")->renderView();
        return $viewcode;
    }

    private static function seoVar() {
        $seo = [];
        $seo['title'] = "DotApp Example: Advanced User Authentication with 2FA and QR Codes";
        $seo['description'] = "Explore how to build a secure user authentication module in the DotApp PHP framework, featuring registration, login, two-factor authentication (2FA) with QR codes and email, and a reusable module design for easy integration across projects.";
        $seo['keywords'] = "DotApp framework, user authentication, two-factor authentication, 2FA, QR codes, PHP module, reusable module, secure login, registration, middleware, DotApp philosophy";
        return $seo;
    }

    public static function login($request, Renderer $renderer) {
        if (Auth::loggedStage() == 2) {
            header("Location: ".Module::getStatic("loginUrl2fa"));
            exit();
        }
        if (Auth::isLogged()) {
            header("Location: ".Module::getStatic("defaultUrl"));
            exit();
        }
        $viewcode = $renderer->module(self::modulename())
                    ->setView("index")
                    ->setViewVar("seo",static::seoVar())
                    ->setViewVar("url",self::call("Users:CreateUser@url"))
                    ->setLayout("login")->renderView();
        return $viewcode;
    }

    public static function loginPost($request) {
        if (Auth::loggedStage() == 2 || Auth::isLogged()) {
            $answer['code'] = 200;
            $body = [];
            $body['status'] = 0;
            $body['error'] = 1;
            $body['errorNo'] = 1;
            $body['message'] = "User is already logged in or two-factor authentication is not completed. Please log out and try again.";
            $body['redirectTo'] = Module::getStatic("loginUrl");
            $answer['body'] = $body;
        } else {
            if ($request->crcCheck()) {
                $answer = $request->form(['POST'],"CSRF", function($request) {
                    $answer = [];
                    $email = $request->data(true)['data']['email'];
                    if (Validator::isEmail($email)) {
                        $data = array();
                        $data['email'] = $email;
                        $data['password'] = $request->data(true)['data']['password'];
                        $login = Auth::login($data,Module::getStatic("autologin"));
                        if ($login['logged'] == true) {
                            $body = [];
                            if (Auth::loggedStage() == 2) {
                                $body['redirectTo'] = Module::getStatic("loginUrl2fa");
                            }
                            if (Auth::isLogged()) {
                                $body['redirectTo'] = Module::getStatic("defaultUrl");
                            }
                            $body['status'] = 1;
                            $body['error'] = 0;
                            $body['message'] = "Login successful.";
                            $answer['code'] = 200;
                            $answer['body'] = $body;
                            return $answer;
                        } else {
                            $body = [];
                            $body['status'] = 0;
                            $body['error'] = 1;
                            $body['errorNo'] = 2;
                            $body['message'] = "Invalid email or password.";
                            $answer['code'] = 200;
                            $answer['body'] = $body;
                            return $answer;
                        }
                    } else {
                        $body = [];
                        $body['status'] = 0;
                        $body['error'] = 1;
                        $body['errorNo'] = 1;
                        $body['message'] = "Please enter a valid email address!";
                        $answer['code'] = 200;
                        $answer['body'] = $body;
                        return $answer;
                    }
                });
            }
        }
        return DotApp::DotApp()->ajaxReply($answer['body'], $answer['code']);
    }

    public static function login2fa($request, Renderer $renderer) {
        $userAttr = Auth::attributes();
        if ($userAttr['tfa_auth'] == 1 && $userAttr['tfa_auth_secret_confirmed'] == 0) {
            return self::confirmTFA_QR($request, $renderer);
        } else if ($userAttr['tfa_auth'] == 1 && $userAttr['tfa_auth_secret_confirmed'] == 1 && Auth::loggedStage() == 2) {
            return self::confirmTFA($request, $renderer);
        }
        header("Location: ".Module::getStatic("loginUrl"));
        exit();
    }

    public static function login2faEmail($request, Renderer $renderer) {
        $userAttr = Auth::attributes();
        if ($userAttr['tfa_auth'] == 1 && $userAttr['tfa_auth_secret_confirmed'] == 0) {
            header("Location: ".Module::getStatic("loginUrl2fa"));
            exit();
        } else if ($userAttr['tfa_auth'] == 1 && $userAttr['tfa_auth_secret_confirmed'] == 1 && Auth::loggedStage() == 2) {
            $viewcode = $renderer->module(self::modulename())
                        ->setView("index")
                        ->setViewVar("seo",static::seoVar())
                        ->setViewVar("url",self::call("Users:CreateUser@url"))
                        ->setViewVar("emailcode",Auth::tfaEmail())
                        ->setLayout("2fa.email")->renderView();
            return $viewcode;
        }
        header("Location: ".Module::getStatic("loginUrl"));
        exit();
    }

    public static function confirmTFA_QR($request, $renderer) {
        $userAttr = Auth::attributes();
        $qrIMG = QR::imageToBase64(QR::generate(TOTP::otpauth($userAttr['email'],$userAttr['tfa_auth_secret']),['bg' => '536592', 'fg' => 'FFFFFF'])->outputPNG());
        $data = Auth::getAuthData();
        $viewcode = $renderer->module(self::modulename())
                    ->setView("index")
                    ->setViewVar("seo",static::seoVar())
                    ->setViewVar("url",self::call("Users:CreateUser@url"))
                    ->setViewVar("qrIMG", $qrIMG)
                    ->setLayout("2fa.auth.confirm")->renderView();
        return $viewcode;
    }

    public static function confirmTFA($request, $renderer) {
        $userAttr = Auth::attributes();
        $viewcode = $renderer->module(self::modulename())
                    ->setView("index")
                    ->setViewVar("seo",static::seoVar())
                    ->setViewVar("url",self::call("Users:CreateUser@url"))
                    ->setLayout("2fa.auth")->renderView();
        return $viewcode;
    }

    public static function login2faPost($request, Renderer $renderer) {
        if (Auth::isLogged()) {
            $body = [];
            $body['redirectTo'] = Module::getStatic("defaultUrl");
            $body['status'] = 1;
            $body['error'] = 0;
            $body['message'] = "You have already confirmed two-factor authentication in another window.";
            $answer['code'] = 200;
            $answer['body'] = $body;
            return DotApp::DotApp()->ajaxReply($answer['body'], $answer['code']);
        }
        $userAttr = Auth::attributes();
        if ($request->crcCheck()) {
            $answer = $request->form(['POST'],"ConfirmAuthCode", function($request) {
                $confirmed = Auth::confirmTwoFactor(['tfa' => $request->data()['data']['code']]);
                if ($confirmed['confirmed'] === true) {
                    $body = [];
                    if (Auth::isLogged()) {
                        $body['redirectTo'] = Module::getStatic("defaultUrl");
                    }
                    $body['status'] = 1;
                    $body['error'] = 0;
                    $body['message'] = "Two-factor authentication successful.";
                    $answer['code'] = 200;
                    $answer['body'] = $body;
                    DB::module("RAW")
                        ->q(function ($qb) use ($userAttr) {
                            $qb->update(Config::get("db","prefix").'users')->set(['tfa_auth_secret_confirmed' => 1])->where('id', '=', $userAttr['id']);
                        })
                        ->execute();
                    return $answer;
                } else {
                    $body = [];
                    $body['status'] = 0;
                    $body['error'] = 1;
                    $body['errorNo'] = 1;
                    $body['message'] = "Invalid two-factor authentication code.";
                    $answer['code'] = 200;
                    $answer['body'] = $body;
                    return $answer;
                }
            },"Users:Login@drop");
            if ($answer !== null) return DotApp::DotApp()->ajaxReply($answer['body'], $answer['code']);

            $answer = $request->form(['POST'],"TwoFactor", function($request) {
                $confirmed = Auth::confirmTwoFactor(['tfa' => $request->data()['data']['code']]);
                if ($confirmed['confirmed'] === true) {
                    $body = [];
                    if (Auth::isLogged()) {
                        $body['redirectTo'] = Module::getStatic("defaultUrl");
                    }
                    $body['status'] = 1;
                    $body['error'] = 0;
                    $body['message'] = "Two-factor authentication successful.";
                    $answer['code'] = 200;
                    $answer['body'] = $body;
                    return $answer;
                } else {
                    $body = [];
                    $body['status'] = 0;
                    $body['error'] = 1;
                    $body['errorNo'] = 1;
                    $body['message'] = "Invalid two-factor authentication code.";
                    $answer['code'] = 200;
                    $answer['body'] = $body;
                    return $answer;
                }
            },"Users:Login@drop");
            if ($answer !== null) return DotApp::DotApp()->ajaxReply($answer['body'], $answer['code']);

            $answer = $request->form(['POST'],"TwoFactorEmail", function($request) {
                $confirmed = Auth::confirmTwoFactor(['tfa_email' => $request->data()['data']['code']]);
                if ($confirmed['confirmed'] === true) {
                    $body = [];
                    if (Auth::isLogged()) {
                        $body['redirectTo'] = Module::getStatic("defaultUrl");
                    }
                    $body['status'] = 1;
                    $body['error'] = 0;
                    $body['message'] = "Two-factor authentication successful.";
                    $answer['code'] = 200;
                    $answer['body'] = $body;
                    return $answer;
                } else {
                    $body = [];
                    $body['status'] = 0;
                    $body['error'] = 1;
                    $body['errorNo'] = 1;
                    $body['message'] = "Invalid two-factor authentication code.";
                    $answer['code'] = 200;
                    $answer['body'] = $body;
                    return $answer;
                }
            },"Users:Login@drop",Module::getStatic("loginUrl2fa"));
            if ($answer !== null) return DotApp::DotApp()->ajaxReply($answer['body'], $answer['code']);
        }
    }

    public static function logout($request, Renderer $renderer) {
        Auth::logout();
        header("Location: ".Module::getStatic("loginUrl"));
        exit();
    }
}
?>

Method Descriptions:

drop(): A fallback method returning false for invalid form submissions, preventing unauthorized access.
index(): Renders the logged-in user’s dashboard using the index.logged layout, displaying the user’s email.
seoVar(): Defines SEO metadata, matching the registration SEO for consistency.
login(): Renders the login form or redirects logged-in users to the dashboard or 2FA page.
loginPost(): Validates email and password, initiating login. If 2FA is required, it redirects to the 2FA page.
login2fa(): Handles 2FA logic, directing users to QR code confirmation or code entry based on their 2FA setup.
login2faEmail(): Renders the email 2FA form, displaying a demo code since no emails are sent.
confirmTFA_QR(): Generates and displays a QR code for initial 2FA setup using the TOTP secret.
confirmTFA(): Renders the 2FA code entry form for authenticator apps.
login2faPost(): Validates 2FA codes (authenticator or email) and updates the user’s 2FA confirmation status. It handles three form types: ConfirmAuthCode, TwoFactor, and TwoFactorEmail.
logout(): Logs out the user and redirects to the login page.

Middleware

Middleware in DotApp acts as a filter or gatekeeper between a request and the controller. It can perform tasks like authentication checks, logging, or modifying requests before they reach the controller or response. In this example, the AuthTest middleware ensures users are authenticated before accessing protected routes.

The middleware is defined in /app/modules/Users/Middleware/AuthTest.php:

<?php
namespace Dotsystems\App\Modules\Users\Middleware;
use Dotsystems\App\Parts\Middleware;
use Dotsystems\App\Parts\Auth;
use Dotsystems\App\Modules\Users\Module;

class AuthTest {
    public static function register() {
        Middleware::define("auth:loginTest", function($request, $next) {
            if (Auth::isLogged()) {
                // Continue to the next middleware or controller
            } else if (Auth::loggedStage() == 2) {
                header("Location: ".Module::getStatic("loginUrl2fa"));
                exit();
            } else {
                header("Location: ".Module::getStatic("loginUrl"));
                exit();
            }
            $next($request);
        });
    }
}
?>

Explanation:

If the user is fully logged in (Auth::isLogged()), the request proceeds to the next middleware or controller.
If the user is in the 2FA stage (Auth::loggedStage() == 2), they’re redirected to the 2FA page.
Otherwise, unauthenticated users are redirected to the login page.
The $next($request) call passes control to the next middleware or controller if the user is authenticated.

The middleware is registered in /app/modules/Users/module.init.php using:

self::call("Users:Middleware\AuthTest@register");

This calls the register() method in AuthTest, defining the auth:loginTest middleware. It’s applied to the default route to protect the logged-in dashboard, ensuring only authenticated users can access it.

Routes

Routes are configured in /app/modules/Users/module.init.php. The module supports configurable URLs, allowing users to customize routes via /app/config.php without modifying the module. Default URLs are provided if no custom settings are defined.

<?php
namespace Dotsystems\App\Modules\Users;
use Dotsystems\App\Parts\Router;
use Dotsystems\App\Parts\Middleware;
use Dotsystems\App\Parts\Config;

class Module {
    public static $autologin;
    public static $defaultUrl;
    public static $allowRegistration;
    public static $registerUrl;
    public static $allowLogin;
    public static $loginUrl;
    public static $loginUrl2fa;
    public static $logoutUrl;
    public static $loginUrl2faEmail;

    public static function getStatic($key) {
        return static::$$key;
    }

    public function initialize($dotApp) {
        self::call("Users:Middleware\AuthTest@register");
        Router::get(static::$defaultUrl, "Users:Login@index", Router::STATIC_ROUTE)
            ->before(Middleware::use("auth:loginTest"));
        if (static::$allowRegistration === true) {
            Router::get(static::$registerUrl, "Users:CreateUser@register", Router::STATIC_ROUTE);
            Router::post(static::$registerUrl, "Users:CreateUser@registerPost", Router::STATIC_ROUTE);
        }
        if (static::$allowLogin === true) {
            Router::get(static::$loginUrl, "Users:Login@login", Router::STATIC_ROUTE);
            Router::post(static::$loginUrl, "Users:Login@loginPost", Router::STATIC_ROUTE);
            Router::get(static::$loginUrl2fa, "Users:Login@login2fa", Router::STATIC_ROUTE);
            Router::post(static::$loginUrl2fa, "Users:Login@login2faPost", Router::STATIC_ROUTE);
            Router::get(static::$loginUrl2faEmail, "Users:Login@login2faEmail", Router::STATIC_ROUTE);
            Router::get(static::$logoutUrl, "Users:Login@logout", Router::STATIC_ROUTE);
        }
    }

    public function initializeRoutes() {
        $initializeRoutes = [];
        static::$autologin = Config::module("Users","autologin") ?? true;
        static::$defaultUrl = Config::module("Users","defaultUrl") ?? "/documentation/examples/run/forms4";
        $initializeRoutes[] = static::$defaultUrl;
        static::$allowRegistration = Config::module("Users","allowRegistration") ?? true;
        static::$registerUrl = Config::module("Users","registerUrl") ?? "/documentation/examples/run/forms4-register";
        if (static::$allowRegistration === true) {
            $initializeRoutes[] = static::$registerUrl;
        }
        static::$allowLogin = Config::module("Users","allowLogin") ?? true;
        static::$loginUrl = Config::module("Users","loginUrl") ?? "/documentation/examples/run/forms4-login";
        static::$loginUrl2fa = Config::module("Users","loginUrl2fa") ?? "/documentation/examples/run/forms4-login-2fa";
        static::$logoutUrl = Config::module("Users","logoutUrl") ?? "/documentation/examples/run/forms4-logout";
        static::$loginUrl2faEmail = Config::module("Users","loginUrl2faEmail") ?? "/documentation/examples/run/forms4-login-2fa-email";
        if (static::$allowLogin === true) {
            $initializeRoutes[] = static::$logoutUrl;
            $initializeRoutes[] = static::$loginUrl;
            $initializeRoutes[] = static::$loginUrl2fa;
            $initializeRoutes[] = static::$loginUrl2faEmail;
        }
        return $initializeRoutes;
    }
}
?>

Explanation:

initializeRoutes() returns an array of specific routes for which the Users module should be initialized. Instead of using ['*'] to initialize the module for all routes, we explicitly define only the relevant routes. This is a best practice, especially for large projects, as it prevents the module from being unnecessarily initialized for every request, improving performance and reducing resource usage. The module is only initialized if the current URL matches one of the routes returned by this function.
initialize() sets up the module’s routes for registration, login, two-factor authentication (2FA), and logout. It applies the auth:loginTest middleware to the default route to ensure proper authentication checks.
Configurable settings (allowRegistration, allowLogin, autologin) allow enabling or disabling features, providing flexibility for different project needs.
Using Config::module ensures that user-defined settings are stored externally in /app/config.php, preserving them during module updates and maintaining portability.

View

The main view, located at /app/modules/Users/views/index.view.php, serves as a common template for all pages:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>{{ var: $seo['title'] }}</title>
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="description" content="{{ var: $seo['description'] }}"/>
    <meta name="keywords" content="{{ var: $seo['keywords'] }}"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="/assets/modules/Users/users.css">
</head>
<body>
    {{ content }}
    <script src="/assets/dotapp/dotapp.js"></script>
    <script src="/assets/modules/Users/users.js"></script>
</body>
</html>

Explanation:

The view includes SEO variables, a viewport meta tag, and links to the module’s CSS (users.css) and JavaScript (users.js).
The {{ content }} placeholder is where layouts (e.g., login, registration) are inserted.
dotapp.js is included for frontend form handling, automatically provided by the framework.

Layouts

Layouts, stored in /app/modules/Users/views/layouts/, define the content for specific pages. Each layout is inserted into the {{ content }} placeholder of the main view.

2FA Auth Confirm (`2fa.auth.confirm.layout.php`)

Displays a QR code for initial 2FA setup with an authenticator app (e.g., Google Authenticator). Users enter a 6-digit code to confirm setup.

<div class="container">
    <nav class="nav-menu">
        <a href="{{ var: $url['defaultUrl'] }}">Home</a>
        <a href="{{ var: $url['logoutUrl'] }}">Logout</a>
    </nav>
    <div class="form-box">
        <h2>2FA Verification</h2>
        <p class="form-description">Two-factor authentication (2FA) is required. Scan the QR code with your authenticator app (e.g., Google Authenticator) and enter the 6-digit code to confirm setup.</p>
        <div class="qr-code">
            <img src="{{ var: $qrIMG }}" alt="2FA QR Code" class="qr-image">
        </div>
        <span class="user-icon">
            <div class="icon-wrapper">
                <svg width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="#ffffff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
                    <rect x="3" y="11" width="18" height="11" rx="2" ry="2"></rect>
                    <path d="M7 11V7a5 5 0 0 1 10 0v4"></path>
                    <path d="M10 16l2 2 4-4"></path>
                </svg>
            </div>
        </span>
        <form id="twofaform" method="POST">
            <div class="form-group">
                <label for="two-fa">Enter 6-digit code</label>
                <div class="two-fa-inputs">
                    <input type="text" maxlength="1" placeholder="-" id="first">
                    <input type="text" maxlength="1" placeholder="-">
                    <input type="text" maxlength="1" placeholder="-">
                    <input type="text" maxlength="1" placeholder="-">
                    <input type="text" maxlength="1" placeholder="-">
                    <input type="text" maxlength="1" placeholder="-">
                </div>
            </div>
            {{ formName(ConfirmAuthCode) }}
            <input type="hidden" name="code" value="">
            <div class="error-message" id="error-message"></div>
            <div class="btn" id="confirm2fa">Confirm</div>
        </form>
    </div>
</div>

Features:

Displays a QR code via {{ var: $qrIMG }}.
Uses six single-character inputs for the 2FA code, stored in a hidden code input.
Includes a navigation menu with "Home" and "Logout" links.

2FA Auth (`2fa.auth.layout.php`)

For subsequent logins, users enter a 2FA code from their authenticator app without seeing the QR code.

<div class="container">
    <nav class="nav-menu">
        <a href="{{ var: $url['defaultUrl'] }}">Home</a>
        <a href="{{ var: $url['logoutUrl'] }}">Logout</a>
    </nav>
    <div class="form-box">
        <h2>2FA Verification</h2>
        <span class="user-icon">
            <div class="icon-wrapper">
                <svg width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="#ffffff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
                    <rect x="3" y="11" width="18" height="11" rx="2" ry="2"></rect>
                    <path d="M7 11V7a5 5 0 0 1 10 0v4"></path>
                    <path d="M10 16l2 2 4-4"></path>
                </svg>
            </div>
        </span>
        <form id="twofaform" method="POST">
            <div class="form-group">
                <label for="two-fa">Enter 6-digit code</label>
                <div class="two-fa-inputs">
                    <input type="text" maxlength="1" placeholder="-" id="first">
                    <input type="text" maxlength="1" placeholder="-">
                    <input type="text" maxlength="1" placeholder="-">
                    <input type="text" maxlength="1" placeholder="-">
                    <input type="text" maxlength="1" placeholder="-">
                    <input type="text" maxlength="1" placeholder="-">
                </div>
            </div>
            <input type="hidden" name="code" value="">
            {{ formName(TwoFactor) }}
            <div class="error-message" id="error-message"></div>
            <div class="btn" id="confirm2fa">Verify</div>
            <p class="form-link">Don't have your phone for 2FA?<br>
            <a href="{{ var: $url['loginUrl2faEmail'] }}">Switch to email verification</a></p>
        </form>
    </div>
</div>

Features:

Allows switching to email 2FA via a link.
Uses {{ formName(TwoFactor) }} to identify the form type.

2FA Email (`2fa.email.layout.php`)

Allows 2FA via an email code (displayed for demo purposes).

<div class="container">
    <nav class="nav-menu">
        <a href="{{ var: $url['defaultUrl'] }}">Home</a>
        <a href="{{ var: $url['logoutUrl'] }}">Logout</a>
    </nav>
    <div class="form-box">
        <h2>2FA Email Verification</h2>
        <p class="form-description">
            Since this is a demo, no email will be sent. Below is the 6-digit code that would typically be emailed to you. Enter this code to simulate verification.
        </p>
        <p class="form-description yourcode">
            Your code: {{ var: $emailcode }}
        </p>
        <span class="user-icon">
            <div class="icon-wrapper">
                <svg width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="#ffffff" stroke-width="2">
                    <rect x="3" y="11" width="18" height="11" rx="2" ry="2"></rect>
                    <path d="M7 11V7a5 5 0 1 0 10 0v4"></path>
                    <path d="M10 16l2 2 4-4"></path>
                </svg>
            </div>
        </span>
        <form id="twofaform" method="POST" action="{{ var: $url['loginUrl2fa'] }}">
            <div class="form-group">
                <label for="two-fa">Enter 6-digit code</label>
                <div class="two-fa-inputs">
                    <input type="text" maxlength="1" placeholder="-" id="first">
                    <input type="text" maxlength="1" placeholder="-">
                    <input type="text" maxlength="1" placeholder="-">
                    <input type="text" maxlength="1" placeholder="-">
                    <input type="text" maxlength="1" placeholder="-">
                    <input type="text" maxlength="1" placeholder="-">
                </div>
            </div>
            <input type="hidden" name="code" value="">
            {{ formName(TwoFactorEmail) }}
            <div class="error-message" id="error-message"></div>
            <div class="btn" id="confirm2fa">Verify</div>
            <p class="form-link">Don't have access to your email?<br>
            <a href="{{ var: $url['loginUrl2fa'] }}">Switch to 2FA Auth App verification</a></p>
        </form>
    </div>
</div>

Explanation:

Shows a demo code via {{ var: $emailcode }}.
The form submits to loginUrl2fa with TwoFactorEmail form type.
Includes a navigation link to switch to authenticator 2FA.

Logged In Dashboard (`index.logged.layout.php`)

Displays a success message and user details after login.

<div class="container">
    <nav class="nav-menu">
        <a href="{{ var: $url['defaultUrl'] }}">Home</a>
        <a href="{{ var: $url['logoutUrl'] }}">Logout</a>
    </nav>
    <div class="form-box">
        <h2>Login Successful</h2>
        <span class="user-icon">
            <span class="icon-wrapper">
                <svg width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="#ffffff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
                    <path d="12 2a10 10 0 0 1 10 10 a0 10 0 0 1-10 10A10 10 0 0 1 2 12A10 10 0 1 12 2z"></path>
                    <path d="M9 12l2 2 4-4"></path>
                </svg>
            </span>
        </span>
        <p class="form-description">
            You have successfully logged in to this test module. Below are your account details:
        </p>
        <hr>
        <div class="form-group">
            <p class="form-description"><b>Logged as:</b> {{ var: $email }}</p>
        </div>
        <hr>
        <p class="form-description explanation">
            This module exemplifies the philosophy of the DotApp framework: create once, reuse everywhere. With DotApp, you can build a robust login and registration module with QR code authentication once. For all future projects, simply copy this module, and you’ll have a fully functional authentication system ready to go. This approach saves an incredible amount of time, streamlining development and ensuring consistency across your applications. Whether you're building a small prototype or a large-scale platform, DotApp empowers you to focus on innovation by eliminating repetitive setup tasks.
        </p>
        <div class="btn">That's All for This Example!</div>
    </div>
</div>

Explanation:

Shows the logged-in user’s email.
Emphasizes DotApp’s modular philosophy in a highlighted text block.

Login Form (`login.layout.php`)

The login form for user authentication.

<div class="container">
    <nav class="nav-menu">
        <a href="{{ var: $url['defaultUrl'] }}">Home</a>
        <a href="{{ var: $url['registerUrl'] }}">Register</a>
    </nav>
    <div class="form-box">
        <h2>Login Example</h2>
        <span class="user-icon">
            <div class="icon-wrapper">
                <svg width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="#ffffff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
                    <path d="M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2"></path>
                    <circle cx="12" cy="7" r="4"></circle>
                </svg>
            </div>
        </span>
        <form id="login" method="POST">
            <div class="form-group">
                <label for="email-login">Email</label>
                <input type="email" name="email" placeholder="Enter your email" required>
            </div>
            <div class="form-group">
                <label for="password-login">Password</label>
                <input type="password" name="password" placeholder="Enter your password" required>
            </div>
            {{ formName(CSRF) }}
            <div class="error-message" id="error-message"></div>
            <button type="submit" class="btn" id="loginbtn">Log In</button>
            <p class="form-link">Don't have an account yet? <a href="{{ var: $url['registerUrl'] }}">Register</a></p>
        </form>
    </div>
</div>

Features:

Simple email and password inputs with CSRF protection.
Links to the registration form.

Registration Form (`register.layout.php`)

The registration form for new users.

<div class="container">
    <nav class="nav-menu">
        <a href="{{ var: $url['defaultUrl'] }}">Home</a>
        <a href="{{ var: $url['loginUrl'] }}">Login</a>
    </nav>
    <div class="form-box">
        <h2>Registration</h2>
        <span class="user-icon">
            <div class="icon-wrapper">
                <svg width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="#ffffff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
                    <path d="M12 20h9"></path>
                    <path d="M16.5 3.5a2.121 2.121 0 0 0 3 3L7 19l-4 1 1-4L16.5 3.5z"></path>
                </svg>
            </div>
        </span>
        <form method="POST" id="registration">
            <div class="form-group">
                <label for="email-reg">Email</label>
                <input type="text" name="email" placeholder="Enter your email">
            </div>
            <div class="form-group">
                <label for="password-reg">Password</label>
                <input type="password" name="password" placeholder="Enter your password">
            </div>
            {{ formName(CSRF) }}
            <div class="error-message" id="error-message"></div>
            <button type="submit" class="btn" id="registrationbtn">Register</button>
            <p class="form-link">Already have an account? <a href="{{ var: $url['loginUrl'] }}">Log in</a></p>
        </form>
    </div>
</div>

Explanation:

Collects email and password fields with CSRF protection.
Links to the login page for existing users.

Assets

Assets (CSS and JavaScript) are stored in /app/modules/Users/assets/ to ensure the module’s styles and scripts are self-contained.

CSS (`users.css`)

Located at /app/modules/Users/assets/css/users.css, the CSS provides a modern, responsive design with:

A glassmorphism-inspired aesthetic (translucent backgrounds, blur effects).
Interactive navigation menus with hover effects.
Styled form elements with visual feedback for inputs (e.g., .ready, .bad classes).
QR code and 2FA input styling.
Responsive adjustments for smaller screens.

Key classes include:

.nav-menu: Styles the navigation bar.
.form-box: Styles form containers.
.two-fa-inputs: Styles 2FA code input fields.
.btn: Styles buttons with loading animations.

* {
    margin: 0;
    padding: 0;
    box-sizing: border-box;
    font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
}

body {
    background: linear-gradient(135deg, #6b7280, #1e3a8a);
    display: flex;
    justify-content: center;
    align-items: center;
    min-height: 100vh;
    padding: 20px;
    overflow-x: hidden;
}

.container {
    max-width: 420px;
    width: 100%;
    margin: 30px auto;
}

/* Menu Styles */
.nav-menu {
    background: rgba(255, 255, 255, 0.1);
    backdrop-filter: blur(10px);
    border-radius: 12px;
    padding: 15px 20px;
    margin-bottom: 30px;
    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.2);
    border: 1px solid rgba(255, 255, 255, 0.2);
    display: flex;
    justify-content: center;
    gap: 30px;
    transition: transform 0.3s ease, box-shadow 0.3s ease;
}

.nav-menu:hover {
    transform: translateY(-3px);
    box-shadow: 0 12px 40px rgba(0, 0, 0, 0.3);
}

.nav-menu a {
    color: #ffffff;
    font-size: 16px;
    font-weight: 500;
    text-decoration: none;
    padding: 8px 16px;
    border-radius: 6px;
    transition: background 0.3s ease, color 0.3s ease, transform 0.2s ease;
    position: relative;
}

.nav-menu a:hover {
    background: rgba(255, 255, 255, 0.6);
    color: #0073ff;
    transform: scale(1.05);
}

.nav-menu a::after {
    content: '';
    position: absolute;
    width: 0;
    height: 2px;
    bottom: 0;
    left: 50%;
    background: #0073ff;
    transition: width 0.3s ease, left 0.3s ease;
}

.nav-menu a:hover::after {
    width: 100%;
    left: 0;
}

/* Form Styles */
.form-box {
    background: rgba(255, 255, 255, 0.1);
    backdrop-filter: blur(10px);
    border-radius: 16px;
    padding: 30px;
    margin-bottom: 30px;
    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.2);
    border: 1px solid rgba(255, 255, 255, 0.2);
    transition: transform 0.3s ease, box-shadow 0.3s ease;
}

.form-box:hover {
    transform: translateY(-5px);
    box-shadow: 0 12px 40px rgba(0, 0, 0, 0.3);
}

h2 {
    text-align: center;
    margin-bottom: 10px;
    color: #ffffff;
    font-size: 24px;
    font-weight: 600;
    letter-spacing: 0.5px;
}

.user-icon {
    display: flex;
    justify-content: center;
    margin-bottom: 20px;
}

.icon-wrapper {
    width: 60px;
    height: 60px;
    background: rgba(255, 255, 255, 0.15);
    border-radius: 50%;
    display: flex;
    justify-content: center;
    align-items: center;
    padding: 8px;
    transition: transform 0.3s ease, background 0.3s ease;
}

.icon-wrapper:hover {
    transform: scale(1.1);
    background: rgba(255, 255, 255, 0.25);
}

.user-icon svg {
    width: 32px;
    height: 32px;
    stroke: #ffffff;
}

.form-group {
    margin-bottom: 20px;
}

label {
    display: block;
    margin-bottom: 8px;
    color: #e5e7eb;
    font-size: 14px;
    font-weight: 500;
}

input[type="text"],
input[type="email"],
input[type="password"] {
    width: 100%;
    padding: 12px;
    background: rgba(255, 255, 255, 0.15);
    border: 1px solid rgba(255, 255, 255, 0.3);
    border-radius: 8px;
    font-size: 16px;
    color: #ffffff;
    transition: border-color 0.3s ease, background 0.3s ease;
}

input[type="text"]::placeholder,
input[type="email"]::placeholder,
input[type="password"]::placeholder {
    color: rgba(255, 255, 255, 0.6);
}

input[type="text"]:focus,
input[type="email"]:focus,
input[type="password"]:focus {
    border-color: #60a5fa;
    background: rgba(255, 255, 255, 0.2);
    outline: none;
}

.btn {
    display: block;
    text-align: center;
    width: 100%;
    padding: 14px;
    background: linear-gradient(90deg, #3b82f6, #60a5fa);
    border: none;
    border-radius: 8px;
    color: #ffffff;
    font-size: 16px;
    font-weight: 600;
    cursor: pointer;
    transition: background 0.3s ease, transform 0.2s ease;
}

.btn:hover {
    background: linear-gradient(90deg, #2563eb, #3b82f6);
    transform: scale(1.02);
}

.btn:active {
    transform: scale(0.98);
}

.btn.loading {
    background: linear-gradient(90deg, #9ca3af, #d1d5db, #9ca3af);
    background-size: 200% 100%;
    animation: loading 1.5s ease-in-out infinite;
    color: #e5e7eb;
    cursor: not-allowed;
    transform: none;
    opacity: 0.7;
    pointer-events: none;
}

@keyframes loading {
    0% {
        background-position: 0% 50%;
    }
    50% {
        background-position: 100% 50%;
    }
    100% {
        background-position: 0% 50%;
    }
}

.form-link {
    display: block;
    text-align: center;
    margin-top: 15px;
    color: #e5e7eb;
    font-size: 14px;
    font-weight: 400;
    text-decoration: none;
    position: relative;
    transition: color 0.3s ease;
}

.form-link a {
    color: #60a5fa;
    font-weight: 500;
    text-decoration: none;
    position: relative;
}

.form-link a:hover {
    color: #93c5fd;
}

.form-link a::after {
    content: '';
    position: absolute;
    width: 0;
    height: 1px;
    bottom: -2px;
    left: 50%;
    background: #60a5fa;
    transition: width 0.3s ease, left 0.3s ease;
}

.form-link a:hover::after {
    width: 100%;
    left: 0;
}

.two-fa-inputs {
    display: flex;
    justify-content: space-between;
    gap: 12px;
}

.two-fa-inputs input {
    width: 48px;
    height: 48px;
    text-align: center;
    font-size: 20px;
    background: rgba(255, 255, 255, 0.15);
    border: 1px solid rgba(255, 255, 255, 0.3);
    border-radius: 8px;
    color: #ffffff;
    text-transform: uppercase;
    transition: border-color 0.3s ease, background 0.3s ease;
}

.two-fa-inputs input:focus {
    border-color: #60a5fa;
    background: rgba(255, 255, 255, 0.2);
    outline: none;
}

.two-fa-inputs input::placeholder {
    color: rgba(255, 255, 255, 0.6);
}

.good INPUT, INPUT.good {
    border: 1px solid rgba(51, 255, 0, 0.8);
}

.ready INPUT, INPUT.ready {
    border: 1px solid rgba(0, 238, 255, 0.8);
}

.bad INPUT, INPUT.bad {
    border: 1px solid rgba(255, 0, 13, 0.8);
}

.error {
    border-color: #ef4444 !important;
    background: rgba(239, 68, 68, 0.2) !important;
}

.form-description {
    text-align: center;
    color: #e5e7eb;
    font-size: 14px;
    font-weight: 400;
    line-height: 1.5;
    margin-bottom: 20px;
    padding: 0 10px;
}

.qr-code {
    text-align: center;
    margin-bottom: 20px;
}

.qr-image {
    max-width: 180px;
    width: 100%;
    display: block;
    margin: 0 auto;
    border: 1px solid rgba(255, 255, 255, 0.3);
    border-radius: 8px;
    padding: 8px;
    background: rgba(255, 255, 255, 0.15);
    transition: transform 0.3s ease, box-shadow 0.3s ease;
}

.qr-image:hover {
    transform: scale(1.05);
    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.2);
}

hr {
    border: none;
    height: 1px;
    background: linear-gradient(90deg, rgba(255, 255, 255, 0.2), rgba(255, 255, 255, 0.5), rgba(255, 255, 255, 0.2));
    margin: 20px 0;
    opacity: 0.6;
    transition: opacity 0.3s ease, transform 0.3s ease;
}

.explanation {
    color: rgb(255, 238, 0);
}

.yourcode {
    font-weight: 600;
    color: #60a5fa;
    text-align: center;
    margin-bottom: 25px;
}

.error-message {
    display: none;
    text-align: center;
    color: #ef4444;
    font-size: 14px;
    font-weight: 500;
    margin-bottom: 15px;
    padding: 10px;
    background: rgba(239, 68, 68, 0.15);
    border: 1px solid rgba(239, 68, 68, 0.3);
    border-radius: 8px;
    transition: opacity 0.3s ease;
}

.error-message.visible {
    display: block;
    opacity: 1;
}

@media (max-width: 480px) {
    .qr-image {
        max-width: 120px;
        padding: 6px;
    }

    .form-description {
        font-size: 13px;
        margin-bottom: 15px;
        padding: 0 5px;
    }

    .container {
        padding: 15px;
    }

    .form-box {
        padding: 20px;
    }

    .nav-menu {
        flex-direction: column;
        gap: 15px;
        padding: 15px;
    }

    .nav-menu a {
        width: 100%;
        text-align: center;
        padding: 10px;
        font-size: 15px;
    }

    .two-fa-inputs input {
        width: 40px;
        height: 40px;
        font-size: 18px;
    }

    h2 {
        font-size: 20px;
    }

    .form-link {
        font-size: 13px;
    }

    .user-icon svg {
        width: 40px;
        height: 40px;
    }
}

JavaScript (`users.js`)

Located at /app/modules/Users/assets/js/users.js, the JavaScript handles form validation and 2FA code entry:

(function() {
    var runMe = function($dotapp) {
        function registration_form($dotapp) {
            $dotapp('#registration input[name="email"]').on("keyup", function() {
                $dotapp('#error-message').removeClass("visible");
                if ($dotapp().validator.isEmail($dotapp(this).val())) {
                    $dotapp(this).removeClass("bad").removeClass("good").addClass("ready");
                } else {
                    $dotapp(this).addClass("bad").removeClass("good").removeClass("ready");
                }
            });
            $dotapp('#registration input[name="password"]').on("keyup", function() {
                $dotapp('#error-message').removeClass("visible");
                if ($dotapp().validator.isStrongPassword($dotapp(this).val())) {
                    $dotapp(this).removeClass("bad").removeClass("good").addClass("ready");
                } else {
                    $dotapp(this).addClass("bad").removeClass("good").removeClass("ready");
                }
            });
            $dotapp()
                .form('#registration')
                .before((data, form) => {
                    $dotapp('#error-message').removeClass("visible");
                    if ($dotapp(form).attr("blocked") == 1) {
                        return $dotapp().halt();
                    }
                    $dotapp(form).attr("blocked", "1");
                    $dotapp("#registrationbtn").addClass("loading");
                })
                .after((data, response, form) => {
                    $dotapp(form).attr("blocked", "0");
                    $dotapp("#registrationbtn").removeClass("loading");
                    if (reply = $dotapp().parseReply(response)) {
                        if (reply.status == 1) {
                            $dotapp('#registration input[name="email"]').removeClass("bad").removeClass("good").removeClass("ready").val("");
                            $dotapp('#registration input[name="password"]').removeClass("bad").removeClass("good").removeClass("ready").val("");
                            alert(reply.message);
                            window.location = reply.redirectTo;
                        } else {
                            if (reply.errorNo == 1) {
                                $dotapp('#registration input[name="email"]').addClass("bad").removeClass("good").removeClass("ready");
                                $dotapp('#error-message').addClass("visible").html(reply.message);
                            }
                            if (reply.errorNo == 2) {
                                $dotapp('#registration input[name="password"]').addClass("bad").removeClass("good").removeClass("ready");
                                $dotapp('#error-message').addClass("visible").html(reply.message);
                            }
                            if (reply.errorNo == 3) {
                                $dotapp('#registration input[name="email"]').addClass("bad").removeClass("good").removeClass("ready");
                                $dotapp('#error-message').addClass("visible").html(reply.message);
                            }
                            if (reply.errorNo == 4) {
                                $dotapp('#error-message').addClass("visible").html(reply.message);
                            }
                        }
                    }
                });
        }
        function login_form($dotapp) {
            $dotapp('#login input[name="email"]').on("keyup", function() {
                $dotapp('#error-message').removeClass("visible");
                if ($dotapp().validator.isEmail($dotapp(this).val())) {
                    $dotapp(this).removeClass("bad").removeClass("good").addClass("ready");
                } else {
                    $dotapp(this).addClass("bad").removeClass("good").removeClass("ready");
                }
            });
            $dotapp('#login input[name="password"]').on("keyup", function() {
                $dotapp('#error-message').removeClass("visible");
                if ($dotapp().validator.isStrongPassword($dotapp(this).val())) {
                    $dotapp(this).removeClass("bad").removeClass("good").addClass("ready");
                } else {
                    $dotapp(this).addClass("bad").removeClass("good").removeClass("ready");
                }
            });
            $dotapp()
                .form('#login')
                .before((data, form) => {
                    $dotapp('#error-message').removeClass("visible");
                    if ($dotapp(form).attr("blocked") == 1) {
                        return $dotapp().halt();
                    }
                    $dotapp(form).attr("blocked", "1");
                    $dotapp("#loginbtn").addClass("loading");
                })
                .after((data, response, form) => {
                    if (reply = $dotapp().parseReply(response)) {
                        if (reply.status == 1) {
                            $dotapp('#login input[name="email"]').removeClass("bad").removeClass("good").removeClass("ready").val("");
                            $dotapp('#login input[name="password"]').removeClass("bad").removeClass("good").removeClass("ready").val("");
                            window.location = reply.redirectTo;
                        } else {
                            if (reply.errorNo == 1) {
                                $dotapp('#login input[name="email"]').addClass("bad").removeClass("good").removeClass("ready");
                                $dotapp('#error-message').addClass("visible").html(reply.message);
                            }
                            if (reply.errorNo == 2) {
                                $dotapp('#login input[name="email"]').addClass("bad").removeClass("good").removeClass("ready");
                                $dotapp('#login input[name="password"]').addClass("bad").removeClass("good").removeClass("ready");
                                $dotapp('#error-message').addClass("visible").html(reply.message);
                            }
                            $dotapp(form).attr("blocked", "0");
                            $dotapp("#loginbtn").removeClass("loading");
                        }
                    } else {
                        $dotapp(form).attr("blocked", "0");
                        $dotapp("#loginbtn").removeClass("loading");
                    }
                });
        }
        function tfa($dotapp) {
            window.setTimeout(function() {
                $dotapp('#first').focus();
            }, 200);
            $dotapp(".two-fa-inputs input").twoFactor((code) => {
                $dotapp("div.two-fa-inputs")
                    .removeClass("bad")
                    .addClass("ready")
                    .removeClass("good");
                $dotapp('#twofaform input[name="code"]').val(code);
                $dotapp('#error-message').removeClass("visible");
                $dotapp("#twofaform").submit();
            }, {
                allowLetters: false,
                uppercase: true,
                autoSubmit: true,
                invalidClass: 'error'
            });
            $dotapp()
                .form('#twofaform')
                .before((data, form) => {
                    $dotapp('#twofaform .two-fa-inputs input').attr("disabled", "1").val("*");
                    $dotapp("#confirm2fa").addClass("loading");
                    if ($dotapp(form).attr("blocked") == 1) {
                        return $dotapp().halt();
                    }
                    $dotapp(form).attr("blocked", "1");
                })
                .after((data, response, form) => {
                    if (reply = $dotapp().parseReply(response)) {
                        if (reply.status == 1) {
                            $dotapp("div.two-fa-inputs").removeClass("bad").removeClass("ready").addClass("good");
                            window.location = reply.redirectTo;
                        } else {
                            $dotapp('#twofaform .two-fa-inputs input').removeAttr("disabled").val("");
                            $dotapp("#confirm2fa").removeClass("loading");
                            $dotapp("div.two-fa-inputs").addClass("bad").removeClass("ready").removeClass("good");
                            $dotapp(form).attr("blocked", "0");
                            $dotapp("#confirm2fa").removeClass("loading");
                            if (reply.errorNo == 1) {
                                $dotapp('#error-message').addClass("visible").html(reply.message);
                            }
                            window.setTimeout(function() {
                                $dotapp('#first').focus();
                            }, 200);
                        }
                    } else {
                        $dotapp('#twofaform .two-fa-inputs input').removeAttr("disabled").val("");
                        $dotapp("div.two-fa-inputs").removeClass("bad").removeClass("ready").removeClass("good");
                        $dotapp(form).attr("blocked", "0");
                        $dotapp("#confirm2fa").removeClass("loading");
                        window.setTimeout(function() {
                            $dotapp('#first').focus();
                        }, 200);
                    }
                });
            $dotapp("#confirm2fa").on("click", function() {
                $dotapp('#error-message').removeClass("visible");
                const code2fa = $dotapp(".two-fa-inputs input").twoFactor();
                if (code2fa === false) {
                    $dotapp("div.two-fa-inputs").addClass("bad").removeClass("ready").removeClass("good");
                    $dotapp('#error-message').addClass("visible").html("Invalid code format");
                } else {
                    $dotapp('#twofaform input[name="code"]').val(code2fa);
                    $dotapp("div.two-fa-inputs").removeClass("bad").removeClass("good").addClass("ready");
                    $dotapp("#twofaform").submit();
                }
            });
            $dotapp("div.two-fa-inputs input").on("keyup", function() {
                $dotapp('#error-message').removeClass("visible");
                const code2fa = $dotapp(".two-fa-inputs input").twoFactor();
                if (code2fa === false) {
                    $dotapp("div.two-fa-inputs").removeClass("bad").removeClass("ready").removeClass("good");
                }
            });
        };
        registration_form($dotapp);
        login_form($dotapp);
        tfa($dotapp);
    };
    if (window.$dotapp) {
        runMe(window.$dotapp);
    } else {
        window.addEventListener('dotapp', function() {
            runMe(window.$dotapp);
        }, { once: true });
    }
})();

Key Functions:

registration_form: Validates email and password inputs, handling registration form submission with visual feedback.
login_form: Similar validation for the login form, redirecting on success.
tfa: Manages 2FA code entry, using the twoFactor function to process 6-digit codes.

JavaScript Functionality

The dotapp.js library provides the twoFactor function for handling 2FA code entry, used in users.js:

$dotapp(".two-fa-inputs input").twoFactor((code) => {
    $dotapp("div.two-fa-inputs")
        .removeClass("bad").addClass("ready").removeClass("good");
    $dotapp('#twofaform input[name="code"]').val(code);
    $dotapp('#error-message').removeClass("visible");
    $dotapp("#twofaform").submit();
}, {
    allowLetters: false,
    uppercase: true,
    autoSubmit: true,
    invalidClass: 'error'
});

Explanation:

Inputs: Selects six input elements within .two-fa-inputs to capture a 6-digit code.
Callback: When a valid code is entered, it updates the hidden code input and submits the form.
Options:
- allowLetters: false: Restricts to numeric input.
- uppercase: true: Converts input to uppercase (though numeric-only).
- autoSubmit: true: Submits the form automatically after the sixth digit.
- invalidClass: 'error': Applies the error class to the parent div.two-fa-inputs if the code is incomplete.
Getter: Calling $dotapp(".two-fa-inputs input").twoFactor() returns the current code as a string or false if invalid.
Best Practice: Store the code in a hidden input (<input type="hidden" name="code" value="">) for server-side processing.

The $dotapp().form() method, used for login and registration forms, was covered in the secure forms example and handles AJAX submissions with .before and .after callbacks for loading states and response processing.

Live Demo

Try the live demo at https://dotapp.dev/documentation/examples/run/forms4. This interactive example lets you test user registration, login, and two-factor authentication with QR codes and email codes, showcasing the module you can reuse in any DotApp project.

Download module at https://github.com/dotsystems-sk/moduleUsers

DEV Community: DotApp PHP Framework

How to Easily Create an MCP Server for Sending Emails with DotApp PHP Framework (Video Tutorial)

What is DotApp?

Step 1: Installing the DotApp PHP Framework

Step 2: Creating the MCP Module and Controller

Step 3: Configuring Email Settings

Step 4: Implementing the MCP Controller

Step 5: Setting Up Routes

Step 6: Testing the MCP Server

Why Try DotApp PHP Framework When Laravel and Symfony Dominate?

Why DotApp Framework Is More Than Just Another PHP Framework

More Than a Backend Framework

What DotApp Brings to the Table

Key Advantages That Set DotApp Apart

1. Driver-Based Services for Ultimate Flexibility

2. Portable Modularity: Copy and Run

3. Effortless Module Optimization

4. Seamless PHP-JavaScript Integration with DotApp.js

Who Is DotApp For?

What’s Next for DotApp?

Conclusion: Why Choose DotApp?

Connector Extension for the Frontend Part of DotApp PHP framework (dotapp.js): Seamlessly Connect Nodes in Just a Few Steps

Better to see it once than hear about it a hundred times. Here's the video:

Previous Articles on the DotApp PHP Framework:

How to Send Emails and Save Them in the Sent Folder with DotApp PHP Framework

Intro

Setting Up the EmailTest Module

Configuring SMTP and IMAP

Adding Email Routes

Understanding the Email Functions

Parameters:

Testing the Routes

Further Reading

Building a Reusable Users Module with DotApp PHP Framework ( + 2FA )

dotApp PHP framework

Users Module Example

Prerequisites

Module Creation

Database Setup

Configuration

Controllers

CreateUser Controller

Login Controller

Middleware

Routes

View

Layouts

2FA Auth Confirm (2fa.auth.confirm.layout.php)

2FA Auth (2fa.auth.layout.php)

2FA Email (2fa.email.layout.php)

Logged In Dashboard (index.logged.layout.php)

Login Form (login.layout.php)

Registration Form (register.layout.php)

Assets

CSS (users.css)

JavaScript (users.js)

JavaScript Functionality

Live Demo

2FA Auth Confirm (`2fa.auth.confirm.layout.php`)

2FA Auth (`2fa.auth.layout.php`)

2FA Email (`2fa.email.layout.php`)

Logged In Dashboard (`index.logged.layout.php`)

Login Form (`login.layout.php`)

Registration Form (`register.layout.php`)

CSS (`users.css`)

JavaScript (`users.js`)