functions_system

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

Functions in file system.php

system_config

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

Parameters:

  • string $filename Full path to the config file

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

system_config_default

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

Parameters:

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

system_load_module

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

Parameters:

  • string $path_to_module Complete path to module file

system_is_module_loaded

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

Parameters:

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

system_init

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

Parameters:

  • 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!

system_parse_request_path

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

SetEnv WDF_FEATURES_REWRITE on  
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

system_instanciate_controller

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

Parameters:

  • mixed $controller_id Whatever system_parse_request_path() returned

system_execute

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

system_invoke_request

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

Parameters:

  • 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

system_exit

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

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

Returns: void

Parameters:

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

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

system_die

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

Parameters:

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

  • string $additional_message More details to be logged

register_hook_function

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

Parameters:

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

  • string $handler_method name of function to call

register_hook

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

Parameters:

  • 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

execute_hooks

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

Parameters:

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

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

is_valid_hook_type

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

Parameters:

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

hook_type_to_string

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

Parameters:

  • int $type Hook type

hook_already_fired

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

Parameters:

  • int $type Hook Type

hook_bound

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

Parameters:

  • int $type Hook Type

system_stacktrace_to_string

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

Parameters:

  • array $stacktrace Use debug_backtrace() to get this

__priorize_classpath

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

Parameters:

  • string $key_to_priorize the key to be priorized

__set_classpath_order

Sets the classpath search order.

Definition: public function __set_classpath_order($class_path_order)

Returns: NOT DOCUMENTED

Parameters:

  • $class_path_order NOT DOCUMENTED

system_spl_autoload

Called whenever a class shall be instanciated but there's no definition found
See http://www.php.net/manual/de/function.spl-autoload-register.php

Definition: public function system_spl_autoload($class_name)

Returns: void

Parameters:

  • string $class_name Name of the class to load

__autoload__template

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

Parameters:

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

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

__search_file_for_class

searches the $CLASS_PATH for the file that defines the class

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

Returns:

Parameters:

  • <type> $class_name

  • <type> $extension

  • <type> $classpath_limit

buildQuery

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)

Parameters:

  • 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

samePage

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)

Parameters:

  • array|string $data Additional data

redirect

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

Parameters:

  • 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

generatePW

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

Parameters:

  • int $len The length of the return string

appendVersion

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

Parameters:

  • string $href The URL

detectUTF8

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

Parameters:

  • string $string String to check

referrer

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

Parameters:

  • string $part Name of URL parameter to get

is_host

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

Parameters:

  • string $host_or_ip Hostname or IP to be checked

cache_get

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

Parameters:

  • 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)

cache_set

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

Parameters:

  • 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

cache_del

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

Parameters:

  • string $key The key identifiying the entry

cache_clear

Clears the cache
Note that calling this will NOT clear the complete $_SESSION variale, but only
$_SESSION["system_internal_cache"].

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

Returns: void

Parameters:

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

  • bool $session_cache If true clears the SESSION cache

cache_list_keys

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

Parameters:

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

  • bool $session_cache If true checks the SESSION cache

current_controller

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

Parameters:

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

current_event

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

constant_from_name

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

Parameters:

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

  • string $constant_name name of the constant to get

name_from_constant

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

Parameters:

  • 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)

system_to_json

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

array(  
'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

Parameters:

  • mixed $value Value to be encoded as JSON

system_call_user_func_array_byref

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

Parameters:

  • object $object Object to call methos in

  • string $funcname Name of method to call

  • array $args Arguments to pass to the method

system_method_exists

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

Parameters:

  • mixed $object_or_classname Object or classname to check

  • string $method_name Name of method to check for

shuffle_assoc

Shuffle an array and preserve key=>value binding
http://www.php.net/manual/en/function.shuffle.php#94697

Definition: public function shuffle_assoc($array)

Returns: void

Parameters:

  • array $array Array to be shuffled

system_render_object_tree

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

Parameters:

  • array $array_of_objects Array of objects

create_class_alias

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

fq_class_name

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

system_process_running

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

Parameters:

  • int $pid Process id to check

system_get_lock

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:

system_get_lock('creating_something');  
// do critical things   
system_release_lock('creating_something');  

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

Parameters:

  • 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

system_release_lock

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

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

Returns: void

Parameters:

  • string $name Name of the lock to release

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