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 ⁽⁴⁵⁾

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