Documentation for class PbDb



/**
 *  @package:   bpl - brain pies library
 * 	class		BpDb
 * 
 *  @author:    BrainPies Team
 *  @copyright: BrainPies Team
 *  @link:		https://brainpies.com
 * 
 *  @license:   GNU/GPL v.3.0 or any later version
 *  @link:		https://www.gnu.org/licenses/gpl-3.0.html GNU/GPL
 * 
 *  @version:   1.0.0
 * 
 * 
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the Free
 * Software Foundation; either version 3 of the License, or (at your option)
 * any later version.

 * This program is distributed 'as is', in the hope that it will be useful, 
 * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
 * more details.

 * You should have received a copy of the GNU General Public License along
 * with this program (COPYING); if not, go to http://www.fsf.org/ or write
 * to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

	/**
	 * @method	count
	 * Method to get rows count.
	 *
	 * @param   string	$table		mandatory	Table to be inspected.
	 * @param   array	$where		mandatory	where clause 'key'=>'value' pairs
	 * @param	array	$extra		optional	array with extraordinary select option
	 *
	 * @return	integer  Contains the number of selected rows.
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	dbTry
	 * Method to execute the query in a safe mode
	 *
	 * @param   object	$db			mandatory	database object
	 * @param	object	$query		mandatory	query object
	 * @param	array	$extra		mandatory	function to perform
	 *
	 * @return	object  query execution result
	 *
	 * @since	1.0.0
	 * 
	 * @example	dbTry($db, $query, array('function'=>'loadObjectList'))
	 */

	/**
	 * @method	delete
	 * Method to execute a delete query.
	 *
	 * @param   string	$table		mandatory			Table to be inspected
	 * @param   mixed	$where		mandatory			array or object - Field to be checked
	 * @param	array	$extra		optional			optional data
	 * 
	 * @return	int | bool			number of affected rows on success, false if fails.
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	getDb
	 * Method to get db instance
	 *
	 * @return	object	db instance
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	getDbFuncs
	 * Method to get the db class supported functions
	 *
	 * @return	array
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	getDbPrefix
	 * Method to get db prefix
	 *
	 * @return	string
	 * 
	 * @uses	class Bp
	 *
	 * @since	1.0.0
	 * 
	 * @example	if my component name is com_mycomponent return: "#__mycomponent_"
	 */

	/**
	 * @method	getInstance
	 * Method to get database table instance
	 * 
	 * @param	string	$table	mandatory 	table name
	 * @param	array	$params	optional	table params
	 * 											'table_prefix' 	=> 'JTable'
	 * 											'component'		=> 'componentname'
	 * 											'db'			=> $db
	 * 
	 * @uses	class Bp
	 * 
	 * @access	private	
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	getJtablePrefix
	 * Method to get table class prefix
	 *
	 * @return	string
	 *
	 * @uses	class	Bp

	 * @since	1.0.0
	 * 
	 * @example	if my component name is com_mycomponent return "mycomponentTable"
	 */

	/**
	 * @method	getList
	 * Method to select a rows list from db.
	 *
	 * @param   mixed	$table		mandatory		Table of current component to be inspected (string) 
	 * 													or array with 'dbprefix' => '#__' and 'dbtable' => 'mycomponent_tablename'
	 * @param   mixed	$where		mandatory		where clause - array or string
	 * @param	array	$extra		optional		array containg join / where clause / order dir etc.
	 *
	 * @return	array | null						Contains the array data or null if fails.
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	getNewTitle
	 * Method to skip duplicated string entry.
	 * 		if the string already exists in db, return the string with an integer appended (ie:2)
	 * 		if you pass a 4th param as true the string will be handled as alias (dashed string)
	 *
	 * @param   string 	$table		mandatory	Table to be inspected.
	 * @param   string	$field		mandatory	Field to be checked.
	 * @param   string	$text		mandatory	Title to transform.
	 * @param	bool	$dash		optional	if true replace spaces with -
	 *
	 * @return	string  the unique string.
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	getResult
	 * Method to select a specific field value from db table.
	 *
	 * @param   mixed	$table		mandatory		Table of current component to be inspected (string) 
	 * 														or array with 
	 * 														'dbprefix' => '#__' 
	 * 														and 'dbtable' => 'component_tablename'
	 * @param   mixed	$where		mandatory		where clause - array or string
	 * @param	array	$extra		optional		array containg join / more complex where clause / order dir etc.
	 *
	 * @return	array | null						Contains the array data or null if fails.
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	getRow
	 * Method to select a single row from db.
	 *
	 * @param   mixed	$table		mandatory	Table of current component to be inspected (string) 
	 * 												or array with 'dbprefix' => '#__' and 'dbtable' => 'mycomponent_tablename'
	 * @param   mixed	$where		mandatory	where clause - array or string
	 * @param	array	$extra		optional	array containg join / where clause / order dir etc.
	 *
	 * @return	object | null		Contains the object data or null if fails.
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	getTableFields
	 * Method to get the fields list of a db table
	 *
	 * @param	mixed	$table	mandatory	db table name
	 * 
	 * @return	array	list of records
	 *
	 * @since	1.0.0
	 * 
	 * @example	passing array
	 * 					'dbtable' key is mandatory
	 * 						you can pass only 'dbtable' => '#__mycomp_tablename'
	 * 					or
	 * 						'dbprefix' => '#__othercomp_', 'dbtable' => 'tablename'
	 * 					in both cases the query will be: from '#__othercomp_tablename'
	 * 			or
	 * 			passing string
	 * 						'mytablename'
	 * 							the query will be: from '#__'.$runningComponentName.'_mytablename'
	 */

	/**
	 * @method	getTableFieldsList
	 * Method to get a unique random string
	 *
	 * @param	string	$table	mandatory	db table name
	 * 
	 * @return	array	list of records
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	getUniqueId
	 * Method to get a unique random string
	 *
	 * @param	string	$table	mandatory	db table name
	 * @param	string	$field	mandatory	db table field name to be checked
	 * @param	int		$l		optional	string lenght	default is 32
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	getWhere
	 * Method to perform where clause
	 *
	 * @param   object	$db			mandatory	db object
	 * @param   object	$query		mandatory	query object to append the where clause to
	 * @param	array	$where		mandatory	where data to assemble
	 *
	 * @access	private
	 * 
	 * @return	object	$query
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	insert
	 * Method to insert a row into db
	 *
	 * @param	array	$table		mandatory	db table
	 * @param   array	$keys		mandatory	field(s) to insert
	 *
	 * @return	int		number of affected rows or false if fails
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	prepareSearch 
	 * Method to prepare a search query for given field(s) and value(s)
	 *
	 * @param   array	$field		mandatory	field(s) to search into
	 * @param   string	$value		mandatory	value to search for
	 * @param	array	$table		mandatory	db table
	 *
	 * @return	object	$query		the search query string
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	preQuery( $query=null)
	 * Method to style a query string in a more readable way
	 *
	 * @param   mixed	$query		string or object Query to be styled
	 *
	 * @return	string  the modified string.
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	select
	 * Method to execute a simple db select query.
	 *
	 * @param   mixed	$table		mandatory	Table of current component to be inspected (string) 
	 * 												or array with 'dbprefix' => '#__' and 'dbtable' => 'mycomponent_tablename'
	 * 												or object with $object->dbprefix = '#__' and $object->dbtable = 'mycomponent_tablename'
	 * @param   mixed	$where		mandatory	where clause - array or string
	 * @param	array	$extra		optional	array containg join / where clause / order dir etc.
	 *
	 * @return	object | null					the object data or null if empty selection or false if fails.
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	store
	 * Method to store data using JTable
	 *
	 * @param   string	$table		Table to be inspected.
	 * @param   array	$keys		Array data to store
	 * @param   array	$params		Array of db info
	 * 								['table_prefix']	will be JTable 				if not given
	 * 								['component']		will be Bp::getComponent() 	if not given
	 * 								['db']				will be self::getDb()		if not given
	 *
	 * @return	bool  	false if fails, true otherwise
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	update
	 * Method to update db table
	 *
	 * @param   string	$table		Table to be inspected.
	 * @param   array	$keys		Array data to store
	 * @param	array	$where		where conditions
	 *
	 * @return	int					Number of affected rows
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	updateCounter
	 * Method to update a counter field
	 *
	 * @param   string	$table		mandatory	Table to be inspected.
	 * @param   array	$keys		mandatory	Array data to store
	 * @param	array	$where		mandatory	Array where clause
	 *
	 * @return	bool  	true on success, false if fails
	 *
	 * @since	1.0.0
	 */