X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=src%2FDatabase%2FDBA.php;h=f3edf52be5f1e973f940402db42ff6cc90b5d16b;hb=f4e1acedfcd86c81403c14747ecfd3b11583506e;hp=9c607638b9c6050b8e069f591881ad3b20b49791;hpb=b8f85f0484fbb1f37e9cae2f4cf98f9349fda099;p=friendica.git

diff --git a/src/Database/DBA.php b/src/Database/DBA.php
index 9c607638b9..f3edf52be5 100644
--- a/src/Database/DBA.php
+++ b/src/Database/DBA.php
@@ -1,4 +1,23 @@
 <?php
+/**
+ * @copyright Copyright (C) 2020, Friendica
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
 
 namespace Friendica\Database;
 
@@ -10,8 +29,6 @@ use PDO;
 use PDOStatement;
 
 /**
- * @class MySQL database class
- *
  * This class is for the low level database stuff that does driver specific things.
  */
 class DBA
@@ -56,7 +73,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Returns the MySQL server version string
+	 * Returns the MySQL server version string
 	 *
 	 * This function discriminate between the deprecated mysql API and the current
 	 * object-oriented mysqli API. Example of returned string: 5.5.46-0+deb8u1
@@ -69,7 +86,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Returns the selected database name
+	 * Returns the selected database name
 	 *
 	 * @return string
 	 * @throws \Exception
@@ -79,19 +96,30 @@ class DBA
 		return DI::dba()->databaseName();
 	}
 
+	/**
+	 * Escape all SQL unsafe data
+	 *
+	 * @param string $str
+	 * @return string escaped string
+	 */
 	public static function escape($str)
 	{
 		return DI::dba()->escape($str);
 	}
 
+	/**
+	 * Checks if the database is connected
+	 *
+	 * @return boolean is the database connected?
+	 */
 	public static function connected()
 	{
 		return DI::dba()->connected();
 	}
 
 	/**
-	 * @brief Replaces ANY_VALUE() function by MIN() function,
-	 *  if the database server does not support ANY_VALUE().
+	 * Replaces ANY_VALUE() function by MIN() function,
+	 * if the database server does not support ANY_VALUE().
 	 *
 	 * Considerations for Standard SQL, or MySQL with ONLY_FULL_GROUP_BY (default since 5.7.5).
 	 * ANY_VALUE() is available from MySQL 5.7.5 https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html
@@ -106,7 +134,7 @@ class DBA
 	}
 
 	/**
-	 * @brief beautifies the query - useful for "SHOW PROCESSLIST"
+	 * beautifies the query - useful for "SHOW PROCESSLIST"
 	 *
 	 * This is safe when we bind the parameters later.
 	 * The parameter values aren't part of the SQL.
@@ -127,7 +155,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Convert parameter array to an universal form
+	 * Convert parameter array to an universal form
 	 * @param array $args Parameter array
 	 * @return array universalized parameter array
 	 */
@@ -144,8 +172,8 @@ class DBA
 	}
 
 	/**
-	 * @brief Executes a prepared statement that returns data
-	 * @usage Example: $r = p("SELECT * FROM `item` WHERE `guid` = ?", $guid);
+	 * Executes a prepared statement that returns data
+	 * Example: $r = p("SELECT * FROM `item` WHERE `guid` = ?", $guid);
 	 *
 	 * Please only use it with complicated queries.
 	 * For all regular queries please use DBA::select or DBA::exists
@@ -162,7 +190,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Executes a prepared statement like UPDATE or INSERT that doesn't return data
+	 * Executes a prepared statement like UPDATE or INSERT that doesn't return data
 	 *
 	 * Please use DBA::delete, DBA::insert, DBA::update, ... instead
 	 *
@@ -178,7 +206,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Check if data exists
+	 * Check if data exists
 	 *
 	 * @param string|array $table     Table name or array [schema => table]
 	 * @param array        $condition array of fields for condition
@@ -196,7 +224,6 @@ class DBA
 	 *
 	 * Please use DBA::selectFirst or DBA::exists whenever this is possible.
 	 *
-	 * @brief Fetches the first row
 	 * @param string $sql SQL statement
 	 * @return array first row of query
 	 * @throws \Exception
@@ -209,7 +236,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Returns the number of affected rows of the last statement
+	 * Returns the number of affected rows of the last statement
 	 *
 	 * @return int Number of rows
 	 */
@@ -219,7 +246,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Returns the number of columns of a statement
+	 * Returns the number of columns of a statement
 	 *
 	 * @param object Statement object
 	 * @return int Number of columns
@@ -229,7 +256,7 @@ class DBA
 		return DI::dba()->columnCount($stmt);
 	}
 	/**
-	 * @brief Returns the number of rows of a statement
+	 * Returns the number of rows of a statement
 	 *
 	 * @param PDOStatement|mysqli_result|mysqli_stmt Statement object
 	 * @return int Number of rows
@@ -240,7 +267,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Fetch a single row
+	 * Fetch a single row
 	 *
 	 * @param mixed $stmt statement object
 	 * @return array current row
@@ -251,7 +278,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Insert a row into a table
+	 * Insert a row into a table
 	 *
 	 * @param string|array $table               Table name or array [schema => table]
 	 * @param array        $param               parameter array
@@ -266,7 +293,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Fetch the id of the last insert command
+	 * Fetch the id of the last insert command
 	 *
 	 * @return integer Last inserted id
 	 */
