class.win32native.php

Go to the documentation of this file.

<?php
/*
 * Copyright (c) 2022-2025 Bearsampp
 * License: GNU General Public License version 3 or later; see LICENSE.txt
 * Website: https://bearsampp.com
 * Github: https://github.com/Bearsampp
 */

class Win32Native
{
    // ========================================================================
    // COM Connection Cache
    // Each COM object is created once per PHP process and reused across calls.
    // On a COM/WMI failure the catching method calls resetConnections() so the
    // next call gets a fresh object instead of reusing a broken cached instance.
    // ========================================================================

    private static ?COM $wmiCimv2 = null;

    private static ?COM $wmiStdRegProv = null;

    private static ?COM $wscriptShell = null;

    private static function getWmiCimv2(): COM
    {
        if (self::$wmiCimv2 === null) {
            self::$wmiCimv2 = new COM("winmgmts://./root/cimv2");
        }
 
        return self::$wmiCimv2;
    }

    private static function getWmiStdRegProv(): COM
    {
        if (self::$wmiStdRegProv === null) {
            self::$wmiStdRegProv = new COM("winmgmts://./root/default:StdRegProv");
        }
 
        return self::$wmiStdRegProv;
    }

    private static function getWscriptShell(): COM
    {
        if (self::$wscriptShell === null) {
            self::$wscriptShell = new COM("WScript.Shell");
        }
 
        return self::$wscriptShell;
    }

    public static function resetConnections(): void
    {
        self::$wmiCimv2      = null;
        self::$wmiStdRegProv = null;
        self::$wscriptShell  = null;
    }

    public static function getProcessList($properties = [])
    {
        Log::debug('getProcessList: Listing processes (COM/WMI)');
 
        $startTime = microtime(true);
 
        try {
            // Create WMI connection
            $wmi = self::getWmiCimv2();
 
            // Build WQL query
            if (empty($properties)) {
                $properties = ['Name', 'ProcessID', 'ExecutablePath'];
            }
 
            $selectClause = implode(', ', $properties);
            $query        = "SELECT {$selectClause} FROM Win32_Process";
 
            // Execute query
            $processes = $wmi->ExecQuery($query);
 
            // Convert to array
            $result = [];
            foreach ($processes as $proc) {
                $process = [];
                foreach ($properties as $prop) {
                    // Handle property access
                    try {
                        $value          = $proc->$prop;
                        $process[$prop] = $value ?? '';
                    } catch (Exception $e) {
                        $process[$prop] = '';
                    }
                }
                $result[] = $process;
            }
 
            $duration = round((microtime(true) - $startTime) * 1000, 2);
            Log::debug('getProcessList: Found ' . count($result) . ' processes in ' . $duration . 'ms (COM/WMI)');
 
            return $result;
        } catch (Exception $e) {
            self::resetConnections();
            Log::error('getProcessList: COM exception: ' . $e->getMessage());
 
            return [];
        }
    }

    public static function killProcess($pid)
    {
        // Validate PID
        if (!is_numeric($pid) || $pid <= 0) {
            Log::error('killProcess: Invalid PID: ' . $pid);
 
            return false;
        }
 
        Log::debug('killProcess: Killing process PID ' . $pid . ' (COM/WMI)');
 
        $startTime = microtime(true);
 
        try {
            // Create WMI connection
            $wmi = self::getWmiCimv2();
 
            // Query for specific process
            $query     = "SELECT * FROM Win32_Process WHERE ProcessID = {$pid}";
            $processes = $wmi->ExecQuery($query);
 
            // Terminate the process
            $found           = false;
            $terminateResult = null;
            foreach ($processes as $proc) {
                $terminateResult = $proc->Terminate();
                $found           = true;
                break;
            }
 
            $duration = round((microtime(true) - $startTime) * 1000, 2);
 
            if (!$found) {
                Log::debug('killProcess: Process ' . $pid . ' not found');
 
                return false;
            }
 
            // Check if Terminate() returned success (0 = success)
            if ($terminateResult !== 0) {
                Log::error('killProcess: Terminate() failed with status code: ' . $terminateResult);
 
                return false;
            }
 
            // Additional verification: check if process still exists after a short delay
            usleep(100000); // Wait 100ms for termination to take effect
            if (self::processExists($pid)) {
                Log::error('killProcess: Process ' . $pid . ' still exists after termination attempt');
 
                return false;
            }
 
            Log::debug('killProcess: Successfully killed process ' . $pid . ' in ' . $duration . 'ms (COM/WMI)');
 
            return true;
        } catch (Exception $e) {
            self::resetConnections();
            Log::error('killProcess: COM exception: ' . $e->getMessage());
 
            return false;
        }
    }

