From b56885e3fcf80b38320b793d638e8ad855b5bf2b Mon Sep 17 00:00:00 2001
From: Hash Borgir <atirjavid@gmail.com>
Date: Thu, 1 Jun 2023 23:29:56 -0600
Subject: [PATCH] _pdo.php clean up and comments

---
 _pdo.php | 122 ++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 99 insertions(+), 23 deletions(-)

diff --git a/_pdo.php b/_pdo.php
index b9c4f34..ec20d45 100755
--- a/_pdo.php
+++ b/_pdo.php
@@ -1,22 +1,47 @@
 <?php
-// PDO helper functions.
-// Copyright (c) 2012-2014 The PHP Desktop authors. All rights reserved.
-// License: New BSD License.
-// Website: http://code.google.com/p/phpdesktop/
+/**
+ * PDO helper functions.
+ *
+ * This code provides helper functions for working with PDO.
+ * It includes functions for connecting to a database, executing queries,
+ * fetching rows and values, and retrieving error information.
+ *
+ * @package PDO_Helper
+ * @copyright Copyright (c) 2012-2014 The PHP Desktop authors
+ * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
+ * @link http://code.google.com/p/phpdesktop/ Website
+ * 
+ * Commented and cleaned by Hash Borgir 
+ */
 
-function PDO_Connect($dsn, $user="", $password="")
+/**
+ * Connects to the database using PDO.
+ *
+ * @param string $dsn The Data Source Name, a string that describes the database source.
+ * @param string $user The username for the database connection.
+ * @param string $password The password for the database connection.
+ * @return void
+ */
+function PDO_Connect($dsn, $user = "", $password = "")
 {
     global $PDO;
     $PDO = new PDO($dsn, $user, $password);
     $PDO->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_WARNING);
-	$PDO->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, false);
+    $PDO->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, false);
 }
-function PDO_FetchOne($query, $params=null)
+
+/**
+ * Fetches a single value from a query.
+ *
+ * @param string $query The SQL query to execute.
+ * @param array|null $params An array of values to bind to the query parameters.
+ * @return mixed|null The fetched value, or null if no value is found.
+ */
+function PDO_FetchOne($query, $params = null)
 {
     global $PDO;
     if (isset($params)) {
-        $stmt = $PDO->prepare($query,array(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => false));
-		
+        $stmt = $PDO->prepare($query, [PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => false]);
         $stmt->execute($params);
     } else {
         $stmt = $PDO->query($query);
@@ -25,78 +50,129 @@ function PDO_FetchOne($query, $params=null)
     if ($row) {
         return $row[0];
     } else {
-        return false;
+        return null;
     }
 }
-function PDO_FetchRow($query, $params=null)
+
+/**
+ * Fetches a single row from a query.
+ *
+ * @param string $query The SQL query to execute.
+ * @param array|null $params An array of values to bind to the query parameters.
+ * @return array|false The fetched row as an associative array, or false if no row is found.
+ */
+function PDO_FetchRow($query, $params = null)
 {
     global $PDO;
     if (isset($params)) {
-        $stmt = $PDO->prepare($query,array(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => false));
+        $stmt = $PDO->prepare($query, [PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => false]);
         $stmt->execute($params);
     } else {
         $stmt = $PDO->query($query);
     }
     return $stmt->fetch(PDO::FETCH_ASSOC);
 }
-function PDO_FetchAll($query, $params=null)
+
+/**
+ * Fetches all rows from a query.
+ *
+ * @param string $query The SQL query to execute.
+ * @param array|null $params An array of values to bind to the query parameters.
+ * @return array The fetched rows as an associative array.
+ */
+function PDO_FetchAll($query, $params = null)
 {
     global $PDO;
     if (isset($params)) {
-        $stmt = $PDO->prepare($query,array(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => false));
+        $stmt = $PDO->prepare($query, [PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => false]);
         $stmt->execute($params);
     } else {
         $stmt = $PDO->query($query);
     }
     return $stmt->fetchAll(PDO::FETCH_ASSOC);
 }
-function PDO_FetchAllAssoc($query, $params=null)
+
+/**
+ * Fetches all rows from a query and groups them by a specific column.
+ *
+ * @param string $query The SQL query to execute.
+ * @param array|null $params An array of values to bind to the query parameters.
+ * @return array The fetched rows as an associative array, grouped by the specified column.
+ */
+function PDO_FetchAllAssoc($query, $params = null)
 {
     global $PDO;
     if (isset($params)) {
-        $stmt = $PDO->prepare($query,array(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => false));
+        $stmt = $PDO->prepare($query, [PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => false]);
         $stmt->execute($params);
     } else {
         $stmt = $PDO->query($query);
     }
-    return $stmt->fetchAll(PDO::FETCH_COLUMN|PDO::FETCH_GROUP);
+    return $stmt->fetchAll(PDO::FETCH_COLUMN | PDO::FETCH_GROUP);
 }
-function PDO_FetchAssoc($query, $params=null)
+
+/**
+ * Fetches key-value pairs from a query.
+ *
+ * @param string $query The SQL query to execute.
+ * @param array|null $params An array of values to bind to the query parameters.
+ * @return array The fetched key-value pairs as an associative array.
+ */
+function PDO_FetchAssoc($query, $params = null)
 {
     global $PDO;
     if (isset($params)) {
-        $stmt = $PDO->prepare($query,array(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => false));
+        $stmt = $PDO->prepare($query, [PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => false]);
         $stmt->execute($params);
     } else {
         $stmt = $PDO->query($query);
     }
     $rows = $stmt->fetchAll(PDO::FETCH_NUM);
-    $assoc = array();
+    $assoc = [];
     foreach ($rows as $row) {
         $assoc[$row[0]] = $row[1];
     }
     return $assoc;
 }
-function PDO_Execute($query, $params=null)
+
+/**
+ * Executes a query.
+ *
+ * @param string $query The SQL query to execute.
+ * @param array|null $params An array of values to bind to the query parameters.
+ * @return PDOStatement|false The PDOStatement object representing the executed query, or false on failure.
+ */
+function PDO_Execute($query, $params = null)
 {
     global $PDO;
     if (isset($params)) {
-        $stmt = $PDO->prepare($query,array(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => false));
+        $stmt = $PDO->prepare($query, [PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => false]);
         $stmt->execute($params);
         return $stmt;
     } else {
         return $PDO->query($query);
     }
 }
+
+/**
+ * Returns the last inserted row ID.
+ *
+ * @return string The last inserted row ID.
+ */
 function PDO_LastInsertId()
 {
     global $PDO;
     return $PDO->lastInsertId();
 }
+
+/**
+ * Returns information about the last error that occurred on the database connection.
+ *
+ * @return array The error information as an array.
+ */
 function PDO_ErrorInfo()
 {
     global $PDO;
     return $PDO->errorInfo();
 }
-
 ?>