@@ -276,7 +303,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Locks a table for exclusive write access
+	 * Locks a table for exclusive write access
 	 *
 	 * This function can be extended in the future to accept a table array as well.
 	 *
@@ -291,7 +318,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Unlocks all locked tables
+	 * Unlocks all locked tables
 	 *
 	 * @return boolean was the unlock successful?
 	 * @throws \Exception
@@ -302,7 +329,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Starts a transaction
+	 * Starts a transaction
 	 *
 	 * @return boolean Was the command executed successfully?
 	 */
@@ -312,7 +339,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Does a commit
+	 * Does a commit
 	 *
 	 * @return boolean Was the command executed successfully?
 	 */
@@ -322,7 +349,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Does a rollback
+	 * Does a rollback
 	 *
 	 * @return boolean Was the command executed successfully?
 	 */
@@ -332,7 +359,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Delete a row from a table
+	 * Delete a row from a table
 	 *
 	 * @param string|array $table      Table name
 	 * @param array        $conditions Field condition(s)
@@ -349,9 +376,9 @@ class DBA
 	}
 
 	/**
-	 * @brief Updates rows
+	 * Updates rows in the database.
 	 *
-	 * Updates rows in the database. When $old_fields is set to an array,
+	 * When $old_fields is set to an array,
 	 * the system will only do an update if the fields in that array changed.
 	 *
 	 * Attention:
@@ -385,7 +412,6 @@ class DBA
 	/**
 	 * Retrieve a single record from a table and returns it in an associative array
 	 *
-	 * @brief Retrieve a single record from a table
 	 * @param string|array $table     Table name or array [schema => table]
 	 * @param array        $fields
 	 * @param array        $condition
@@ -400,7 +426,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Select rows from a table and fills an array with the data
+	 * Select rows from a table and fills an array with the data
 	 *
 	 * @param string|array $table     Table name or array [schema => table]
 	 * @param array        $fields    Array of selected fields, empty for all
@@ -417,7 +443,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Select rows from a table
+	 * Select rows from a table
 	 *
 	 * @param string|array $table     Table name or array [schema => table]
 	 * @param array        $fields    Array of selected fields, empty for all
@@ -445,7 +471,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Counts the rows from a table satisfying the provided condition
+	 * Counts the rows from a table satisfying the provided condition
 	 *
 	 * @param string|array $table     Table name or array [schema => table]
 	 * @param array        $condition array of fields for condition
@@ -510,7 +536,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Returns the SQL condition string built from the provided condition array
+	 * Returns the SQL condition string built from the provided condition array
 	 *
 	 * This function operates with two modes.
 	 * - Supplied with a filed/value associative array, it builds simple strict
@@ -620,7 +646,21 @@ class DBA
 	}
 
 	/**
-	 * @brief Returns the SQL parameter string built from the provided parameter array
+	 * Returns the SQL parameter string built from the provided parameter array
+	 *
+	 * Expected format for each key:
+	 *
+	 * group_by:
+	 *  - list of column names
+	 *
+	 * order:
+	 *  - numeric keyed column name => ASC
+	 *  - associative element with boolean value => DESC (true), ASC (false)
+	 *  - associative element with string value => 'ASC' or 'DESC' literally
+	 *
+	 * limit:
+	 *  - single numeric value => count
+	 *  - list with two numeric values => offset, count
 	 *
 	 * @param array $params
 	 * @return string
@@ -639,7 +679,11 @@ class DBA
 				if ($order === 'RAND()') {
 					$order_string .= "RAND(), ";
 				} elseif (!is_int($fields)) {
-					$order_string .= self::quoteIdentifier($fields) . " " . ($order ? "DESC" : "ASC") . ", ";
+					if ($order !== 'DESC' && $order !== 'ASC') {
+						$order = $order ? 'DESC' : 'ASC';
+					}
+
+					$order_string .= self::quoteIdentifier($fields) . " " . $order . ", ";
 				} else {
 					$order_string .= self::quoteIdentifier($order) . ", ";
 				}
@@ -660,7 +704,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Fills an array with data from a query
+	 * Fills an array with data from a query
 	 *
 	 * @param object $stmt statement object
 	 * @param bool   $do_close
@@ -672,7 +716,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Returns the error number of the last query
+	 * Returns the error number of the last query
 	 *
 	 * @return string Error number (0 if no error)
 	 */
@@ -682,7 +726,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Returns the error message of the last query
+	 * Returns the error message of the last query
 	 *
 	 * @return string Error message ('' if no error)
 	 */
@@ -692,7 +736,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Closes the current statement
+	 * Closes the current statement
 	 *
 	 * @param object $stmt statement object
 	 * @return boolean was the close successful?
@@ -703,7 +747,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Return a list of database processes
+	 * Return a list of database processes
 	 *
 	 * @return array
 	 *      'list' => List of processes, separated in their different states
@@ -715,6 +759,17 @@ class DBA
 		return DI::dba()->processlist();
 	}
 
+	/**
+	 * Fetch a database variable
+	 *
+	 * @param string $name
+	 * @return string content
+	 */
+	public static function getVariable(string $name)
+	{
+		return DI::dba()->getVariable($name);
+	}
+
 	/**
 	 * Checks if $array is a filled array with at least one entry.
 	 *
@@ -728,7 +783,7 @@ class DBA
 	}
 
 	/**
-	 * @brief Escapes a whole array
+	 * Escapes a whole array
 	 *
 	 * @param mixed   $arr           Array with values to be escaped
 	 * @param boolean $add_quotation add quotation marks for string values