    public static function processExists($pid)
    {
        if (!is_numeric($pid) || $pid <= 0) {
            return false;
        }
 
        try {
            $wmi       = self::getWmiCimv2();
            $query     = "SELECT ProcessID FROM Win32_Process WHERE ProcessID = {$pid}";
            $processes = $wmi->ExecQuery($query);
 
            foreach ($processes as $proc) {
                return true;
            }
 
            return false;
        } catch (Exception $e) {
            self::resetConnections();
 
            return false;
        }
    }

    public static function getProcessInfo($pid, $properties = [])
    {
        if (!is_numeric($pid) || $pid <= 0) {
            return false;
        }
 
        if (empty($properties)) {
            $properties = ['Name', 'ProcessID', 'ExecutablePath', 'CommandLine'];
        }
 
        try {
            $wmi          = self::getWmiCimv2();
            $selectClause = implode(', ', $properties);
            $query        = "SELECT {$selectClause} FROM Win32_Process WHERE ProcessID = {$pid}";
            $processes    = $wmi->ExecQuery($query);
 
            foreach ($processes as $proc) {
                $result = [];
                foreach ($properties as $prop) {
                    try {
                        $value         = $proc->$prop;
                        $result[$prop] = $value ?? '';
                    } catch (Exception $e) {
                        $result[$prop] = '';
                    }
                }
 
                return $result;
            }
 
            return false;
        } catch (Exception $e) {
            self::resetConnections();
            Log::error('getProcessInfo: COM exception: ' . $e->getMessage());
 
            return false;
        }
    }

    public static function findProcessesByName($name, $properties = [])
    {
        if (empty($name)) {
            return [];
        }
 
        if (empty($properties)) {
            $properties = ['Name', 'ProcessID', 'ExecutablePath'];
        }
 
        try {
            $wmi          = self::getWmiCimv2();
            $selectClause = implode(', ', $properties);
 
            // Sanitize the name parameter to prevent WQL injection
            // Escape single quotes by doubling them (WQL standard)
            $safeName = str_replace("'", "''", $name);
 
            $query     = "SELECT {$selectClause} FROM Win32_Process WHERE Name = '{$safeName}'";
            $processes = $wmi->ExecQuery($query);
 
            $result = [];
            foreach ($processes as $proc) {
                $process = [];
                foreach ($properties as $prop) {
                    try {
                        $value          = $proc->$prop;
                        $process[$prop] = $value ?? '';
                    } catch (Exception $e) {
                        $process[$prop] = '';
                    }
                }
                $result[] = $process;
            }
 
            return $result;
        } catch (Exception $e) {
            self::resetConnections();
            Log::error('findProcessesByName: COM exception: ' . $e->getMessage());
 
            return [];
        }
    }

    public static function getCurrentPid()
    {
        return getmypid();
    }
 
    // ========================================================================
    // Registry Operations (COM/WScript.Shell)
    // ========================================================================

