Daniel Spors edited this page May 8, 2014 · 4 revisions
Clone this wiki locally

Functions in file system.php


Loads a config file.
Should not be used if a config file is present in root path.

Definition: public function system_config($filename, $reset_to_defaults=true)

Returns: void


  • string $filename Full path to the config file

  • bool $reset_to_defaults If true resets the complete config to the one to read


Resets the global $CONFIG variable to defauls values.
Just sets some useful default values. This is also a good reference of the basic system variables.

Definition: public function system_config_default($reset=true)

Returns: void


  • bool $reset If true resets the config completely to default, extends/overwrites only if false


Loads a module. Use this to manually load a module. You can also add it to the config so that
system_init() loads it automatically.

Definition: public function system_load_module($path_to_module)

Returns: void


  • string $path_to_module Complete path to module file


Checks if a module is already loaded.
Looks into $GLOBALS["loaded_modules"] if there's a key named $mod.

Definition: public function system_is_module_loaded($mod)

Returns: bool true or false


  • string $mod The name of the module (not the path!)


Initializes the Scavix ScavixWDF.
This is one of two essential functions you must know about. Initializes the complete ScavixWDF, loads all essentials and defined modules and initializes them,
prepares the session and writes out some headers (from config too).

Definition: public function system_init($application_name, $skip_header=false, $logging_category=false)

Returns: void


  • string $application_name Application name. This will become your session cookie name!

  • bool $skip_header Optional. If true, will not send headers.

  • bool $logging_category An initial category for logging. Very optional!


Parses the request and returns a controller/event pair (if present).
Note that your .htaccess files must contain these lines:

RewriteCond %{REQUEST_FILENAME} !-f 
RewriteCond %{REQUEST_FILENAME} !-d 
RewriteCond %{REQUEST_URI} !index.php   
RewriteRule (.*) index.php?wdf_route=$1 [L,QSA] 

Definition: public function system_parse_request_path()

Returns: void


Instanciates the previously chosen controller
Checks what is requested: and object from the object-store, a controller via classname and loads/instaciates it.
Will also die in AJAX requests when something weird is called or throw an exception if in normal mode.

Definition: public function system_instanciate_controller($controller_id)

Returns: ICallable Fresh Instance of whatever is needed


  • mixed $controller_id Whatever system_parse_request_path() returned


Executes the current request.
This is the second of two essential functions.
It runs the actual execution. If fact it is the only place where you will
find an echo in the ScavixWDF code.

Definition: public function system_execute()

Returns: void


Executes the given request. Will parse the target class/method for required parameters
and prepare the data given in the $_REQUEST variable to match them.

Definition: public function system_invoke_request($target_class, $target_event, $pre_execute_hook_type)

Returns: mixed The result of the target-methods


  • string $target_class Name of the class

  • string $target_event Name of the method

  • int $pre_execute_hook_type Type of Hook to be executed pre call


Terminats the current run and presents a result to the browser.

Definition: public function system_exit($result=null, $die=true)

Returns: void


  • mixed $result The result that shall be passed to the browser

  • bool $die If true uses die() for output, else uses echo()


Terminats the current run.
Will be called from exception and error handlers. You may, call this directly, but we
recommend to throw an exception instead. See the WdfException class and it's Raise() method for more about this.
Note: This function will call die()!

Definition: public function system_die($reason, $additional_message)

Returns: void


  • string $reason The reason as human readable and hopefully understandable text

  • string $additional_message More details to be logged


Registers a function to be executed on a system hook.
Note that this registers a function! If you want an objects method to be executed, see register_hook().

Definition: public function register_hook_function($type, $handler_method)

Returns: void


  • int $type Valid hook type (see the HOOK_* constants)

  • string $handler_method name of function to call


Registers a method to be executed on a system hook. Note that this registers an objects method! If you want function to be executed, see register_hook_function().

Definition: public function register_hook($type, $handler_obj, $handler_method)

Returns: void


  • int $type Valid hook type (see the HOOK_* constants)

  • object $handler_obj The object containig the handler method

  • string $handler_method name of method to call


Executes a system hook (calls all registered handlers). This is very internal, but no magic: just loops all registered handlers and calls them. Arguments given vary from hook_type to hook_type.

Definition: public function execute_hooks($type, $arguments)

Returns: void


  • int $type Valid hook type (see the HOOK_* constants)

  • array $arguments to be passed to the handler functions/methods


Checks if a given int is a valid hook type. Checks a given integer if it represents a valid hook_type.

Definition: public function is_valid_hook_type($type)

Returns: bool true if valid


  • int $type Value to be checked against valid hook type (see the HOOK_* constants)


Returns the string representation of an int hook type.
In fact just returns the constant name as a string, so

echo (hook_type_to_string(HOOK_POST_INIT) == 'HOOK_POST_INIT')?'true':'false';  
// output: true 

Definition: public function hook_type_to_string($type)

Returns: string Type as string or 'HOOK_UNDEFINED' if $type is not a valid hook type


  • int $type Hook type


