boilercraft 1.0.0

package/templates/raw-php-mysql/app/Controllers/AuthController.php

@@ -0,0 +1,73 @@
+<?php
+namespace App\Controllers;
+
+use App\Models\User;
+use App\Config\Auth;
+
+class AuthController {
+    public function showLogin(): void {
+        require __DIR__ . '/../Views/auth/login.php';
+    }
+
+    public function login(): void {
+        header('Content-Type: application/json');
+        $raw = file_get_contents('php://input');
+        $data = json_decode($raw, true) ?: $_POST;
+
+        $email = trim($data['email'] ?? '');
+        $password = $data['password'] ?? '';
+
+        $userModel = new User();
+        $user = $userModel->findByEmail($email);
+
+        if ($user && password_verify($password, $user['password'])) {
+            Auth::login($user);
+            echo json_encode(['success' => true, 'redirect' => '/dashboard']);
+        } else {
+            http_response_code(401);
+            echo json_encode(['success' => false, 'error' => 'Invalid email or password']);
+        }
+    }
+
+    public function showRegister(): void {
+        require __DIR__ . '/../Views/auth/register.php';
+    }
+
+    public function register(): void {
+        header('Content-Type: application/json');
+        $raw = file_get_contents('php://input');
+        $data = json_decode($raw, true) ?: $_POST;
+
+        $name = trim($data['name'] ?? '');
+        $email = trim($data['email'] ?? '');
+        $password = $data['password'] ?? '';
+        $role = $data['role'] ?? 'user';
+
+        if (empty($name) || empty($email) || strlen($password) < 6) {
+            http_response_code(422);
+            echo json_encode(['success' => false, 'error' => 'Name, valid email and min 6 char password required.']);
+            return;
+        }
+
+        $userModel = new User();
+        if ($userModel->findByEmail($email)) {
+            http_response_code(409);
+            echo json_encode(['success' => false, 'error' => 'Email already registered.']);
+            return;
+        }
+
+        $hashed = password_hash($password, PASSWORD_BCRYPT);
+        $userModel->createWithPassword($name, $email, $hashed, $role);
+        
+        $newUser = $userModel->findByEmail($email);
+        Auth::login($newUser);
+
+        echo json_encode(['success' => true, 'redirect' => '/dashboard']);
+    }
+
+    public function logout(): void {
+        Auth::logout();
+        header('Location: /login');
+        exit;
+    }
+}

package/templates/raw-php-mysql/app/Controllers/HomeController.php

@@ -0,0 +1,65 @@
+<?php
+namespace App\Controllers;
+
+use App\Models\User;
+
+class HomeController {
+    public function index(): void {
+        $appName = "{{APP_TITLE}}";
+        $appDesc = "{{APP_DESC}}";
+        $author = "{{AUTHOR}}";
+        
+        $userModel = new User();
+        $users = $userModel->all();
+
+        require __DIR__ . '/../Views/home.php';
+    }
+
+    /**
+     * AJAX Endpoint for User Registration
+     */
+    public function apiCreateUser(): void {
+        header('Content-Type: application/json');
+        $raw = file_get_contents('php://input');
+        $data = json_decode($raw, true) ?: $_POST;
+
+        $name = trim($data['name'] ?? '');
+        $email = trim($data['email'] ?? '');
+
+        if (empty($name) || empty($email)) {
+            http_response_code(422);
+            echo json_encode(['success' => false, 'error' => 'Name and Email are required.']);
+            return;
+        }
+
+        try {
+            $userModel = new User();
+            $userModel->create($name, $email);
+            echo json_encode(['success' => true, 'message' => 'User created via AJAX successfully!']);
+        } catch (\Exception $e) {
+            http_response_code(500);
+            echo json_encode(['success' => false, 'error' => $e->getMessage()]);
+        }
+    }
+
+    /**
+     * AJAX Endpoint for fetching Users list
+     */
+    public function apiGetUsers(): void {
+        header('Content-Type: application/json');
+        $userModel = new User();
+        $users = $userModel->all();
+        echo json_encode(['success' => true, 'data' => $users]);
+    }
+
+    public function apiHealth(): void {
+        header('Content-Type: application/json');
+        echo json_encode([
+            'status' => 'online',
+            'platform' => 'Raw PHP MVC',
+            'database' => 'MySQL PDO',
+            'ajax_support' => true,
+            'timestamp' => time()
+        ]);
+    }
+}