    private static function mapRegistryHive($hive)
    {
        $hiveMap = [
            'HKLM'               => 'HKLM',
            'HKCU'               => 'HKCU',
            'HKCR'               => 'HKCR',
            'HKU'                => 'HKU',
            'HKEY_LOCAL_MACHINE' => 'HKLM',
            'HKEY_CURRENT_USER'  => 'HKCU',
            'HKEY_CLASSES_ROOT'  => 'HKCR',
            'HKEY_USERS'         => 'HKU',
        ];
 
        return isset($hiveMap[$hive]) ? $hiveMap[$hive] : $hive;
    }

    public static function registryExists($hive, $key, $value = null)
    {
        $hive    = self::mapRegistryHive($hive);
        $regPath = $hive . '\\' . $key;
 
        Log::debug('registryExists: Checking ' . $regPath . ($value !== null ? '\\' . $value : ' (key)') . ' (COM)');
 
        try {
            if ($value === null) {
                // Check if the key itself exists
                // Use StdRegProv::EnumKey for reliable key existence checking
                // This avoids false negatives from checking for a default value that may not exist
                try {
                    $wmi = self::getWmiStdRegProv();
 
                    // Map hive names to WMI constants
                    $hiveConstMap = [
                        'HKCR' => 0x80000000,  // HKEY_CLASSES_ROOT
                        'HKCU' => 0x80000001,  // HKEY_CURRENT_USER
                        'HKLM' => 0x80000002,  // HKEY_LOCAL_MACHINE
                        'HKU'  => 0x80000003,  // HKEY_USERS
                    ];
 
                    $hConst = $hiveConstMap[$hive] ?? 0x80000002;  // Default to HKLM
 
                    // EnumKey checks if parent key's subkeys contain the requested key
                    // For root-level checks, pass empty parent
                    $pathParts = explode('\\', $key);
 
                    if (count($pathParts) === 1) {
                        // Top-level key: parent is root
                        $parentKey = '';
                        $keyName   = $pathParts[0];
                    } else {
                        // Nested key: split parent from key name
                        $keyName   = array_pop($pathParts);
                        $parentKey = implode('\\', $pathParts);
                    }
 
                    $subKeys = null;
                    $rc      = $wmi->EnumKey($hConst, $parentKey, $subKeys);
 
                    if ($rc !== 0 || !is_array($subKeys)) {
                        Log::debug('registryExists: Key not found (EnumKey failed)');
 
                        return false;
                    }
 
                    // Check if our key name is in the list of subkeys
                    $exists = false;
                    foreach ($subKeys as $subKey) {
                        if (strcasecmp($subKey, $keyName) === 0) {
                            $exists = true;
                            break;
                        }
                    }
 
                    if ($exists) {
                        Log::debug('registryExists: Key found');
 
                        return true;
                    } else {
                        Log::debug('registryExists: Key not found');
 
                        return false;
                    }
                } catch (Exception $e) {
                    self::$wmiStdRegProv = null;
                    Log::error('registryExists: StdRegProv exception during key check: ' . $e->getMessage());
 
                    return false;
                }
            } else {
                // Check if a specific value exists within the key
                // Use WScript.Shell::RegRead for value existence
                try {
                    $shell     = self::getWscriptShell();
                    $valuePath = $regPath . '\\' . $value;
                    $shell->RegRead($valuePath);
                    Log::debug('registryExists: Value found');
 
                    return true;
                } catch (Exception $e) {
                    Log::debug('registryExists: Value not found');
 
                    return false;
                }
            }
        } catch (Exception $e) {
            self::resetConnections();
            Log::error('registryExists: COM exception: ' . $e->getMessage());
 
            return false;
        }
    }

