From 633760bed4436d2507ec3865ae230d68e65b8a03 Mon Sep 17 00:00:00 2001 From: Can Arslan Date: Fri, 13 Apr 2018 22:25:01 +0200 Subject: [PATCH] Better PHPDoc PHPDoc updated for some param/return/throws parts --- MysqliDb.php | 525 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 308 insertions(+), 217 deletions(-) diff --git a/MysqliDb.php b/MysqliDb.php index 6a55bddf..1d0ac38d 100644 --- a/MysqliDb.php +++ b/MysqliDb.php @@ -18,48 +18,56 @@ class MysqliDb /** * Static instance of self + * * @var MysqliDb */ protected static $_instance; /** * Table prefix + * * @var string */ public static $prefix = ''; /** * MySQLi instances + * * @var mysqli[] */ protected $_mysqli = array(); /** * The SQL query to be prepared and executed + * * @var string */ protected $_query; /** * The previously executed SQL query + * * @var string */ protected $_lastQuery; /** * The SQL query options required after SELECT, INSERT, UPDATE or DELETE + * * @var array */ protected $_queryOptions = array(); /** * An array that holds where joins + * * @var array */ protected $_join = array(); /** * An array that holds where conditions + * * @var array */ protected $_where = array(); @@ -73,78 +81,91 @@ class MysqliDb /** * An array that holds having conditions + * * @var array */ protected $_having = array(); /** * Dynamic type list for order by condition value + * * @var array */ protected $_orderBy = array(); /** * Dynamic type list for group by condition value + * * @var array */ protected $_groupBy = array(); - - /** - * Dynamic type list for tempromary locking tables. - * @var array - */ + + /** + * Dynamic type list for temporary locking tables. + * + * @var array + */ protected $_tableLocks = array(); - - /** - * Variable which holds the current table lock method. - * @var string - */ + + /** + * Variable which holds the current table lock method. + * + * @var string + */ protected $_tableLockMethod = "READ"; - + /** * Dynamic array that holds a combination of where condition/table data value types and parameter references + * * @var array */ protected $_bindParams = array(''); // Create the empty 0 index /** * Variable which holds an amount of returned rows during get/getOne/select queries + * * @var string */ public $count = 0; /** * Variable which holds an amount of returned rows during get/getOne/select queries with withTotalCount() + * * @var string */ public $totalCount = 0; /** * Variable which holds last statement error + * * @var string */ protected $_stmtError; /** * Variable which holds last statement error code + * * @var int */ protected $_stmtErrno; /** * Is Subquery object + * * @var bool */ protected $isSubQuery = false; /** * Name of the auto increment column + * * @var int */ protected $_lastInsertId = null; /** * Column names for update when using onDuplicate method + * * @var array */ protected $_updateColumns = null; @@ -152,36 +173,42 @@ class MysqliDb /** * Return type: 'array' to return results as array, 'object' as object * 'json' as json string + * * @var string */ public $returnType = 'array'; /** * Should join() results be nested by table + * * @var bool */ protected $_nestJoin = false; /** * Table name (with prefix, if used) - * @var string + * + * @var string */ private $_tableName = ''; /** * FOR UPDATE flag + * * @var bool */ protected $_forUpdate = false; /** * LOCK IN SHARE MODE flag + * * @var bool */ protected $_lockInShareMode = false; /** * Key field for Map()'ed result array + * * @var string */ protected $_mapKey = null; @@ -230,7 +257,7 @@ class MysqliDb * @param string $username * @param string $password * @param string $db - * @param int $port + * @param int $port * @param string $charset * @param string $socket */ @@ -271,6 +298,7 @@ public function __construct($host = null, $username = null, $password = null, $d * A method to connect to the database * * @param null|string $connectionName + * * @throws Exception * @return void */ @@ -304,6 +332,9 @@ public function connect($connectionName = 'default') $this->_mysqli[$connectionName] = $mysqli; } + /** + * @throws Exception + */ public function disconnectAll() { foreach (array_keys($this->_mysqli) as $k) { @@ -313,7 +344,9 @@ public function disconnectAll() /** * Set the connection name to use in the next query + * * @param string $name + * * @return $this * @throws Exception */ @@ -330,7 +363,9 @@ public function connection($name) * A method to disconnect from the database * * @params string $connection connection name to disconnect - * @throws Exception + * + * @param string $connection + * * @return void */ public function disconnect($connection = 'default') @@ -344,8 +379,10 @@ public function disconnect($connection = 'default') /** * Create & store at _mysqli new mysqli instance + * * @param string $name - * @param array $params + * @param array $params + * * @return $this */ public function addConnection($name, array $params) @@ -368,8 +405,9 @@ public function addConnection($name, array $params) /** * A method to get mysqli object or create it in case needed - * + * * @return mysqli + * @throws Exception */ public function mysqli() { @@ -441,7 +479,7 @@ public function jsonBuilder() /** * Helper function to create dbObject with array return type - * Added for consistency as thats default output type + * Added for consistency as that's default output type * * @return MysqliDb */ @@ -465,8 +503,8 @@ public function objectBuilder() /** * Method to set a prefix * - * @param string $prefix Contains a tableprefix - * + * @param string $prefix Contains a table prefix + * * @return MysqliDb */ public function setPrefix($prefix = '') @@ -475,14 +513,18 @@ public function setPrefix($prefix = '') return $this; } - /** - * Pushes a unprepared statement to the mysqli stack. - * WARNING: Use with caution. - * This method does not escape strings by default so make sure you'll never use it in production. - * - * @author Jonas Barascu - * @param [[Type]] $query [[Description]] - */ + /** + * Pushes a unprepared statement to the mysqli stack. + * WARNING: Use with caution. + * This method does not escape strings by default so make sure you'll never use it in production. + * + * @author Jonas Barascu + * + * @param [[Type]] $query [[Description]] + * + * @return bool|mysqli_result + * @throws Exception + */ private function queryUnprepared($query) { // Execute query @@ -508,6 +550,7 @@ private function queryUnprepared($query) * @param array $bindParams Variables array to bind to the SQL statement. * * @return array Contains the returned rows from the query. + * @throws Exception */ public function rawQuery($query, $bindParams = null) { @@ -544,6 +587,7 @@ public function rawQuery($query, $bindParams = null) * @param array $bindParams Variables array to bind to the SQL statement. * * @return array|null Contains the returned row from the query. + * @throws Exception */ public function rawQueryOne($query, $bindParams = null) { @@ -564,6 +608,7 @@ public function rawQueryOne($query, $bindParams = null) * @param array $bindParams Variables array to bind to the SQL statement. * * @return mixed Contains the returned rows from the query. + * @throws Exception */ public function rawQueryValue($query, $bindParams = null) { @@ -587,11 +632,12 @@ public function rawQueryValue($query, $bindParams = null) /** * A method to perform select query - * - * @param string $query Contains a user-provided select query. + * + * @param string $query Contains a user-provided select query. * @param int|array $numRows Array to define SQL limit in format Array ($offset, $count) * * @return array Contains the returned rows from the query. + * @throws Exception */ public function query($query, $numRows = null) { @@ -611,8 +657,8 @@ public function query($query, $numRows = null) * * @uses $MySqliDb->setQueryOption('name'); * - * @param string|array $options The optons name of the query. - * + * @param string|array $options The options name of the query. + * * @throws Exception * @return MysqliDb */ @@ -650,6 +696,7 @@ public function setQueryOption($options) * Function to enable SQL_CALC_FOUND_ROWS in the get queries * * @return MysqliDb + * @throws Exception */ public function withTotalCount() { @@ -660,12 +707,13 @@ public function withTotalCount() /** * A convenient SELECT * function. * - * @param string $tableName The name of the database table to work with. - * @param int|array $numRows Array to define SQL limit in format Array ($offset, $count) + * @param string $tableName The name of the database table to work with. + * @param int|array $numRows Array to define SQL limit in format Array ($offset, $count) * or only $count - * @param string $columns Desired columns + * @param string $columns Desired columns * - * @return array Contains the returned rows from the select query. + * @return array|MysqliDb Contains the returned rows from the select query. + * @throws Exception */ public function get($tableName, $numRows = null, $columns = '*') { @@ -701,10 +749,11 @@ public function get($tableName, $numRows = null, $columns = '*') /** * A convenient SELECT * function to get one record. * - * @param string $tableName The name of the database table to work with. - * @param string $columns Desired columns - * + * @param string $tableName The name of the database table to work with. + * @param string $columns Desired columns + * * @return array Contains the returned rows from the select query. + * @throws Exception */ public function getOne($tableName, $columns = '*') { @@ -724,11 +773,12 @@ public function getOne($tableName, $columns = '*') /** * A convenient SELECT COLUMN function to get a single column value from one row * - * @param string $tableName The name of the database table to work with. - * @param string $column The desired column - * @param int $limit Limit of rows to select. Use null for unlimited..1 by default + * @param string $tableName The name of the database table to work with. + * @param string $column The desired column + * @param int $limit Limit of rows to select. Use null for unlimited..1 by default * * @return mixed Contains the value of a returned column / array of values + * @throws Exception */ public function getValue($tableName, $column, $limit = 1) { @@ -755,10 +805,11 @@ public function getValue($tableName, $column, $limit = 1) /** * Insert method to add new row * - * @param string $tableName The name of the table. - * @param array $insertData Data containing information for inserting into the DB. + * @param string $tableName The name of the table. + * @param array $insertData Data containing information for inserting into the DB. * - * @return bool Boolean indicating whether the insert query was completed succesfully. + * @return bool Boolean indicating whether the insert query was completed successfully. + * @throws Exception */ public function insert($tableName, $insertData) { @@ -768,11 +819,12 @@ public function insert($tableName, $insertData) /** * Insert method to add several rows at once * - * @param string $tableName The name of the table. - * @param array $multiInsertData Two-dimensinal Data-array containing information for inserting into the DB. - * @param array $dataKeys Optinal Table Key names, if not set in insertDataSet. + * @param string $tableName The name of the table. + * @param array $multiInsertData Two-dimensional Data-array containing information for inserting into the DB. + * @param array $dataKeys Optional Table Key names, if not set in insertDataSet. * * @return bool|array Boolean indicating the insertion failed (false), else return id-array ([int]) + * @throws Exception */ public function insertMulti($tableName, array $multiInsertData, array $dataKeys = null) { @@ -810,10 +862,11 @@ public function insertMulti($tableName, array $multiInsertData, array $dataKeys /** * Replace method to add new row * - * @param string $tableName The name of the table. - * @param array $insertData Data containing information for inserting into the DB. + * @param string $tableName The name of the table. + * @param array $insertData Data containing information for inserting into the DB. * - * @return bool Boolean indicating whether the insert query was completed succesfully. + * @return bool Boolean indicating whether the insert query was completed successfully. + * @throws Exception */ public function replace($tableName, $insertData) { @@ -824,9 +877,10 @@ public function replace($tableName, $insertData) * A convenient function that returns TRUE if exists at least an element that * satisfy the where condition specified calling the "where" method before this one. * - * @param string $tableName The name of the database table to work with. + * @param string $tableName The name of the database table to work with. * * @return bool + * @throws Exception */ public function has($tableName) { @@ -842,6 +896,7 @@ public function has($tableName) * @param int $numRows Limit on the number of rows that can be updated. * * @return bool + * @throws Exception */ public function update($tableName, $tableData, $numRows = null) { @@ -864,11 +919,12 @@ public function update($tableName, $tableData, $numRows = null) /** * Delete query. Call the "where" method first. * - * @param string $tableName The name of the database table to work with. - * @param int|array $numRows Array to define SQL limit in format Array ($offset, $count) + * @param string $tableName The name of the database table to work with. + * @param int|array $numRows Array to define SQL limit in format Array ($offset, $count) * or only $count * * @return bool Indicates success. 0 or 1. + * @throws Exception */ public function delete($tableName, $numRows = null) { @@ -900,8 +956,8 @@ public function delete($tableName, $numRows = null) * * @param string $whereProp The name of the database field. * @param mixed $whereValue The value of the database field. - * @param string $operator Comparison operator. Default is = - * @param string $cond Condition of where statement (OR, AND) + * @param string $operator Comparison operator. Default is = + * @param string $cond Condition of where statement (OR, AND) * * @return MysqliDb */ @@ -925,9 +981,9 @@ public function where($whereProp, $whereValue = 'DBNULL', $operator = '=', $cond * This function store update column's name and column name of the * autoincrement column * - * @param array $updateColumns Variable with values - * @param string $lastInsertId Variable value - * + * @param array $updateColumns Variable with values + * @param string $lastInsertId Variable value + * * @return MysqliDb */ public function onDuplicate($updateColumns, $lastInsertId = null) @@ -944,7 +1000,7 @@ public function onDuplicate($updateColumns, $lastInsertId = null) * * @param string $whereProp The name of the database field. * @param mixed $whereValue The value of the database field. - * @param string $operator Comparison operator. Default is = + * @param string $operator Comparison operator. Default is = * * @return MysqliDb */ @@ -952,7 +1008,7 @@ public function orWhere($whereProp, $whereValue = 'DBNULL', $operator = '=') { return $this->where($whereProp, $whereValue, $operator, 'OR'); } - + /** * This method allows you to specify multiple (method chaining optional) AND HAVING statements for SQL queries. * @@ -960,7 +1016,9 @@ public function orWhere($whereProp, $whereValue = 'DBNULL', $operator = '=') * * @param string $havingProp The name of the database field. * @param mixed $havingValue The value of the database field. - * @param string $operator Comparison operator. Default is = + * @param string $operator Comparison operator. Default is = + * + * @param string $cond * * @return MysqliDb */ @@ -988,7 +1046,7 @@ public function having($havingProp, $havingValue = 'DBNULL', $operator = '=', $c * * @param string $havingProp The name of the database field. * @param mixed $havingValue The value of the database field. - * @param string $operator Comparison operator. Default is = + * @param string $operator Comparison operator. Default is = * * @return MysqliDb */ @@ -1002,10 +1060,10 @@ public function orHaving($havingProp, $havingValue = null, $operator = null) * * @uses $MySqliDb->join('table1', 'field1 <> field2', 'LEFT') * - * @param string $joinTable The name of the table. + * @param string $joinTable The name of the table. * @param string $joinCondition the condition. - * @param string $joinType 'LEFT', 'INNER' etc. - * + * @param string $joinType 'LEFT', 'INNER' etc. + * * @throws Exception * @return MysqliDb */ @@ -1026,84 +1084,88 @@ public function join($joinTable, $joinCondition, $joinType = '') return $this; } - - - /** - * This is a basic method which allows you to import raw .CSV data into a table - * Please check out http://dev.mysql.com/doc/refman/5.7/en/load-data.html for a valid .csv file. - - * @author Jonas Barascu (Noneatme) - * @param string $importTable The database table where the data will be imported into. - * @param string $importFile The file to be imported. Please use double backslashes \\ and make sure you - * @param string $importSettings An Array defining the import settings as described in the README.md - * @return boolean - */ + + + /** + * This is a basic method which allows you to import raw .CSV data into a table + * Please check out http://dev.mysql.com/doc/refman/5.7/en/load-data.html for a valid .csv file. + * + * @author Jonas Barascu (Noneatme) + * + * @param string $importTable The database table where the data will be imported into. + * @param string $importFile The file to be imported. Please use double backslashes \\ and make sure you + * @param string $importSettings An Array defining the import settings as described in the README.md + * + * @return boolean + * @throws Exception + */ public function loadData($importTable, $importFile, $importSettings = null) - { + { // We have to check if the file exists - if(!file_exists($importFile)) { + if (!file_exists($importFile)) { // Throw an exception - throw new Exception("importCSV -> importFile ".$importFile." does not exists!"); - return; + throw new Exception("importCSV -> importFile " . $importFile . " does not exists!"); } - + // Define the default values // We will merge it later $settings = Array("fieldChar" => ';', "lineChar" => PHP_EOL, "linesToIgnore" => 1); - - // Check the import settings - if(gettype($importSettings) == "array") { + + // Check the import settings + if (gettype($importSettings) == "array") { // Merge the default array with the custom one $settings = array_merge($settings, $importSettings); } - + // Add the prefix to the import table $table = self::$prefix . $importTable; - + // Add 1 more slash to every slash so maria will interpret it as a path - $importFile = str_replace("\\", "\\\\", $importFile); - + $importFile = str_replace("\\", "\\\\", $importFile); + // Switch between LOAD DATA and LOAD DATA LOCAL $loadDataLocal = isset($settings["loadDataLocal"]) ? 'LOCAL' : ''; - + // Build SQL Syntax - $sqlSyntax = sprintf('LOAD DATA %s INFILE \'%s\' INTO TABLE %s', + $sqlSyntax = sprintf('LOAD DATA %s INFILE \'%s\' INTO TABLE %s', $loadDataLocal, $importFile, $table); - + // FIELDS $sqlSyntax .= sprintf(' FIELDS TERMINATED BY \'%s\'', $settings["fieldChar"]); - if(isset($settings["fieldEnclosure"])) { + if (isset($settings["fieldEnclosure"])) { $sqlSyntax .= sprintf(' ENCLOSED BY \'%s\'', $settings["fieldEnclosure"]); } - + // LINES $sqlSyntax .= sprintf(' LINES TERMINATED BY \'%s\'', $settings["lineChar"]); - if(isset($settings["lineStarting"])) { + if (isset($settings["lineStarting"])) { $sqlSyntax .= sprintf(' STARTING BY \'%s\'', $settings["lineStarting"]); } - + // IGNORE LINES $sqlSyntax .= sprintf(' IGNORE %d LINES', $settings["linesToIgnore"]); - - // Exceute the query unprepared because LOAD DATA only works with unprepared statements. + + // Execute the query unprepared because LOAD DATA only works with unprepared statements. $result = $this->queryUnprepared($sqlSyntax); // Are there rows modified? // Let the user know if the import failed / succeeded return (bool) $result; } - - /** - * This method is usefull for importing XML files into a specific table. - * Check out the LOAD XML syntax for your MySQL server. - * - * @author Jonas Barascu - * @param string $importTable The table in which the data will be imported to. - * @param string $importFile The file which contains the .XML data. - * @param string $importSettings An Array defining the import settings as described in the README.md - * - * @return boolean Returns true if the import succeeded, false if it failed. - */ + + /** + * This method is useful for importing XML files into a specific table. + * Check out the LOAD XML syntax for your MySQL server. + * + * @author Jonas Barascu + * + * @param string $importTable The table in which the data will be imported to. + * @param string $importFile The file which contains the .XML data. + * @param string $importSettings An Array defining the import settings as described in the README.md + * + * @return boolean Returns true if the import succeeded, false if it failed. + * @throws Exception + */ public function loadXml($importTable, $importFile, $importSettings = null) { // We have to check if the file exists @@ -1112,33 +1174,33 @@ public function loadXml($importTable, $importFile, $importSettings = null) throw new Exception("loadXml: Import file does not exists"); return; } - + // Create default values $settings = Array("linesToIgnore" => 0); - // Check the import settings + // Check the import settings if(gettype($importSettings) == "array") { $settings = array_merge($settings, $importSettings); } // Add the prefix to the import table $table = self::$prefix . $importTable; - + // Add 1 more slash to every slash so maria will interpret it as a path - $importFile = str_replace("\\", "\\\\", $importFile); - + $importFile = str_replace("\\", "\\\\", $importFile); + // Build SQL Syntax - $sqlSyntax = sprintf('LOAD XML INFILE \'%s\' INTO TABLE %s', + $sqlSyntax = sprintf('LOAD XML INFILE \'%s\' INTO TABLE %s', $importFile, $table); - + // FIELDS if(isset($settings["rowTag"])) { $sqlSyntax .= sprintf(' ROWS IDENTIFIED BY \'%s\'', $settings["rowTag"]); } - + // IGNORE LINES $sqlSyntax .= sprintf(' IGNORE %d LINES', $settings["linesToIgnore"]); - + // Exceute the query unprepared because LOAD XML only works with unprepared statements. $result = $this->queryUnprepared($sqlSyntax); @@ -1152,12 +1214,12 @@ public function loadXml($importTable, $importFile, $importSettings = null) * * @uses $MySqliDb->orderBy('id', 'desc')->orderBy('name', 'desc', '^[a-z]')->orderBy('name', 'desc'); * - * @param string $orderByField The name of the database field. - * @param string $orderByDirection Order direction. - * @param mixed $customFieldsOrRegExp Array with fieldset for ORDER BY FIELD() ordering or string with regular expresion for ORDER BY REGEXP ordering - * - * @throws Exception + * @param string $orderByField The name of the database field. + * @param string $orderbyDirection + * @param mixed $customFieldsOrRegExp Array with fieldset for ORDER BY FIELD() ordering or string with regular expression for ORDER BY REGEXP ordering + * * @return MysqliDb + * @throws Exception */ public function orderBy($orderByField, $orderbyDirection = "DESC", $customFieldsOrRegExp = null) { @@ -1206,17 +1268,18 @@ public function groupBy($groupByField) $this->_groupBy[] = $groupByField; return $this; } - - - /** - * This method sets the current table lock method. - * - * @author Jonas Barascu - * @param string $method The table lock method. Can be READ or WRITE. - * - * @throws Exception - * @return MysqliDb - */ + + + /** + * This method sets the current table lock method. + * + * @author Jonas Barascu + * + * @param string $method The table lock method. Can be READ or WRITE. + * + * @throws Exception + * @return MysqliDb + */ public function setLockMethod($method) { // Switch the uppercase string @@ -1233,21 +1296,22 @@ public function setLockMethod($method) } return $this; } - - /** - * Locks a table for R/W action. - * - * @author Jonas Barascu - * @param string $table The table to be locked. Can be a table or a view. - * - * @throws Exception - * @return MysqliDb if succeeeded; - */ + + /** + * Locks a table for R/W action. + * + * @author Jonas Barascu + * + * @param string|array $table The table to be locked. Can be a table or a view. + * + * @return bool if succeeded; + * @throws Exception + */ public function lock($table) { // Main Query $this->_query = "LOCK TABLES"; - + // Is the table an array? if(gettype($table) == "array") { // Loop trough it and attach it to the query @@ -1263,20 +1327,20 @@ public function lock($table) else{ // Build the table prefix $table = self::$prefix . $table; - + // Build the query $this->_query = "LOCK TABLES ".$table." ".$this->_tableLockMethod; } - // Exceute the query unprepared because LOCK only works with unprepared statements. + // Execute the query unprepared because LOCK only works with unprepared statements. $result = $this->queryUnprepared($this->_query); $errno = $this->mysqli()->errno; - + // Reset the query $this->reset(); // Are there rows modified? - if($result) { + if($result) { // Return true // We can't return ourself because if one table gets locked, all other ones get unlocked! return true; @@ -1289,20 +1353,21 @@ public function lock($table) // Return the success value return false; } - - /** - * Unlocks all tables in a database. - * Also commits transactions. - * - * @author Jonas Barascu - * @return MysqliDb - */ + + /** + * Unlocks all tables in a database. + * Also commits transactions. + * + * @author Jonas Barascu + * @return MysqliDb + * @throws Exception + */ public function unlock() { // Build the query $this->_query = "UNLOCK TABLES"; - // Exceute the query unprepared because UNLOCK and LOCK only works with unprepared statements. + // Execute the query unprepared because UNLOCK and LOCK only works with unprepared statements. $result = $this->queryUnprepared($this->_query); $errno = $this->mysqli()->errno; @@ -1318,17 +1383,18 @@ public function unlock() else { throw new Exception("Unlocking of tables failed", $errno); } - - + + // Return self return $this; } - + /** * This methods returns the ID of the last inserted item * * @return int The last inserted item ID. + * @throws Exception */ public function getInsertId() { @@ -1341,6 +1407,7 @@ public function getInsertId() * @param string $str The string to escape. * * @return string The escaped string. + * @throws Exception */ public function escape($str) { @@ -1354,6 +1421,7 @@ public function escape($str) * since _mysqli is protected. * * @return bool True if connection is up + * @throws Exception */ public function ping() { @@ -1423,8 +1491,8 @@ protected function _bindParams($values) * ' $operator ($subquery) ' formats * * @param string $operator - * @param mixed $value Variable with values - * + * @param mixed $value Variable with values + * * @return string */ protected function _buildPair($operator, $value) @@ -1443,11 +1511,12 @@ protected function _buildPair($operator, $value) /** * Internal function to build and execute INSERT/REPLACE calls * - * @param string $tableName The name of the table. - * @param array $insertData Data containing information for inserting into the DB. - * @param string $operation Type of operation (INSERT, REPLACE) + * @param string $tableName The name of the table. + * @param array $insertData Data containing information for inserting into the DB. + * @param string $operation Type of operation (INSERT, REPLACE) * - * @return bool Boolean indicating whether the insert query was completed succesfully. + * @return bool Boolean indicating whether the insert query was completed successfully. + * @throws Exception */ private function _buildInsert($tableName, $insertData, $operation) { @@ -1484,11 +1553,12 @@ private function _buildInsert($tableName, $insertData, $operation) * any passed update data, and the desired rows. * It then builds the SQL query. * - * @param int|array $numRows Array to define SQL limit in format Array ($offset, $count) + * @param int|array $numRows Array to define SQL limit in format Array ($offset, $count) * or only $count - * @param array $tableData Should contain an array of data for updating the database. + * @param array $tableData Should contain an array of data for updating the database. * - * @return mysqli_stmt Returns the $stmt object. + * @return mysqli_stmt|bool Returns the $stmt object. + * @throws Exception */ protected function _buildQuery($numRows = null, $tableData = null) { @@ -1501,7 +1571,7 @@ protected function _buildQuery($numRows = null, $tableData = null) $this->_buildOrderBy(); $this->_buildLimit($numRows); $this->_buildOnDuplicate($tableData); - + if ($this->_forUpdate) { $this->_query .= ' FOR UPDATE'; } @@ -1532,7 +1602,8 @@ protected function _buildQuery($numRows = null, $tableData = null) * * @param mysqli_stmt $stmt Equal to the prepared statement object. * - * @return array The results of the SQL fetch. + * @return array|string The results of the SQL fetch. + * @throws Exception */ protected function _dynamicBindResults(mysqli_stmt $stmt) { @@ -1638,7 +1709,7 @@ protected function _dynamicBindResults(mysqli_stmt $stmt) /** * Abstraction method that will build an JOIN part of the query - * + * * @return void */ protected function _buildJoinOld() @@ -1664,11 +1735,11 @@ protected function _buildJoinOld() /** * Insert/Update query helper - * + * * @param array $tableData * @param array $tableColumns - * @param bool $isInsert INSERT operation flag - * + * @param bool $isInsert INSERT operation flag + * * @throws Exception */ public function _buildDataPairs($tableData, $tableColumns, $isInsert) @@ -1728,6 +1799,8 @@ public function _buildDataPairs($tableData, $tableColumns, $isInsert) * Helper function to add variables into the query statement * * @param array $tableData Variable with values + * + * @throws Exception */ protected function _buildOnDuplicate($tableData) { @@ -1752,8 +1825,10 @@ protected function _buildOnDuplicate($tableData) /** * Abstraction method that will build an INSERT or UPDATE part of the query - * + * * @param array $tableData + * + * @throws Exception */ protected function _buildInsertQuery($tableData) { @@ -1780,9 +1855,9 @@ protected function _buildInsertQuery($tableData) /** * Abstraction method that will build the part of the WHERE conditions - * + * * @param string $operator - * @param array $conditions + * @param array $conditions */ protected function _buildCondition($operator, &$conditions) { @@ -1878,9 +1953,9 @@ protected function _buildOrderBy() /** * Abstraction method that will build the LIMIT part of the WHERE statement * - * @param int|array $numRows Array to define SQL limit in format Array ($offset, $count) + * @param int|array $numRows Array to define SQL limit in format Array ($offset, $count) * or only $count - * + * * @return void */ protected function _buildLimit($numRows) @@ -1918,7 +1993,7 @@ protected function _prepareQuery() $this->autoReconnectCount++; return $this->_prepareQuery(); } - + $error = $this->mysqli()->error; $query = $this->_query; $errno = $this->mysqli()->errno; @@ -1928,7 +2003,7 @@ protected function _prepareQuery() /** * Referenced data array is required by mysqli since PHP 5.3+ - * + * * @param array $arr * * @return array @@ -1950,9 +2025,9 @@ protected function refValues(array &$arr) /** * Function to replace ? with variables from bind variable - * + * * @param string $str - * @param array $vals + * @param array $vals * * @return string */ @@ -1994,6 +2069,7 @@ public function getLastQuery() * Method returns mysql error * * @return string + * @throws Exception */ public function getLastError() { @@ -2005,6 +2081,7 @@ public function getLastError() /** * Method returns mysql error code + * * @return int */ public function getLastErrno () { @@ -2031,16 +2108,16 @@ public function getSubQuery() $this->reset(); return $val; } - + /* Helper functions */ /** * Method returns generated interval function as a string * * @param string $diff interval in the formats: - * "1", "-1d" or "- 1 day" -- For interval - 1 day - * Supported intervals [s]econd, [m]inute, [h]hour, [d]day, [M]onth, [Y]ear - * Default null; + * "1", "-1d" or "- 1 day" -- For interval - 1 day + * Supported intervals [s]econd, [m]inute, [h]hour, [d]day, [M]onth, [Y]ear + * Default null; * @param string $func Initial date * * @return string @@ -2079,12 +2156,13 @@ public function interval($diff, $func = "NOW()") * Method returns generated interval function as an insert/update function * * @param string $diff interval in the formats: - * "1", "-1d" or "- 1 day" -- For interval - 1 day - * Supported intervals [s]econd, [m]inute, [h]hour, [d]day, [M]onth, [Y]ear - * Default null; + * "1", "-1d" or "- 1 day" -- For interval - 1 day + * Supported intervals [s]econd, [m]inute, [h]hour, [d]day, [M]onth, [Y]ear + * Default null; * @param string $func Initial date * * @return array + * @throws Exception */ public function now($diff = null, $func = "NOW()") { @@ -2093,9 +2171,9 @@ public function now($diff = null, $func = "NOW()") /** * Method generates incremental function call - * + * * @param int $num increment by int or float. 1 by default - * + * * @throws Exception * @return array */ @@ -2108,10 +2186,10 @@ public function inc($num = 1) } /** - * Method generates decrimental function call - * + * Method generates decremental function call + * * @param int $num increment by int or float. 1 by default - * + * * @return array * @throws Exception */ @@ -2125,22 +2203,22 @@ public function dec($num = 1) /** * Method generates change boolean function call - * + * * @param string $col column name. null by default - * + * * @return array */ public function not($col = null) { - return array("[N]" => (string) $col); + return array("[N]" => (string)$col); } /** * Method generates user defined function call - * + * * @param string $expr user function body - * @param array $bindParams - * + * @param array $bindParams + * * @return array */ public function func($expr, $bindParams = null) @@ -2150,9 +2228,9 @@ public function func($expr, $bindParams = null) /** * Method creates new mysqlidb object for a subquery generation - * + * * @param string $subQueryAlias - * + * * @return MysqliDb */ public static function subQuery($subQueryAlias = "") @@ -2177,6 +2255,7 @@ public function copy() * * @uses mysqli->autocommit(false) * @uses register_shutdown_function(array($this, "_transaction_shutdown_check")) + * @throws Exception */ public function startTransaction() { @@ -2190,6 +2269,7 @@ public function startTransaction() * * @uses mysqli->commit(); * @uses mysqli->autocommit(true); + * @throws Exception */ public function commit() { @@ -2204,6 +2284,7 @@ public function commit() * * @uses mysqli->rollback(); * @uses mysqli->autocommit(true); + * @throws Exception */ public function rollback() { @@ -2218,6 +2299,7 @@ public function rollback() * atomic operations sane. * * @uses mysqli->rollback(); + * @throws Exception */ public function _transaction_status_check() { @@ -2228,11 +2310,11 @@ public function _transaction_status_check() } /** - * Query exection time tracking switch + * Query execution time tracking switch * - * @param bool $enabled Enable execution time tracking + * @param bool $enabled Enable execution time tracking * @param string $stripPrefix Prefix to strip from the path in exec log - * + * * @return MysqliDb */ public function setTrace($enabled, $stripPrefix = null) @@ -2265,6 +2347,7 @@ private function _traceGetCaller() * @param array $tables Table name or an Array of table names to check * * @return bool True if table exists + * @throws Exception */ public function tableExists($tables) { @@ -2285,9 +2368,9 @@ public function tableExists($tables) /** * Return result as an associative array with $idField field value used as a record key - * + * * Array Returns an array($k => $v) if get(.."param1, param2"), array ($k => array ($v, $v)) otherwise - * + * * @param string $idField field name to use for a mapped element key * * @return MysqliDb @@ -2299,13 +2382,16 @@ public function map($idField) } /** - * Pagination wraper to get() + * Pagination wrapper to get() * * @access public - * @param string $table The name of the database table to work with - * @param int $page Page number + * + * @param string $table The name of the database table to work with + * @param int $page Page number * @param array|string $fields Array or coma separated list of fields to fetch + * * @return array + * @throws Exception */ public function paginate ($table, $page, $fields = null) { $offset = $this->pageLimit * ($page - 1); @@ -2323,6 +2409,9 @@ public function paginate ($table, $page, $fields = null) { * @param string $whereProp The name of the database field. * @param mixed $whereValue The value of the database field. * + * @param string $operator + * @param string $cond + * * @return $this */ public function joinWhere($whereJoin, $whereProp, $whereValue = 'DBNULL', $operator = '=', $cond = 'AND') @@ -2339,8 +2428,9 @@ public function joinWhere($whereJoin, $whereProp, $whereValue = 'DBNULL', $opera * @param string $whereJoin The name of the table followed by its prefix. * @param string $whereProp The name of the database field. * @param mixed $whereValue The value of the database field. + * @param string $operator * - * @return dbWrapper + * @return $this */ public function joinOrWhere($whereJoin, $whereProp, $whereValue = 'DBNULL', $operator = '=', $cond = 'AND') { @@ -2379,8 +2469,9 @@ protected function _buildJoin () { /** * Convert a condition and value into the sql string - * @param String $operator The where constraint operator - * @param String $val The where constraint value + * + * @param String $operator The where constraint operator + * @param String|array $val The where constraint value */ private function conditionToSql($operator, $val) { switch (strtolower ($operator)) {