Skip to content

P
PHP-MySQLi-Database-Class
Commit dc1bf98e authored by Can Arslan's avatar Can Arslan Committed by Alexander Butenko
Browse files
Options

Better PHPDoc (#746) 

PHPDoc updated for some param/return/throws parts
parent bc561ccc
Show whitespace changes
Inline Side-by-side
Showing with 308 additions and 217 deletions
MysqliDb.php
View file @ dc1bf98e
......@@ -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)) {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

Technounit-GROUP 2023