Checks if the hook of the given type is already fired
Sometimes you'll need to know the step of the current execution. You may use this function
to check which hooks have already been fired.

Definition: public function hook_already_fired($type)

Returns: bool true|false


  • int $type Hook Type


Checks if there is a handler bound to a HOOK
Checks if there's at least one handler registered for the hook

Definition: public function hook_bound($type)

Returns: bool true|false


  • int $type Hook Type


Returns a string representation of the given stacktrace This is kind of internal, but may be of use. We shift the stacktrace a bit to have more information in each line that belong together.

Definition: public function system_stacktrace_to_string($stacktrace)

Returns: string The stacktrace-string


  • array $stacktrace Use debug_backtrace() to get this


Sets a specific key of the classpath array to be searched first.

Definition: public function __priorize_classpath($key_to_priorize)

Returns: array The classpath array before reordering


  • string $key_to_priorize the key to be priorized


Sets the classpath search order.

Definition: public function __set_classpath_order($class_path_order)



  • $class_path_order NOT DOCUMENTED


Called whenever a class shall be instanciated but there's no definition found

Definition: public function system_spl_autoload($class_name)

Returns: void


  • string $class_name Name of the class to load


Tries to load the template for the calling class

Definition: public function __autoload__template($controller, $template_name)

Returns: bool|string Returns the filename if found, else false


  • object|string $controller Object or class to load template for

  • string $template_name Pass '' (empty string) for this.


searches the $CLASS_PATH for the file that defines the class

Definition: public function __search_file_for_class($class_name, $extension, $classpath_limit=false)



  • <type> $class_name

  • <type> $extension

  • <type> $classpath_limit


Builds a request.
This is quite basic and used very often. It will return an URL to the given controller. It checks if the routing features are enabled and ensures the the URLs are working!

Definition: public function buildQuery($controller, $event, $data, $url_root=false)

Returns: string A complete Request (for use as HREF)


  • mixed $controller The page to be loaded (can be Renderable or string)

  • string $event The event to be executed

  • array|string $data Optional data to be passed

  • string $url_root Optional root, will use system-wide detected/set one if not given


Builds a query for the current page.
Calls buildQuery internally to build an URL to the current route.

Definition: public function samePage($data)

Returns: string A complete Request (for use as HREF)


  • array|string $data Additional data


Executed a header redirect to another page. Calls buildQuery internally to build an URL to the current route, but will also work
if $controller already is an URL. Note: Will terminate the current processing silently and sent a "Location" header!

Definition: public function redirect($controller, $event, $data, $url_root=false)

Returns: void


  • string $controller The page to be called

  • string $event The event to be executed

  • array|string $data Optional data to be passed

  • string $url_root Optional root, will use system-wide detected/set one if not given


Generates random string in the given length.
Can be used as password, sessionid, ticket....

Definition: public function generatePW($len)

Returns: string The generated string sequence


  • int $len The length of the return string


Appends a version parameter to a link.
This is useful to avoid browser-side CSS and JS caching.

Definition: public function appendVersion($href)

Returns: string A new URL appended the nocache string


  • string $href The URL


Checks a string and returns true if it is UTF-8 encoded This performs some dirty checks and tries to detect if the given string is UTF8 encoded

Definition: public function detectUTF8($string)

Returns: bool True if UTF-8


  • string $string String to check


Returns an array containing the parameters of the referrer string.
If $part is given (and set in data) will only return this value.

Definition: public function referrer($part)

Returns: string|array Value of URL parameter $part if given, else array of all URL parameters


  • string $part Name of URL parameter to get


Checks wether the calling IP address matches the given host od IP.
May be useful to detect known IP addresses/hosts easily

Definition: public function is_host($host_or_ip)

Returns: bool true or false


  • string $host_or_ip Hostname or IP to be checked


Returns a value from the wdf cache. There are multiple caches: SESSION and global.
Global cache required additional globalcache module to be loaded.
Will only consult globalcache if $use_global_cache is true and $use_session_cache is false or
the object is not found in the SESSION cache

Definition: public function cache_get($key, $default=false, $use_global_cache=true, $use_session_cache=true)

Returns: mixed The value if found, else the default value


  • string $key Identifies what you want

  • mixed $default The default value you want if key is not present in the cache

  • bool $use_global_cache If true checks the global cache too (see globalcache module)

  • bool $use_session_cache If true checks the SESSION cache (that one is before the global cache)


Stores a string value into the internal cache.
Noting to say. Just stores where you want.

Definition: public function cache_set($key, $value, $ttl=false, $use_global_cache=true, $use_session_cache=true)

Returns: void


  • string $key a key for the value

  • string $value the value to store

  • int $ttl Time to life in seconds. -1 if it shall live forever

  • bool $use_global_cache If true stores in the global cache (see globalcache module)

  • bool $use_session_cache If true stores in the SESSION cache


Removes an entry from the cache Will simply do nothing if there's nothing stored for the key.

Definition: public function cache_del($key)

Returns: void


  • string $key The key identifiying the entry