    public static function registryGetValue($hive, $key, $value = '')
    {
        $hive    = self::mapRegistryHive($hive);
        $regPath = $hive . '\\' . $key;
 
        if ($value !== '') {
            $regPath .= '\\' . $value;
        } else {
            // For default value, append backslash
            $regPath .= '\\';
        }
 
        Log::debug('registryGetValue: Reading ' . $regPath . ' (COM)');
 
        $startTime = microtime(true);
 
        try {
            $shell  = self::getWscriptShell();
            $result = $shell->RegRead($regPath);
 
            $duration = round((microtime(true) - $startTime) * 1000, 2);
 
            // Convert result to appropriate PHP type
            if (is_object($result)) {
                // COM objects need special handling
                $result = (string)$result;
            }
 
            Log::debug('registryGetValue: Found value in ' . $duration . 'ms (COM)');
 
            return $result;
        } catch (Exception $e) {
            Log::debug('registryGetValue: Value not found');
 
            return null;
        }
    }

    public static function registrySetValue($hive, $key, $value, $data, $type = 'REG_SZ')
    {
        $hive    = self::mapRegistryHive($hive);
        $regPath = $hive . '\\' . $key . '\\' . $value;
 
        // Validate type
        $validTypes = ['REG_SZ', 'REG_EXPAND_SZ', 'REG_DWORD', 'REG_BINARY'];
        if (!in_array($type, $validTypes)) {
            Log::error('registrySetValue: Invalid type: ' . $type);
 
            return false;
        }
 
        Log::debug('registrySetValue: Writing ' . $regPath . ' (' . $type . ') (COM)');
 
        $startTime = microtime(true);
 
        try {
            $shell = self::getWscriptShell();
 
            // Convert data based on type
            if ($type === 'REG_DWORD') {
                $data = (int)$data;
            }
 
            // Write the value
            $shell->RegWrite($regPath, $data, $type);
 
            $duration = round((microtime(true) - $startTime) * 1000, 2);
            Log::debug('registrySetValue: Successfully wrote value in ' . $duration . 'ms (COM)');
 
            return true;
        } catch (Exception $e) {
            self::resetConnections();
            Log::error('registrySetValue: COM exception: ' . $e->getMessage());
 
            return false;
        }
    }

    public static function registryDeleteValue($hive, $key, $value)
    {
        $hive    = self::mapRegistryHive($hive);
        $regPath = $hive . '\\' . $key . '\\' . $value;
 
        Log::debug('registryDeleteValue: Deleting ' . $regPath . ' (COM)');
 
        $startTime = microtime(true);
 
        try {
            $shell = self::getWscriptShell();
 
            // Delete the value
            $shell->RegDelete($regPath);
 
            $duration = round((microtime(true) - $startTime) * 1000, 2);
            Log::debug('registryDeleteValue: Successfully deleted value in ' . $duration . 'ms (COM)');
 
            return true;
        } catch (Exception $e) {
            // If the value doesn't exist, that's OK
            $errorMsg = $e->getMessage();
            if (strpos($errorMsg, 'Unable to remove') !== false ||
                strpos($errorMsg, 'Invalid root') !== false) {
                Log::debug('registryDeleteValue: Value does not exist (already deleted)');
 
                return true;
            }
 
            self::resetConnections();
            Log::error('registryDeleteValue: COM exception: ' . $e->getMessage());
 
            return false;
        }
    }

    public static function registryDeleteKey($hive, $key)
    {
        $hive    = self::mapRegistryHive($hive);
        $regPath = $hive . '\\' . $key . '\\';
 
        Log::debug('registryDeleteKey: Deleting ' . $regPath . ' (COM)');
 
        try {
            $shell = self::getWscriptShell();
 
            // Delete the key (note the trailing backslash)
            $shell->RegDelete($regPath);
 
            Log::debug('registryDeleteKey: Successfully deleted key (COM)');
 
            return true;
        } catch (Exception $e) {
            // If the key doesn't exist, that's OK
            $errorMsg = $e->getMessage();
            if (strpos($errorMsg, 'Unable to remove') !== false ||
                strpos($errorMsg, 'Invalid root') !== false) {
                Log::debug('registryDeleteKey: Key does not exist (already deleted)');
 
                return true;
            }
 
            self::resetConnections();
            Log::error('registryDeleteKey: COM exception: ' . $e->getMessage());
 
            return false;
        }
    }
 