package/templates/raw-php-mysql/app/Models/User.php

@@ -0,0 +1,60 @@
+<?php
+namespace App\Models;
+
+use App\Config\QueryBuilder;
+use App\Config\Database;
+
+class User {
+    protected string $table = 'users';
+
+    public function __construct() {
+        $this->initSchema();
+    }
+
+    private function initSchema(): void {
+        $sql = "CREATE TABLE IF NOT EXISTS {$this->table} (
+            id INT AUTO_INCREMENT PRIMARY KEY,
+            name VARCHAR(100) NOT NULL,
+            email VARCHAR(150) UNIQUE NOT NULL,
+            password VARCHAR(255) NULL,
+            role VARCHAR(50) DEFAULT 'user',
+            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        ) ENGINE=INNODB;";
+        Database::execute($sql);
+    }
+
+    public function all(): array {
+        return QueryBuilder::table($this->table)
+            ->orderBy('id', 'DESC')
+            ->limit(20)
+            ->get();
+    }
+
+    public function find(int $id): ?array {
+        return QueryBuilder::table($this->table)
+            ->where('id', $id)
+            ->first();
+    }
+
+    public function findByEmail(string $email): ?array {
+        return QueryBuilder::table($this->table)
+            ->where('email', $email)
+            ->first();
+    }
+
+    public function createWithPassword(string $name, string $email, string $passwordHash, string $role = 'user'): bool {
+        return QueryBuilder::table($this->table)->insert([
+            'name' => $name,
+            'email' => $email,
+            'password' => $passwordHash,
+            'role' => $role
+        ]);
+    }
+
+    public function create(string $name, string $email): bool {
+        return QueryBuilder::table($this->table)->insert([
+            'name' => $name,
+            'email' => $email
+        ]);
+    }
+}

package/templates/raw-php-mysql/app/Views/404.php

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>404 Not Found</title>
+    <link rel="stylesheet" href="/css/theme.css">
+</head>
+<body style="display: flex; height: 100vh; align-items: center; justify-content: center; text-align: center;">
+    <div>
+        <h1 style="font-size: 4rem; color: var(--color-primary);">404</h1>
+        <p style="color: var(--color-text-muted);">Page Not Found</p>
+        <a href="/" style="color: var(--color-primary); text-decoration: underline; margin-top: 1rem; display: inline-block;">Return Home</a>
+    </div>
+</body>
+</html>

package/templates/raw-php-mysql/app/Views/auth/login.php

@@ -0,0 +1,66 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Login — Access Account</title>
+    <link rel="stylesheet" href="/css/theme.css">
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
+</head>
+<body class="min-h-screen flex items-center justify-center p-6 bg-[var(--color-bg)] text-[var(--color-text)]">
+    <div class="max-w-md w-full p-8 rounded-2xl bg-[var(--color-surface)] border border-[var(--color-border)] shadow-2xl">
+        <h2 class="text-2xl font-bold mb-1">Welcome Back</h2>
+        <p class="text-sm text-[var(--color-text-muted)] mb-6">Sign in to your authenticated account</p>
+
+        <form id="loginForm" class="space-y-4">
+            <div>
+                <label class="block text-xs font-semibold mb-1">Email Address</label>
+                <input type="email" id="email" required class="w-full px-4 py-2.5 rounded-xl border border-[var(--color-border)] bg-[var(--color-bg)] text-[var(--color-text)] outline-none focus:border-[var(--color-primary)]">
+            </div>
+            <div>
+                <label class="block text-xs font-semibold mb-1">Password</label>
+                <input type="password" id="password" required class="w-full px-4 py-2.5 rounded-xl border border-[var(--color-border)] bg-[var(--color-bg)] text-[var(--color-text)] outline-none focus:border-[var(--color-primary)]">
+            </div>
+
+            <div id="loginMsg" class="text-xs font-semibold"></div>
+
+            <button type="submit" id="btnLogin" class="w-full py-3 rounded-xl bg-[var(--color-primary)] text-white font-bold hover:opacity-95 transition shadow-lg shadow-[var(--color-primary)]/25">
+                Sign In
+            </button>
+        </form>
+
+        <p class="text-xs text-center mt-6 text-[var(--color-text-muted)]">
+            Don't have an account? <a href="/register" class="text-[var(--color-primary)] font-bold">Register</a>
+        </p>
+    </div>
+
+    <script>
+        $('#loginForm').on('submit', function(e) {
+            e.preventDefault();
+            const btn = $('#btnLogin');
+            const msg = $('#loginMsg');
+            btn.prop('disabled', true).text('Verifying...');
+
+            $.ajax({
+                url: '/api/login',
+                type: 'POST',
+                contentType: 'application/json',
+                data: JSON.stringify({
+                    email: $('#email').val(),
+                    password: $('#password').val()
+                }),
+                success: function(res) {
+                    msg.html('<span class="text-emerald-500">✓ Login successful! Redirecting...</span>');
+                    window.location.href = res.redirect || '/dashboard';
+                },
+                error: function(xhr) {
+                    const err = xhr.responseJSON ? xhr.responseJSON.error : 'Invalid credentials';
+                    msg.html('<span class="text-rose-500">✗ ' + err + '</span>');
+                    btn.prop('disabled', false).text('Sign In');
+                }
+            });
+        });
+    </script>
+</body>
+</html>

