UPDATE :

ADDED 4 Separate Files For functions.... Question Edited Accordingly.

Please check new code for security and other points.

Providing code with some usage examples

Original Class Created on which following answers received...

Link - HERE ( Deleted Original Content From HEre Due To Characters Limit in question )

Expecting your valuable suggestions on it.

UPDATED FILES :

DatabaseConfig.php

<?php
declare(strict_types=1);
// DatabaseConfig.php

// --- Database Configuration Constants ---
// Define these constants with your actual database credentials.
// For security, consider loading these from environment variables or a configuration file outside the web root.
define('DB_HOST', 'localhost'); // Your database host
define('DB_NAME', 'test_db');   // Your database name
define('DB_USER', 'root');      // Your database username
define('DB_PASSWORD', '');          // Your database password
define('DB_CHARSET', 'utf8mb4'); // Default character set

// Define the default timezone for date/time functions.
// Refer to PHP's list of supported timezones: https://www.php.net/manual/en/timezones.php
define('DEFAULT_APP_TIMEZONE', 'Asia/Kolkata');

// Set the default timezone for all date/time functions in the script.
date_default_timezone_set(DEFAULT_APP_TIMEZONE);

?>

DatabaseConnection.php

<?php
declare(strict_types=1);
// DatabaseConnection.php

require_once 'DatabaseConfig.php';

/**
 * DatabaseConnection Class
 * Manages the PDO connection to a MySQL database.
 */
class DatabaseConnection
{
    private PDO $pdo;

    /**
     * Constructor: Establishes a PDO connection to the database.
     *
     * @param string $host The database host.
     * @param string $dbName The database name.
     * @param string $user The database username.
     * @param string $password The database password.
     * @param string $charset The character set.
     * @throws Exception If the database connection fails.
     */
    public function __construct(
        string $host = DB_HOST,
        string $dbName = DB_NAME,
        string $user = DB_USER,
        string $password = DB_PASSWORD,
        string $charset = DB_CHARSET
    ) {
        $dsn = "mysql:host={$host};dbname={$dbName};charset={$charset}";
        $options = [
            PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
            PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
            PDO::ATTR_EMULATE_PREPARES   => false,
        ];

        try {
            $this->pdo = new PDO($dsn, $user, $password, $options);
        } catch (PDOException $e) {
            $errorMessage = "Database connection failed: " . $e->getMessage();
            error_log($errorMessage); // Log the error
            // Re-throw a generic Exception for the calling code to handle
            throw new Exception("A critical database connection error occurred. Please try again later.");
        }
    }

    /**
     * Returns the PDO instance.
     *
     * @return PDO The PDO database connection object.
     */
    public function getPdo(): PDO
    {
        return $this->pdo;
    }
}

QueryBuilder.php

<?php
declare(strict_types=1);
// QueryBuilder.php

/**
 * QueryBuilder Class
 * Responsible for building SQL query components and escaping identifiers.
 */
class QueryBuilder
{
    /**
     * Escapes a database identifier (table name, column name, alias) with backticks
     * and handles existing backticks within the identifier.
     *
     * @param string $identifier The identifier name to escape.
     * @param bool $doubleBackticks If true, doubles internal backticks (default: true).
     * Set to false for aliases where doubling might not be desired
     * if they are simple, unquoted identifiers. However, for for full safety,
     * it's generally best to always escape.
     * @return string The escaped identifier.
     */
    public function escapeIdentifier(string $identifier, bool $doubleBackticks = true): string
    {
        if ($doubleBackticks) {
            // Escape any existing backticks by doubling them
            $identifier = str_replace("`", "``", $identifier);
        }
        // Wrap the identifier in backticks
        return "`" . $identifier . "`";
    }

    /**
     * Helper function to build the WHERE clause string and populate parameters array.
     * Supports AND conditions at the top level and one special '_OR_' group.
     * The '_OR_' group should contain an array of condition sets, where each set
     * is ANDed internally, and then these sets are ORed together.
     *
     * @param array<string, mixed> $conditions An associative array of column => value pairs for the WHERE clause.
     * Can include a special '_OR_' key for OR conditions.
     * @param array<mixed> $params Reference to the main parameters array to add new values.
     * @return string The WHERE clause string (e.g., " WHERE `column` = ? AND (`other_column` = ? OR `another_column` = ?)").
     */
    public function buildWhereClause(array $conditions, array &$params): string
    {
        $whereParts = [];
        $orGroupClauses = [];

        foreach ($conditions as $key => $value) {
            if ($key === '_OR_' && is_array($value)) {
                $currentOrGroupParts = [];
                foreach ($value as $orConditionSet) {
                    if (is_array($orConditionSet)) {
                        $subConditionParts = [];
                        foreach ($orConditionSet as $subColumn => $subValue) {
                            $conditionPart = $this->_processSingleCondition($subColumn, $subValue, $params);
                            if ($conditionPart !== null) {
                                $subConditionParts[] = $conditionPart;
                            }
                        }
                        if (!empty($subConditionParts)) {
                            $currentOrGroupParts[] = "(" . implode(" AND ", $subConditionParts) . ")";
                        }
                    } else {
                        error_log("Invalid OR condition set format. Expected an array of associative arrays.");
                    }
                }
                if (!empty($currentOrGroupParts)) {
                    $orGroupClauses[] = "(" . implode(" OR ", $currentOrGroupParts) . ")";
                }
            } else {
                $conditionPart = $this->_processSingleCondition($key, $value, $params);
                if ($conditionPart !== null) {
                    $whereParts[] = $conditionPart;
                }
            }
        }

        $finalWhereParts = array_merge($whereParts, $orGroupClauses);

        return empty($finalWhereParts) ? '' : " WHERE " . implode(" AND ", $finalWhereParts);
    }

    /**
     * Helper function to process a single condition (column => value pair).
     *
     * @param string $column The column name.
     * @param mixed $value The value for the condition.
     * @param array<mixed> $params Reference to the main parameters array to add new values.
     * @return string|null The SQL snippet for the condition, or null if invalid.
     */
    private function _processSingleCondition(string $column, mixed $value, array &$params): ?string
    {
        $operator = '=';
        $field = $column;
        $isBinary = false;

        if (strpos(strtoupper(trim($column)), 'BINARY ') === 0) {
            $isBinary = true;
            $field = substr(trim($column), 7);
        }

        if (preg_match('/(.*?)\s*(<|>|<=|>=|!=|<>|LIKE|NOT LIKE|IN|NOT IN|IS NULL|IS NOT NULL)$/i', $field, $matches)) {
            $field = trim($matches[1]);
            $operator = strtoupper(trim($matches[2]));
        }

        $field_escaped = $this->escapeIdentifier($field);
        if ($isBinary) {
            $field_escaped = "BINARY {$field_escaped}";
        }

        if ($operator === 'IN' || $operator === 'NOT IN') {
            if (is_array($value)) {
                $placeholders = $this->inClauseHelper($value, $params);
                return "{$field_escaped} {$operator} ({$placeholders})";
            } else {
                error_log("Invalid value for IN/NOT IN clause for column '{$field}'. Value must be an array.");
                return null;
            }
        } elseif ($operator === 'IS NULL' || $operator === 'IS NOT NULL') {
            return "{$field_escaped} {$operator}";
        } else {
            $params[] = $value;
            return "{$field_escaped} {$operator} ?";
        }
    }

    /**
     * Helper function to generate placeholders for an IN clause and bind parameters.
     *
     * @param array<mixed> $values An array of values for the IN clause.
     * @param array<mixed> $params Reference to the main parameters array to add new values.
     * @return string A string of comma-separated placeholders (e.g., '?, ?, ?').
     */
    public function inClauseHelper(array $values, array &$params): string
     {
        if (empty($values)) {
            return 'NULL';
        }
        $placeholders = implode(', ', array_fill(0, count($values), '?'));
        foreach ($values as $val) {
            $params[] = $val;
        }
        return $placeholders;
    }
}

CrudOperations.php

<?php
declare(strict_types=1);
// CrudOperations.php

require_once 'DatabaseConnection.php';
require_once 'QueryBuilder.php';

/**
 * CrudOperations Class
 * Provides core CRUD (Create, Read, Update, Delete) functionalities.
 */
class CrudOperations
{
    private PDO $pdo;
    private QueryBuilder $queryBuilder;
    private int $queryCount = 0;

    /**
     * Constructor.
     *
     * @param PDO $pdo The PDO database connection object.
     */
    public function __construct(PDO $pdo)
     {
        $this->pdo = $pdo;
        $this->queryBuilder = new QueryBuilder();
    }

    /**
     * Execute arbitrary SQL queries (SELECT, INSERT, UPDATE, DELETE, etc.).
     * This function uses prepared statements to prevent SQL injection.
     *
     * @param string $sql The SQL query string.
     * @param array<mixed> $params An associative or indexed array of parameters to bind to the query.
     * @return PDOStatement Returns the PDOStatement object on success.
     * @throws PDOException If the query execution fails.
     */
    public function executeQuery(string $sql, array $params = []): PDOStatement
    {
        try {
            $stmt = $this->pdo->prepare($sql);
            $stmt->execute($params);
            $this->queryCount++;
            return $stmt;
        } catch (PDOException $e) {
            $errorMessage = "Query execution failed: " . $e->getMessage() . " SQL: " . $sql . " Params: " . json_encode($params);
            error_log($errorMessage);
            // Re-throw the exception to allow calling code to handle it
            throw $e;
        }
    }

    /**
     * Retrieve the number of rows from a table based on multiple WHERE clauses.
     *
     * @param string $table The name of the table.
     * @param array<string, mixed> $conditions An associative array of column => value pairs for the WHERE clause.
     * @return int The number of rows matching the conditions, or 0 on error.
     */
    public function numRows(string $table, array $conditions = []): int
    {
        $sql = "SELECT COUNT(*) FROM " . $this->queryBuilder->escapeIdentifier($table);
        $params = [];
        $whereClause = $this->queryBuilder->buildWhereClause($conditions, $params);

        $sql .= $whereClause;

        try {
            $stmt = $this->executeQuery($sql, $params);
            $result = $stmt->fetchColumn();
            return is_numeric($result) ? (int) $result : 0;
        } catch (PDOException $e) {
            // Logged in executeQuery, re-throw or handle as appropriate for this specific method
            return 0; // Return 0 rows on error
        }
    }