    // ========================================================================
    // Shortcuts & Special Paths (COM/WScript.Shell)
    // ========================================================================

    public static function getSpecialFolderPath($folderName)
    {
        Log::debug('getSpecialFolderPath: Getting ' . $folderName . ' path (COM)');
 
        $startTime = microtime(true);
 
        try {
            $shell = self::getWscriptShell();
 
            // Get the special folder path
            $path = $shell->SpecialFolders($folderName);
 
            $duration = round((microtime(true) - $startTime) * 1000, 2);
 
            if ($path && !empty($path)) {
                // Convert to Unix-style path
                $path = str_replace('\\', '/', $path);
                Log::debug('getSpecialFolderPath: Found ' . $folderName . ' in ' . $duration . 'ms (COM)');
 
                return $path;
            } else {
                Log::debug('getSpecialFolderPath: ' . $folderName . ' not found');
 
                return false;
            }
        } catch (Exception $e) {
            self::resetConnections();
            Log::error('getSpecialFolderPath: COM exception: ' . $e->getMessage());
 
            return false;
        }
    }

    public static function createShortcut($shortcutPath, $targetPath, $workingDir = '', $description = '', $iconPath = '')
    {
        Log::debug('createShortcut: Creating shortcut at ' . $shortcutPath . ' (COM)');
 
        $startTime = microtime(true);
 
        try {
            $shell = self::getWscriptShell();
 
            // Create the shortcut object
            $shortcut = $shell->CreateShortcut($shortcutPath);
 
            // Set shortcut properties
            $shortcut->TargetPath = $targetPath;
 
            if (!empty($workingDir)) {
                $shortcut->WorkingDirectory = $workingDir;
            }
 
            if (!empty($description)) {
                $shortcut->Description = $description;
            }
 
            if (!empty($iconPath)) {
                $shortcut->IconLocation = $iconPath;
            }
 
            // Save the shortcut
            $shortcut->Save();
 
            $duration = round((microtime(true) - $startTime) * 1000, 2);
            Log::debug('createShortcut: Successfully created shortcut in ' . $duration . 'ms (COM)');
 
            return true;
        } catch (Exception $e) {
            self::resetConnections();
            Log::error('createShortcut: COM exception: ' . $e->getMessage());
 
            return false;
        }
    }
 
    // ========================================================================
    // File Operations (COM/FileSystemObject or Native PHP)
    // ========================================================================

    public static function countFilesFolders($path)
    {
        Log::debug('countFilesFolders: Counting in ' . $path . ' (Native PHP)');
 
        $startTime = microtime(true);
 
        try {
            if (!is_dir($path)) {
                Log::error('countFilesFolders: Path is not a directory: ' . $path);
 
                return false;
            }
 
            $count = 0;
 
            // Use RecursiveDirectoryIterator for efficient recursive counting
            try {
                $iterator = new RecursiveIteratorIterator(
                    new RecursiveDirectoryIterator($path, RecursiveDirectoryIterator::SKIP_DOTS),
                    RecursiveIteratorIterator::SELF_FIRST
                );
 
                foreach ($iterator as $item) {
                    $count++;
                }
            } catch (Exception $e) {
                // If RecursiveIterator fails, fall back to manual recursion
                Log::debug('countFilesFolders: RecursiveIterator failed, using manual recursion');
                $count = self::countFilesFoldersManual($path);
            }
 
            $duration = round((microtime(true) - $startTime) * 1000, 2);
            Log::debug('countFilesFolders: Counted ' . $count . ' items in ' . $duration . 'ms (Native PHP)');
 
            return $count;
        } catch (Exception $e) {
            Log::error('countFilesFolders: Exception: ' . $e->getMessage());
 
            return false;
        }
    }