package/templates/raw-php-mysql/app/Views/auth/register.php

@@ -0,0 +1,71 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Register — Create Account</title>
+    <link rel="stylesheet" href="/css/theme.css">
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
+</head>
+<body class="min-h-screen flex items-center justify-center p-6 bg-[var(--color-bg)] text-[var(--color-text)]">
+    <div class="max-w-md w-full p-8 rounded-2xl bg-[var(--color-surface)] border border-[var(--color-border)] shadow-2xl">
+        <h2 class="text-2xl font-bold mb-1">Create Account</h2>
+        <p class="text-sm text-[var(--color-text-muted)] mb-6">Register a new authenticated profile</p>
+
+        <form id="regForm" class="space-y-4">
+            <div>
+                <label class="block text-xs font-semibold mb-1">Full Name</label>
+                <input type="text" id="name" required class="w-full px-4 py-2.5 rounded-xl border border-[var(--color-border)] bg-[var(--color-bg)] text-[var(--color-text)] outline-none focus:border-[var(--color-primary)]">
+            </div>
+            <div>
+                <label class="block text-xs font-semibold mb-1">Email Address</label>
+                <input type="email" id="email" required class="w-full px-4 py-2.5 rounded-xl border border-[var(--color-border)] bg-[var(--color-bg)] text-[var(--color-text)] outline-none focus:border-[var(--color-primary)]">
+            </div>
+            <div>
+                <label class="block text-xs font-semibold mb-1">Password</label>
+                <input type="password" id="password" minlength="6" required class="w-full px-4 py-2.5 rounded-xl border border-[var(--color-border)] bg-[var(--color-bg)] text-[var(--color-text)] outline-none focus:border-[var(--color-primary)]">
+            </div>
+
+            <div id="regMsg" class="text-xs font-semibold"></div>
+
+            <button type="submit" id="btnReg" class="w-full py-3 rounded-xl bg-[var(--color-primary)] text-white font-bold hover:opacity-95 transition shadow-lg shadow-[var(--color-primary)]/25">
+                Register Now
+            </button>
+        </form>
+
+        <p class="text-xs text-center mt-6 text-[var(--color-text-muted)]">
+            Already registered? <a href="/login" class="text-[var(--color-primary)] font-bold">Login</a>
+        </p>
+    </div>
+
+    <script>
+        $('#regForm').on('submit', function(e) {
+            e.preventDefault();
+            const btn = $('#btnReg');
+            const msg = $('#regMsg');
+            btn.prop('disabled', true).text('Creating Account...');
+
+            $.ajax({
+                url: '/api/register',
+                type: 'POST',
+                contentType: 'application/json',
+                data: JSON.stringify({
+                    name: $('#name').val(),
+                    email: $('#email').val(),
+                    password: $('#password').val()
+                }),
+                success: function(res) {
+                    msg.html('<span class="text-emerald-500">✓ Account created! Redirecting...</span>');
+                    window.location.href = res.redirect || '/dashboard';
+                },
+                error: function(xhr) {
+                    const err = xhr.responseJSON ? xhr.responseJSON.error : 'Registration failed';
+                    msg.html('<span class="text-rose-500">✗ ' + err + '</span>');
+                    btn.prop('disabled', false).text('Register Now');
+                }
+            });
+        });
+    </script>
+</body>
+</html>

