zoglair

This is the second core class (the other one being zObject) which is explicitly included in the bootstrap script. It wraps global configuration settings and provides critical static methods for request processing and object instantiation.

This class is instantiated as the globally available $zoglair object.

Parent Class
zObject
Public Methods (45)
bytes2str, debug, decode64, decode_text, encode64, encode_html, encode_text, explode, explode_ids, filter_post, get_active, get_data_dir, get_domain_skins, get_inrange, get_temp_file, globin, hash, indent, ini2map, is_acp, is_int, is_map, is_set, load_extension, load_plugin, load_settings, load_sitemap, load_table, merge_arrays, next_clip_id, number_format, process_url, process_url2, redirect, rel2abs, replace, set_query_var, shebang, shebang_merge, split, split_camel, trim, ucpath, uorc_error, version
Protected Methods
none

string bytes2str(integer $bytes, integer $round=2, string $space='')‎static

Converts an integer representing a size in bytes, to its string shortcut equivalent, properly tagged. For example:

$s = zoglair::bytes2str(123456); // $s = 120.56KB

Parameters
• The size (in bytes) to be converted
• Number of decimal digits (precision)
• Delimiter between number and unit
Returns
The input converted

boolean debug(string $what)‎static

Checks the status of a binary debug flag, as set in the System settings dialog in ACP, or the debug dialog.

Parameters
The name of the flag to check. It can be “js”,“css”,“sql”,“coreDump” or “outputBuffer”.
Returns
TRUE if the flag is set, FALSE if not

mixed decode64(string $str)‎static

The reverse of encode64().

Parameters
The output of the encoding counterpart
Returns
Any serializable PHP element

See also encode64().

string decode_text(string $text, string $tag=self::Z_TAG_PASSTHROUGH)‎static

Decodes text blocks previously encoded with encode_text(). Please, be aware that while the encoding function accepts a single block which is encoded as a whole, this one accepts text (usually the page itself) which is searched for encoded fragments. All of them (marked with the same tag) are decoded in one call.

Parameters
• The text to be searched for encoded fragments
• The tag used for encoding those fragments
Returns
The input text with all encoded fragments decoded

See also encode_text().

string encode64(mixed $var)‎static

This serializes, compresses and base64 encodes an element, in one go. It uses a slightly modified base64 character set so that the result is both url safe and fully compatible with zoglair parsing functions.

Parameters
Any serializable PHP element
Returns
The input encoded

See also decode64().

string encode_html(string $html)‎static

A plain wrapper of htmlspecialchars() using proper values for the default parameters. Please, do not use the PHP function as it may lead to problems.

Parameters
The html to be encoded (converted)
Returns
The encoded input, with all special (and unsafe) chars converted to html entities

string encode_text(string $text, string $tag=self::Z_TAG_PASSTHROUGH)‎static

Encodes a text block, like for example a <textarea> or <code> content, that should be output as is and not parsed for markup. The default $tag value is used in the final stage of the bootstrap procedure to decode text blocks previously encoded (with the same tag) during page generation. If you supply your own tag then the resulting block will be left untouched. You will be responsible for decoding it at some point before output, unless you want it to appear encoded.

Parameters
• The text to be encoded
• The tag to be used for enclosing the encoded text, so that it can be decoded back
Returns
The text encoded, or unencoded in case of this (or the tag) is empty

See also decode_text().

array explode(string $str)‎static

This is a wrapper of explode(). The difference is that it can use the first character of the string as delimiter, as long as it is not alphanumeric. If it is, then comma is used by default. For example, in “;foo;bar” the first character is the semicolon and (since it is not alphanumeric) that will be used as delimiter. This is very convenient in cases where the user is asked to enter a list of delimited words but the delimiter itself is part of one or more words. In such cases, the user may choose any unique symbol as an alternative.

Parameters
A comma delimited list of words, values, tokens, etc, to be split and fill an array
Returns
A array (vector) of the delimited substrings, or FALSE in case of the input string is empty

array explode_ids(string $str)‎static

Returns an array filled with the comma delimited ids and/or id ranges, found in $str. For example, the input string “1,3-6,8” will be parsed as if it was “1,3,4,5,6,8”.

Parameters
The input string
Returns
An array of (string) ids

array filter_post(array $POST)‎static

Filters $_POST like arrays, by encoding unsafe html characters to their entity equivalents, unless the current user has the “postHtml” privilege. No need to call it explicitly for the actual $_POST superglobal, as zoglair does it for you automatically and places the safe array under the “z_pst” info key. Generally, no zoglair plugin should access any superglobal whatsoever.

Parameters
Either $_POST or a similar array to filter
Returns
The input array filtered, or unaltered if the current user has the required privilege.

string get_active(string $what)‎static

