Better PHPDoc (#746)

PHPDoc updated for some param/return/throws parts

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. 
+     * Dynamic type list for temporary locking tables.
+     *
      * @var array
      */
 	protected $_tableLocks = array();
 
     /**
      * 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
      */
     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;
@@ -271,6 +298,7 @@ class MysqliDb
      * A method to connect to the database
      *
      * @param null|string $connectionName
+     *
      * @throws Exception
      * @return void
      */
@@ -304,6 +332,9 @@ class MysqliDb
         $this->_mysqli[$connectionName] = $mysqli;
     }
 
+    /**
+     * @throws Exception
+     */
     public function disconnectAll()
     {
         foreach (array_keys($this->_mysqli) as $k) {
@@ -313,7 +344,9 @@ class MysqliDb
 
     /**
      * Set the connection name to use in the next query
+     *
      * @param string $name
+     *
      * @return $this
      * @throws Exception
      */
@@ -330,7 +363,9 @@ class MysqliDb
      * 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 @@ class MysqliDb
 
     /**
      * Create & store at _mysqli new mysqli instance
+     *
      * @param string $name
      * @param array  $params
+     *
      * @return $this
      */
     public function addConnection($name, array $params)
@@ -370,6 +407,7 @@ class MysqliDb
      * A method to get mysqli object or create it in case needed
      *
      * @return mysqli
+     * @throws Exception
      */
     public function mysqli()
     {
@@ -441,7 +479,7 @@ class MysqliDb
 
     /**
      * 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,7 +503,7 @@ class MysqliDb
     /**
      * Method to set a prefix
      *
-     * @param string $prefix     Contains a tableprefix
+     * @param string $prefix Contains a table prefix
      *
      * @return MysqliDb
      */
@@ -481,7 +519,11 @@ class MysqliDb
      * 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)
 	{
@@ -508,6 +550,7 @@ class MysqliDb
      * @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 @@ class MysqliDb
      * @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 @@ class MysqliDb
      * @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)
     {
@@ -592,6 +637,7 @@ class MysqliDb
      * @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,7 +657,7 @@ class MysqliDb
      *
      * @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 @@ class MysqliDb
      * Function to enable SQL_CALC_FOUND_ROWS in the get queries
      *
      * @return MysqliDb
+     * @throws Exception
      */
     public function withTotalCount()
     {
@@ -665,7 +712,8 @@ class MysqliDb
      *                               or only $count
      * @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 = '*')
     {
@@ -705,6 +753,7 @@ class MysqliDb
      * @param string $columns   Desired columns
      *
      * @return array Contains the returned rows from the select query.
+     * @throws Exception
      */
     public function getOne($tableName, $columns = '*')
     {
@@ -729,6 +778,7 @@ class MysqliDb
      * @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)
     {
@@ -758,7 +808,8 @@ class MysqliDb
      * @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)
     {
@@ -769,10 +820,11 @@ class MysqliDb
      * 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 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)
     {
@@ -813,7 +865,8 @@ class MysqliDb
      * @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)
     {
@@ -827,6 +880,7 @@ class MysqliDb
      * @param string $tableName The name of the database table to work with.
      *
      * @return bool
+     * @throws Exception
      */
     public function has($tableName)
     {
@@ -842,6 +896,7 @@ class MysqliDb
      * @param int    $numRows   Limit on the number of rows that can be updated.
      *
      * @return bool
+     * @throws Exception
      */
     public function update($tableName, $tableData, $numRows = null)
     {
@@ -869,6 +924,7 @@ class MysqliDb
      *                               or only $count
      *
      * @return bool Indicates success. 0 or 1.
+     * @throws Exception
      */
     public function delete($tableName, $numRows = null)
     {
@@ -963,6 +1019,8 @@ class MysqliDb
      * @param mixed  $havingValue The value of the database field.
      * @param string $operator    Comparison operator. Default is =
      *
+     * @param string $cond
+     *
      * @return MysqliDb
      */
 
@@ -1032,20 +1090,22 @@ class MysqliDb
     /**
      * 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
@@ -1053,7 +1113,7 @@ class MysqliDb
 		$settings = Array("fieldChar" => ';', "lineChar" => PHP_EOL, "linesToIgnore" => 1);
 
 		// Check the import settings
-		if(gettype($importSettings) == "array") {
+		if (gettype($importSettings) == "array") {
 			// Merge the default array with the custom one
 			$settings = array_merge($settings, $importSettings);
 		}
@@ -1073,20 +1133,20 @@ class MysqliDb
 
 		// 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?
@@ -1095,15 +1155,17 @@ class MysqliDb
 	}
 
     /**
-	 * This method is usefull for importing XML files into a specific table.
+     * 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)
 	{
@@ -1154,11 +1216,11 @@ class MysqliDb
      * @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
+     * @param string $orderbyDirection
+     * @param mixed  $customFieldsOrRegExp Array with fieldset for ORDER BY FIELD() ordering or string with regular expression for ORDER BY REGEXP ordering
      *
-     * @throws Exception
      * @return MysqliDb
+     * @throws Exception
      */
     public function orderBy($orderByField, $orderbyDirection = "DESC", $customFieldsOrRegExp = null)
     {
@@ -1213,6 +1275,7 @@ class 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
@@ -1239,10 +1302,11 @@ class MysqliDb
      * 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.
      *
+     * @param string|array $table The table to be locked. Can be a table or a view.
+     *
+     * @return bool if succeeded;
      * @throws Exception
-	 * @return MysqliDb if succeeeded;
      */
 	public function lock($table)
 	{
@@ -1269,7 +1333,7 @@ class MysqliDb
 			$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;
 
@@ -1297,13 +1361,14 @@ class MysqliDb
      *
      * @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;
 
@@ -1330,6 +1395,7 @@ class MysqliDb
      * This methods returns the ID of the last inserted item
      *
      * @return int The last inserted item ID.
+     * @throws Exception
      */
     public function getInsertId()
     {
@@ -1342,6 +1408,7 @@ class MysqliDb
      * @param string $str The string to escape.
      *
      * @return string The escaped string.
+     * @throws Exception
      */
     public function escape($str)
     {
@@ -1355,6 +1422,7 @@ class MysqliDb
      * since _mysqli is protected.
      *
      * @return bool True if connection is up
+     * @throws Exception
      */
     public function ping()
     {
@@ -1448,7 +1516,8 @@ class MysqliDb
      * @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)
     {
@@ -1489,7 +1558,8 @@ class MysqliDb
      *                               or only $count
      * @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)
     {
@@ -1533,7 +1603,8 @@ class MysqliDb
      *
      * @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)
     {
@@ -1729,6 +1800,8 @@ class MysqliDb
      * Helper function to add variables into the query statement
      *
      * @param array $tableData Variable with values
+     *
+     * @throws Exception
      */
     protected function _buildOnDuplicate($tableData)
     {
@@ -1755,6 +1828,8 @@ class MysqliDb
      * Abstraction method that will build an INSERT or UPDATE part of the query
      *
      * @param array $tableData
+     *
+     * @throws Exception
      */
     protected function _buildInsertQuery($tableData)
     {
@@ -1995,6 +2070,7 @@ class MysqliDb
      * Method returns mysql error
      *
      * @return string
+     * @throws Exception
      */
     public function getLastError()
     {
@@ -2006,6 +2082,7 @@ class MysqliDb
 
     /**
      * Method returns mysql error code
+     *
      * @return int
      */
     public function getLastErrno () {
@@ -2086,6 +2163,7 @@ class MysqliDb
      * @param string $func Initial date
      *
      * @return array
+     * @throws Exception
      */
     public function now($diff = null, $func = "NOW()")
     {
@@ -2109,7 +2187,7 @@ class MysqliDb
     }
 
     /**
-     * Method generates decrimental function call
+     * Method generates decremental function call
      *
      * @param int $num increment by int or float. 1 by default
      *
@@ -2133,7 +2211,7 @@ class MysqliDb
      */
     public function not($col = null)
     {
-        return array("[N]" => (string) $col);
+        return array("[N]" => (string)$col);
     }
 
     /**
@@ -2178,6 +2256,7 @@ class MysqliDb
      *
      * @uses mysqli->autocommit(false)
      * @uses register_shutdown_function(array($this, "_transaction_shutdown_check"))
+     * @throws Exception
      */
     public function startTransaction()
     {
@@ -2191,6 +2270,7 @@ class MysqliDb
      *
      * @uses mysqli->commit();
      * @uses mysqli->autocommit(true);
+     * @throws Exception
      */
     public function commit()
     {
@@ -2205,6 +2285,7 @@ class MysqliDb
      *
      * @uses mysqli->rollback();
      * @uses mysqli->autocommit(true);
+     * @throws Exception
      */
     public function rollback()
     {
@@ -2219,6 +2300,7 @@ class MysqliDb
      * atomic operations sane.
      *
      * @uses mysqli->rollback();
+     * @throws Exception
      */
     public function _transaction_status_check()
     {
@@ -2229,7 +2311,7 @@ class MysqliDb
     }
 
     /**
-     * Query exection time tracking switch
+     * Query execution time tracking switch
      *
      * @param bool   $enabled     Enable execution time tracking
      * @param string $stripPrefix Prefix to strip from the path in exec log
@@ -2266,6 +2348,7 @@ class MysqliDb
      * @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)
     {
@@ -2300,13 +2383,16 @@ class MysqliDb
     }
 
     /**
-     * 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 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);
@@ -2324,6 +2410,9 @@ class MysqliDb
      * @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')
@@ -2340,8 +2429,9 @@ class MysqliDb
      * @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')
     {
@@ -2380,8 +2470,9 @@ class MysqliDb
 
     /**
      * 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|array $val      The where constraint value
      */
     private function conditionToSql($operator, $val) {
         switch (strtolower ($operator)) {