    /**
     * Retrieve the query results in a single array.
     *
     * @param string $table The name of the table to retrieve data from.
     * @param array<string, mixed> $conditions An associative array of column => value pairs for the WHERE clause.
     * @param array<string> $selectColumns An array of column names to select (default: ['*'] for all columns).
     * @param array<string, string>|string $orderBy An ORDER BY clause. If an array (e.g., `['column_name' => 'ASC']`),
     * column names will be escaped. If a string, it's used as-is (developer's responsibility to sanitize).
     * @param array<string>|string $groupBy A GROUP BY clause. If an array (e.g., `['column1', 'column2']`),
     * column names will be escaped. If a string, it's used as-is (developer's responsibility to sanitize).
     * @param int|null $limit A LIMIT clause.
     * @param int $fetch_style The PDO fetch style.
     * @return array<array<string, mixed>> An array of query results.
     */
    public function getResults(
        string $table,
        array $conditions = [],
        array $selectColumns = ['*'],
        array|string $orderBy = '',
        array|string $groupBy = '',
        ?int $limit = null,
        int $fetch_style = PDO::FETCH_ASSOC
    ): array {
        $selectClause = implode(", ", array_map([$this->queryBuilder, 'escapeIdentifier'], $selectColumns));
        $params = [];
        $whereClause = $this->queryBuilder->buildWhereClause($conditions, $params);

        $sql = "SELECT {$selectClause} FROM " . $this->queryBuilder->escapeIdentifier($table) . "{$whereClause}";

        if (!empty($groupBy)) {
            if (is_array($groupBy)) {
                $escapedGroupBy = implode(", ", array_map([$this->queryBuilder, 'escapeIdentifier'], $groupBy));
                $sql .= " GROUP BY {$escapedGroupBy}";
            } else {
                // Developer's responsibility to sanitize if string is provided
                $sql .= " GROUP BY {$groupBy}";
            }
        }

        if (!empty($orderBy)) {
            if (is_array($orderBy)) {
                $orderByParts = [];
                foreach ($orderBy as $column => $direction) {
                    $direction = strtoupper($direction);
                    if (!in_array($direction, ['ASC', 'DESC'])) {
                        $direction = 'ASC'; // Default to ASC for invalid directions
                    }
                    $orderByParts[] = $this->queryBuilder->escapeIdentifier($column) . " {$direction}";
                }
                $sql .= " ORDER BY " . implode(", ", $orderByParts);
            } else {
                // Developer's responsibility to sanitize if string is provided
                $sql .= " ORDER BY {$orderBy}";
            }
        }

        if ($limit !== null && $limit > 0) {
            $sql .= " LIMIT {$limit}";
        }

        try {
            $stmt = $this->executeQuery($sql, $params);
            return $stmt->fetchAll($fetch_style);
        } catch (PDOException $e) {
            // Logged in executeQuery, re-throw or handle as appropriate for this specific method
            return []; // Return empty array on error
        }
    }

    /**
     * Get the ID of the last inserted row.
     *
     * @return string The ID of the last inserted row.
     */
    public function lastInsertId(): string
    {
        return $this->pdo->lastInsertId();
    }

    /**
     * Check if a table exists in the current database.
     *
     * @param string $tableName The name of the table to check.
     * @return bool True if the table exists, false otherwise.
     */
    public function tableExists(string $tableName): bool
    {
        $sql = "SHOW TABLES LIKE ?";
        try {
            $stmt = $this->executeQuery($sql, [$tableName]);
            return $stmt->rowCount() > 0;
        } catch (PDOException $e) {
            // Logged in executeQuery, re-throw or handle as appropriate for this specific method
            return false; // Table does not exist on error
        }
    }

    /**
     * Check if a given table record exists based on conditions.
     *
     * @param string $table The name of the table.
     * @param array<string, mixed> $conditions An associative array of column => value pairs for the WHERE clause.
     * @return bool True if the record exists, false otherwise.
     */
    public function recordExists(string $table, array $conditions = []): bool
    {
        return $this->numRows($table, $conditions) > 0;
    }

    /**
     * Return a query result that has just one row.
     *
     * @param string $table The name of the table to retrieve data from.
     * @param array<string, mixed> $conditions An associative array of column => value pairs for the WHERE clause.
     * @param array<string> $selectColumns An array of column names to select (default: ['*'] for all columns).
     * @param int $fetch_style The PDO fetch style.
     * @return array<string, mixed>|false An associative array representing the single row, or false if no row is found or on error.
     */
    public function getSingleRow(string $table, array $conditions = [], array $selectColumns = ['*'], int $fetch_style = PDO::FETCH_ASSOC): array|false
    {
        $selectClause = implode(", ", array_map([$this->queryBuilder, 'escapeIdentifier'], $selectColumns));
        $params = [];
        $whereClause = $this->queryBuilder->buildWhereClause($conditions, $params);

        $sql = "SELECT {$selectClause} FROM " . $this->queryBuilder->escapeIdentifier($table) . "{$whereClause} LIMIT 1";

        try {
            $stmt = $this->executeQuery($sql, $params);
            return $stmt->fetch($fetch_style);
        } catch (PDOException $e) {
            // Logged in executeQuery, re-throw or handle as appropriate for this specific method
            return false; // Return false on error
        }
    }

    /**
     * Execute an INSERT query from values that define table, field names, and field values.
     *
     * @param string $table The table name.
     * @param array<string, mixed> $data An associative array of column => value pairs to insert.
     * @return bool True on success, false on failure.
     */
    public function insert(string $table, array $data): bool
    {
        if (empty($data)) {
            return false;
        }

        $columns = implode(", ", array_map([$this->queryBuilder, 'escapeIdentifier'], array_keys($data)));
        $placeholders = implode(", ", array_fill(0, count($data), '?'));
        $params = array_values($data);

        $sql = "INSERT INTO " . $this->queryBuilder->escapeIdentifier($table) . " ({$columns}) VALUES ({$placeholders})";
        try {
            $this->executeQuery($sql, $params);
            return true;
        } catch (PDOException $e) {
            // Logged in executeQuery, re-throw or handle as appropriate for this specific method
            return false; // Return false on error
        }
    }

    /**
     * Execute an INSERT MULTI query for inserting multiple rows at once.
     *
     * @param string $table The table name.
     * @param array<array<string, mixed>> $dataArray An array of associative arrays, where each inner array represents a row to insert.
     * @return bool True on success, false on failure.
     */
    public function insertMulti(string $table, array $dataArray): bool
    {
        if (empty($dataArray) || !is_array($dataArray[0])) {
            return false;
        }

        $columns = implode(", ", array_map([$this->queryBuilder, 'escapeIdentifier'], array_keys($dataArray[0])));
        $placeholders = "(" . implode(", ", array_fill(0, count($dataArray[0]), '?')) . ")";

        $values = [];
        $params = [];
        foreach ($dataArray as $row) {
            if (!is_array($row)) { // Ensure each row is an array
                error_log("Invalid row format in insertMulti. Expected an array.");
                return false;
            }
            $values[] = $placeholders;
            $params = array_merge($params, array_values($row));
        }

        $sql = "INSERT INTO " . $this->queryBuilder->escapeIdentifier($table) . " ({$columns}) VALUES " . implode(", ", $values);
        try {
            $this->executeQuery($sql, $params);
            return true;
        } catch (PDOException $e) {
            // Logged in executeQuery, re-throw or handle as appropriate for this specific method
            return false; // Return false on error
        }
    }

    /**
     * Execute an UPDATE query from values that define table, field names, field values, and conditions.
     *
     * @param string $table The table name.
     * @param array<string, mixed> $data An associative array of column => new_value pairs to update.
     * @param array<string, mixed> $conditions An associative array of column => value pairs for the WHERE clause.
     * @return bool True on success, false on failure.
     */
    public function update(string $table, array $data, array $conditions): bool
    {
        if (empty($data) || empty($conditions)) {
            return false;
        }

        $setParts = [];
        $params = [];
        foreach ($data as $column => $value) {
            $setParts[] = $this->queryBuilder->escapeIdentifier($column) . " = ?";
            $params[] = $value;
        }
        $setClause = implode(", ", $setParts);

        $whereClause = $this->queryBuilder->buildWhereClause($conditions, $params);

        $sql = "UPDATE " . $this->queryBuilder->escapeIdentifier($table) . " SET {$setClause} {$whereClause}";
        try {
            $this->executeQuery($sql, $params);
            return true;
        } catch (PDOException $e) {
            // Logged in executeQuery, re-throw or handle as appropriate for this specific method
            return false; // Return false on error
        }
    }

    /**
     * Execute a DELETE query from values that define table and conditions.
     *
     * @param string $table The table name.
     * @param array<string, mixed> $conditions An associative array of column => value pairs for the WHERE clause.
     * @return bool True on success, false on failure.
     */
    public function delete(string $table, array $conditions): bool
    {
        if (empty($conditions)) {
            error_log("Attempted to delete from table '{$table}' without conditions. Operation aborted.");
            return false; // Prevent accidental full table deletion
        }

        $params = [];
        $whereClause = $this->queryBuilder->buildWhereClause($conditions, $params);

        $sql = "DELETE FROM " . $this->queryBuilder->escapeIdentifier($table) . " {$whereClause}";
        try {
            $this->executeQuery($sql, $params);
            return true;
        } catch (PDOException $e) {
            // Logged in executeQuery, re-throw or handle as appropriate for this specific method
            return false; // Return false on error
        }
    }

    /**
     * Truncate a table (removes all rows and resets auto-increment counter).
     *
     * @param string $tableName The name of the table to truncate.
     * @return bool True on success, false on failure.
     */
    public function truncateTable(string $tableName): bool
    {
        $sql = "TRUNCATE TABLE " . $this->queryBuilder->escapeIdentifier($tableName);
        try {
            $this->executeQuery($sql);
            return true;
        } catch (PDOException $e) {
            // Logged in executeQuery, re-throw or handle as appropriate for this specific method
            return false; // Return false on error
        }
    }