package/templates/raw-php-mysql/app/Views/dashboard.php

@@ -0,0 +1,50 @@
+<?php
+use App\Config\Auth;
+$currentUser = Auth::user();
+?>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Dashboard — Authenticated Area</title>
+    <link rel="stylesheet" href="/css/theme.css">
+    <script src="https://cdn.tailwindcss.com"></script>
+</head>
+<body class="p-8 bg-[var(--color-bg)] text-[var(--color-text)] min-h-screen">
+    <div class="max-w-4xl mx-auto">
+        <div class="flex justify-between items-center pb-6 border-b border-[var(--color-border)] mb-8">
+            <div>
+                <h1 class="text-3xl font-extrabold">Protected Dashboard</h1>
+                <p class="text-sm text-[var(--color-text-muted)]">Session Authentication & Role Authorization Active</p>
+            </div>
+            <div class="flex items-center gap-4">
+                <span class="px-3 py-1 text-xs rounded-full bg-emerald-500/10 text-emerald-400 font-bold border border-emerald-500/20">
+                    Role: <?= htmlspecialchars($currentUser['role']) ?>
+                </span>
+                <a href="/logout" class="px-4 py-2 rounded-xl border border-[var(--color-border)] text-sm font-semibold hover:bg-rose-500 hover:text-white transition">
+                    Logout
+                </a>
+            </div>
+        </div>
+
+        <div class="p-6 rounded-2xl bg-[var(--color-surface)] border border-[var(--color-border)] shadow-xl mb-6">
+            <h3 class="font-bold text-lg mb-2">Welcome, <?= htmlspecialchars($currentUser['name']) ?>!</h3>
+            <p class="text-sm text-[var(--color-text-muted)] mb-4">You are authorized to view this page. Your email is <strong><?= htmlspecialchars($currentUser['email']) ?></strong>.</p>
+            
+            <div class="p-4 rounded-xl bg-[var(--color-bg)] border border-[var(--color-border)] font-mono text-xs text-emerald-400">
+                // Session State<br>
+                User ID: <?= $currentUser['id'] ?><br>
+                Role: <?= $currentUser['role'] ?><br>
+                Guard: Middleware::auth() Passed
+            </div>
+        </div>
+
+        <?php if ($currentUser['role'] === 'admin'): ?>
+        <div class="p-6 rounded-2xl bg-amber-500/10 border border-amber-500/30 text-amber-200">
+            <h4 class="font-bold mb-1">👑 Admin Only Area</h4>
+            <p class="text-xs">This section is strictly rendered because your account has the 'admin' permission.</p>
+        </div>
+        <?php endif; ?>
+    </div>
+</body>
+</html>

package/templates/raw-php-mysql/app/Views/home.php