Returns active user preferences, falling back to default values.

Parameters
The preference to return, from the following list:
  • 'lang'    ISO-639-1 language abbreviation
  • 'dir'     text direction (“ltr” or “rtl”)
  • 'from'    the first component of “dir” (“left” or “right”)
  • 'left'    same as “from”
  • 'to'      the last component of “dir” (“left” or “right”)
  • 'right'   same as “to”
  • 'nts'     number thousands separator
  • 'nds'     number decimals separator
  • 'cn'      currency name
  • 'cs'      currency symbol
  • 'lu'      length unit
  • 'wu'      weight unit
  • 'acs'     accented character set
  • 'tcs'     transliterated character set
  • 'skin'    skin and style delimited by a dot (“skin.style”)
  • 'logo'    logo associated with “skin” or the default one
  • 'node'    current sitemap node served
  • 'nodeId'  current sitemap node id
  • 'product' active products table name (product or bimPRO)
Returns
The preference requested

string get_data_dir(string $slot, boolean $create=TRUE)‎static

Returns one of the predefined system-wide writable directories, as a relative path. You can make it absolute by either prepending Z_ROOT or using rel2abs(). As all directories in zoglair, the returned path has a trailing slash.

Parameters
• One of the following predefined available slots:
  • zoglair::Z_GDD_CACHE  used by zCaheFile
  • zoglair::Z_GDD_ADDON  used by zClipLoopAddonBuild
  • zoglair::Z_GDD_TEMP   general use
  • zoglair::Z_GDD_BERI   used by zDbmsBase
  • zoglair::Z_GDD_UPLOAD used for uploaded content
  • zoglair::Z_GDD_THUMBS used for thumbnails
  • zoglair::Z_GDD_CSS    used for compiled CSS
  • zoglair::Z_GDD_PDF    used for dynamic PDFs
• Create it, if not exists?
Returns
The (relative) path to the directory requested

See also get_temp_file().

array get_domain_skins()‎static

Returns a tree of available skin.style combinatios, along with their associative logos, depending on ACP domain settings and style availability in the skin group folder.

Parameters
none
Returns
A tree of available skin choices

mixed get_inrange(mixed $val, mixed $min, mixed $max)‎static

Makes sure that a (scalar) value is between a min and a max (inclusive).

Parameters
• A scalar to be checked against given limits
• The lower limit
• The upper limit
Returns
The input value unchanged, or set to min/max

void get_temp_file()‎static

Returns the path to a temporary file inside the zoglair::Z_GDD_TEMP writable slot. The filename produced is not checked for existance. The caller is responsible for deleting (unlink) it. As all paths in zoglair, this is relative! You can convert it to absolute by either prepending Z_ROOT or using rel2abs().

Parameters
none
Returns
void

See also get_data_dir().

object globin(string $which='')‎static

Returns the instance of a global plugin. You can use this function in place of the global PHP keyword.

Parameters
The name of the globin requested. It can be one of the following:
  • 'dbms' => $zDbms
  • 'cahe' => $zCahe
  • 'auth' => $zAuth
  • 'unit' => $zUnit
  • 'skin' => $zSkin
Returns
The object requested or $zoglair itself if called without arguments.

string hash(string $str='', string $salt='')‎static

Generic hash and salt function, used for passwords, session ids, etc. If called without arguments, it returns a random hex string which can be used as a salt to a subsequent string hashing. If $str is set, a hash (with optional salt) is calculated and returned.

The input is hashed 1 to 3 times, as following: First it is cheched against the zoglair::Z_REX_HASH pattern for finding out if it is clear text or 1-pass hashed (for example, a password sent from a login form could be already hashed by javascript). If it is clear text then it is hashed. Next, it is hashed unconditionally. Finally, if the salt argument is not empty, it is concatenuated and hashed once more.

Notice: The algorithm used is defined in zoglair::Z_REX_HASH_FUNC. The output can be preg_matched against zoglair::Z_REX_HASH and its length is always zoglair::Z_REX_HASH_LEN bytes.

Parameters
• The string to be hashed (clear text or 1-pass hash)
• An optional salt to be used in hashing
Returns
A hash or salt, depending on input

string indent(string $text, integer $indent)‎static

Indents a text block according to the global zoglair define of Z_TAB_WIDTH spaces per tab position (4).

Parameters
• The text to be indented
• Tab positions to indent
Returns
The input text indented

array ini2map(string $ini, boolean $sections=FALSE)‎static

Converts an *.ini-like block of text (string) to an associative array (map). Such blocks are quite common in zoglair database. The string is expected to be consisted of lines ended with 0x0A (the default line ending) and each line to contain a name=value pair. Spaces are trimmed and all values are treated as strings.