    /**
     * Perform a JOIN operation on multiple tables.
     *
     * @param array<string, string> $tables An associative array of table_name => alias (e.g., ['users' => 'u']).
     * @param array<string> $onConditions An array of strings representing the JOIN ON conditions (e.g., 'u.id = o.user_id').
     * NOTE: These conditions are directly concatenated. Ensure they are from a trusted source and do not contain
     * unvalidated user input to prevent SQL injection.
     * @param array<string> $selectColumns An array of columns to select (default: ['*']).
     * @param array<string, mixed> $whereConditions An associative array of column => value pairs for the WHERE clause.
     * @return array<array<string, mixed>> An array of joined query results. Returns an empty array on no results or error.
     */
    public function joinTable(array $tables, array $onConditions, array $selectColumns = ['*'], array $whereConditions = []): array
    {
        if (empty($tables) || empty($onConditions)) {
            return [];
        }

        $fromClause = '';
        $joinClause = '';
        $firstTable = true;

        foreach ($tables as $tableName => $alias) {
            if ($firstTable) {
                // Escape table name and alias. Aliases typically don't need internal backtick doubling if they are simple.
                $fromClause = $this->queryBuilder->escapeIdentifier($tableName) . " AS " . $this->queryBuilder->escapeIdentifier($alias, false);
                $firstTable = false;
            } else {
                $joinClause .= " INNER JOIN " . $this->queryBuilder->escapeIdentifier($tableName) . " AS " . $this->queryBuilder->escapeIdentifier($alias, false);
            }
        }

        if (!empty($onConditions)) {
            // WARNING: $onConditions are directly concatenated. Sanitize or whitelist input in application layer.
            $joinClause .= " ON " . implode(" AND ", $onConditions);
        }

        $selectClause = implode(", ", array_map([$this->queryBuilder, 'escapeIdentifier'], $selectColumns));

        $params = [];
        $whereClause = $this->queryBuilder->buildWhereClause($whereConditions, $params);

        $sql = "SELECT {$selectClause} FROM {$fromClause} {$joinClause} {$whereClause}";

        try {
            $stmt = $this->executeQuery($sql, $params);
            return $stmt->fetchAll(PDO::FETCH_ASSOC);
        } catch (PDOException $e) {
            // Logged in executeQuery, re-throw or handle as appropriate for this specific method
            return []; // Return empty array on error
        }
    }

    /**
     * Retrieves records where a specified column's value is within a given array of values (IN clause).
     *
     * @param string $table The name of the table.
     * @param string $column The column name to apply the IN condition on.
     * @param array<mixed> $values An array of values to check against the column.
     * @param array<string, mixed> $additionalConditions Optional associative array of additional WHERE conditions (ANDed).
     * @param array<string> $selectColumns An array of column names to select (default: ['*'] for all columns).
     * @param array<string, string>|string $orderBy An ORDER BY clause. If an array (e.g., `['column_name' => 'ASC']`),
     * column names will be escaped. If a string, it's used as-is (developer's responsibility to sanitize).
     * @param array<string>|string $groupBy A GROUP BY clause. If an array (e.g., `['column1', 'column2']`),
     * column names will be escaped. If a string, it's used as-is (developer's responsibility to sanitize).
     * @param int|null $limit A LIMIT clause.
     * @return array<array<string, mixed>> An array of query results.
     */
    public function in(
        string $table,
        string $column,
        array $values,
        array $additionalConditions = [],
        array $selectColumns = ['*'],
        array|string $orderBy = '',
        array|string $groupBy = '',
        ?int $limit = null
    ): array {
        if (empty($table) || empty($column) || empty($values)) {
            error_log("Invalid parameters for 'in' function. Table, column, and non-empty array of values are required.");
            return [];
        }

        $conditions = array_merge($additionalConditions, [
            "{$column} IN" => $values
        ]);

        return $this->getResults($table, $conditions, $selectColumns, $orderBy, $groupBy, $limit);
    }

    /**
     * Executes a SELECT query using FIND_IN_SET on a specified column.
     *
     * @param string $table The name of the table to query.
     * @param string $value The value to search for within the comma-separated string.
     * @param string $column The column name containing comma-separated values.
     * @param array<string> $selectColumns An array of column names to select (default: ['*']).
     * @param array<string, mixed> $additionalConditions Optional associative array of additional WHERE conditions.
     * @param int $fetch_style The PDO fetch style.
     * @return array<array<string, mixed>> An array of query results.
     */
    public function findInSet(string $table, string $value, string $column, array $selectColumns = ['*'], array $additionalConditions = [], int $fetch_style = PDO::FETCH_ASSOC): array
    {
        $selectClause = implode(", ", array_map([$this->queryBuilder, 'escapeIdentifier'], $selectColumns));
        $params = [$value];

        $whereParts = ["FIND_IN_SET(?, " . $this->queryBuilder->escapeIdentifier($column) . ")"];

        if (!empty($additionalConditions)) {
            $tempParams = [];
            $additionalWhereClause = $this->queryBuilder->buildWhereClause($additionalConditions, $tempParams);
            if (strpos($additionalWhereClause, ' WHERE ') === 0) {
                $additionalWhereClause = substr($additionalWhereClause, 7);
            }
            if (!empty($additionalWhereClause)) {
                $whereParts[] = $additionalWhereClause;
                $params = array_merge($params, $tempParams);
            }
        }

        $whereClause = " WHERE " . implode(" AND ", $whereParts);

        $sql = "SELECT {$selectClause} FROM " . $this->queryBuilder->escapeIdentifier($table) . "{$whereClause}";

        try {
            $stmt = $this->executeQuery($sql, $params);
            return $stmt->fetchAll($fetch_style);
        } catch (PDOException $e) {
            // Logged in executeQuery, re-throw or handle as appropriate for this specific method
            return []; // Return empty array on error
        }
    }

    /**
     * Checks if a record exists in a table based on given conditions.
     *
     * @param string $table The database table name.
     * @param array<string, mixed> $conditions An associative array of column name => column value to match.
     * @return bool True if the record exists, false otherwise.
     */
    public function exists(string $table = '', array $conditions = []): bool
    {
        if (empty($table) || empty($conditions)) {
            return false;
        }
        return $this->numRows($table, $conditions) > 0;
    }

    /**
     * CASE-SENSITIVE check to see if a record exists in a table based on given conditions.
     * Uses BINARY comparison for case sensitivity.
     *
     * @param string $table The database table name.
     * @param array<string, mixed> $conditions An associative array of column name => column value to match.
     * @return bool True if the record exists case-sensitively, false otherwise.
     */
    public function binExists(string $table = '', array $conditions = []): bool
    {
        if (empty($table) || empty($conditions)) {
            return false;
        }

        $binaryConditions = [];
        foreach ($conditions as $field => $value) {
            $binaryConditions["BINARY " . $field] = $value;
        }

        return $this->numRows($table, $binaryConditions) > 0;
    }

    /**
     * Returns the number of fields (columns) in the result set of a query.
     *
     * @param PDOStatement|false $stmt The PDOStatement object returned by executeQuery.
     * @return int The number of fields, or 0 if statement is invalid.
     */
    public function getNumFields(PDOStatement|false $stmt): int
    {
        if ($stmt instanceof PDOStatement) {
            return $stmt->columnCount();
        }
        return 0;
    }

    /**
     * Returns an array of field (column) names from the result set of a query.
     *
     * @param PDOStatement|false $stmt The PDOStatement object returned by executeQuery.
     * @return array<string> An array of column names, or an empty array if statement is invalid.
     */
    public function getListFields(PDOStatement|false $stmt): array
    {
        $fieldNames = [];
        if ($stmt instanceof PDOStatement) {
            for ($i = 0; $i < $stmt->columnCount(); $i++) {
                $meta = $stmt->getColumnMeta($i);
                if (isset($meta['name'])) {
                    $fieldNames[] = $meta['name'];
                }
            }
        }
        return $fieldNames;
    }

    /**
     * Display the total number of queries performed by this instance.
     *
     * @return int The total number of queries executed.
     */
    public function getQueryCount(): int
    {
        return $this->queryCount;
    }
}

UtilityFunctions.php

<?php
declare(strict_types=1);
// UtilityFunctions.php

// Include random-code-generators-pdo.php if it contains functions used here.
require_once 'random-code-generators-pdo.php';

/**
 * UtilityFunctions Class
 * Provides a collection of general-purpose utility methods.
 */
class UtilityFunctions
{
    /**
     * Filter input data to prevent XSS and other vulnerabilities.
     * This function can handle strings and arrays recursively.
     *
     * @param mixed $data The input data (string or array).
     * @return mixed The filtered data.
     */
    public function filter(mixed $data): mixed
    {
        if (is_array($data)) {
            foreach ($data as $key => $value) {
                $data[$key] = $this->filter($value);
            }
            return $data;
        } else {
            // Ensure $data is a string before passing to htmlspecialchars
            $data = (string) $data;
            $data = htmlspecialchars($data, ENT_QUOTES, 'UTF-8');
            $data = strip_tags($data);
            return $data;
        }
    }

    /**
     * Escape a single string or an array of literal text values.
     * This is a basic escaping and should be used cautiously. For SQL, prepared statements are preferred.
     *
     * @param string|array<string> $value The string or array of strings to escape.
     * @return string|array<string> The escaped string(s).
     */
    public function escape(string|array $value): string|array
    {
        if (is_array($value)) {
            return array_map('addslashes', $value); // Basic escaping, not SQL-safe without context
        }
        return addslashes($value); // Basic escaping, not SQL-safe without context
    }

    /**
     * Calculate the difference between two dates.
     *
     * @param string $date1 The first date string (e.g., 'YYYY-MM-DD').
     * @param string $date2 The second date string (e.g., 'YYYY-MM-DD').
     * @return array<string, int> An associative array with 'years', 'months', 'days'. Returns empty array on invalid dates.
     */
    public function dateDifference(string $date1, string $date2): array
    {
        try {
            $dt1 = new DateTime($date1);
            $dt2 = new DateTime($date2);
            $interval = $dt1->diff($dt2);
            return [
                'years' => $interval->y,
                'months' => $interval->m,
                'days' => $interval->d,
            ];
        } catch (Exception $e) {
            error_log("Invalid date format in dateDifference: " . $e->getMessage());
            return [];
        }
    }

