| core_lang

# Procedural File: Bs_Misc.lib.php Source Location: /core/lang/Bs_Misc.lib.php ## Classes: ## Page Details: #### Tags:
version: | 4.3.$Revision: 1.5 $ $Date: 2003/12/14 09:55:38 $
author: | andrej arn <at blueshoes dot org>, Sam Blum <sam at blueshoes dot org>
### applyOutputHandlers [line 304]
`&string &applyOutputHandlers( string &$string)`
applies the registered output handlers. #### Tags:
see: | registerOutputHandler(), spit(), redirect()
#### Parameters
string | &$string |
[ Top ] ### arrayToHtml [line 395]
`string arrayToHtml( array $array)`
Loops the given array or object and returns some html code with the key/value pairs. I am using this peace of code all the time while coding/debugging so i thought it would be a handy function. of course this moves the array pointer. #### Parameters
array | $array | or object $array
[ Top ] ### boolToString [line 570]
`string boolToString( bool $param)`
Converts a bool to a string. If $param is (evaluates to) TRUE, returns 'true' etc. #### Tags:
return: | ('true' or 'false')
#### Parameters
bool | $param |
[ Top ] ### bsSessionBrowscap [line 69]
`void bsSessionBrowscap( )`
deals with session and browscap, whatever is needed. this code could be in the site's conf file, but because it's always the same logic this code has been outsourced. it's required that $GLOBALS['bsSession'] OR $GLOBALS['Bs_SimpleSession'] is set. otherwise this function won't do anything. #### Tags:
access: | public
[ Top ] ### bsSetCookie [line 369]
`void bsSetCookie( string $name, [string $value = ''], [int $expire = NULL], [string $path = NULL], [string $domain = NULL], [int $secure = NULL])`
Sends a cookie to the client. Please *always* use this function instead of php's setcookie() function. If you look at http://www.php.net/manual/en/function.setcookie.php there are currently over 100 (!) user contributed messages about this topic. This has a reason. Sean McLean's had a closer look at the problem in the "The great PHP cookie test" http://www.rnetwork.tv/cookietest/ (and http://www.chipchapin.com/WebTools/cookietest.php) and his comment is: "The answer to the problem of different browsers handling cookies differently: There is none! I conducted a test, running 10 different ways of setting cookies, and not a single way of setting cookies worked consistently on every browser. Our solution was to use multiple ways of setting cookies ..." In the mean time (1.1.2002) Sean has added 3 additional setting and method #13 seems quite successful so far. #13 : header("Set-Cookie: testCookie=foo; path=/; domain=.foo.com; expires=" .gmstrftime("%A, %d-%b-%Y %H:%M:%S GMT",time()+9600)); This would mean to set the header manually using the header() function. So we wrap the cookie handling here. All params are the same as in setcookie(). Please rtfm for cookies. It really is a special case with many pitfalls. INFO: Per default, IE6 requires sites that set cookies to have P3P policies (as defined by W3C) or otherwise the cookies are 'downgraded', thus are deleted when IE is closed. See http://support.microsoft.com/default.aspx?scid=kb;EN-US;q260971&GSSNB=1 http://www.w3.org/P3P/ According to Netscape's cookie spec: 20 cookies per server or domain, 300 total cookies, and 4k per cookie. http://www.netscape.com/newsref/std/cookie_spec.html Surprisingly, javascript cookies are the most reliable (if javascript is able to run of course). E.g.: echo "<script>document.cookie = 'test_cookie' + '=' + 'foo';</script>\n"; #### Tags:
see: | php's setcookie() and headers_sent().
#### Parameters
string | $name | the key
string | $value | if not set or set to an empty string '', the client will delete the cookie.
int | $expire | a unix timestamp
string | $path |
string | $domain |
int | $secure | (would be a boolean, but because php uses an int, we do it too.)
[ Top ] ### bs_addIncludePath [line 194]
`void bs_addIncludePath( string $path)`
adds the path specified to the include_path php setting. UNIX: "/path1:/path2" Windows: "\path1;\path2" #### Tags:
since: | bs4.5
#### Parameters
string | $path |
[ Top ] ### bs_dump [line 443]
`HTML bs_dump( mixed $param, [bool $noEcho = FALSE])`
Beautify var_dump a little and add #### Tags:
return: | sting (see text above)
#### Parameters
mixed | $param |
bool | $noEcho | FALSE= echo / TRUE = return output string
[ Top ] ### bs_lazyLoadClass [line 1402]
`bool bs_lazyLoadClass( string $classPath, [string $useCorePath = TRUE])`
loads a class on demand. it's faster to load a class only on demand if it's not always used. compared to requireing the dependent classes on top of each class. #### Tags:
return: | (TRUE if it is included now or has already been, FALSE if it failed. it won't throw any error or die.)
see: | bs_lazyLoadPackage()
#### Parameters
string | $classPath |
string | $useCorePath | (if $APP['path']['core'] should be prepended, default is TRUE.)
[ Top ] ### bs_lazyLoadPackage [line 1431]
`bool bs_lazyLoadPackage( string $packageName, [string $useCorePath = TRUE])`
loads a package on demand. it's faster to load a class only on demand if it's not always used. compared to requireing the dependent classes on top of each class. currently these package names are known: 'html/form' 'html/form/domapi' 'html/form/specialfields' #### Tags:
return: | (TRUE if it is included now or has already been, FALSE if any class include failed or if package name unknown. it won't throw any error or die.)
see: | bs_lazyLoadPackage()
#### Parameters
string | $packageName |
string | $useCorePath | (if $APP['path']['core'] should be prepended, default is TRUE.)
[ Top ] ### bs_loadVar [line 893]
`bool bs_loadVar( &$theVar &$theVar, $fullFilePath $fullFilePath)`
This is the opposite function of bs_storeVar() (See there) NOTE: If TRUE is returned the passed parameter $theVar will contain the value you stored with bs_storeVar(). If FALSE is returned $theVar will contain the error that occured or the value NULL (in case of a FATAL-PHP error) #### Tags:
return: | TRUE on success, FALSE otherwise.
see: | bs_loadVar() (In this file)
#### Parameters
&$theVar | &$theVar | mixed see text above.
$fullFilePath | $fullFilePath | string Valid path + file-name
[ Top ] ### bs_recursiveStripSlashes [line 1523]
`void bs_recursiveStripSlashes( &$toStrip &$toStrip)`
Strips all slashes from an string or array/hash recursively #### Parameters
&$toStrip | &$toStrip | mixed array or string
[ Top ] ### bs_registerShutdownMethod [line 1049]
`TRUE bs_registerShutdownMethod( int $line, int $file, object &$object, mixed $methodName, [array $params = NULL], string $method)`
Register *object methods* as shutdown functions. Unfortunately php's register_shutdown_function() cannot work with objects and cannot take function parameters. This function can! NOTE: Because it is importent that the shut down works we are conservative about the registered methods: If the object you pass is not an object or the method is not a method of the passed object, this function will TERMINATE PHP WITH USER ERROR ! Usage sample : //register our own shutdown function bs_registerShutdownMethod(__LINE__, __FILE__, object <any object>, string <methode>, array <parameter vector>); Andrej has submitted a simular function to http://www.php.net/manual/en/function.register-shutdown-function.php #### Tags:
return: | on success, otherwise TERMINATES PHP WITH USER ERROR!
access: | public
author: | andrej arn <at blueshoes dot org>, Sam Blum <sam at blueshoes dot org>
#### Parameters
int | $line | The line number __LINE__
int | $file | The file name __FILE__
object | &$object |
string | $method | the method name without parenthesis (eg 'someFunction')
array | $params | (optional) A vector! The params you want to pass along with the function. They are passed by value.
[ Top ] ### bs_storeVar [line 869]
`bool bs_storeVar( $theVar $theVar, $fullFilePath $fullFilePath)`
This function is very useful for saving PHP vars in an easy-to-read format to disk. USAGE: Just call with any (non recursive) PHP variable and a valid path + file-name. To fetch the var use bs_loadVar() NOTE: According to tests it is up to 10 times faster to use serialize to store php variable data in files. (However it is not a human-readable format then). #### Tags:
return: | TRUE on success, FALSE otherwise.
see: | bs_loadVar() (In this file)
#### Parameters
$theVar | $theVar | mixed Any (non recursive) PHP variable.
$fullFilePath | $fullFilePath | string Valid path + file-name
[ Top ] ### bs_testShutdown [line 1099]
`bool bs_testShutdown( object &$object, mixed $methodName, string $method)`
Test the bs_registerShutdownMethod() if it works. To see if your method gets properly called you may call this function for testing. Supply the same object and method name as you registered before and the method will be called just as it would during a shutdown. But as it isn't a real shutdown you can echo some output to check if it's running OK. During a real PHP shutdown echo's don't work. #### Tags:
return: | TRUE if object/method found, otherwise FALSE
see: | bs_registerShutdownMethod(), bs_testShutdown()
author: | Sam Blum <at blueshoes dot org>, andrej arn <andrej at blueshoes dot org>
#### Parameters
object | &$object |
string | $method | the method name without parenthesis (eg 'someFunction')
[ Top ] ### bs_undoMagicQuotes [line 1508]
`void bs_undoMagicQuotes( [&$toStrip 0 = mixed array or string])`
Check if magic-quotes are on, and if so strip all slashes from $_POST, $_GET, $_COOKIE and $_REQUEST NOTE: After stripping set the 'magic_quotes_gpc' flag to FALSE. #### Parameters
&$toStrip | 0 | mixed array or string
[ Top ] ### classHyrachy [line 1175]
`array &classHyrachy( mixed &$classOrObject)`
Separate an object (or class) in it's hyrachy-components (vars and methods) Analyse the class and it's parents and divide the vars and methods in a class (object) hyrachy-tree. Starts with 0 with the root object and has following stucture: $objHyrachy[$nr]['name'] -> object name ['vars'] -> object vars *excluding all* vars from parent objects ['methods'] -> object methods *excluding all* methods from parent objects ['allVars'] -> all vars of the passed object ['allMethods'] -> all methods of the passed object NOTE: Needs PHP V4.0.5 or up #### Tags:
return: | See above
see: | classHyrachyToHtml()
throws: | FALSE on error.
#### Parameters
mixed | &$classOrObject | Either a object or the name of the class (string)
[ Top ] ### classHyrachyToHtml [line 1554]
`string &classHyrachyToHtml( mixed &$param)`
Returns a HTML output of a class separate in it's hyrachy-components. Analyse the class and it's parents using the function classHyrachy() and return a HTML output. Used for debugging. NOTE: Needs PHP V4.0.5 or up #### Tags:
return: | see above
see: | classHyrachy()
#### Parameters
mixed | &$param | Either a object or the name of the class (string) or the output of classHyrachy()
[ Top ] ### dump [line 424]
`void dump( mixed &$param, [mixed $noEcho = FALSE])`
Beautify var_dump a little and add #### Tags:
deprecated: | since bs-4.4 Use bs_dump() --Sam
see: | bs_dump()
[ Top ] ### evalErrorHandler [line 918]
`void evalErrorHandler( mixed $errNo, mixed $errStr, mixed $errFile, mixed $errLine)`
DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, Used only by evalWrap(). [ Top ] ### evalWrap [line 979]
`mixed evalWrap( string $phpCode, [string $security = 'high'], [bool $suppressErrors = FALSE], [array $params = array()])`
DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, DEPRECATED, Please migrate to evalWrapper(). evalWrap() wraps PHP's eval() ('old' version) The passed PHP code rests in it's own scope and will not interfere with the rest of the program by accident. In future it may prevent certain calls. The passed $phpCode is interpreted just like a normal php script but all output (e.g. normal text and PHP-echo's) is catched and will make up the output of this function. NOTE I : It's recommended to pass the $phpCode WITH the '<?php'- wrapping tags. Just as if your were coding a php-script. Mix of html and PHP is allowed! If you leave out the '<?php'- wrapping tags it will still work. This is a PHP-eval() feature; don't know how it exactly works but if eval() fails to understand the *beginning* of the passed $phpCode it assumes it's normal text and will stop (without a message). Otherwise it starts parsing as usual. NOTE II: If the $phpCode contains a 'return $foo;' at the *top* level, thus *outside* a class or function, then the that return value is the return value of this function. IMPORTANT! : Output has priority over a return-value! If you're interested in the unsing a return() call, then *no* output is to be produced. Reason: See above "Comment to PHP's eval() an the evalWrapper's" param $phpCode The passed PHP code rests in it's own scope and will not interfere with the rest of the program by accident. In future it may prevent certain calls. The passed $phpCode is interpreted just like a normal php script but all output (e.g. normal text and PHP-echo's) is catched and will make up the output of this function. param $security: (For future use) VALUE | MEANING -------+-------------------------------------------------------- 'high' | no db and file access is permitted. no shell commands. 'low' | no shell commands. 'none' | everything is permitted, no restrictions. param $params: If you want to pass variables into the scope of the passed code you must set up a hash array with the variable name as key and the value that belongs to it. E.g. If you want $foo and $bar to be in scope, make an hash as follows: array('foo'=>$foo, 'bar'=>$bar); You can also pass by reference doing array('foo'=> &$foo, 'bar'=> &$bar); #### Tags:
return: | this can be anything, whatever the evaluated code returns.
todo: | return a bs_exception if the security check complains or a parse error occures while evaluating $phpCode.
todo: | add something to disallow output (echo, print, escaping code).
todo: | make use of the $security param.
throws: | if the evaluated code does not return, or if a parse error occures, or if the security check complains, NULL is returned.
access: | public
deprecated: | since 1.3.02 Use evalWrapper() --Sam
#### Parameters
string | $phpCode | the string you want to evaluate. Must be properly escaped etc. rtfm.
string | $security | (optional, default 'high') see above.
bool | $suppressErrors | (optional, default FALSE).
array | $params | default is an empty array. can be a hash holding key/value pairs where the key is the var name and the value is the var value (or a reference to it isn't a bad idea).
[ Top ] ### evalWrapper [line 757]
`string evalWrapper( string $phpCode, hash &$context, [array $params = array()])`
evalWrapper (The new version. Replaces evalWrap().) NOTE: Read the stuff above as intro. The passed PHP code rests in it's own scope and will not interfere with the rest of the program by accident. In future it may prevent certain calls. The passed $phpCode is interpreted just like a normal php script but all output (e.g. normal text and PHP-echo's) is catched and will make up the output of this function. NOTE: Parameter $context is a hash array taken by reference. It's used to pass data to and form evalWrapper(). A sample of $context and it's fields is the var $MISC_evalWrapperContextDefault just above. #### Tags:
return: | The output of the code (echo's and that stuff).
#### Parameters
string | $phpCode | The PHP code to evaluate. It's recommended to write the $phpCode you pass *WITH* the '<?php'- wrapping tags. Just as if you were coding a php-script. Mix of HTML and PHP is then allowed! If you leave out the '<?php'- wrapping tags it will still work, assuming it's pure PHP code (no HTML/PHP mix).
hash | &$context | See $MISC_evalWrapperContextDefault above. Samples: (PHP 4.2 and below) $context = array('display_errors' => TRUE, 'sourceFile'=>'foo.php', 'file'=>__FILE__, 'function'=>'foo', 'line'=>__LINE__); (PHP 4.3 and up) $context = array('display_errors' => TRUE, 'sourceFile'=>'foo.php');
array | $params | If you want to pass variables into the scope of the passed code you must set up a hash array holding key/value pairs where the key is the var name and the value is the var value (or a reference to it isn't a bad idea). E.g. If you want $foo and $bar to be in scope, make an hash as follows: array('foo'=>$foo, 'bar'=>$bar); You can also pass by reference doing array('foo'=> &$foo, 'bar'=> &$bar);
[ Top ] ### getAbsoluteFile [line 538]
`void getAbsoluteFile( )`
Get the physical absolute path (with file) of the current script. example: c:/sites/www.domain.com/directory/index.php #### Tags:
see: | getAbsolutePath()
[ Top ] ### getAbsolutePath [line 523]
`void getAbsolutePath( )`
Get the physical absolute path (without file) of the current script. example: c:/sites/www.domain.com/directory/ #### Tags:
see: | getAbsoluteFile()
[ Top ] ### getAbsoluteWebFile [line 479]
`void getAbsoluteWebFile( )`
Get the absolute path (with file) of the current script. example: http://www.domain.com:80/directory/file.php #### Tags:
see: | getAbsoluteWebPath(), getAbsoluteWebFileQuery()
[ Top ] ### getAbsoluteWebFileQuery [line 510]
`void getAbsoluteWebFileQuery( )`
Get the absolute path (with file and querystring) of the current script. example: http://www.domain.com:80/directory/file.php?a=b&c=d #### Tags:
see: | getAbsoluteWebPath(), getAbsoluteWebFile()
[ Top ] ### getAbsoluteWebPath [line 467]
`void getAbsoluteWebPath( )`
Get the absolute path (without file) of the current script. example: http://www.domain.com:80/directory/ #### Tags:
see: | getAbsoluteWebFile(), getAbsoluteWebFileQuery()
[ Top ] ### getTmp [line 1340]
`string getTmp( )`
returns the systems default temp dir. if it cannot be determined, the function attempts to create '/tmp'. if that fails aswell, the function throws bool FALSE. i don't expect this to happen. but... backslashs are returned as foreslashes, and the last slash is added. examples: c:/temp/ /tmp/ #### Tags:
throws: | bool FALSE (if could not determine and/or create temp dir. that should never happen.)
[ Top ] ### isAlphaNumeric [line 587]
`bool isAlphaNumeric( mixed &$var)`
Returns TRUE if the given var is a string, int or double. returns FALSE otherwise (object, array, bool, resource, unknown, null). #### Parameters
mixed | $var |
[ Top ] ### isInvisible [line 622]
`bool isInvisible( string $string)`
Tells if a given string contains only whitespace character. For example a string with is composed of only spaces, tabs: "\t", line breaks: "\n" and "\r" is considered invisible. A string like '0' is considered to be visible. so this is not like empty() in php. --sam to andrej: What is "\v"? And a better name isWhite() --andrej to sam: i don't know :) and is that name really better? cause of 'whitespace'? to me it looks invisible, not white (color). but... i don't mind. maybe a function name with a bs_ prefix would have been better. #### Parameters
string | $string |
[ Top ] ### isTrue [line 552]
`bool isTrue( string $value)`
Intelligent is TRUE tester. Tells whether a value should be considered as true or not. this is useful for ini files for example where all these values should be treated as TRUE: Yes, Y, Ja, Oui, On, True (string or bool), 1 (string or int) => all case insensitive everything else, like No, Off, False, 0, is treated as FALSE. #### Parameters
string | $value |
[ Top ] ### isWhite [line 626]
`void isWhite( mixed $string)`
[ Top ] ### levenshteinPercent [line 1489]
`int levenshteinPercent( string $one, string $two)`
returns the levenshtein in %. the smaller the number the better (more similar) the strings. examples: levenshteinPercent('foo', 'bar'); => 100 (all letters need to be changed.) levenshteinPercent('aaaaaa', 'b'); => 100 (all letters need to be changed.) levenshteinPercent('foobar', 'bar'); => 50 (3 letters need to be inserted, that's 50% changes.) levenshteinPercent('foobar', 'foobar'); => 0 (no changes are needed.) #### Tags:
return: | (full non-float number from 0 to 100)
#### Parameters
string | $one |
string | $two |
[ Top ] ### misc_ErrorHandler [line 641]
`void misc_ErrorHandler( mixed $errNr, mixed $errMsg, mixed $errFile, mixed $errLine, mixed $errContext)`
A own error handler. How to use : set_error_handler('misc_ErrorHandler'); Your code here restore_error_handler(); Errors are then cauptured in the global variable $MISC_errorHandler_lastError [ Top ] ### parseUid [line 1260]
`array parseUid( string $UID)`
parses an UID string into an array. for the definition of an UID see the naming part of codingGuidelines.txt. #### Tags:
return: | (hash)
see: | uidArrayToString()
#### Parameters
string | $UID |
[ Top ] ### redirect [line 165]
`void redirect( string $url)`
Redirect to the given url and terminate the execution of the current script immediatly. please use this and don't do it manually using header() because then we could not do the output handlers. #### Tags:
todo: | if we get a relative url we have to make it absolute, otherwise some clients may not understand it.
see: | php's header() and headers_sent().
#### Parameters
string | $url | (may be relative but i highly recommend to use it absolute.)
[ Top ] ### registerOutputHandler [line 294]
`void registerOutputHandler( string $function, [array $params = array()])`
registers an output handler. all output (from spit() will be run through the given output handler(s). they are applied in the same order as they are registered. param $params: vector with the params to call the output handler. you may want to pass the array (or the params inside the array) by reference. see example. example: let's use the rewriteUrlSession() output handler. it will attach the current session id to all url's. bedefault it will only be applied to relative url's. but we're going to tell it our own domains so it can do it on absolute links aswell: $absoluteUrl = array(); //define array $params = array(NULL, $absoluteUrl); registerOutputHandler('rewriteUrlSession', $params); $absoluteUrl = array('www.yourdomain.com', 'yourdomain.com'); now because you did not pass $params by reference (or add $absoluteUrl by reference to the array $params) it cannot be done, your domains won't be known. got that? all output handlers need to take exactly 2 params by reference: the string and additional params. take rewriteUrlSession() as an example. #### Tags:
see: | spit()
access: | public
#### Parameters
string | $function | the function name of the output handler
array | $params | (vector, see above)
[ Top ] ### rewriteUrlSession [line 240]
`string rewriteUrlSession( string $string, array $params)`
rewrites the urls in the given string with the sid. if sid is not given, the global one will be used. unfortunately php does not have such a function yet. the functionality exists using --enable-trans-sid, but not as separate function. and it does not work in all cases, namely: Header("Location: url") => Header("Location: url?" . SID) Meta-refresh <META http-equiv="refresh" content="5; URL=$refresh?SID"> Javascript client side programmed links 4.0.6, it apparently did not work with POST forms. only works on relative url's. someone said he lost the var when referring dir/ instead of dir/index.php does not work with output buffering because the SID is added after, and thus fucks up the output size value. links to downloadable file slike download.exe?PHPSESSID=SID give problems? this function uses the vars $GLOBALS['bsSession']->getSid() string the session id to use $APP['sess']['tags'] array vector the tags to search for url's $APP['sess']['domains'] array vector the domains to treat as local #### Tags:
todo: | write main code
see: | registerOutputHandler(), var $APP['sess']
access: | public
#### Parameters
string | $string |
array | $params | (vector, empty here but we need it set.)
[ Top ] ### spit [line 323]
`void spit( string $string)`
spits out the given string to the client browser using the registered output handler(s). spit it out ... CH-T ... in your face (missy elliott :) #### Tags:
see: | registerOutputHandler()
access: | public
#### Parameters
string | $string | give it by reference if you can, but be aware that it will most likely be modified.
[ Top ] ### uidArrayToString [line 1317]
`string uidArrayToString( array $UID)`
opposite of parseUid(). #### Tags:
see: | parseUid()
#### Parameters
array | $UID |
[ Top ] ### _bs_shutdown [line 1129]
`void _bs_shutdown( [int $triggerNr = -1])`
The BS shutdown function that PHP will call on shutdown Read above what this function is used for. NOTE: The parameter $triggerNr is used for testing. If >=0 only the method that is at position $triggerNr will be called. #### Tags:
see: | bs_registerShutdownMethod(), bs_testShutdown()
author: | Sam Blum <at blueshoes dot org>, andrej arn <andrej at blueshoes dot org>
#### Parameters
int | $triggerNr | (see text above)
[ Top ] Documentation generated on Mon, 29 Dec 2003 21:11:47 +0100 by phpDocumentor 1.2.3