@@ -0,0 +1,83 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="{{COLOR_MODE}}">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title><?= htmlspecialchars($appName) ?></title>
+    <link rel="stylesheet" href="/css/theme.css">
+    {{STYLESHEET_LINK}}
+    <!-- jQuery Support CDN -->
+    <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
+</head>
+<body class="p-6">
+    <div style="max-width: 900px; margin: 2rem auto; text-align: center;">
+        {{LOGO_HTML}}
+        <h1 style="font-size: 2.5rem; font-weight: 800; margin-bottom: 0.5rem;"><?= htmlspecialchars($appName) ?></h1>
+        <p style="color: var(--color-text-muted); font-size: 1.1rem;"><?= htmlspecialchars($appDesc) ?></p>
+        <p style="font-size: 0.85rem; color: var(--color-primary); font-weight: 700; margin-top: 4px;">Crafted by <?= htmlspecialchars($author) ?></p>
+
+        <!-- AJAX Live Form Demo (jQuery / Vanilla Fetch) -->
+        <div style="text-align: left; padding: 2rem; background: var(--color-surface); border: 1px solid var(--color-border); border-radius: var(--radius-base); margin-top: 2rem; box-shadow: 0 10px 30px rgba(0,0,0,0.15);">
+            <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 1rem;">
+                <h3 style="margin: 0;">⚡ Live AJAX + jQuery Demo (No Page Reload)</h3>
+                <span style="font-size: 0.75rem; padding: 4px 8px; border-radius: 6px; background: rgba(16, 185, 129, 0.2); color: #10b981; font-weight: bold;">AJAX Ready</span>
+            </div>
+            
+            <p style="color: var(--color-text-muted); font-size: 0.9rem;">
+                এই Raw PHP আর্কিটেকচারে আপনি নির্দ্বিধায় <strong>jQuery, Axios, Fetch API, Tailwind CSS</strong> বা <strong>Bootstrap 5</strong> যা ইচ্ছা ব্যবহার করতে পারবেন।
+            </p>
+
+            <form id="ajaxUserForm" style="display: grid; grid-template-columns: 1fr 1fr auto; gap: 10px; margin-top: 1rem;">
+                <input type="text" id="ajaxName" placeholder="Full Name" required style="padding: 10px; border-radius: 8px; border: 1px solid var(--color-border); background: var(--color-bg); color: var(--color-text);">
+                <input type="email" id="ajaxEmail" placeholder="Email Address" required style="padding: 10px; border-radius: 8px; border: 1px solid var(--color-border); background: var(--color-bg); color: var(--color-text);">
+                <button type="submit" id="btnSubmit" style="background: var(--color-primary); color: white; border: none; padding: 10px 18px; border-radius: 8px; font-weight: bold; cursor: pointer;">
+                    Send via AJAX
+                </button>
+            </form>
+            <div id="ajaxResponse" style="margin-top: 10px; font-size: 0.85rem; font-weight: 600;"></div>
+        </div>
+
+        <!-- Dynamic UI Components Section -->
+        <div style="text-align: left; padding: 2rem; background: var(--color-surface); border: 1px solid var(--color-border); border-radius: var(--radius-base); margin-top: 2rem;">
+            <h4>Included Interactive UI Components:</h4>
+            {{UI_COMPONENTS}}
+        </div>
+    </div>
+
+    <!-- Live jQuery AJAX Handling Script -->
+    <script>
+        $(document).ready(function() {
+            $('#ajaxUserForm').on('submit', function(e) {
+                e.preventDefault();
+                const btn = $('#btnSubmit');
+                const resp = $('#ajaxResponse');
+
+                btn.prop('disabled', true).text('Saving...');
+                resp.html('<span style="color: var(--color-primary);">Connecting with server...</span>');
+
+                $.ajax({
+                    url: '/api/users',
+                    type: 'POST',
+                    contentType: 'application/json',
+                    data: JSON.stringify({
+                        name: $('#ajaxName').val(),
+                        email: $('#ajaxEmail').val()
+                    }),
+                    success: function(response) {
+                        resp.html('<span style="color: #10b981;">✓ ' + response.message + '</span>');
+                        $('#ajaxUserForm')[0].reset();
+                    },
+                    error: function(xhr) {
+                        const err = xhr.responseJSON ? xhr.responseJSON.error : 'Submission failed';
+                        resp.html('<span style="color: #ef4444;">✗ ' + err + '</span>');
+                    },
+                    complete: function() {
+                        btn.prop('disabled', false).text('Send via AJAX');
+                    }
+                });
+            });
+        });
+    </script>
+    <script src="/js/theme.js"></script>
+</body>
+</html>

package/templates/raw-php-mysql/config/Auth.php

@@ -0,0 +1,62 @@
+<?php
+namespace App\Config;
+
+class Auth {
+    public static function init(): void {
+        if (session_status() === PHP_SESSION_NONE) {
+            session_start();
+        }
+    }
+
+    public static function login(array $user): void {
+        self::init();
+        $_SESSION['user_id'] = $user['id'];
+        $_SESSION['user_role'] = $user['role'] ?? 'user';
+        $_SESSION['user_name'] = $user['name'];
+        $_SESSION['user_email'] = $user['email'];
+    }
+
+    public static function check(): bool {
+        self::init();
+        return isset($_SESSION['user_id']);
+    }
+
+    public static function user(): ?array {
+        self::init();
+        if (!self::check()) return null;
+        return [
+            'id' => $_SESSION['user_id'],
+            'name' => $_SESSION['user_name'],
+            'email' => $_SESSION['user_email'],
+            'role' => $_SESSION['user_role']
+        ];
+    }
+
+    public static function id(): ?int {
+        self::init();
+        return $_SESSION['user_id'] ?? null;
+    }
+
+    public static function hasRole(string|array $roles): bool {
+        self::init();
+        if (!self::check()) return false;
+        $userRole = $_SESSION['user_role'] ?? 'user';
+        if (is_array($roles)) {
+            return in_array($userRole, $roles);
+        }
+        return $userRole === $roles;
+    }
+
+    public static function logout(): void {
+        self::init();
+        $_SESSION = [];
+        if (ini_get("session.use_cookies")) {
+            $params = session_get_cookie_params();
+            setcookie(session_name(), '', time() - 42000,
+                $params["path"], $params["domain"],
+                $params["secure"], $params["httponly"]
+            );
+        }
+        session_destroy();
+    }
+}