    /**
     * Calculate the difference between two datetimes.
     *
     * @param string $datetime1 The first datetime string (e.g., 'YYYY-MM-DD HH:MM:SS').
     * @param string $datetime2 The second datetime string (e.g., 'YYYY-MM-DD HH:MM:SS').
     * @return array<string, int> An associative array with 'years', 'months', 'days', 'hours', 'minutes', 'seconds'. Returns empty array on invalid datetimes.
     */
    public function datetimeDifference(string $datetime1, string $datetime2): array
    {
        try {
            $dt1 = new DateTime($datetime1);
            $dt2 = new DateTime($datetime2);
            $interval = $dt1->diff($dt2);
            return [
                'years' => $interval->y,
                'months' => $interval->m,
                'days' => $interval->d,
                'hours' => $interval->h,
                'minutes' => $interval->i,
                'seconds' => $interval->s,
            ];
        } catch (Exception $e) {
            error_log("Invalid datetime format in datetimeDifference: " . $e->getMessage());
            return [];
        }
    }

    /**
     * Convert a past datetime into a human-readable "time ago" string.
     *
     * @param string $datetime The past datetime string (e.g., 'YYYY-MM-DD HH:MM:SS').
     * @return string The "time ago" string, or "Invalid date" on error.
     */
    public function timeAgo(string $datetime): string
    {
        try {
            $now = new DateTime();
            $past = new DateTime($datetime);
            $diff = $now->diff($past);

            if ($diff->y > 0) {
                return $diff->y . ' year' . ($diff->y > 1 ? 's' : '') . ' ago';
            } elseif ($diff->m > 0) {
                return $diff->m . ' month' . ($diff->m > 1 ? 's' : '') . ' ago';
            } elseif ($diff->d > 0) {
                return $diff->d . ' day' . ($diff->d > 1 ? 's' : '') . ' ago';
            } elseif ($diff->h > 0) {
                return $diff->h . ' hour' . ($diff->h > 1 ? 's' : '') . ' ago';
            } elseif ($diff->i > 0) {
                return $diff->i . ' minute' . ($diff->i > 1 ? 's' : '') . ' ago';
            } else {
                return $diff->s . ' second' . ($diff->s > 1 ? 's' : '') . ' ago';
            }
        } catch (Exception $e) {
            error_log("Invalid datetime format in timeAgo: " . $e->getMessage());
            return "Invalid date";
        }
    }

    /**
     * Convert a numeric amount to Indian currency format (e.g., 1,23,456.78).
     *
     * @param float|int $amount The numeric amount.
     * @param int $decimalPlaces The number of decimal places (default: 2).
     * @return string The formatted amount.
     */
    public function amountToIndianFormat(float|int $amount, int $decimalPlaces = 2): string
    {
        $num = (string) round($amount, $decimalPlaces);
        if (strpos($num, '.') === false) {
            $num .= '.00';
        }

        $exploded = explode('.', $num);
        $integer = $exploded[0];
        $decimal = $exploded[1] ?? '';

        $len = strlen($integer);
        $result = '';
        $count = 0;

        for ($i = $len - 1; $i >= 0; $i--) {
            $result = $integer[$i] . $result;
            $count++;
            if ($count == 3 && $i != 0) {
                $result = ',' . $result;
                $count = 0;
            } elseif ($count == 2 && $i != 0 && $len > 3 && $i != ($len - 3)) { // For lakhs and crores
                $result = ',' . $result;
                $count = 0;
            }
        }

        if ($decimalPlaces > 0) {
            $decimal = str_pad(substr($decimal, 0, $decimalPlaces), $decimalPlaces, '0', STR_PAD_RIGHT);
            return $result . '.' . $decimal;
        } else {
            return $result;
        }
    }

    /**
     * Convert a numeric amount to text in Indian format (e.g., "One Lakh Twenty-Three Thousand Rupees").
     * Supports up to Crores.
     *
     * @param float|int $amount The numeric amount.
     * @return string The amount in words.
     */
    public function amountToTextIndianFormat(float|int $amount): string
    {
        $number = explode('.', sprintf('%.2f', $amount));
        $rupees = (int) $number[0];
        $paisa = (int) ($number[1] ?? 0);

        $words = '';

        if ($rupees > 0) {
            $words .= $this->convertNumberToWordsIndian($rupees) . ' Rupees';
        }
 
        if ($paisa > 0) {
            if ($rupees > 0) {
                $words .= ' and ';
            }
            $words .= $this->convertNumberToWordsIndian($paisa) . ' Paisa';
        }

        if (empty($words)) {
            return 'Zero Rupees';
        }

        return trim($words);
    }

    /**
     * Private helper function to convert numbers to words in Indian system.
     *
     * @param int $num The number to convert.
     * @return string The number in words.
     */
    private function convertNumberToWordsIndian(int $num): string
    {
        $n = abs($num);
        $ones = [
            0 => '', 1 => 'One', 2 => 'Two', 3 => 'Three', 4 => 'Four', 5 => 'Five',
            6 => 'Six', 7 => 'Seven', 8 => 'Eight', 9 => 'Nine', 10 => 'Ten',
            11 => 'Eleven', 12 => 'Twelve', 13 => 'Thirteen', 14 => 'Fourteen',
            15 => 'Fifteen', 16 => 'Sixteen', 17 => 'Seventeen', 18 => 'Eighteen',
            19 => 'Nineteen'
        ];
        $tens = [
            2 => 'Twenty', 3 => 'Thirty', 4 => 'Forty', 5 => 'Fifty',
            6 => 'Sixty', 7 => 'Seventy', 8 => 'Eighty', 9 => 'Ninety'
        ];

        if ($n < 20) {
            return $ones[$n];
        }
        if ($n < 100) {
            return $tens[intdiv($n, 10)] . ' ' . $ones[$n % 10];
        }

        $words = [];

        // Crores
        if ($n >= 10000000) {
            $words[] = $this->convertNumberToWordsIndian(intdiv($n, 10000000)) . ' Crore';
            $n %= 10000000;
        }
        // Lakhs
        if ($n >= 100000) {
            $words[] = $this->convertNumberToWordsIndian(intdiv($n, 100000)) . ' Lakh';
            $n %= 100000;
        }
        // Thousands
        if ($n >= 1000) {
            $words[] = $this->convertNumberToWordsIndian(intdiv($n, 1000)) . ' Thousand';
            $n %= 1000;
        }
        // Hundreds
        if ($n >= 100) {
            $words[] = $this->convertNumberToWordsIndian(intdiv($n, 100)) . ' Hundred';
            $n %= 100;
        }
        // Remaining (tens and ones)
        if ($n > 0) {
            $words[] = $this->convertNumberToWordsIndian($n);
        }

        return implode(' ', $words);
    }

    /**
     * Smart word wrap for long strings, preventing single long words from breaking line length.
     *
     * @param string $string The input string.
     * @param int $width The maximum line width.
     * @param string $break The line break string (e.g., "<br>", "\n").
     * @return string The wrapped string.
     */
    public function smartWordwrap(string $string, int $width = 75, string $break = "<br>"): string
    {
        $pattern = sprintf('/([^ ]{%d,})/', $width);
        $output = '';
        $words = preg_split($pattern, $string, -1, PREG_SPLIT_NO_EMPTY | PREG_SPLIT_DELIM_CAPTURE);

        if ($words === false) {
            error_log("Failed to split string in smartWordwrap.");
            return $string; // Return original string on error
        }

        foreach ($words as $word) {
            if (str_contains($word, ' ')) {
                $output .= $word;
            } else {
                $wrapped = explode($break, wordwrap($output, $width, $break));
                $lastWrappedLine = end($wrapped);
                $count = $width - (strlen($lastWrappedLine) % $width);

                $output .= substr($word, 0, $count) . $break;
                $output .= wordwrap(substr($word, $count), $width, $break, true);
            }
        }
        return wordwrap($output, $width, $break);
    }

    /**
     * Converts a "minutes.seconds" string to total seconds.
     *
     * @param string $minSec The time string in "minutes.seconds" format.
     * @return int The total number of seconds.
     */
    public function convertMinSecToSeconds(string $minSec): int
    {
        $parts = explode('.', $minSec);
        $minutes = (int) ($parts[0] ?? 0);
        $seconds = (int) ($parts[1] ?? 0);
        return $minutes * 60 + $seconds;
    }

    /**
     * Checks if a string contains only English characters (UTF-8 safe).
     *
     * @param string $str The string to check.
     * @return bool True if the string contains only English characters, false otherwise.
     */
    public function isEnglish(string $str): bool
    {
        if (strlen($str) != mb_strlen($str, 'utf-8')) {
            return false;
        } else {
            return true;
        }
    }

    /**
     * Checks if a given text contains a URL (simple check for 'http' or 'www.').
     *
     * @param string $text The text to check.
     * @return bool True if a URL is found, false otherwise.
     */
    public function isUrlInText(string $text): bool
    {
        $bHasLink = str_contains($text, 'http') || str_contains($text, 'www.');
        return $bHasLink;
    }

    /**
     * Checks if a password meets specified strength requirements (uppercase, lowercase, number, special char, length).
     *
     * @param string $password The password string to check.
     * @param int $minlen Minimum allowed length (default: 7).
     * @param int $maxlen Maximum allowed length (default: 21).
     * @return bool True if the password meets requirements, false otherwise.
     */
    public function checkPassword(string $password, int $minlen = 7, int $maxlen = 21): bool
    {
        $uppercase = (bool) preg_match('@[A-Z]@', $password);
        $lowercase = (bool) preg_match('@[a-z]@', $password);
        $number = (bool) preg_match('@[0-9]@', $password);
        $specialChar = (bool) preg_match('@[^\w]@', $password);

        if ($uppercase && $lowercase && $number && $specialChar && strlen($password) >= $minlen && strlen($password) <= $maxlen) {
            return true;
        } else {
            return false;
        }
    }

    /**
     * Hides a portion of an email address for display.
     *
     * @param string $email The email address.
     * @return string The obfuscated email address.
     */
    public function hideMail(string $email): string
    {
        $parts = explode('@', $email);
        if (count($parts) !== 2) {
            return $email;
        }
        $username = $parts[0];
        $domain = $parts[1];

        $hiddenUsername = substr($username, 0, min(2, strlen($username))) . str_repeat('*', max(1, strlen($username) - 2));

        return $hiddenUsername . '@' . $domain;
    }