Notice: This is no wrapper or substitute of parse_ini_string().

Parameters
• The string to be parsed and converted
• By setting this to TRUE, the result will be a tree (with sections as keys) instead of a map
Returns
The string converted to a map

boolean is_acp()‎static

Used for finding out if the current request comes from inside ACP. This is needed for switching the skin and the menus, as well as for adjusting the phrasing mechanism.

Parameters
none
Returns
TRUE if running ACP, FALSE if not

boolean is_int(mixed $mixed)‎static

Finds whether a variable is integer or a string of digits. It substitutes is_numeric() because that one accepts sign, decimals and exponents, things that we do not want when checking for a passed id.

Parameters
The variable being evaluated
Returns
TRUE if $mixed is integer, FALSE otherwise

boolean is_map(mixed $mixed)‎static

Finds whether a variable is a map (associative array).

Parameters
The variable being evaluated
Returns
TRUE if $mixed is map, FALSE otherwise

boolean is_set(mixed $mixed)‎static

Finds whether a variable is a set (vector of associative arrays). Not to be confused with isset()!

Parameters
The variable being evaluated
Returns
TRUE if $mixed is a set, FALSE otherwise

object load_extension(mixed $Caller, string $name, boolean $base=FALSE)‎static

A load_plugin() wrapper, for loading an extension, that is, a plugin which is designed to extend a parent plugin and placed under a directory named after that. For example, the “clip/loop.php” is a plugin which has its extensions placed under “clip/loop/”.

Parameters
• The calling plugin or class
• The name of the extension to load
• If TRUE, the extension is loaded from the “base/” subdirectory (instead of the “Caller/” one)
Returns
The extension requested

object load_plugin(string $group, string $pin, mixed $args='')‎static

Vital and central dynamic class loading and instantiation function, automatically adding some basic reflection properties.

Parameters
• The group folder in which the plugin belongs, eg: “auth”, “clip”, “data”, etc
• The plugin's name, eg: “form”
• Optional arguments to be passed to the constructor, as part of its $INFO parameter: must be either a map or a string formatted like a URL query
Returns
The plugin requested or NULL in case of error

array load_settings(mixed $mixed)‎static

Loads system or user settings: persistent grouped name=value pairs. Settings are stored in the Udf database table, along with their attributes, so that they can be editable. Every setting belongs to a group according to its scope or functionality. This function retreives the group(s) of specified settings and not individual pairs.

Parameters
An object, CSV string or array with group names whose values are to be retreived. If an object is passed, then its class will be used as the group name. Examples:
  • zoglair::load_settings($MyClip)
  • zoglair::load_settings('zClipMyClip')
  • zoglair::load_settings('group1,...,groupN')
  • zoglair::load_settings(array('group1',...,'groupN'))
Returns
A tree with the settings requested: the root level is the name of the group and each entry on this level is a map with name=value pairs.

array load_sitemap()‎static

Loads the domain's sitemap, filtered by the connected user security level. The result is cached and is used for menus, link building and other internal stuff.

Parameters
none
Returns
A tree with all sitemap nodes that the connected user can access

object load_table(string $table)‎static

A load_plugin() wrapper, for loading a (database) table model. If the requested table is already loaded (instantiated), then it is reused (tables are singletons).

Parameters
A table name, as listed in the “data” group folder (without extension)
Returns
The requested table instance

array merge_arrays(array $A1, array $A2)‎static

A substitute for array_merge(), which handles array values properly (and recursively).

Parameters
• The first array to merge
• The second array to merge
Returns
An array which combines both input arrays

string next_clip_id()‎static

Generates a serial id, in the form “zClipN” (where N=1,2,...,N), for use as the “id” value of an html div holding a clip's content.

Parameters
none
Returns
A unique clip identifier

string number_format(float $number, boolean $money)‎static

A plain wrapper of number_format(), using proper values for the default parameters.

Parameters
• The number being formatted
• Is it about money?
Returns
A formatted version of $number with 2 decimals if $money is TRUE and no decimals if it is FALSE

object process_url(string $url)‎static

Processes a url, either embedded or the one initially requested by the user agent. In all cases, the url is relative and completely unrelated to the underlying file structure.

The method cracks the url, loads the appropriate content handler and - if required - loads the user specified skin to render the content. There are two kinds of url handlers: units (for browser urls) and clips (for embedded ones). There is only one call to process a browser url, and that is from inside the bootstrap code, by passing a special “magic” value as the $url parameter. All other calls are from inside templates, skins, layouts and user content.

Parameters
The url to process
Returns
The unit or clip which handled the url

mixed process_url2(string $url)‎static

This is a simple wrapper of process_url(). The only difference between them is the return value: instead of returning the object which handled the url, it returns the object's content. That is usually a string, but may be an array for JSON responces.

