Documentation for class Bp



/**
 *  @package:   bpl - brain pies library
 * 	class		Bp
 * 
 *  @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	addCss
	 * Method to include a css style sheet in HEAD section
	 *
	 * @param	string		$url	url to css file
	 * @param	bool		$root
	 * 
	 * @return	void		
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	addFavicon
	 * Method add a favicon tag in HEAD section
	 *
	 * @param	string		$href		mandatory	path to icon image
	 * @param	string		$type		optional	image type
	 * @param	string		$relation	optional	relation
	 * 
	 * @return	void
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	addHeadTag
	 * Method add a tag in HEAD section
	 *
	 * @param	string		$data	mandatory	the custom tag to add
	 * @param	string		$type	optional	the type of tag
	 * 
	 * @return	void
	 * 
	 * @since	1.0.0
	 * 
	 * @todo	expand with other tag type
	 * @todo	parse array or object
	 */

	/**
	 * @method	addJava
	 * Method to include a js file in HEAD section
	 *
	 * @param	string	$url	mandatory	url to js file
	 * @param	bool	$root	optonal		set to true to prefix $url with JUri::base()
	 * 										JUri::base() = ie in admin side: http://www.mysite.com/administrator/
	 * 
	 * @return	void
	 * 		
	 * @since	1.0.0
	 */

	/**
	 * @method	addJavaCode
	 * Method to include a javascript code directly in HEAD section
	 *
	 * @param	string	$data	mandatory	script code
	 * 
	 * @return	void
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	addMex
	 * Method to enqueue a text message
	 *
	 * @param	string	$mex	mandatory	message to be enqueued
	 * @param	string	$type	optional	message type
	 *
	 * @return	void
	 *
	 * @since 	1.0.0
	 */

	/**
	 * @method	arrayUniqueKeys
	 * Method to skip all duplicate keys in a bidimensional array
	 *
	 * @param 	array	$array	mandatory	
	 * 
	 * @return	array 
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	br2nl($string)
	 * Method to replace <br/> or <br /> with \n
	 *
	 * @param	string		$string		mandatory	
	 * 
	 * @return	string
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	formatPageTitle
	 * Method to format page title accordingly with Joomla configuration
 	 *
	 * @param	string	$title	mandatory
	 * 
	 * @return	string
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	get
	 * Method to retrieve request data
	 *
	 * @param	string	$var	  		mandatory	variable name to search for		
	 * @param	mixed	$def	  		optional  	default value to return if not found
	 * @param	string	$type	 		optional	filter to apply
	 * @param	string	$superGlobal	optional	superglobal (POST or GET) to search in only
	 *
	 * @return	mixed	    			filtered var value on success or passed default value if fails
	 *
	 * @since	1.0.0
	 * 
	 * 
	 * 	AVAILABLE FILTERS		
	 *	INT or INTEGER		Only use the first integer value
	 *	UINT				Only use the first integer value
	 *	FLOAT or DOUBLE		Only use the first floating point value
	 *	BOOL or BOOLEAN		Return boolean
	 *	WORD				Only allow characters a-z, and underscores
	 *	ALNUM				Allow a-z and 0-9 only
	 *	CMD					Allow a-z, 0-9, underscore, dot, dash. Also remove leading dots from result
	 *	BASE64				Allow a-z, 0-9, slash, plus, equals.
	 *	STRING				Converts the input to a plain text string; strips all tags / attributes.
	 *	HTML				Converts the input to a string; strips all HTML tags / attributes.
	 *	ARRAY				Attempts to convert the input to an array
	 *	PATH				Converts the input into a string and validates it as a path. (e.g. path/to/file.png or path/to/dir)
	 *						    Note: Does NOT accept absolute paths, or paths ending in a trailing slash.
     * 						    For a visual representation of the pattern matching used, see:
     *                          http://www.regexper.com/#^[A-Za-z0-9_-]%2B[A-Za-z0-9_\.-]*%28[\\\\\%2F][A-Za-z0-9_-]%2B[A-Za-z0-9_\.-]*%29*%24
	 * 						    Will return null if the input was invalid.
	 *	RAW					The raw input. No sanitation provided.
	 *	USERNAME			Strips all invalid username characters
	 */

	/**
	 * @method	getAclTitle
	 * Method to get ACL Title
	 *
	 * @param	int			$id		mandatory	id of acl
	 * 
	 * @return	string		ACL title
	 * 
	 * @uses	class		BpDb
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	getApp
     * Method to get application object. 
	 * 
     * The class does anything special but simplify the class call
	 * You simply have to think what you want and write it down 
	 * in a shorter way saving digits and time
	 *
	 * @return	object	application class object
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	getComponent
	 * Method to retrieve the running component name
	 *
	 * @return	string	component name less 'com_'
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	getDevice
	 * Method to retrieve the user's device type
	 *
	 * @return	string	device type ( desktop | tablet | mobile )
	 * 
	 * @uses	Mobile_Detect class
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	getDoc
	 * Method to get current document object
	 * 
     * The class does anything special but simplify the class call
	 * You simply have to think what you want and write it down
	 * in a shorter way saving digits and time
	 *
	 * @return	object	document class object
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	getLang
	 * Method to get global language object
	 *
	 * @param	string		$option		optional	specific language object element
	 * 
	 * @return	object		language object by default or specific parameter value if optional param is passed
	 *
	 * @since	1.0.0
	 * 
	 * NOTE: params to pass
	 * tag:			return language tag value 			ie: "en-GB"
	 * name:		return language name				ie: "English (en-GB)"
	 * nativeName:	return native language name			ie: "English (United Kingdom)"		NOTE: please note the camelToe of param passed
	 * rtl:			return boolean 1 or 0
	 * locale:		return lacale data comma separated	ie: "en_GB.utf8, en_GB.UTF-8, en_GB, eng_GB, en, 
	 * 														english, english-uk, uk, gbr, britain, england, 
	 * 														great britain, uk, united kingdom, united-kingdom"
	 * firstDay:	return the first day of the week	ie: "1"
	 * weekEnd:		return weekend params				ie: "0,6"
	 * calendar:	return the user calendar			ie: "gregorian"
	 */

	/**
	 * @method	getModel
	 * Method to get a model object from anywhere
	 *
	 * @param	string		$name		mandatory	the model name
	 * @param	string		$component	optional	the component name (without 'com_')
	 * @param	string		$prefix		optional	the model prefix (component name will be used if not passed)
	 * @param	bool		$site		optional	site or administrator component's folder side
	 * 
	 * @return	object		model object
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	getParamsC
	 * Method to retrieve componet params
	 *
	 * @param	string	optional component name - if missing retunrs running component's params
	 * 
	 * @return	object	component params || null if fails
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	getParamsJ
	 * Method to retrieve Joomla's Params (config)
	 *
	 * @return	protected class object
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	getParamsP
	 * Method to retrieve plugin params
	 *
	 * @param	string	$pluginType		mandatory	type of plugin 		ie: "system"
	 * @param	string	$plugin			mandatory	name of plugin		ie: "myplugin"
	 *
	 * @return	object	plugin params
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	getRandomId
	 * Method to get a random string lenght $l
	 *
	 * @param	int		$l	optional 	the lenght of the string - default 32
	 * 
	 * @return	alnum	a random string (alnum)
	 *
	 * @since	1.0.0
	*/

	/**
	 * @method	getSess
	 * Method to get Session $var
	 *
	 * @param	string	$var	var to get
	 *
	 * @return	mixed
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	getSubStr
	 * Method to get a sub string using delimiter codes
	 *
	 * @param	string	$string		the string to search into
	 * @param	string	$start		the string code start delimiter
	 * @param	string	$end		the string code end delimiter
	 *
	 * @return	mixed
	 *
	 * @since	1.0.0
	 * 
	 * @author	Justin Cook
	 * @link:	http://justincook.com
	 * 
	 * @example: 	getSubStr("This is [start]my beautiful car[end]")		return: "my beautiful car"
	 */

	/**
	 * @method	getUrl
	 * Method to get current url properties
	 *
	 * @param	string	$type	// the information you want to get
	 * 
	 * @return	mixed
	 * 
	 * @since	1.0.0
	 * 
	 * NOTE: examples are related to this url:
	 * http://www.mysite.com/administrator/index.php?option=com_component&request=myrequest
	 * 
	 * @example:	complete: 	return http://www.mysite.com/administrator/index.php?option=com_component&request=myrequest
	 * @example:	query: 		return option=com_component&request=myrequest
	 * @example:	host:		return www.mysite.com
	 * @example:	anchor:		return everything after the '#'
	 * @example:	path:		return administrator/index.php
	 * @example:	http:		return http
	 * @example:	ssl:		return false
	 */

	/**
	 * @method	getUser
	 * Method to get the user class object
	 * 
     * The class does anything special but simplify the class call
	 * You simply have to think what you want and write it down
	 * in a shorter way saving digits and time
	 * Let's call the class the way you think
	 *
	 * @return	object	$user object
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	getUsState
	 * Method to get user State $var
	 *
	 * @param	string	$var	var get back
	 * @param	mixed	$value	value to return if $var not found
	 *
	 * @return	mixed
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	getView
	 * Method to retrieve the current view
	 * 
	 * The method first attempts to look for a view value
	 * if fails then look for a task and split the dot separated value
	 * return null if fails
	 *
	 * @return	string | null
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	getXml
	 * Method to retrieve an xml file, like component manifest data or just a single info like the version data
	 * 
	 * @param	mixed array/object	$data		optional	specific data or running component will be selected
	 *
	 * @return	mixed	string | object | null if fails
	 * 
	 * @since	1.0.0
	 * 
	 * NOTE: pass component name less 'com_' or plugin name less 'plg_' or module name less 'mod_'
	 */

	/**
	 * @method	isAdminSide
	 * Method to check if the current side is administrator
	 * 
     * The class does anything special but simplify the class call
	 * You simply have to think what you want and write it down
	 * Let's call the class the way you think
	 *
	 * @return	int		1 if current side is administrator, 0 otherwise
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	isDebug()
	 * Method to check if component debug is enabled
	 *
	 * @return	bool
	 * 
	 * @since	1.0.0
	 * 
	 * NOTE:
	 * Sometime you may want to get an error message logged in error log file
	 * or displayed on screen 
	 * or displayed on screen only to you
	 * In plugin config set the following params:
	 * debug - bool
	 * debug_to_screen - bool
	 * debug_to_ip - bool
	 * debug_ips - all IP(s) comma separated you want the error displayed to
	 * 
	 * usage:
	 * 		set debug to 1 to get error messages logged in 'error_log' file
	 * or
	 * 		set debug to 1 and debug_to_screen to 1 if you want both logged in 'error_log' file
	 * 			and displaye to the screen (to every user)
	 * or
	 * 		set debug to 1 and debug_to_screen to 1 and debug_to_ip to 1 if you want both
	 * 			logged in 'error_log' file and displayed to screen only to user with specific IP
	 * 			then set debug_ips with the list of IP(s) you want the error messages displayed to
	 * 			each IP comma separated (with out spaces) 
	 * 
	 * 
	 * 	to use in your script:
	 * 
	 * 		if( Bp::isDebug()):
	 *  		do_my_debug_things();
	 * 		endif;
	 * 
	 * or
	 * 		$debug = Bp::isDebug(true);
	 * 		$debug is now an object:
	 * 		$debug->debug 		: bool - whether or not debug is on
	 * 		$debug->to_screen 	: bool - whether or not the 'display to screen' option is active
	 * 		$debug->to_ip		: bool - whether or not the filter to specific IP(s) is actve
	 * 		$debug->ip			: bool - whether or not the user IP is allowed to get the error messages displayed
	*/

	/**
	 * @method	isExt
	 * Method to check if an extension exists
	 *
	 * @param	string	$ext	mandatory	the extension complete name ie: "com_mycomponent"
	 * 
	 * @return	object	database row of 'extensions' table
	 * 
	 * @uses	class	BpDb
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	loadLayout
	 * Method to load a layout related to a view
	 *
	 * @param	string	$layout		mandatory		the name of the layout to load
	 * @param	string	$path		optional		the folder to search in 
	 * 
	 * @return	object
	 * 
	 * @since	1.0.0
	 * 
	 * NOTE: $path with no trailing slash
	 */

	/**
	 * @method	log
	 * Method to log messages into errors log file
	 *
	 * @param	string	$mex		mandatory	message
	 * @param	string	$errType	optional	error type
	 *
	 * @uses	class	BpDate
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	nl2br($string)
	 * Method to replace \n with <br /> 
	 *
	 * @param	string		$string		mandatory	
	 * 
	 * @return	string
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	redir
	 * Method set redirect command
	 * Sometimes you need to redirect the user showing a message on the landing page
	 * Do it with a single, short, simple command
	 *
	 * @param	string	$dir		directory to redirect to
	 * @param	string	$text		message to enqueue with
	 * @param	string	$textType	message type
	 *
	 * @return	void
	 *
	 * @since	1.0.0
	 * 
	 * NOTE: MESSAGE TYPE
	 * ERROR
	 * NOTICE
	 * WARNING
	 * MESSAGE
	 */

	/**
	 * @method	replace
	 * Method to replace placeholders with data
	 * If a placeholder(s) is orphane (hasn't any data associated)
	 * it will be removed from the string
	 *
	 * @param	mixed	$replace	mandatory	array or object	| keys-replace pairs
	 * @param	string	$template	mandatory	the string to modify
	 * @param	mixed	$key		optional	'braces' || 'square' || 'both'
	 *
	 * @return	string	$string	edited string or false if fails
	 * 
	 * @uses			slaveReplaceBraces()
	 * @uses			slaveReplaceSquare()
	 * 
	 * @since	1.0.0
	 * 
	 * NOTE: you can use placeholder with:
	 * braces 	{PLACEHOLDER} 
	 * square 	[PLACEHOLDER]
	 * both	{PLACEHOLDER1} [PLACEHOLDER2]
	 * you can be specific with the third parameter, default is braces
	 */

	/**
	 * @method	route($dir = null, $absolute = false)
	 * Method to get Url routed to relative or absolute address
	 *
     * The class does anything special but simplify the class call
	 * You simply have to think what you want and write it down 
	 * in a shorter way saving digits and time
	 * 
	 * @param	string	$dir		mandatory	directory to redirect to
	 * @param	bool	$current	optional	true or false
	 *
	 * @return	string
	 *
	 * @since	0.1.0
	 * 
	 * @example: JUri::current() in admin side = http://www.mysite.com/administrator/index.php
	 */

	/**
	 * @method	slaveReplaceBraces
	 * Method to replace placeholders with data
	 *
	 * @param	mixed	$replace	array or object	| keys-replace pairs
	 * @param	string	$template	the string to modify
	 *
	 * @return	string	$template	edited string
	 * 
	 * @access	private
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	slaveReplaceSquare
	 * Method to replace placeholders with data
	 *
	 * @param	mixed	$replace	array or object	| keys-replace pairs
	 * @param	string	$template	the string to modify
	 *
	 * @return	string	$template	edited string
	 * 
	 * @access	private
	 * 
	 * @since	1.0.0
	 */

	/**
	 * @method	set
	 * Method to set a specific data in request
	 *
	 * @param	string	$var		mandatory	the request var to set
	 * @param	mixed	$value		optional	the value to set the var to
	 * 
	 * @return	void
	 *
	 * @since 	1.0.0
	*/

	/**
	 * @method	setLogger
	 * Method to set the proper errors log file
	 *
	 * @return	void
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	setSess($var = null, $value = null)
	 * Method to set Session $var
	 *
	 * @param	string	$var	mandatory	var to set
	 * @param	mixed	$value	optional	value to set var to
	 *
	 * @return	void
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	setUsState($var=null, $value=null)
	 * Method to set user State $var
	 *
	 * @param	string	$var	mandatory	var to set
	 * @param	mixed	$value	optional	value to set var to
	 *
	 * @return	void
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method simpleEncrypt
	 * Method to simple "encrypt" (obfuscating, to better say) a string with a key
	 *
	 * this method "cript" and "uncript" the string using the same key
	 *
	 * @param	string	$str	the string to encrypt
	 * @param	string	$key	the key to be used to encrypt
	 * 
	 * @return	string			the obfuscated string
	 * 
	 * @since	1.0.0
	 * 
	 * NOTE: DO NOT USE THIS METHOD FOR SECURITY PURPOSE!!!!!!!!!!!!
	 * 
	 * just use it to (let's say) show a string in a way not easly recognizable
	 * use the same key to "encrypt" and "decript"
	 * @example simpleEncrypt('mystring', '1001010001111') to encrypt (return: "\HBECX_V" )
	 * @example	to "decrypt" : simpleEncrypt('\HBECX_V', '1001010001111') return "mystring"
	 */

	/**
	 * @method	txt
	 * Method to translate string accordingly with plural
	 *
	 * @param	string					$string		mandatory	the string to translate
	 * @param	mixed		int/array	$n			optional	an integer or an array containg an integer and directives
	 * 																•	'int'  => 5
	 * 																			will use the integer to search and 
	 * 																			to populate the string
	 * 																•	jsSafe => true 	
	 * 																			return a string javascript compatible
	 * 																•	script => true 	
	 * 																			interpret backslash \n and \t
	 * @return	string		translated string
	 *
	 * @since	1.0.0
	 */

	/**
	 * @method	vd
	 * Method to format var_dump
	 *
	 * @param	var		$data	mandatory	anything goes
	 * @param	bool	$echo	optional	display formatted string if true, 
	 * 										return the formatted string if false
	 * 
	 * @return	mixed	void or string
	 *
	 * @since	1.0.0
	 */