    /**
     * Obfuscates an email address, optionally also obfuscating the domain.
     *
     * @param string $email The email address to obfuscate.
     * @param bool $domain_ If true, obfuscate the domain part as well.
     * @return string The obfuscated email string.
     */
    public function ofuscaEmail(string $email, bool $domain_ = false): string
    {
        $seg = explode('@', $email);
        if (count($seg) !== 2) {
            return $email;
        }
        $user = '';
        $domain = '';

        if (strlen($seg[0]) > 3) {
            $sub_seg = str_split($seg[0]);
            $user .= $sub_seg[0] . $sub_seg[1];
            for ($i = 2; $i < count($sub_seg) - 1; $i++) {
                if ($sub_seg[$i] === '.' || $sub_seg[$i] === '_') {
                    $user .= $sub_seg[$i];
                } else {
                    $user .= '*';
                }
            }
            $user .= $sub_seg[count($sub_seg) - 1];
        } else {
            $sub_seg = str_split($seg[0]);
            $user .= $sub_seg[0];
            for ($i = 1; $i < count($sub_seg); $i++) {
                $user .= ($sub_seg[$i] === '.') ? '.' : '*';
            }
        }

        if ($domain_) {
            $sub_seg2 = str_split($seg[1]);
            $domain .= $sub_seg2[0];
            for ($i = 1; $i < count($sub_seg2) - 2; $i++) {
                $domain .= ($sub_seg2[$i] === '.') ? '.' : '*';
            }
            $domain .= $sub_seg2[count($sub_seg2) - 2] . $sub_seg2[count($sub_seg2) - 1];
        } else {
            $domain = $seg[1];
        }

        return $user . '@' . $domain;
    }

    /**
     * Hides the middle part of a mobile number with asterisks.
      *
     * @param string $mobile The mobile number.
     * @return string The obfuscated mobile number.
     */
    public function hideMobile(string $mobile): string
    {
        return substr($mobile, 0, -4) . "****";
    }

    /**
     * Hides a specific part of a mobile number with a custom mask.
     *
     * @param string $mobile The mobile number.
     * @return string The masked mobile number.
     */
    public function hiddenMobile(string $mobile): string
    {
        return substr_replace($mobile, '#-###-###', 1, 7);
    }

    /**
     * Formats a date string to 'dd Month Walpole' (e.g., '01 January 2023').
     *
     * @param string $newdate The date string.
     * @return string The formatted date.
     */
    public function dateFormat1(string $newdate): string
    {
        $changed_date = date('d F Y', strtotime($newdate));
        return $changed_date;
    }

    /**
     * Formats a date string to 'dd Mon Walpole' (e.g., '01 Jan 2023').
     *
     * @param string $newdate The date string.
     * @return string The formatted date.
     */
    public function dateFormat2(string $newdate): string
    {
        $changed_date = date('d M Y', strtotime($newdate));
        return $changed_date;
    }

    /**
     * Formats a time string to 'HH:MM' (24-hour format).
     *
     * @param string $newdate The datetime string.
     * @return string The formatted time.
     */
    public function timeFormat1(string $newdate): string
    {
        $changed_date = date('H:i', strtotime($newdate));
        return $changed_date;
    }

    /**
     * Formats a datetime string to 'dd Mon Walpole HH:MM:SS'.
     *
     * @param string $newdate The datetime string.
     * @return string The formatted datetime.
     */
    public function datetimeFormat1(string $newdate): string
    {
        $changed_date = date('d M Y H:i:s', strtotime($newdate));
        return $changed_date;
    }

    /**
     * Formats a datetime string to 'On dd Mon Walpole At HH:MM:SS'.
     *
     * @param string $newdate The datetime string.
     * @return string The formatted datetime.
     */
    public function datetimeFormat2(string $newdate): string
    {
        $changed_date1 = 'On ' . date('d M Y', strtotime($newdate));
        $changed_date2 = 'At ' . date('H:i:s', strtotime($newdate));
        $changed_date = $changed_date1 . ' ' . $changed_date2;
        return $changed_date;
    }

    /**
     * Formats a datetime string to 'dd Mon Walpole HH:MM'.
     *
     * @param string $newdate The datetime string.
     * @return string The formatted datetime.
     */
    public function datetimeFormat3(string $newdate): string
    {
        $changed_date = date('d M Y H:i', strtotime($newdate));
        return $changed_date;
    }

    /**
     * Formats a datetime string to 'On<b> dd Mon Walpole</b> At<b> HH:MM</b>' with bold tags.
     *
     * @param string $newdate The datetime string.
     * @return string The formatted datetime with HTML tags.
     */
    public function datetimeFormat4(string $newdate): string
    {
        $changed_date1 = 'On<b> ' . date('d M Y', strtotime($newdate)) . '</b>';
        $changed_date2 = 'At<b> ' . date('H:i', strtotime($newdate)) . '</b>';
        $changed_date = $changed_date1 . ' ' . $changed_date2;
        return $changed_date;
    }

    /**
     * Calculates the difference between two dates in years.
     *
     * @param string $date_greater The later date string (e.g., 'YYYY-MM-DD').
     * @param string $date_old The earlier date string (e.g., 'YYYY-MM-DD').
     * @return int The difference in full years.
     */
    public function dateDifferenceYears(string $date_greater = '', string $date_old = ''): int
    {
        try {
            $d1 = new DateTime($date_greater);
            $d2 = new DateTime($date_old);
            $diff = $d2->diff($d1);
            return $diff->y;
        } catch (Exception $e) {
            error_log("Invalid date format in dateDifferenceYears: " . $e->getMessage());
            return 0;
        }
    }

    /**
     * Calculates the difference between two dates and returns it in "X years Y months" or "Y months" format.
     *
     * @param string $date1 The first date string.
     * @param string $date2 The second date string.
     * @return string The formatted date difference.
     */
    public function dateDifference1(string $date1 = '', string $date2 = ''): string
    {
        try {
            $datetime1 = date_create(date("Y-m-d", strtotime($date1)));
            $datetime2 = date_create(date("Y-m-d", strtotime($date2)));

            if ($datetime1 === false || $datetime2 === false) {
                throw new Exception("Invalid date format provided.");
            }

            $interval = date_diff($datetime1, $datetime2);

            if ($interval->y >= 1) {
                $result = $interval->y . ' year' . ($interval->y > 1 ? 's' : '') . ' ' . $interval->m . ' month' . ($interval->m > 1 ? 's' : '');
            } else {
                $result = $interval->m . ' month' . ($interval->m > 1 ? 's' : '');
            }
            return $result;
        } catch (Exception $e) {
            error_log("Invalid date format in dateDifference1: " . $e->getMessage());
            return "Invalid date";
        }
    }

    /**
     * Calculates the difference between two datetimes in minutes.
     *
     * @param string $date1 The first datetime string.
     * @param string $date2 The second datetime string.
     * @return string The difference in minutes (e.g., "30 minutes").
     */
    public function datetimeDifferenceInMinutes(string $date1 = '', string $date2 = ''): string
    {
        try {
            $datetime1 = date_create(date("Y-m-d H:i:s", strtotime($date1)));
            $datetime2 = date_create(date("Y-m-d H:i:s", strtotime($date2)));
 
            if ($datetime1 === false || $datetime2 === false) {
                throw new Exception("Invalid datetime format provided.");
            }

            $interval = date_diff($datetime1, $datetime2);
            $min = $interval->days * 24 * 60;
            $min += $interval->h * 60;
            $min += $interval->i;

            $result = $min . ' minutes';
            return $result;
        } catch (Exception $e) {
            error_log("Invalid datetime format in datetimeDifferenceInMinutes: " . $e->getMessage());
            return "Invalid datetime";
        }
    }

    /**
     * Calculates age from a birthdate in "X Years, Y Months, Z Days" format.
     *
     * @param string $birthdate The birthdate string (e.g., 'YYYY-MM-DD').
     * @return string The calculated age string.
     */
    public function ageCalculation(string $birthdate): string
    {
        try {
            $sdate = new DateTime($birthdate);
            $edate = new DateTime();
            $interval = $sdate->diff($edate);
            $result = $interval->y . " Years, " . $interval->m . " Months, " . $interval->d . " Days ";
            return $result;
        } catch (Exception $e) {
            error_log("Invalid birthdate format in ageCalculation: " . $e->getMessage());
            return "Invalid birthdate";
        }
    }

    /**
     * Checks if a numeric value is a decimal number (contains a fractional part).
     *
     * @param float|int $val The value to check.
     * @return bool True if the value is numeric and has a decimal part, false otherwise.
     */
    public function isDecimal(float|int $val): bool
    {
        if ((is_numeric($val)) && (floor($val) != $val)) {
            return true;
        } else {
            return false;
        }
    }

    /**
     * Converts a number to words (English format).
     *
     * @param float|int $num The number to convert.
     * @return string The number in words.
     */
    public function numberToWords(float|int $num): string
    {
        $ones = array(
            1 => "one", 2 => "two", 3 => "three", 4 => "four", 5 => "five",
            6 => "six", 7 => "seven", 8 => "eight", 9 => "nine", 10 => "ten",
            11 => "eleven", 12 => "twelve", 13 => "thirteen", 14 => "fourteen",
            15 => "fifteen", 16 => "sixteen", 17 => "seventeen", 18 => "eighteen",
            19 => "nineteen"
        );
        $tens = array(
            1 => "ten", 2 => "twenty", 3 => "thirty", 4 => "forty", 5 => "fifty",
            6 => "sixty", 7 => "seventy", 8 => "eighty", 9 => "ninety"
        );
        $hundreds = array(
            "hundred", "thousand", "million", "billion", "trillion", "quadrillion"
        );
        $num_formatted = number_format($num, 2, ".", ",");
        $num_arr = explode(".", $num_formatted);
        $wholenum = $num_arr[0];
        $decnum = $num_arr[1];
        $whole_arr = array_reverse(explode(",", $wholenum));
        krsort($whole_arr);
        $rettxt = "";
        foreach ($whole_arr as $key => $i) {
            $i_int = (int) $i; // Cast to int for array access
            if ($i_int < 20) {
                $rettxt .= $ones[$i_int];
            } elseif ($i_int < 100) {
                $rettxt .= $tens[intdiv($i_int, 10)];
                $rettxt .= " " . $ones[$i_int % 10];
            } else {
                $rettxt .= $ones[intdiv($i_int, 100)] . " " . $hundreds[0];
                $rettxt .= " " . $tens[intdiv(($i_int % 100), 10)];
                $rettxt .= " " . $ones[$i_int % 10];
            }
            if ($key > 0) {
                $rettxt .= " " . $hundreds[$key] . " ";
            }
        }
        if ((int)$decnum > 0) {
            $rettxt .= " and ";
            $decnum_int = (int) $decnum;
            if ($decnum_int < 20) {
                $rettxt .= $ones[$decnum_int];
            } elseif ($decnum_int < 100) {
                $rettxt .= $tens[intdiv($decnum_int, 10)];
                $rettxt .= " " . $ones[$decnum_int % 10];
            }
        }
        return trim($rettxt);
    }