    private static function countFilesFoldersManual($path)
    {
        $count = 0;
 
        try {
            $items = @scandir($path);
 
            if ($items === false) {
                return 0;
            }
 
            foreach ($items as $item) {
                if ($item === '.' || $item === '..') {
                    continue;
                }
 
                $fullPath = $path . DIRECTORY_SEPARATOR . $item;
                $count++; // Count this item
 
                if (is_dir($fullPath)) {
                    // Recursively count subdirectory
                    $count += self::countFilesFoldersManual($fullPath);
                }
            }
        } catch (Exception $e) {
            // Silently handle errors (permission denied, etc.)
        }
 
        return $count;
    }

    public static function countFilesFoldersCOM($path)
    {
        Log::debug('countFilesFoldersCOM: Counting in ' . $path . ' (COM/FSO)');
 
        $startTime = microtime(true);
 
        try {
            $fso = new COM("Scripting.FileSystemObject");
 
            if (!$fso->FolderExists($path)) {
                Log::error('countFilesFoldersCOM: Path does not exist: ' . $path);
 
                return false;
            }
 
            $count = self::countFolderItemsCOM($fso, $path);
 
            $duration = round((microtime(true) - $startTime) * 1000, 2);
            Log::debug('countFilesFoldersCOM: Counted ' . $count . ' items in ' . $duration . 'ms (COM/FSO)');
 
            return $count;
        } catch (Exception $e) {
            Log::error('countFilesFoldersCOM: COM exception: ' . $e->getMessage());
 
            return false;
        }
    }

    private static function countFolderItemsCOM($fso, $path)
    {
        try {
            $folder = $fso->GetFolder($path);
 
            // Count files and subfolders in this folder
            $count = $folder->Files->Count + $folder->SubFolders->Count;
 
            // Recursively count subfolders
            foreach ($folder->SubFolders as $subFolder) {
                $count += self::countFolderItemsCOM($fso, $subFolder->Path);
            }
 
            return $count;
        } catch (Exception $e) {
            // Silently handle errors (permission denied, etc.)
            return 0;
        }
    }
 
    // ========================================================================
    // Service Operations (COM/WMI)
    // ========================================================================

    public static function getServiceInfo($serviceName, $properties = [])
    {
        Log::debug('getServiceInfo: Getting info for service ' . $serviceName . ' (COM/WMI)');
 
        $startTime = microtime(true);
 
        try {
            // Create WMI connection
            $wmi = self::getWmiCimv2();
 
            // Default properties if none specified
            if (empty($properties)) {
                $properties = [
                    'Name',
                    'DisplayName',
                    'State',
                    'Status',
                    'StartMode',
                    'PathName',
                    'ProcessId',
                    'Started',
                    'StartName',
                    'Description'
                ];
            }
 
            // Build WQL query
            $selectClause    = implode(', ', $properties);
            $safeServiceName = str_replace("'", "''", $serviceName);
            $query           = "SELECT {$selectClause} FROM Win32_Service WHERE Name = '{$safeServiceName}'";
 
            // Execute query
            $services = $wmi->ExecQuery($query);
 
            // Get the first (and should be only) result
            foreach ($services as $service) {
                $result = [];
                foreach ($properties as $prop) {
                    try {
                        $value         = $service->$prop;
                        $result[$prop] = $value ?? '';
                    } catch (Exception $e) {
                        $result[$prop] = '';
                    }
                }
 
                $duration = round((microtime(true) - $startTime) * 1000, 2);
                Log::debug('getServiceInfo: Found service in ' . $duration . 'ms (COM/WMI)');
 
                return $result;
            }
 
            // Service not found
            Log::debug('getServiceInfo: Service not found');
 
            return false;
        } catch (Exception $e) {
            self::resetConnections();
            Log::error('getServiceInfo: COM exception: ' . $e->getMessage());
 
            return false;
        }
    }