Parameters
The url to process
Returns
The url handler's content (usually a string)

void redirect(string $location='', integer $status=307)‎static

Outputs an HTTP Redirection header and exits. If called without arguments, it will 307 redirect to the home page.

Parameters
• The location at which the user agent is to be redirected (it can be either external or internal)
• The specific redirection status code (3xx) to be used: use 301 for a permanent redirect, or 307 (the default) for a temporary one
Returns
void

See also List of HTTP status codes.

string rel2abs(string $path)‎static

Converts a relative path (file or directory) to an absolute one. It is aware of root vs non-root paths, and handles them accordingly.

Parameters
A relative path to be converted
Returns
The input converted

string replace(string $text, array $MOV, boolean $vector=FALSE)‎static

Replaces embedded variables in a text block, with values taken from a given array, either indexed (vector) or associative (map). Variables must be enclosed in “%”, for example “this is a %var%”. If a map is given, the function will search for its keys, otherwise it will use a running index (1-based) as variable names. Index based variables are only used in phrases.

It is worth mentioning that if a value is a text block itself, then the replacement takes care of proper indentation!

Parameters
• The text to be searched and replaced
• A map or vector, holding substitution values
• Should the array passed treated as a vector?
Returns
The input text will all found variables replaced

string set_query_var(string $var, string $url='')‎static

Adds (if not exists) or changes (if exists) a given query string in a given URL. The string must be formatted as one or more “name=value” pairs, delimited by “&” (umbersand).

Parameters
• The query variable(s) to set
• The URL on which the operation will apply. If left empty, the active URL will be used.
Returns
The $url modified as requested

string shebang(string $text, mixed &$shbng)‎static

Used for extracting meta information found in the first line of a text block prefixed with a shebang. If such a line is found, then $text is splitted accordingly. Shebangs are used in various places, for example, in user content for marking up the class or style of certain paragraphs.

Parameters
• A string (text block), possibly having a shebang header
• A reference which will be filled with the contents of the shebang header (if found). If the shebang's format is a list of attributes and values, then it will become a map.
Returns
The input string unaltered, or with its header removed

void shebang_merge(array &$ROW, string $prefix='')‎static

Given a table $ROW containing a “text” column with a possible shebang, it copies any shebang defined fields, to the array. If there is no “text” key in the $ROW - or - there is no shebang, $ROW is left unaltered.

Parameters
• A map, normally the result of a database SELECT
• An optional prefix for the shebang defined fields/columns
Returns
void

void split(string $str, string &$left, string &$right, string $del=' ', boolean $trim=TRUE)‎static

Splits a string into 2 substrings separated by a given delimiter. Useful for parsing name,value pairs.

Parameters
• The string to be splitted, eg: “name value”
• A reference to hold the leading substring
• A reference to hold the trailing substring
• The delimiter to be used for splitting
• Trim substrings?
Returns
void

array split_camel(string $str, boolean $lcfirst=FALSE)‎static

Splits a camelCase identifier into its components (words).

Parameters
• The identifier to be splitted, eg: “zClipForm”
• If TRUE, lowercase each component's first character
Returns
A vector with the input's components

string trim(string $text)‎static

Trims a text block according to the global zoglair text formatting rule, that is:

  1. All combinations of CR-LF are replaced by a single LF (NL)
  2. Three or more successive LF are reduced to two
  3. Leading and trailing white space is removed
Parameters
The text to be trimmed
Returns
The input text trimmed

string ucpath(string $path)‎static

Converts a path to a class name, acting as a map between external and internal naming conventions. For example, “clip/form” will become “ClipForm”.

Parameters
A path
Returns
The path converted to its equivalent class name (without the leading “z”)

void uorc_error(object $Uorc, integer $code)‎static

Sets the status code of a unit or clip. If its content is empty, it is set to a relevant error description.

Parameters
• The unit or clip whose status is to be set
• An http status code or one of the following constants:
  • zoglair::Z_ERR_BAD_REQUEST
  • zoglair::Z_ERR_FORBIDDEN
  • zoglair::Z_ERR_NOT_FOUND
  • zoglair::Z_ERR_UNKNOWN
Returns
void

mixed version(mixed $which=1)‎static

A polymorphic function to convert between version types, or retreive addon version information.

Parameters
A timestamp (integer) or a string (formatted as “YY.MM.DD”), to be converted to string or integer respectively. If it is an integer and less than 1000, it is evaluated as an addon ID and that addon's version is returned. The default value is the ID of zoglair.
Returns
A timestamp or a string (“YY.MM.DD”), depending on input
(C) Nick B. Cassos - All Rights Reserved
powered by zoglair
page generated in 275ms (11 queries, 13ms)