    /**
     * Converts a number to words in Indian currency format (Rupees and Paise).
     *
     * @param float|int $number The amount to convert.
     * @return string The amount in words with HTML formatting.
     */
    public function convertToIndianCurrency(float|int $number): string
    {
        $no = round($number);
        $decimal = (int) round(($number - $no), 2) * 100;
        $digits_length = strlen((string)$no);
        $i = 0;
        $str = array();
        $words = array(
            0 => '', 1 => 'One', 2 => 'Two', 3 => 'Three', 4 => 'Four',
            5 => 'Five', 6 => 'Six', 7 => 'Seven', 8 => 'Eight', 9 => 'Nine',
            10 => 'Ten', 11 => 'Eleven', 12 => 'Twelve', 13 => 'Thirteen',
            14 => 'Fourteen', 15 => 'Fifteen', 16 => 'Sixteen', 17 => 'Seventeen',
            18 => 'Eighteen', 19 => 'Nineteen', 20 => 'Twenty', 30 => 'Thirty',
            40 => 'Forty', 50 => 'Fifty', 60 => 'Sixty', 70 => 'Seventy',
            80 => 'Eighty', 90 => 'Ninety'
        );
        $digits = array('', 'Hundred', 'Thousand', 'Lakh', 'Crore');
        while ($i < $digits_length) {
            $divider = ($i == 2) ? 10 : 100;
            $num_segment = (int) floor($no % $divider);
            $no = (int) floor($no / $divider);
            $i += $divider == 10 ? 1 : 2;
            if ($num_segment) {
                $plural = ((count($str) > 0) && $num_segment > 9) ? 's' : '';
                $current_word = '';
                if ($num_segment < 21) {
                    $current_word = $words[$num_segment];
                } else {
                    $current_word = $words[intdiv($num_segment, 10) * 10] . ' ' . $words[$num_segment % 10];
                }
                $str [] = trim($current_word . ' ' . $digits[count($str)] . $plural);
            } else {
                $str [] = '';
            }
        }

        $Rupees = implode(' ', array_reverse(array_filter($str)));
        $paise = '';
        if ($decimal > 0) {
            $paise_word = '';
            if ($decimal < 21) {
                $paise_word = $words[$decimal];
            } else {
                $paise_word = $words[intdiv($decimal, 10) * 10] . ' ' . $words[$decimal % 10];
            }
            $paise = "And <font style='font-weight:500;'>" . trim($paise_word) . '</font> Paise ';
        }
        
        $final_rupees_text = $Rupees ? 'Rupees <font style="font-weight:500;">' . $Rupees . '</font>' : '';
        
        return trim($final_rupees_text . ' ' . $paise) . " Only";
    }

    /**
     * Cleans a string by stripping slashes, decoding HTML entities, converting newlines to <br>, and URL decoding.
     *
     * @param string $data The string to clean.
     * @return string The cleaned string.
     */
    public function clean(string $data): string
    {
        $data = stripslashes($data);
        $data = html_entity_decode($data, ENT_QUOTES, 'UTF-8');
        $data = nl2br($data);
        $data = urldecode($data);
        return $data;
    }
}

db.php - Central DB and Utility Include

<?php
declare(strict_types=1);

// This file is intended to be included at the top of every page
// to provide easy access to database and utility functionalities.

// Include all necessary core classes
require_once __DIR__ . '/DatabaseConfig.php';
require_once __DIR__ . '/DatabaseConnection.php';
require_once __DIR__ . '/QueryBuilder.php';
require_once __DIR__ . '/CrudOperations.php';
require_once __DIR__ . '/UtilityFunctions.php';
require_once __DIR__ . '/random-code-generators-pdo.php'; // Include if random functions are needed globally

// Global variables to hold our instantiated objects
// Using global for simplicity in small to medium applications.
// For larger applications, consider dependency injection or a service container.
global $dbConnection, $crud, $utils;

try {
    // 1. Establish database connection
    $dbConnection = new DatabaseConnection(
        DB_HOST,
        DB_NAME,
        DB_USER,
        DB_PASSWORD,
        DB_CHARSET
    );

    // 2. Initialize CRUD operations with the PDO object
    $crud = new CrudOperations($dbConnection->getPdo());

    // 3. Initialize Utility functions
    $utils = new UtilityFunctions();

} catch (Exception $e) {
    // Centralized error handling for critical database connection issues.
    // In a production environment, you would log this error and display a
    // user-friendly message without exposing sensitive details.
    error_log("Critical Application Error: " . $e->getMessage());
    // You might redirect to an error page or display a generic message
    die("<h1>Site is temporarily unavailable.</h1><p>We are experiencing technical difficulties. Please try again later.</p>");
}

// Now, on any page where you include 'db.php', you can directly use:
// $crud->getResults(...)
// $utils->dateFormat1(...)
// etc.
// Example:
// require_once 'db.php';
// $users = $crud->getResults('users');
// echo $utils->timeAgo($users[0]['created_at']);

?>

Providing code with some usage examples

<?php
 define('HST', 'localhost'); // Your database host
 define('USR', 'root');      // Your database username
 define('PWD', '');          // Your database password
 define('DBN', 'test_db');   // Your database name
 define('SEND_ERRORS_TO', ''); // e.g., 'your_admin_email@example.com'
 define('DEFAULT_TIMEZONE', 'Asia/Kolkata');

/* ^^ can be defined in different file and can be included that file here. */

 date_default_timezone_set(DEFAULT_TIMEZONE);


class DB {
    private $host;
    private $dbName;
    private $user;
    private $password;
    private $charset;
    private $pdo;
    private $queryCount = 0;
    private $errorEmailRecipient = SEND_ERRORS_TO;

    /**
    * Constructor: Connect to a given MySQL server.
    *
    * Usage Example:
    * $database = new DB(HST, DBN, USR, PWD, 'utf8mb4');
    *
    * @param string $host The database host (e.g., 'localhost').
    * @param string $dbName The database name.
    * @param string $user The database username.
    * @param string $password The database password.
    * @param string $charset The character set (default: 'utf8mb4').
    */
    public function __construct($host = HST, $dbName = DBN, $user = USR, $password = PWD, $charset = 'utf8mb4') {
    $this->host = $host;
    $this->dbName = $dbName;
    $this->user = $user;
    $this->password = $password;
    $this->charset = $charset;

    $dsn = "mysql:host={$this->host};dbname={$this->dbName};charset={$this->charset}";
    $options = [
        PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION, // Throw exceptions on errors
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,     // Default fetch mode to associative array
        PDO::ATTR_EMULATE_PREPARES   => false,                // Disable emulation for better security and performance
    ];

    try {
        $this->pdo = new PDO($dsn, $this->user, $this->password, $options);
    } catch (PDOException $e) {
        $errorMessage = "Database connection failed: " . $e->getMessage();
        error_log($errorMessage); // Log the error
        $this->send_error_email("Database Connection Error", $errorMessage);
        throw new Exception("A critical database error occurred. Please try again later.");
    }
  }

     /**
     * Execute arbitrary SQL queries (SELECT, INSERT, UPDATE, DELETE, etc.).
     * This function uses prepared statements to prevent SQL injection.
     *
     * Usage Example:
     * $stmt = $database->execute_query("SELECT * FROM users WHERE id = ?", [1]);
     * if ($stmt) {
     * $user = $stmt->fetch();
     * print_r($user);
     * }
     *
     * $stmt = $database->execute_query("INSERT INTO products (name, price) VALUES (?, ?)", ["Laptop", 1200.50]);
     * if ($stmt->rowCount() > 0) {
     * echo "Product added successfully!";
     * }
     *
     * @param string $sql The SQL query string.
     * @param array $params An associative or indexed array of parameters to bind to the query.
     * @return PDOStatement|false Returns the PDOStatement object on success, or false on failure.
     */
    public function execute_query($sql, $params = []) {
    try {
        $stmt = $this->pdo->prepare($sql);
        $stmt->execute($params);
        $this->queryCount++;
        return $stmt;
    } catch (PDOException $e) {
        $errorMessage = "Query execution failed: " . $e->getMessage() . " SQL: " . $sql . " Params: " . json_encode($params);
        error_log($errorMessage);
        $this->send_error_email("Database Query Error", $errorMessage);
        return false;
    }
}


     /**
     * Retrieve the number of rows from a table based on multiple WHERE clauses.
     *
     * Usage Example:
     * $conditions = [
     * 'status' => 'active',
     * 'category_id' => 5
     * ];
     * $active_products_count = $database->num_rows('products', $conditions);
     * OR $active_products_count = $database->num_rows('products', ['status' => 'active','category_id' => 5]);
     * echo "Number of active products: " . $active_products_count;
     *
     * @param string $table The name of the table.
     * @param array $conditions An associative array of column => value pairs for the WHERE clause.
     * @return int The number of rows matching the conditions, or 0 on error.
     */
    public function num_rows($table, $conditions = []) {
    $sql = "SELECT COUNT(*) FROM `{$table}`";
    $params = [];
    $whereClause = $this->build_where_clause($conditions, $params);

    $sql .= $whereClause;

    $stmt = $this->execute_query($sql, $params);
    if ($stmt) {
        return (int) $stmt->fetchColumn();
    }
    return 0;
 }