package/templates/raw-php-mysql/config/Database.php

@@ -0,0 +1,100 @@
+<?php
+namespace App\Config;
+
+use PDO;
+use PDOException;
+
+class Database {
+    private static ?PDO $instance = null;
+
+    /**
+     * Get Singleton PDO connection with multi-driver support:
+     * - MySQL / MariaDB (utf8mb4)
+     * - MSSQL (sqlsrv / dblib)
+     * - PostgreSQL (pgsql)
+     * - SQLite (zero-config local file)
+     */
+    public static function getConnection(): PDO {
+        if (self::$instance === null) {
+            $dbType = strtolower(getenv('DB_CONNECTION') ?: '{{DB_TYPE}}');
+            $host   = getenv('DB_HOST') ?: '127.0.0.1';
+            $dbname = getenv('DB_NAME') ?: getenv('DB_DATABASE') ?: '{{DB_NAME}}';
+            $user   = getenv('DB_USER') ?: getenv('DB_USERNAME') ?: 'root';
+            $pass   = getenv('DB_PASS') ?: getenv('DB_PASSWORD') ?: '';
+            
+            $commonOptions = [
+                PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
+                PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
+                PDO::ATTR_EMULATE_PREPARES   => false,
+            ];
+
+            try {
+                switch ($dbType) {
+                    case 'mssql':
+                    case 'sqlsrv':
+                        $port = getenv('DB_PORT') ?: '1433';
+                        // Checks if sqlsrv driver exists, else fallback to dblib
+                        if (in_array('sqlsrv', PDO::getAvailableDrivers())) {
+                            $dsn = "sqlsrv:Server={$host},{$port};Database={$dbname};TrustServerCertificate=true";
+                        } else {
+                            $dsn = "dblib:host={$host}:{$port};dbname={$dbname}";
+                        }
+                        self::$instance = new PDO($dsn, $user, $pass, $commonOptions);
+                        break;
+
+                    case 'pgsql':
+                    case 'postgres':
+                        $port = getenv('DB_PORT') ?: '5432';
+                        $dsn = "pgsql:host={$host};port={$port};dbname={$dbname}";
+                        self::$instance = new PDO($dsn, $user, $pass, $commonOptions);
+                        break;
+
+                    case 'sqlite':
+                        $sqlitePath = getenv('DB_PATH') ?: __DIR__ . '/../../database.sqlite';
+                        if (!file_exists($sqlitePath)) {
+                            touch($sqlitePath);
+                        }
+                        $dsn = "sqlite:{$sqlitePath}";
+                        self::$instance = new PDO($dsn, null, null, $commonOptions);
+                        break;
+
+                    case 'mysql':
+                    case 'mariadb':
+                    default:
+                        $port = getenv('DB_PORT') ?: '3306';
+                        $charset = 'utf8mb4';
+                        $dsn = "mysql:host={$host};port={$port};dbname={$dbname};charset={$charset}";
+                        self::$instance = new PDO($dsn, $user, $pass, $commonOptions);
+                        break;
+                }
+            } catch (PDOException $e) {
+                http_response_code(500);
+                header('Content-Type: application/json');
+                echo json_encode([
+                    'success' => false,
+                    'error' => "Database Connection Failed [Engine: {$dbType}]",
+                    'message' => $e->getMessage()
+                ]);
+                exit;
+            }
+        }
+        return self::$instance;
+    }
+
+    /**
+     * Helper to run parameterized queries safely
+     */
+    public static function query(string $sql, array $params = []): array {
+        $stmt = self::getConnection()->prepare($sql);
+        $stmt->execute($params);
+        return $stmt->fetchAll();
+    }
+
+    /**
+     * Helper for INSERT / UPDATE / DELETE
+     */
+    public static function execute(string $sql, array $params = []): bool {
+        $stmt = self::getConnection()->prepare($sql);
+        return $stmt->execute($params);
+    }
+}