    public static function listServices($properties = [])
    {
        Log::debug('listServices: Listing all services (COM/WMI)');
 
        $startTime = microtime(true);
 
        try {
            // Create WMI connection
            $wmi = self::getWmiCimv2();
 
            // Default properties if none specified
            if (empty($properties)) {
                $properties = ['Name', 'DisplayName', 'State', 'StartMode'];
            }
 
            // Build WQL query
            $selectClause = implode(', ', $properties);
            $query        = "SELECT {$selectClause} FROM Win32_Service";
 
            // Execute query
            $services = $wmi->ExecQuery($query);
 
            // Convert to array
            $result = [];
            foreach ($services as $service) {
                $serviceInfo = [];
                foreach ($properties as $prop) {
                    try {
                        $value              = $service->$prop;
                        $serviceInfo[$prop] = $value ?? '';
                    } catch (Exception $e) {
                        $serviceInfo[$prop] = '';
                    }
                }
                $result[] = $serviceInfo;
            }
 
            $duration = round((microtime(true) - $startTime) * 1000, 2);
            Log::debug('listServices: Found ' . count($result) . ' services in ' . $duration . 'ms (COM/WMI)');
 
            return $result;
        } catch (Exception $e) {
            self::resetConnections();
            Log::error('listServices: COM exception: ' . $e->getMessage());
 
            return [];
        }
    }

    public static function serviceExists($serviceName)
    {
        try {
            $wmi = self::getWmiCimv2();
            // Sanitize the serviceName parameter to prevent WQL injection
            // Escape single quotes by doubling them (WQL standard)
            $safeServiceName = str_replace("'", "''", $serviceName);
            $query           = "SELECT Name FROM Win32_Service WHERE Name = '{$safeServiceName}'";
 
            // Execute query
            $services = $wmi->ExecQuery($query);
 
            foreach ($services as $service) {
                return true;
            }
 
            return false;
        } catch (Exception $e) {
            self::resetConnections();
 
            return false;
        }
    }

    public static function getServiceState($serviceName)
    {
        try {
            $wmi = self::getWmiCimv2();
            // Sanitize the serviceName parameter to prevent WQL injection
            // Escape single quotes by doubling them (WQL standard)
            $safeServiceName = str_replace("'", "''", $serviceName);
            $query           = "SELECT State FROM Win32_Service WHERE Name = '{$safeServiceName}'";
 
            // Execute query
            $services = $wmi->ExecQuery($query);
 
            foreach ($services as $service) {
                return $service->State;
            }
 
            return false;
        } catch (Exception $e) {
            self::resetConnections();
 
            return false;
        }
    }
 
    // ========================================================================
    // Browser Detection (COM/Registry)
    // ========================================================================

    public static function getDefaultBrowser()
    {
        Log::debug('getDefaultBrowser: Reading default browser (COM)');
 
        $startTime = microtime(true);
 
        // Try to read the default browser from registry
        $browserPath = self::registryGetValue('HKLM', 'SOFTWARE\\Classes\\http\\shell\\open\\command', '');
 
        if ($browserPath === null) {
            Log::debug('getDefaultBrowser: No default browser found');
 
            return false;
        }
 
        $duration = round((microtime(true) - $startTime) * 1000, 2);
 
        // Extract the executable path from the command
        // Format is usually: "C:\Program Files\Browser\browser.exe" -- "%1"
        if (preg_match('/"([^"]+)"/', $browserPath, $matches)) {
            $path = $matches[1];
        } else {
            // No quotes, take everything before the first space or use as-is
            $path = trim(explode(' ', $browserPath)[0]);
            $path = str_replace('"', '', $path);
        }
 
        Log::debug('getDefaultBrowser: Found browser in ' . $duration . 'ms (COM)');
 
        return $path;
    }