    /**
     * Retrieve the query results in a single array.
     * This function now accepts table name, conditions, selected columns, order by, group by, and limit.
     *
     * Usage Example:
     * // Fetch all users
     * $allUsers = $database->get_results('users');
     *
     * // Fetch active users, selecting specific columns
     * $activeUsers = $database->get_results('users', ['status' => 'active'], ['id', 'name', 'email']);
     * foreach ($activeUsers as $user) {
     * echo $user['name'] . " - " . $user['email'] . "<br>";
     * }
     *
     * // Fetch products with price greater than 100, ordered by price descending, limited to 5
     * $expensiveProducts = $database->get_results('products', ['price >' => 100], ['name', 'price'], 'price DESC', null, 5);
     *
     * // Fetch the latest user added (by ID)
     * $latestUser = $database->get_results('users', [], ['id', 'name'], 'id DESC', null, 1);
     * if (!empty($latestUser)) {
     * echo "Latest user: " . $latestUser[0]['name'];
     * }
     *
     * // Get count of users by role
     * $userRoleCounts = $database->get_results('users', [], ['role', 'COUNT(id) as user_count'], '', 'role');
     * foreach ($userRoleCounts as $roleCount) {
     * echo "Role: " . $roleCount['role'] . ", Count: " . $roleCount['user_count'] . "<br>";
     * }
     *
     * // Example with OR condition:
     * $conditions_or = [
     * 'status' => 'active', // This will be ANDed
     * '_OR_' => [           // This whole block will be ORed together
     * ['role' => 'admin'],
     * ['role' => 'editor', 'department' => 'marketing'] // This is (role = 'editor' AND department = 'marketing')
     * ]
     * ];
     * $users_complex = $database->get_results('users', $conditions_or, ['name', 'email', 'role', 'department']);
     *
     * @param string $table The name of the table to retrieve data from.
     * @param array $conditions An associative array of column => value pairs for the WHERE clause.
     * Supports operators like 'column >', 'column <', 'column LIKE', 'column IN', etc.
     * @param array $selectColumns An array of column names to select (default: ['*'] for all columns).
     * @param string $orderBy An ORDER BY clause (e.g., 'column_name ASC', 'column_name DESC').
     * @param string $groupBy A GROUP BY clause (e.g., 'column_name', 'column1, column2').
     * @param int|null $limit A LIMIT clause (e.g., 10).
     * @param int $fetch_style The PDO fetch style (e.g., PDO::FETCH_ASSOC, PDO::FETCH_OBJ).
     * @return array An array of query results. Returns an empty array on no results or error.
     */

     public function get_results($table, $conditions = [], $selectColumns = ['*'], $orderBy = '', $groupBy = '', $limit = null, $fetch_style = PDO::FETCH_ASSOC)  {
    $selectClause = implode(", ", $selectColumns);
    $params = [];
    $whereClause = $this->build_where_clause($conditions, $params);

    $sql = "SELECT {$selectClause} FROM `{$table}`{$whereClause}";

    if (!empty($groupBy)) {
        $sql .= " GROUP BY {$groupBy}";
    }

    if (!empty($orderBy)) {
        $sql .= " ORDER BY {$orderBy}";
    }

    if ($limit !== null && is_int($limit) && $limit > 0) {
        $sql .= " LIMIT {$limit}";
    }

    $stmt = $this->execute_query($sql, $params);
    if ($stmt) {
        return $stmt->fetchAll($fetch_style);
    }
    return [];
 }


     /**
     * Determine if one value or an array of values contain common MySQL function calls.
     * This is a basic check and should not replace prepared statements for security.
     *
     * Usage Example:
     * if ($database->contains_mysql_functions($_GET['order_by'])) {
     * echo "Potential SQL injection attempt detected!";
     * } else {
     * // Proceed with using $_GET['order_by'] in ORDER BY clause (carefully!)
     * }
     *
     * @param mixed $value The string or array of strings to check.
     * @return bool True if any common MySQL function is found, false otherwise.
     */
    public function contains_mysql_functions($value) {
    $functions = [
        'SLEEP', 'BENCHMARK', 'UNION', 'SELECT', 'INSERT', 'UPDATE', 'DELETE',
        'DROP', 'TRUNCATE', 'ALTER', 'CREATE', 'GRANT', 'REVOKE', 'RENAME',
        'LOAD_FILE', 'OUTFILE', 'INFILE', '@@', 'CONCAT', 'CAST', 'CONVERT',
        'ASCII', 'CHAR', 'UNHEX', 'HEX', 'MID', 'SUBSTRING', 'LEFT', 'RIGHT',
        'IF', 'CASE', 'AND', 'OR', 'XOR', 'NOT', 'NULL', 'VERSION', 'DATABASE',
        'USER', 'CURRENT_USER', 'SYSTEM_USER', 'SESSION_USER', 'SCHEMA',
        'INFORMATION_SCHEMA', 'MYSQL.USER', 'PASSWORD', 'MD5', 'SHA1', 'SHA2',
        'AES_ENCRYPT', 'AES_DECRYPT', 'FROM_UNIXTIME', 'UNIX_TIMESTAMP',
        'GROUP_CONCAT', 'ORDER BY', 'GROUP BY', 'HAVING', 'LIMIT', 'OFFSET'
    ];

    $regex = '/\b(' . implode('|', $functions) . ')\b/i';

    if (is_array($value)) {
        foreach ($value as $val) {
            if (preg_match($regex, $val)) {
                return true;
            }
        }
    } else {
        if (preg_match($regex, $value)) {
            return true;
        }
    }
    return false;
  }


    /**
    * Check if a table exists in the current database.
    * 
    * Usage Example:
    * if ($database->table_exists('users')) {
    * echo "Table 'users' exists.";
    * } else {
    * echo "Table 'users' does not exist.";
    * }
    *
    * @param string $tableName The name of the table to check.
    * @return bool True if the table exists, false otherwise.
    */
    public function table_exists($tableName) {
    $sql = "SHOW TABLES LIKE ?";
    $stmt = $this->execute_query($sql, [$tableName]);
    return $stmt && $stmt->rowCount() > 0;
  }


      /**
      * Execute an INSERT query from values that define table, field names, and field values.
      *
      * Usage Example:
      * $new_user_data = [
      * 'name' => 'Alice Smith',
      * 'email' => 'alice@example.com',
      * 'status' => 'active'
      * ];
      * if ($database->insert('users', $new_user_data)) {
      * echo "New user inserted successfully!";
      * echo "Last Insert ID: " . $database->last_insert_id();
      * } else {
      * echo "Failed to insert new user.";
      * }
      *
      * @param string $table The table name.
      * @param array $data An associative array of column => value pairs to insert.
      * @return bool True on success, false on failure.
      */
     public function insert($table, $data)
{
    if (empty($data)) {
        return false;
    }

    // Escape column names with backticks to prevent SQL injection in column names
    $columns = implode(", ", array_map(function($column) {
        return "`" . str_replace("`", "``", $column) . "`";
    }, array_keys($data)));
     
    $placeholders = implode(", ", array_fill(0, count($data), '?'));
    $params = array_values($data);

    $sql = "INSERT INTO `{$table}` ({$columns}) VALUES ({$placeholders})";
    $stmt = $this->execute_query($sql, $params);
    return $stmt !== false;
}


   /**
    * Execute an INSERT MULTI query for inserting multiple rows at once.
    * 
    * Usage Example:
    * $products_to_add = [
    * ['name' => 'Keyboard', 'price' => 75.00, 'category_id' => 1],
    * ['name' => 'Mouse', 'price' => 25.50, 'category_id' => 1],
    * ['name' => 'Monitor', 'price' => 299.99, 'category_id' => 2]
    * ];
    * if ($database->insert_multi('products', $products_to_add)) {
    * echo "Multiple products inserted successfully!";
    * } else {
    * echo "Failed to insert multiple products.";
    * }
    *
    * @param string $table The table name.
    * @param array $dataArray An array of associative arrays, where each inner array represents a row to insert.
    * @return bool True on success, false on failure.
    */
    public function insert_multi($table, $dataArray)
{
    if (empty($dataArray) || !is_array($dataArray[0])) {
        return false;
    }

    // Escape column names with backticks to prevent SQL injection in column names
    $columns = implode(", ", array_map(function($column) {
        return "`" . str_replace("`", "``", $column) . "`";
    }, array_keys($dataArray[0])));

    $placeholders = "(" . implode(", ", array_fill(0, count($dataArray[0]), '?')) . ")";

    $values = [];
    $params = [];
    foreach ($dataArray as $row) {
        $values[] = $placeholders;
        $params = array_merge($params, array_values($row));
    }

    $sql = "INSERT INTO `{$table}` ({$columns}) VALUES " . implode(", ", $values);
    $stmt = $this->execute_query($sql, $params);
    return $stmt !== false;
}

    /**
    * Execute an UPDATE query from values that define table, field names, field values, and conditions.
    *
    * Usage Example:
    * $update_data = ['status' => 'inactive', 'last_login' => date('Y-m-d H:i:s')];
    * $conditions = ['id' => 1];
    * if ($database->update('users', $update_data, $conditions)) {
    * echo "User ID 1 updated successfully!";
    * } else {
    * echo "Failed to update user ID 1.";
    * }
    *
    * @param string $table The table name.
    * @param array $data An associative array of column => new_value pairs to update.
    * @param array $conditions An associative array of column => value pairs for the WHERE clause.
    * @return bool True on success, false on failure. 
    */
     public function update($table, $data, $conditions)
{
    if (empty($data) || empty($conditions)) {
        return false;
    }

    $setParts = [];
    $params = [];
    foreach ($data as $column => $value) {
        // Escape column names with backticks for the SET clause
        $escapedColumn = "`" . str_replace("`", "``", $column) . "`";
        $setParts[] = "{$escapedColumn} = ?";
        $params[] = $value;
    }
    $setClause = implode(", ", $setParts);

    $whereClause = $this->build_where_clause($conditions, $params);

    $sql = "UPDATE `{$table}` SET {$setClause} {$whereClause}";
    $stmt = $this->execute_query($sql, $params);
    return $stmt !== false;
}

