CoreLibs/development
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

DB\IO phpdoc layout update

Browse Source 
Add line between params and method description
This commit is contained in:
Clemens Schwaighofer
2023-06-09 10:21:02 +09:00
parent ec3ca787fa
commit ec4bf54d81
1 changed files with 53 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
www/lib/CoreLibs/DB/IO.php
View File

@@ -525,8 +525,10 @@ class IO
} }
/** /**
* internal connection function. Used to connect to the DB if there is no connection done yet. * internal connection function.
* Used to connect to the DB if there is no connection done yet.
* Called before any execute * Called before any execute
*
* @return bool true on successfull connect, false if failed * @return bool true on successfull connect, false if failed
*/ */
private function __connectToDB(): bool private function __connectToDB(): bool
@@ -571,6 +573,7 @@ class IO
/** /**
* close db connection * close db connection
* only used by the deconstructor * only used by the deconstructor
*
* @return void has no return * @return void has no return
*/ */
private function __closeDB(): void private function __closeDB(): void
@@ -585,6 +588,7 @@ class IO
* checks if query is a SELECT, SHOW or WITH, if not error, 0 return * checks if query is a SELECT, SHOW or WITH, if not error, 0 return
* NOTE: * NOTE:
* Query needs to start with SELECT, SHOW or WITH * Query needs to start with SELECT, SHOW or WITH
*
* @param string $query query to check * @param string $query query to check
* @return bool true if matching, false if not * @return bool true if matching, false if not
*/ */
@@ -602,6 +606,7 @@ class IO
* if pure is set to true, only when INSERT is set will return true * if pure is set to true, only when INSERT is set will return true
* NOTE: * NOTE:
* Queries need to start with INSERT, UPDATE, DELETE. Anything else is ignored * Queries need to start with INSERT, UPDATE, DELETE. Anything else is ignored
*
* @param string $query query to check * @param string $query query to check
* @param bool $pure pure check (only insert), default false * @param bool $pure pure check (only insert), default false
* @return bool true if matching, false if not * @return bool true if matching, false if not
@@ -620,6 +625,7 @@ class IO
/** /**
* returns true if the query starts with UPDATE * returns true if the query starts with UPDATE
* query NEEDS to start with UPDATE * query NEEDS to start with UPDATE
*
* @param string $query query to check * @param string $query query to check
* @return bool returns true if the query starts with UPDATE * @return bool returns true if the query starts with UPDATE
*/ */
@@ -635,6 +641,7 @@ class IO
* internal funktion that creates the array * internal funktion that creates the array
* NOTE: * NOTE:
* used in db_dump_data only * used in db_dump_data only
*
* @param array<mixed> $array array to print * @param array<mixed> $array array to print
* @return string string with printed and formated array * @return string string with printed and formated array
*/ */
@@ -740,6 +747,7 @@ class IO
* Is called on base queries to reset error before each run * Is called on base queries to reset error before each run
* Recent error history can be checked with * Recent error history can be checked with
* dbGetErrorHistory or dbGetWarningHistory * dbGetErrorHistory or dbGetWarningHistory
*
* @return void * @return void
*/ */
private function __dbErrorReset(): void private function __dbErrorReset(): void
@@ -751,6 +759,7 @@ class IO
/** /**
* Check if there is a cursor and write this cursors error info * Check if there is a cursor and write this cursors error info
*
* @param \PgSql\Result|false $cursor current cursor for pg_result_error, * @param \PgSql\Result|false $cursor current cursor for pg_result_error,
* pg_last_error too, but pg_result_error * pg_last_error too, but pg_result_error
* is more accurate (PgSql\Result) * is more accurate (PgSql\Result)
@@ -811,6 +820,7 @@ class IO
* error level, source as :: separated string * error level, source as :: separated string
* additional pg error message if exists and optional msg given on error call * additional pg error message if exists and optional msg given on error call
* all error messages are grouped by error_history_id set when errors are reset * all error messages are grouped by error_history_id set when errors are reset
*
* @param string $level * @param string $level
* @param string $error_id * @param string $error_id
* @param string $where_called * @param string $where_called
@@ -841,6 +851,7 @@ class IO
/** /**
* write an error * write an error
*
* @param integer $error_id Any Error ID, used in debug message string * @param integer $error_id Any Error ID, used in debug message string
* @param \PgSql\Result|false $cursor Optional cursor, passed on to preprocessor * @param \PgSql\Result|false $cursor Optional cursor, passed on to preprocessor
* @param string $msg optional message added to debug * @param string $msg optional message added to debug
@@ -868,6 +879,7 @@ class IO
/** /**
* write a warning * write a warning
*
* @param integer $warning_id Integer warning id added to debug * @param integer $warning_id Integer warning id added to debug
* @param \PgSql\Result|false $cursor Optional cursor, passed on to preprocessor * @param \PgSql\Result|false $cursor Optional cursor, passed on to preprocessor
* @param string $msg optional message added to debug * @param string $msg optional message added to debug
@@ -895,6 +907,7 @@ class IO
/** /**
* if there is the 'to_encoding' var set, * if there is the 'to_encoding' var set,
* and the field is in the wrong encoding converts it to the target * and the field is in the wrong encoding converts it to the target
*
* @param array<mixed>|false $row Array from fetch_row * @param array<mixed>|false $row Array from fetch_row
* @return array<mixed>|false Convert fetch_row array, or false * @return array<mixed>|false Convert fetch_row array, or false
*/ */
@@ -931,6 +944,7 @@ class IO
/** /**
* for debug purpose replaces $1, $2, etc with actual data * for debug purpose replaces $1, $2, etc with actual data
*
* @param string $query Query to replace values in * @param string $query Query to replace values in
* @param array<mixed> $data The data array * @param array<mixed> $data The data array
* @return string string of query with data inside * @return string string of query with data inside
@@ -964,7 +978,9 @@ class IO
} }
/** /**
* extracts schema and table from the query, if no schema returns just empty string * extracts schema and table from the query,
* if no schema returns just empty string
*
* @param string $query insert/select/update/delete query * @param string $query insert/select/update/delete query
* @return array<mixed> array with schema and table * @return array<mixed> array with schema and table
*/ */
@@ -1003,6 +1019,7 @@ class IO
/** /**
* check if there is another query running, or do we hang after a * check if there is another query running, or do we hang after a
* PHP error * PHP error
*
* @param integer $timeout_seconds For complex timeout waits, default 3 seconds * @param integer $timeout_seconds For complex timeout waits, default 3 seconds
* @return bool True for connection OK, else false * @return bool True for connection OK, else false
*/ */
@@ -1021,6 +1038,7 @@ class IO
/** /**
* dbReturn * dbReturn
* Read data from previous written data cache * Read data from previous written data cache
*
* @param string $query_hash The hash for the current query * @param string $query_hash The hash for the current query
* @param bool $assoc_only Only return assoc value (key named) * @param bool $assoc_only Only return assoc value (key named)
* @return array<mixed> Current position query data from cache * @return array<mixed> Current position query data from cache
@@ -1099,6 +1117,7 @@ class IO
* - checks for insert if returning is set/pk name * - checks for insert if returning is set/pk name
* - sets internal hash for query * - sets internal hash for query
* - checks multiple call count * - checks multiple call count
*
* @param string $query Query string * @param string $query Query string
* @param array<mixed> $params Query params, needed for hash creation * @param array<mixed> $params Query params, needed for hash creation
* @param string $pk_name primary key * @param string $pk_name primary key
@@ -1292,6 +1311,7 @@ class IO
* insert_id_ext [DEPRECATED, all in insert_id_arr] * insert_id_ext [DEPRECATED, all in insert_id_arr]
* - holds all returning as array * - holds all returning as array
* TODO: Only use insert_id_arr and use functions to get ok array or single * TODO: Only use insert_id_arr and use functions to get ok array or single
*
* @param bool $returning_id * @param bool $returning_id
* @param string $query * @param string $query
* @param string|null $pk_name * @param string|null $pk_name
@@ -1384,6 +1404,7 @@ class IO
* closes the db_connection * closes the db_connection
* normally this is not used, as the class deconstructor closes * normally this is not used, as the class deconstructor closes
* the connection down * the connection down
*
* @return void has no return * @return void has no return
*/ */
public function dbClose(): void public function dbClose(): void
@@ -1405,6 +1426,7 @@ class IO
* returns the db init error * returns the db init error
* if failed to connect it is set to false * if failed to connect it is set to false
* else true * else true
*
* @return bool Connection status * @return bool Connection status
*/ */
public function dbGetConnectionStatus(): bool public function dbGetConnectionStatus(): bool
@@ -1414,6 +1436,7 @@ class IO
/** /**
* get certain settings like username, db name * get certain settings like username, db name
*
* @param string $name what setting to query * @param string $name what setting to query
* @return int|string|bool setting value, if not allowed name return false * @return int|string|bool setting value, if not allowed name return false
*/ */
@@ -1458,6 +1481,7 @@ class IO
/** /**
* prints out status info from the connected DB (might be usefull for debug stuff) * prints out status info from the connected DB (might be usefull for debug stuff)
*
* @param bool $log Show db connection info, default true * @param bool $log Show db connection info, default true
* if set to false won't write to error_msg var * if set to false won't write to error_msg var
* @param bool $strip Strip all HTML * @param bool $strip Strip all HTML
@@ -1497,6 +1521,7 @@ class IO
/** /**
* Server version as integer value * Server version as integer value
*
* @return integer Version as integer * @return integer Version as integer
*/ */
public function dbVersionNumeric(): int public function dbVersionNumeric(): int
@@ -1506,6 +1531,7 @@ class IO
/** /**
* return current database version (server side) as string * return current database version (server side) as string
*
* @return string database version as string * @return string database version as string
*/ */
public function dbVersion(): string public function dbVersion(): string
@@ -1515,6 +1541,7 @@ class IO
/** /**
* extended version info, can access all additional information data * extended version info, can access all additional information data
*
* @param string $parameter Array parameter name, if not valid returns * @param string $parameter Array parameter name, if not valid returns
* empty string * empty string
* @param bool $strip Strip extended server info string, default true * @param bool $strip Strip extended server info string, default true
@@ -1528,6 +1555,7 @@ class IO
/** /**
* All possible parameter names for dbVersionInfo * All possible parameter names for dbVersionInfo
*
* @return array<mixed> List of all parameter names * @return array<mixed> List of all parameter names
*/ */
public function dbVersionInfoParameters(): array public function dbVersionInfoParameters(): array
@@ -1537,6 +1565,7 @@ class IO
/** /**
* returns bool true or false if the string matches the database version * returns bool true or false if the string matches the database version
*
* @param string $compare string to match in type =X.Y, >X.Y, <X.Y, <=X.Y, >=X.Y * @param string $compare string to match in type =X.Y, >X.Y, <X.Y, <=X.Y, >=X.Y
* @return bool true for ok, false on not ok * @return bool true for ok, false on not ok
*/ */
@@ -1605,6 +1634,7 @@ class IO
/** /**
* dumps ALL data for this query, OR if no query given all in cursor_ext array * dumps ALL data for this query, OR if no query given all in cursor_ext array
*
* @param string $query Query, if given, only from this quey (if found) * @param string $query Query, if given, only from this quey (if found)
* else current cursor * else current cursor
* @return string Formated string with all the data in the array * @return string Formated string with all the data in the array
@@ -1632,6 +1662,7 @@ class IO
/** /**
* neutral function to escape a string for DB writing * neutral function to escape a string for DB writing
*
* @param string|int|float|bool $string string to escape * @param string|int|float|bool $string string to escape
* @return string escaped string * @return string escaped string
*/ */
@@ -1643,6 +1674,7 @@ class IO
/** /**
* neutral function to escape a string for DB writing * neutral function to escape a string for DB writing
* this one adds '' quotes around the string * this one adds '' quotes around the string
*
* @param string|int|float|bool $string string to escape * @param string|int|float|bool $string string to escape
* @return string escaped string * @return string escaped string
*/ */
@@ -1653,6 +1685,7 @@ class IO
/** /**
* string escape for column and table names * string escape for column and table names
*
* @param string $string string to escape * @param string $string string to escape
* @return string escaped string * @return string escaped string
*/ */
@@ -1663,6 +1696,7 @@ class IO
/** /**
* escape data for writing to bytea type column field * escape data for writing to bytea type column field
*
* @param string $data data to escape to bytea * @param string $data data to escape to bytea
* @return string escaped bytea string * @return string escaped bytea string
*/ */
@@ -1673,6 +1707,7 @@ class IO
/** /**
* unescape bytea data back to normal binrary data * unescape bytea data back to normal binrary data
*
* @param string $bytea bytea data stream * @param string $bytea bytea data stream
* @return string binary data string * @return string binary data string
*/ */
@@ -1683,6 +1718,7 @@ class IO
/** /**
* clear up any data for valid DB insert * clear up any data for valid DB insert
*
* @param int|float|string|bool|null $value to escape data * @param int|float|string|bool|null $value to escape data
* @param string $kbn escape trigger type * @param string $kbn escape trigger type
* @return string escaped value * @return string escaped value
@@ -1749,6 +1785,7 @@ class IO
* if the input is a single char 't' or 'f * if the input is a single char 't' or 'f
* it will return the bool value instead * it will return the bool value instead
* also converts smallint 1/0 to true false * also converts smallint 1/0 to true false
*
* @param string|bool|int $string 't' / 'f' or any string, or bool true/false * @param string|bool|int $string 't' / 'f' or any string, or bool true/false
* @param bool $rev do reverse (bool to string) * @param bool $rev do reverse (bool to string)
* @return bool|string correct php bool true/false * @return bool|string correct php bool true/false
@@ -1784,6 +1821,7 @@ class IO
/** /**
* only for postgres. pretty formats an age or datetime difference string * only for postgres. pretty formats an age or datetime difference string
*
* @param string $interval Age or interval/datetime difference * @param string $interval Age or interval/datetime difference
* @param bool $show_micro micro on off (default false) * @param bool $show_micro micro on off (default false)
* @return string Y/M/D/h/m/s formatted string (like timeStringFormat) * @return string Y/M/D/h/m/s formatted string (like timeStringFormat)
@@ -1835,6 +1873,7 @@ class IO
/** /**
* this is only needed for Postgresql. Converts postgresql arrays to PHP * this is only needed for Postgresql. Converts postgresql arrays to PHP
* Recommended to rather user 'array_to_json' instead and convet JSON in PHP * Recommended to rather user 'array_to_json' instead and convet JSON in PHP
*
* @param string $text input text to parse to an array * @param string $text input text to parse to an array
* @return array<mixed> PHP array of the parsed data * @return array<mixed> PHP array of the parsed data
* @deprecated Recommended to use 'array_to_json' in PostgreSQL instead * @deprecated Recommended to use 'array_to_json' in PostgreSQL instead
@@ -1851,6 +1890,7 @@ class IO
/** /**
* returns an array of the table with columns and values. FALSE on no table found * returns an array of the table with columns and values. FALSE on no table found
*
* @param string $table table name * @param string $table table name
* @param string $schema optional schema name * @param string $schema optional schema name
* @return array<mixed>|false array of table data, false on error (table not found) * @return array<mixed>|false array of table data, false on error (table not found)
@@ -2238,6 +2278,7 @@ class IO
* for INSERT INTO queries it is highly recommended to set the pk_name to avoid an * for INSERT INTO queries it is highly recommended to set the pk_name to avoid an
* additional read from the database for the PK NAME * additional read from the database for the PK NAME
* Wrapper for dbExecParams without params * Wrapper for dbExecParams without params
*
* @param string $query the query, if not given, * @param string $query the query, if not given,
* the query class var will be used * the query class var will be used
* if this was not set, method will quit with false * if this was not set, method will quit with false
@@ -2307,10 +2348,9 @@ class IO
} }
} }
// add adbExecParams(string $query = '', array $params = [], string $pk_name = ')
/** /**
* executes a cursor and returns the data, if no more data 0 will be returned * executes a cursor and returns the data, if no more data 0 will be returned
*
* @param \PgSql\Result|false $cursor the cursor from db_exec or * @param \PgSql\Result|false $cursor the cursor from db_exec or
* pg_query/pg_exec/mysql_query * pg_query/pg_exec/mysql_query
* if not set will use internal cursor, * if not set will use internal cursor,
@@ -2343,6 +2383,7 @@ class IO
/** /**
* returns the FIRST row of the given query * returns the FIRST row of the given query
* wrapper for dbReturnRowParms * wrapper for dbReturnRowParms
*
* @param string $query the query to be executed * @param string $query the query to be executed
* @param bool $assoc_only if true, only return assoc entry (default false) * @param bool $assoc_only if true, only return assoc entry (default false)
* @return array<mixed>|false row array or false on error * @return array<mixed>|false row array or false on error
@@ -2388,6 +2429,7 @@ class IO
/** /**
* creates an array of hashes of the query (all data) * creates an array of hashes of the query (all data)
* Wrapper for dbReturnArrayParams * Wrapper for dbReturnArrayParams
*
* @param string $query the query to be executed * @param string $query the query to be executed
* @param bool $assoc_only if true, only name ref are returned (default true) * @param bool $assoc_only if true, only name ref are returned (default true)
* @return array<mixed>|false array of hashes (row -> fields), false on error * @return array<mixed>|false array of hashes (row -> fields), false on error
@@ -2557,6 +2599,7 @@ class IO
/** /**
* gets how often a query was called already * gets how often a query was called already
*
* @param string $query query string * @param string $query query string
* @param array<mixed> $params If the query is params type we need params * @param array<mixed> $params If the query is params type we need params
* data to create a unique call one, optional * data to create a unique call one, optional
@@ -2581,6 +2624,7 @@ class IO
* for INSERT INTO queries it is highly recommended * for INSERT INTO queries it is highly recommended
* to set the pk_name to avoid an additional * to set the pk_name to avoid an additional
* read from the database for the PK NAME * read from the database for the PK NAME
*
* @param string $stm_name statement name * @param string $stm_name statement name
* @param string $query queryt string to run * @param string $query queryt string to run
* @param string $pk_name optional primary key * @param string $pk_name optional primary key
@@ -2693,6 +2737,7 @@ class IO
/** /**
* runs a prepare query * runs a prepare query
*
* @param string $stm_name statement name for the query to run * @param string $stm_name statement name for the query to run
* @param array<mixed> $data data to run for this query, empty array for none * @param array<mixed> $data data to run for this query, empty array for none
* @return \PgSql\Result|false false on error, or result on OK * @return \PgSql\Result|false false on error, or result on OK
@@ -2791,6 +2836,7 @@ class IO
* executes the query async so other methods can be run at the same time * executes the query async so other methods can be run at the same time
* Wrapper for dbExecParamsAsync * Wrapper for dbExecParamsAsync
* NEEDS : dbCheckAsync * NEEDS : dbCheckAsync
*
* @param string $query query to run * @param string $query query to run
* @param string $pk_name optional primary key name, only used with * @param string $pk_name optional primary key name, only used with
* insert for returning call * insert for returning call
@@ -2890,6 +2936,7 @@ class IO
/** /**
* checks a previous async query and returns data if finished * checks a previous async query and returns data if finished
* NEEDS : dbExecAsync * NEEDS : dbExecAsync
*
* @return \PgSql\Result|bool cursor resource if the query is still running, * @return \PgSql\Result|bool cursor resource if the query is still running,
* false if an error occured or cursor of that query * false if an error occured or cursor of that query
*/ */
@@ -2930,6 +2977,7 @@ class IO
/** /**
* Returns the current async running query hash * Returns the current async running query hash
*
* @return string Current async running query hash * @return string Current async running query hash
*/ */
public function dbGetAsyncRunning(): string public function dbGetAsyncRunning(): string
@@ -2948,6 +2996,7 @@ class IO
/** /**
* writes into one table based on array of table columns * writes into one table based on array of table columns
*
* @param array<mixed> $write_array list of elements to write * @param array<mixed> $write_array list of elements to write
* @param array<mixed> $not_write_array list of elements not to write * @param array<mixed> $not_write_array list of elements not to write
* @param int $primary_key id key to decide if we write insert or update * @param int $primary_key id key to decide if we write insert or update