Clears the cache
Note that calling this will NOT clear the complete $_SESSION variale, but only

Definition: public function cache_clear($global_cache=true, $session_cache=true)

Returns: void


  • bool $global_cache If true clears the global cache (see globalcache module)

  • bool $session_cache If true clears the SESSION cache


Returns a list of all keys in the cache Note that the returned array contains all key that are in one of the requested stores.
Means that there may be keys that are only in SESSION, but not in globalcache.

Definition: public function cache_list_keys($global_cache=true, $session_cache=true)

Returns: array All defined keys


  • bool $global_cache If true checks the global cache (see globalcache module)

  • bool $session_cache If true checks the SESSION cache


Returns the current chosen controller
Note that if you request a controller object ($as_string==false) that may still be a string, if it has not been
instaciated yet!

Definition: public function current_controller($as_string=true)

Returns: mixed Depending on $as_string: Classname/Id or controller object


  • bool $as_string If true will return the classname (or id if it is from object store)


Returns the current chosen event
This can return an empty string if there's no current event or if that has not yet been parsed or if it simply IS an empty string.

Definition: public function current_event()

Returns: string The current event


Returns the value of a given class constant.
Will check against name match and will use endswith to try to find
names without prefix.
Check is case insensitive!

Definition: public function constant_from_name($class_name_or_object, $constant_name)

Returns: mixed value of the found constant or NULL


  • string $class_name_or_object name of the class or object containing the constant

  • string $constant_name name of the constant to get


Returns the name of a given class constant. Will check all constant values and return the first match.

Definition: public function name_from_constant($class_name, $constant_value, $prefix=false)

Returns: string name of the found constant or NULL


  • string $class_name name of the class containing the constant

  • mixed $constant_value value of the constant to get

  • string $prefix Checked constants need to start with this prefix (useful if there are different constants with the same value)


Wrapper for json_encode that ensures JS functions are not quoted.
Will detect code that starts with '[jscode]' or 'function(' Example:

'test1'=>"function(){alert('1');}",   // <- works   
'test2'=>"[jscode]SomeFunctionName",  // <- SomeFunctionName must be defined in code    
'test3'=>"[jscode]alert('1')"         // <- wont work because it is a call! 

will generate

{"test1":function(){alert('1');}, "test2":SomeFunctionName, "test3": alert('1')} // <- syntax error due to test3    

Note: Make sure your 'embedded' JS code does NOT end with a semicolon (;)!

Definition: public function system_to_json($value)

Returns: string JSON encoded value


  • mixed $value Value to be encoded as JSON


Calls an objects method with given arguments
call_user_func_array does not allow byref arguments since 5.3 anymore so we wrap this in our own funtion. This is even faster then call_user_func_array.

Definition: public function system_call_user_func_array_byref($object, $funcname, $args)

Returns: mixed The result of the called method


  • object $object Object to call methos in

  • string $funcname Name of method to call

  • array $args Arguments to pass to the method


Checks if a method exists in a class.
This performs cached searches, so it is faster than native method_exists function when called
multiple times.

Definition: public function system_method_exists($object_or_classname, $method_name)

Returns: bool true or false


  • mixed $object_or_classname Object or classname to check

  • string $method_name Name of method to check for


Shuffle an array and preserve key=>value binding

Definition: public function shuffle_assoc($array)

Returns: void


  • array $array Array to be shuffled


Renders a complete object tree. This means that the tree is checked for Renderable objects, arrays and so on
and all the needed actions are triggered recursively.

Definition: public function system_render_object_tree($array_of_objects)

Returns: mixed An array containing the rendered strings


  • array $array_of_objects Array of objects


INTERNAL Called from the autoloader and used for backwards compatibility: This is needed for projects that do not yet use WDF with namespaces).


INTERNAL Maps a classname given as string to a full qualified class identifier.


Checks if a process it still running.
Note that this depends on shell_exec(), so make sure it not disabled in php.ini.

Definition: public function system_process_running($pid)

Returns: bool true if running, else false


  • int $pid Process id to check


Creates a named lock.
This is useful in some special cases where different PHP processes are creating for example datasets that must be
unique. So use it like this:

// do critical things   

Note that system_get_lock will check all existent locks if the processes that created them are still running
by using system_process_running(). That one depends on shell_exec() so make sure it is not disabled.
Another note to the datasource argument: This defaults to 'internal' and the 'internal' datasource defaults to 'sqlite:memory'. So if you dont change this the locks will have no effect beyond process bounds!

Definition: public function system_get_lock($name, $datasource, $timeout)

Returns: void|bool Returns true|false only if $timeout is <=0. Else will return nothing or throw an exception


  • string $name A name for the lock.

  • mixed $datasource Name of datasource to use or DataSource object itself.

  • int $timeout Timeout in seconds (an Exception will be thrown on timeout). If <=0 will return immediately true|false


Releases a named lock.
See system_get_lock() for details about this.

Definition: public function system_release_lock($name, $datasource)

Returns: void


  • string $name Name of the lock to release

  • mixed $datasource Name of datasource to use or DataSource object itself.