    /**
    * Execute a DELETE query from values that define table and conditions. 
    *
    * Usage Example:
    * $conditions = ['status' => 'inactive', 'last_login <' => '2023-01-01'];
    * if ($database->delete('users', $conditions)) {
    * echo "Inactive users deleted successfully!";
    * } else {
    * echo "Failed to delete inactive users.";
    * }
    *
    * @param string $table The table name.
    * @param array $conditions An associative array of column => value pairs for the WHERE clause.
    * Supports operators like 'column >', 'column <', 'column LIKE', etc.
    * @return bool True on success, false on failure.
    */
    public function delete($table, $conditions) {
    if (empty($conditions)) {
        // Prevent accidental full table deletion without conditions
        error_log("Attempted to delete from table '{$table}' without conditions. Operation aborted.");
        $this->send_error_email("Security Alert: Unconditional Delete Attempt", "Attempted to delete from table '{$table}' without conditions.");
        return false;
    }

    $params = [];
    $whereClause = $this->build_where_clause($conditions, $params);

    $sql = "DELETE FROM `{$table}` {$whereClause}";
    $stmt = $this->execute_query($sql, $params);
    return $stmt !== false;
 }

     /**
     * Helper function to build the WHERE clause string and populate parameters array.
     * Supports AND conditions at the top level and one special '_OR_' group.
     * The '_OR_' group should contain an array of condition sets, where each set
     * is ANDed internally, and then these sets are ORed together.
     *
     * @param array $conditions An associative array of column => value pairs for the WHERE clause.
     * Can include a special '_OR_' key for OR conditions.
     * @param array $params Reference to the main parameters array to add new values.
     * @return string The WHERE clause string (e.g., " WHERE `column` = ? AND (`other_column` = ? OR `another_column` = ?)").
    */
    private function build_where_clause($conditions, &$params)
{
    $whereParts = [];
    $orGroupClauses = [];

    foreach ($conditions as $key => $value) {
        if ($key === '_OR_' && is_array($value)) {
            // This is an OR group, process each sub-condition set
            $currentOrGroupParts = [];
            foreach ($value as $orConditionSet) {
                if (is_array($orConditionSet)) {
                    $subConditionParts = [];
                    foreach ($orConditionSet as $subColumn => $subValue) {
                        // Build each individual condition within the OR group
                        $operator = '=';
                        $field = $subColumn;
                        $isBinary = false;

                        if (strpos(strtoupper(trim($subColumn)), 'BINARY ') === 0) {
                            $isBinary = true;
                            $field = substr(trim($subColumn), 7);
                        }

                        if (preg_match('/(.*?)\s*(<|>|<=|>=|!=|<>|LIKE|NOT LIKE|IN|NOT IN|IS NULL|IS NOT NULL)$/i', $field, $matches)) {
                            $field = trim($matches[1]);
                            $operator = strtoupper(trim($matches[2]));
                        }

                        $field_escaped = "`" . str_replace("`", "``", $field) . "`"; // Escape column name
                        if ($isBinary) {
                            $field_escaped = "BINARY {$field_escaped}";
                        }

                        if ($operator === 'IN' || $operator === 'NOT IN') {
                            if (is_array($subValue)) {
                                $placeholders = $this->in_clause_helper($field, $subValue, $params);
                                $subConditionParts[] = "{$field_escaped} {$operator} ({$placeholders})";
                            } else {
                                error_log("Invalid value for IN/NOT IN clause within OR group for column '{$field}'. Value must be an array.");
                                continue;
                            }
                        } elseif ($operator === 'IS NULL' || $operator === 'IS NOT NULL') {
                            $subConditionParts[] = "{$field_escaped} {$operator}";
                        } else {
                            $subConditionParts[] = "{$field_escaped} {$operator} ?";
                            $params[] = $subValue;
                        }
                    }
                    if (!empty($subConditionParts)) {
                        $currentOrGroupParts[] = "(" . implode(" AND ", $subConditionParts) . ")";
                    }
                } else {
                    error_log("Invalid OR condition set format. Expected an array of associative arrays.");
                }
            }
            if (!empty($currentOrGroupParts)) {
                $orGroupClauses[] = "(" . implode(" OR ", $currentOrGroupParts) . ")";
            }
        } else {
            // This is a regular AND condition
            $operator = '=';
            $field = $key; // $key is the column name
            $isBinary = false;

            if (strpos(strtoupper(trim($key)), 'BINARY ') === 0) {
                $isBinary = true;
                $field = substr(trim($key), 7);
            }

            if (preg_match('/(.*?)\s*(<|>|<=|>=|!=|<>|LIKE|NOT LIKE|IN|NOT IN|IS NULL|IS NOT NULL)$/i', $field, $matches)) {
                $field = trim($matches[1]);
                $operator = strtoupper(trim($matches[2]));
            }

            $field_escaped = "`" . str_replace("`", "``", $field) . "`"; // Escape column name
            if ($isBinary) {
                $field_escaped = "BINARY {$field_escaped}";
            }

            if ($operator === 'IN' || $operator === 'NOT IN') {
                if (is_array($value)) {
                    $placeholders = $this->in_clause_helper($field, $value, $params);
                    $whereParts[] = "{$field_escaped} {$operator} ({$placeholders})";
                } else {
                    error_log("Invalid value for IN/NOT IN clause for column '{$field}'. Value must be an array.");
                    continue;
                }
            } elseif ($operator === 'IS NULL' || $operator === 'IS NOT NULL') {
                $whereParts[] = "{$field_escaped} {$operator}";
            } else {
                $whereParts[] = "{$field_escaped} {$operator} ?";
                $params[] = $value;
            }
        }
    }
    // Combine all AND parts and the OR group clauses
    $finalWhereParts = array_merge($whereParts, $orGroupClauses);

    return empty($finalWhereParts) ? '' : " WHERE " . implode(" AND ", $finalWhereParts);
}


    /**
    * Truncate a table (removes all rows and resets auto-increment counter).
    *
    * Usage Example:
    * if ($database->truncate_table('logs')) {
    * echo "Table 'logs' truncated successfully!";
    * } else {
    * echo "Failed to truncate table 'logs'.";
    * }
    * 
    * @param string $tableName The name of the table to truncate.
    * @return bool True on success, false on failure.
    */
    public function truncate_table($tableName) {
    try {
        $sql = "TRUNCATE TABLE `{$tableName}`";
        $stmt = $this->pdo->prepare($sql);
        $stmt->execute();
        $this->queryCount++;
        return true;
    } catch (PDOException $e) {
        $errorMessage = "Failed to truncate table '{$tableName}': " . $e->getMessage();
        error_log($errorMessage);
        $this->send_error_email("Database Truncate Error", $errorMessage);
        return false;
    }
  }


    /**
    * Send email messages with MySQL access and query errors.
    * Requires mail() function to be configured on the server.
    *
    * Usage Example (internal, called by class methods on error):
    * $this->send_error_email("Database Connection Error", "Could not connect to MySQL.");
    *
    * @param string $subject The subject of the email.
    * @param string $message The body of the email. 
    * @return bool True if the email was sent successfully, false otherwise. 
    */
   public function send_error_email($subject, $message) {
    if ($this->errorEmailRecipient === null || $this->errorEmailRecipient === '') {
        // No recipient set, so don't send email
        return false;
    }

    $headers = 'From: [email protected]' . "\r\n" .
               'Reply-To: webmaster@yourdomain.com' . "\r\n" .
               'X-Mailer: PHP/' . phpversion();

    // In a real application, you might want to format the message better
    // and include more context like $_SERVER data, stack trace, etc.
    $fullMessage = "An error occurred in your application:\n\n" .
                   "Subject: " . $subject . "\n" .
                   "Message: " . $message . "\n\n" .
                   "Timestamp: " . date('Y-m-d H:i:s') . "\n" .
                   "Script: " . ($_SERVER['PHP_SELF'] ?? 'N/A') . "\n" .
                   "Referer: " . ($_SERVER['HTTP_REFERER'] ?? 'N/A') . "\n" .
                   "User Agent: " . ($_SERVER['HTTP_USER_AGENT'] ?? 'N/A');

    return mail($this->errorEmailRecipient, $subject, $fullMessage, $headers);
  }

    /**
    * Set the email recipient for error notifications.
    *
    * Usage Example:
    * $database->set_error_email_recipient('admin@yourdomain.com');
    *
    * @param string $email The email address to send error notifications to.
    */
    public function set_error_email_recipient($email) {
    $this->errorEmailRecipient = $email;
  }

    /**
    * Display the total number of queries performed during all instances of the class.
    *
    * Usage Example:
    * echo "Total queries executed: " . $database->get_query_count();
    *
    * @return int The total number of queries executed.
    */
    public function get_query_count() {
      return $this->queryCount;
   }


   /**
   * Checks if a record exists in a table based on given conditions.
   * This function securely uses prepared statements via num_rows.
   *
   * Usage Example:
   * $check_user = ['user_email' => '[email protected]', 'user_id' => 48];
   * $exists = $database->exists('users', $check_user);
   *
   * @param string $table The database table name.
   * @param array $conditions An associative array of column name => column value to match. 
   * @return bool True if the record exists, false otherwise.
   */
   public function exists($table = '', $conditions = []) {
    if (empty($table) || empty($conditions)) {
        return false;
    }
    return $this->num_rows($table, $conditions) > 0;
  }


   /**
   * Returns the number of fields (columns) in the result set of a query.
   *
   * Usage Example:
   * $stmt = $database->execute_query("SELECT id, name, email FROM users LIMIT 1");
   * $numFields = $database->get_num_fields($stmt); // Output: 3
   *
   * @param PDOStatement|false $stmt The PDOStatement object returned by execute_query.
   * @return int The number of fields, or 0 if statement is invalid.
  */
  public function get_num_fields($stmt) {
    if ($stmt instanceof PDOStatement) {
        return $stmt->columnCount();
    }
    return 0;
  }

  /**
  * Returns an array of field (column) names from the result set of a query.
  *
  * Usage Example:
  * $stmt = $database->execute_query("SELECT id, name, email, status, created_at FROM users LIMIT 1");
  * $fieldNames = $database->get_list_fields($stmt); // Output: ['id', 'name', 'email', 'status', 'created_at']
  *
  * @param PDOStatement|false $stmt The PDOStatement object returned by execute_query.
  * @return array An array of column names, or an empty array if statement is invalid.
  */
  public function get_list_fields($stmt)  {
    $fieldNames = [];
    if ($stmt instanceof PDOStatement) {
        for ($i = 0; $i < $stmt->columnCount(); $i++) {
            $meta = $stmt->getColumnMeta($i);
            $fieldNames[] = $meta['name'];
        }
    }
    return $fieldNames;
  }

 } /* end of class DB */