    public static function getInstalledBrowsers()
    {
        Log::debug('getInstalledBrowsers: Enumerating installed browsers (Hybrid - No VBS)');
 
        $startTime = microtime(true);
        $browsers  = [];
 
        // Known browser registry names (covers 99% of browsers)
        $knownBrowsers = [
            // Major browsers
            'Google Chrome',
            'Microsoft Edge',
            'Opera',
            'Brave',
            'Vivaldi',
            'Chromium',
 
            // Firefox variants
            'Firefox',
            'Firefox-308046B0AF4A39CB',  // Common Firefox GUID
            'Firefox Developer Edition',
            'Firefox Nightly',
 
            // Other browsers
            'Safari',
            'Waterfox',
            'Pale Moon',
            'Yandex',
            'IEXPLORE.EXE',
            'Total Browser',
            'Maxthon',
            'Seamonkey',
            'K-Meleon',
            'Basilisk',
            'Tor Browser',
            'Slimjet',
            'Epic Privacy Browser',
            'Comodo Dragon',
            'SRWare Iron',
            'Cent Browser',
            '360 Browser',
            'UC Browser',
            'Avast Secure Browser',
            'AVG Secure Browser',
        ];
 
        // Registry paths to check
        $registryPaths = [
            ['hive' => 'HKLM', 'key' => 'SOFTWARE\\WOW6432Node\\Clients\\StartMenuInternet'],
            ['hive' => 'HKLM', 'key' => 'SOFTWARE\\Clients\\StartMenuInternet'],
            ['hive' => 'HKCU', 'key' => 'SOFTWARE\\Clients\\StartMenuInternet'],
        ];
 
        // Check each known browser in each registry path
        foreach ($registryPaths as $regPath) {
            $hive     = $regPath['hive'];
            $basePath = $regPath['key'];
 
            foreach ($knownBrowsers as $browserName) {
                try {
                    // Try to read the browser's command path
                    $commandPath = self::registryGetValue(
                        $hive,
                        $basePath . '\\' . $browserName . '\\shell\\open\\command',
                        ''
                    );
 
                    if ($commandPath !== null && !empty($commandPath)) {
                        // Extract executable path
                        $exePath = self::extractBrowserExecutablePath($commandPath);
 
                        if ($exePath && !in_array($exePath, $browsers)) {
                            Log::debug('getInstalledBrowsers: Found ' . $browserName . ': ' . $exePath);
                            $browsers[] = $exePath;
                        }
                    }
                } catch (Exception $e) {
                    // Browser not found, continue
                    continue;
                }
            }
        }
 
        $duration = round((microtime(true) - $startTime) * 1000, 2);
        Log::debug('getInstalledBrowsers: Found ' . count($browsers) . ' browser(s) in ' . $duration . 'ms (Hybrid - No VBS)');
 
        // Always return an array (possibly empty) to simplify call sites
        return $browsers;
    }

    private static function extractBrowserExecutablePath($commandPath)
    {
        if (empty($commandPath)) {
            return false;
        }
 
        // Method 1: Extract path from quotes
        // Format: "C:\Program Files\Browser\browser.exe" --arguments
        if (preg_match('/"([^"]+\\.exe)"/i', $commandPath, $matches)) {
            return $matches[1];
        }
 
        // Method 2: Extract path without quotes but with .exe
        // Format: C:\Program Files\Browser\browser.exe --arguments
        if (preg_match('/^([^\\s]+\\.exe)/i', trim($commandPath), $matches)) {
            return $matches[1];
        }
 
        // Method 3: Handle paths with spaces but no quotes (rare)
        // Try to find .exe in the string
        if (preg_match('/([A-Z]:\\\\[^"]+\\.exe)/i', $commandPath, $matches)) {
            return $matches[1];
        }
 
        // Method 4: Fallback - take everything before first space
        $parts = explode(' ', trim($commandPath));
        $path  = str_replace('"', '', $parts[0]);
 
        // Validate it looks like a path
        if (stripos($path, '.exe') !== false) {
            return $path;
        }
 
        return false;
    }
}