Procedural File: _misc.funcs.php
Source Location: /qp_inc/_core/_misc.funcs.php
Page Details
This file implements general purpose functions.
This file is part of Quam Plures - http://quamplures.net/ See also https://launchpad.net/quam-plures.
| Author: | fplanque: Francois PLANQUE. |
| Author: | blueyed: Daniel HAHLER. |
| Author: | cafelog (team) |
| Author: | jeffbearer: Jeff BEARER. |
| Author: | sakichan: Nobuo SAKIYAMA. |
| Author: | vegarg: Vegar BERG GULDAL. |
| Author: | mbruneau: Marc BRUNEAU / PROGIDISTRI |
| Copyright: | (c)2003-2009 by Francois PLANQUE - http://fplanque.net/ Parts of this file are copyright (c)2004-2006 by Daniel HAHLER - http://thequod.de/contact. Parts of this file are copyright (c)2005-2006 by PROGIDISTRI - http://progidistri.com/. |
| Copyright: | (c) 2009 - 2011 by the Quam Plures developers - http://quamplures.net/ |
| Todo: | dh> Refactor into smaller chunks/files. We should avoid using a "huge" misc early! - _debug.funcs.php
- _formatting.funcs.php
- _date.funcs.php
- ?
NOTE: Encapsulation functions into classes would allow using autoloading (http://php.net/autoload) in PHP5..! |
| Filesource: | Source Code for this file |
Functions
string action_icon(
string $title, string $icon, string $url, [string $word = NULL], [integer $icon_weight = NULL], [integer $word_weight = NULL], [array $link_attribs = array()]
)
|
|
Create IMG tag for an action icon.
Parameters:
|
string |
$title: |
TITLE text (IMG and A link) |
|
string |
$icon: |
icon code for get_icon() |
|
string |
$url: |
URL where the icon gets linked to (empty to not wrap the icon in a link) |
|
string |
$word: |
word to be displayed after icon (if no icon gets displayed, $title will be used instead!) |
|
integer |
$icon_weight: |
1-5: weight of the icon. The icon will be displayed only if its weight is >= than the user setting threshold. Use 5, if it's a required icon - all others could get disabled by the user. (Default: 4) |
|
integer |
$word_weight: |
1-5: weight of the word. The word will be displayed only if its weight is >= than the user setting threshold. (Default: 1) |
|
array |
$link_attribs: |
Additional attributes to the A tag. The values must be properly encoded for html output (e.g. quotes). It may also contain these params: - 'use_js_popup': if true, the link gets opened as JS popup. You must also pass an "id" attribute for this!
- 'use_js_size': use this to override the default popup size ("500, 400")
- 'class': defaults to 'action_icon', if not set; use "" to not use it
|
API Tags:
| Return: | The generated action icon link. |
boolean array_equal(
array $one, array $two
)
|
|
Check if two arrays contain the same elements.
Parameters:
|
array |
$one: |
The first array. |
|
array |
$two: |
The second array. |
API Tags:
| Return: | True if both arrays contain the same elements, false otherwise. |
void autobrize(
$content
)
|
|
Parameters:
autobrize_callback [line 362]
string autobrize_callback(
string $content
)
|
|
Adds 's to non code blocks
Parameters:
API Tags:
| Return: | content with 's added |
bad_request_die [line 1821]
void bad_request_die(
[string $additional_info = '']
)
|
|
Outputs Bad request Error message. When in debug mode it also prints a backtrace.
This should be used when a bad user input is detected?
Parameters:
|
string |
$additional_info: |
Message to output (HTML) |
callback_on_non_matching_blocks [line 642]
string callback_on_non_matching_blocks(
string $text, string $pattern, callback $callback, [array $params = array()]
)
|
|
Split $text into blocks by using $pattern and call $callback on the non-matching blocks.
The non-matching block's text is the first param to $callback and additionally $params gets passed. This gets used to make links clickable or replace smilies. E.g., to replace only in non-HTML tags, call it like:
Parameters:
|
string |
$text: |
Text to handle |
|
string |
$pattern: |
Regular expression pattern that defines blocks to exclude. |
|
callback |
$callback: |
Function name or object/method array to use as callback. Each non-matching block gets passed as first param, additional params may be passed with $params. |
|
array |
$params: |
Of additional ("static") params to $callback. |
API Tags:
void compact_date(
string $date
)
|
|
Compact a date in a number keeping only integer value of the string
Parameters:
void convert_chars(
$content, [ $flag = 'html']
)
|
|
Convert all non ASCII chars (except if UTF-8, GB2312 or CP1251) to &#nnnn; unicode references.
Also convert entities to &#nnnn; unicode references if output is not HTML (eg XML) Preserves < > and quotes. fplanque: simplified sakichan: pregs instead of loop
Parameters:
*** // Formatting functions ****
Parameters:
date_add_days [line 1009]
integer date_add_days(
integer $timestamp, integer $days
)
|
|
Add given # of days to a timestamp
Parameters:
|
integer |
$timestamp: |
timestamp |
|
integer |
$days: |
days |
API Tags:
void date_i18n(
string $dateformatstring, integer $unixtimestamp, [boolean $useGM = false]
)
|
|
Date internationalization: same as date() formatting but with i18n support
Parameters:
|
string |
$dateformatstring: |
enhanced format string |
|
integer |
$unixtimestamp: |
UNIX timestamp |
|
boolean |
$useGM: |
true to use GM time |
void date_sprintf(
$string, $timestamp
)
|
|
Format dates into a string in a way similar to sprintf()
Parameters:
date_sprintf_callback [line 1026]
void date_sprintf_callback(
$matches
)
|
|
Parameters:
void debug_die(
[string $additional_info = ''], [array $params = array()]
)
|
|
Outputs Unexpected Error message. When in debug mode it also prints a backtrace.
This should be used instead of die() everywhere. This should NOT be used instead of exit() anywhere. Dying means the application has encontered and unexpected situation, i-e: something that should never occur during normal operation. Examples: database broken, user changed URL by hand...
Parameters:
|
string |
$additional_info: |
Message to output |
|
array |
$params: |
Additional params - "status" (Default: '500 Internal Server Error')
|
void debug_fopen(
$filename, $mode
)
|
|
Parameters:
void debug_fwrite(
$fp, $string
)
|
|
Parameters:
debug_get_backtrace [line 1502]
string debug_get_backtrace(
[integer|NULL $limit_to_last = NULL], [array $ignore_from = array( 'function' => 'debug_get_backtrace' )], [integer $offset_ignore_from = 0]
)
|
|
Get a function trace from http://www.php.net/debug_backtrace as html table.
Adopted from http://us2.php.net/manual/de/function.debug-backtrace.php#47644.
Parameters:
|
integer|NULL |
$limit_to_last: |
Get the last x entries from the stack (after $ignore_from is applied). Anything non-numeric means "all". |
|
array |
$ignore_from: |
After a key/value pair matches a stack entry, this and the rest is ignored. For example, array('class' => 'DB') would exclude everything after the stack "enters" class DB and everything that got called afterwards. You can also give an array of arrays which means that every condition in one of the given array must match. |
|
integer |
$offset_ignore_from: |
Number of stack entries to include, after $ignore_from matches. |
API Tags:
void debug_info(
[boolean $force = false], [boolean $force_clean = false]
)
|
|
T-Tag: Outputs debug info according to $debug or $force param.
Parameters:
|
boolean |
$force: |
true to force output regardless of $debug |
|
boolean |
$force_clean: |
true to force clean output (without HTML) regardless of $is_cli |
decompact_date [line 2949]
void decompact_date(
string $date
)
|
|
Decompact a date in a date format ( Y-m-d h:m:s )
Parameters:
void disp_cond(
mixed $var, string $disp_one, [string $disp_more = NULL], [string $disp_none = NULL]
)
|
|
If first parameter evaluates to true printf() gets called using the first parameter as args and the second parameter as print-pattern
Parameters:
|
mixed |
$var: |
variable to test and output if it's true or $disp_none is given |
|
string |
$disp_one: |
printf-pattern to use (%s gets replaced by $var) |
|
string |
$disp_more: |
printf-pattern to use, if $var is numeric and > 1 (%s gets replaced by $var) |
|
string |
$disp_none: |
printf-pattern to use if $var evaluates to false (%s gets replaced by $var) |
string evo_strlen(
string $string
)
|
|
mbstring wrapper for strlen function
Parameters:
string evo_substr(
string $string, [int $start = 0], [int $length = '#']
)
|
|
mbstring wrapper for substr function
Parameters:
|
string |
$string: |
|
|
int |
$start: |
start position |
|
int |
$length: |
string length |
format_french_phone [line 3019]
void format_french_phone(
string $phone
)
|
|
Format a string in a french phone number
Parameters:
|
string |
$phone: |
phone number |
void format_phone(
string $phone, [ $hide_country_dialing_code_if_same_as_locale = true]
)
|
|
Check the format of the phone number param and format it in a french number if it is.
Parameters:
|
string |
$phone: |
phone number |
|
|
$hide_country_dialing_code_if_same_as_locale: |
|
string format_to_js(
string $unformatted
)
|
|
Basic tidy up of strings
Parameters:
|
string |
$unformatted: |
raw data |
API Tags:
Information Tags:
| Author: | Yabba |
| Author: | Tblue |
format_to_output [line 271]
string format_to_output(
string $content, [string $format = 'htmlbody']
)
|
|
Format a string/content for being output
Parameters:
|
string |
$content: |
raw text |
|
string |
$format: |
format, can be one of the following - raw: do nothing
- htmlbody: display in HTML page body: allow full HTML
- entityencoded: Special mode for RSS 0.92: allow full HTML but escape it
- htmlhead: strips out HTML (mainly for use in Title)
- htmlattr: use as an attribute: escapes quotes, strip tags
- formvalue: use as a form value: escapes quotes and < > but leaves code alone
- text: use as plain-text, e.g. for ascii-mails
- xml: use in an XML file: strip HTML tags
- xmlattr: use as an attribute: strips tags and escapes quotes
|
API Tags:
Information Tags:
| Author: | fplanque |
| Todo: | htmlspecialchars() takes a charset argument, which we could provide ($evo_charset?) |
void form_date(
string $date, [string $time = '']
)
|
|
Parameters:
|
string |
$date: |
date (YYYY-MM-DD) |
|
string |
$time: |
time |
generate_random_key [line 2840]
string generate_random_key(
[integer $length = 32], [string $keychars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789']
)
|
|
Generate a valid key of size $length.
Parameters:
|
integer |
$length: |
length of key |
|
string |
$keychars: |
chars to use in generated key |
API Tags:
generate_random_passwd [line 2860]
string generate_random_passwd(
[integer $length = 8]
)
|
|
Generate a random password with no ambiguous chars
Parameters:
|
integer |
$length: |
length of password |
API Tags:
gen_order_clause [line 3277]
string gen_order_clause(
$order_by, $order_dir, $dbprefix, $dbIDname_disambiguation
)
|
|
Generate order by clause
Parameters:
|
|
$order_by: |
|
|
|
$order_dir: |
|
|
|
$dbprefix: |
|
|
|
$dbIDname_disambiguation: |
|
get_available_sort_options [line 3255]
array get_available_sort_options(
)
|
|
API Tags:
get_base_domain [line 2800]
string get_base_domain(
string $url
)
|
|
Get the base domain (without protocol and any subdomain) of an URL.
Gets a max of 3 domain parts (x.y.tld)
Parameters:
API Tags:
| Return: | the base domain (may become empty, if found invalid) |
get_bzr_revision [line 3356]
boolean|int get_bzr_revision(
)
|
|
Get the Bazaar revision of this QP installation.
Useful for snapshot users etc. -- they can include it in bug reports. This function tries to find out the current revision from the .bzr control directory or from the file .bzrrevision in the installation root (this is used for snapshots).
API Tags:
| Return: | false on failure, the bzr revision otherwise. |
mixed &get_Cache(
string $objectName
)
|
|
Get a cache reference.
Parameters:
|
string |
$objectName: |
The cache to get (see source code for possible names). |
API Tags:
| Return: | The requested cache (debug_die()s on invalid cache name). |
Information Tags:
| Todo: | fp> split into 1 function per case. (typed @return values) |
get_field_attribs_as_string [line 3065]
string get_field_attribs_as_string(
array $field_attribs, [boolean $format_to_output = true]
)
|
|
Build a string out of $field_attribs, with each attribute prefixed by a space character.
Parameters:
|
array |
$field_attribs: |
Array of field attributes. |
|
boolean |
$format_to_output: |
Use format_to_output() for the attributes? |
void get_icon(
string $iconKey, [string $what = 'imgtag'], [array $params = NULL], [boolean $include_in_legend = false]
)
|
|
Get properties of an icon.
Note: to get a file type icon, use File::get_icon() instead.
Parameters:
|
string |
$iconKey: |
icon for what? (key) |
|
string |
$what: |
what to return for that icon ('imgtag', 'alt', 'legend', 'file', 'url', 'size' imgsize()) |
|
array |
$params: |
additional params ( 'class' => class name when getting 'imgtag', 'size' => param for 'size', 'title' => title attribute for 'imgtag') |
|
boolean |
$include_in_legend: |
true to include this icon into the legend at the bottom of the page (works for 'imgtag' only) |
API Tags:
get_IconLegend [line 3302]
Get the IconLegend instance.
API Tags:
| Return: | or false, if the user has not set "display_icon_legend" |
array|string get_ip_list(
[boolean $firstOnly = false]
)
|
|
Get list of client IP addresses from REMOTE_ADDR and HTTP_X_FORWARDED_FOR, in this order. '' is used when no IP could be found.
Parameters:
|
boolean |
$firstOnly: |
True, to get only the first IP (probably REMOTE_ADDR) |
API Tags:
| Return: | Depends on first param. |
get_link_showhide [line 2906]
string get_link_showhide(
string $link_id, string $target_id, $text_when_displayed, $text_when_hidden, [ $display_hidden = true]
)
|
|
Generate a link that toggles display of an element on clicking.
Parameters:
|
string |
$link_id: |
ID (html) of the link |
|
string |
$target_id: |
ID (html) of the target to toggle displaying |
|
|
$text_when_displayed: |
|
|
|
$text_when_hidden: |
|
|
|
$display_hidden: |
|
API Tags:
| Uses: | toggle_display_by_id() - (JS) |
Information Tags:
| Todo: | Provide functionality to make those links accessible without JS (using GET parameter) |
get_manual_link [line 3037]
string get_manual_link(
string $topic
)
|
|
Generate a link to a online help resource.
testing the concept of online help (aka webhelp). this function should be relocated somewhere better if it is taken onboard by the project
Parameters:
Information Tags:
| Todo: | (legacy): replace [?] with icon, |
| Todo: | (legacy): write url suffix dynamically based on topic and language |
get_start_date_for_week [line 1041]
void get_start_date_for_week(
integer $year, integer $week, integer $startofweek
)
|
|
Parameters:
|
integer |
$year: |
year |
|
integer |
$week: |
month (0-53) |
|
integer |
$startofweek: |
0 for sunday, 1 for monday |
get_weekstartend [line 1069]
void get_weekstartend(
date $date, integer $startOfWeek
)
|
|
Get start and end day of a week, based on day f the week and start-of-week
Used by Calendar
Parameters:
|
date |
$date: |
|
|
integer |
$startOfWeek: |
0 for Sunday, 1 for Monday |
implode_with_and [line 3122]
string implode_with_and(
$arr, [ $implode_by = ', '], [ $implode_last = ' &amp; ']
)
|
|
Implode array( 'x', 'y', 'z' ) to something like 'x, y and z'. Useful for displaying list to the end user.
If there's one element in the table, it is returned. If there are at least two elements, the last one is concatenated using $implode_last, while the ones before are imploded using $implode_by.
Parameters:
|
|
$arr: |
|
|
|
$implode_by: |
|
|
|
$implode_last: |
|
Information Tags:
| Todo: | dh> I don't think using entities/HTML as default for $implode_last is sane! Use "&" instead and make sure that the output for HTML is HTML compliant.. |
| Todo: | Support for locales that have a different kind of enumeration?! |
is_admin_page [line 3103]
Is the current page an admin/backoffice page?
is_create_action [line 2870]
void is_create_action(
$action
)
|
|
Parameters:
bool is_email(
string $email, [string $format = 'simple']
)
|
|
Check that email address looks valid.
Parameters:
|
string |
$email: |
email address to check |
|
string |
$format: |
Format to use ('simple', 'rfc') 'simple': Single email address. 'rfc': Full email address, may include name (RFC2822) - example@example.org
- Me <example@example.org>
- "Me" <example@example.org>
|
API Tags:
Are we running on a Windows server?
jsspecialchars [line 2923]
string jsspecialchars(
string $s
)
|
|
Escape a string to be used in Javascript.
Parameters:
void load_funcs(
$funcs_path
)
|
|
Load functions file
Parameters:
mail_encode_header_string [line 2224]
void mail_encode_header_string(
string $header_str, [string $mode = 'Q']
)
|
|
Encode to RFC 1342 "Representation of Non-ASCII Text in Internet Message Headers"
Parameters:
|
string |
$header_str: |
|
|
string |
$mode: |
'Q' for Quoted printable, 'B' for base64 |
mail_sanitize_header_string [line 2205]
void mail_sanitize_header_string(
$header_str, [ $close_brace = false]
)
|
|
Prevent email header injection.
Parameters:
|
|
$header_str: |
|
|
|
$close_brace: |
|
make_clickable [line 692]
string make_clickable(
$text, [ $moredelim = '&amp;'], [ $callback = 'make_clickable_callback']
)
|
|
Make links clickable in a given text.
It replaces only text which is not between <a> tags already.
Parameters:
|
|
$text: |
|
|
|
$moredelim: |
|
|
|
$callback: |
|
Information Tags:
| Todo: | dh> this should not replace links in tags! currently fails for something like '<img src=" http://example.com/" />' (not usual though!) fp> I am trying to address this by not replacing anything inside tags fp> This should be replaced by a clean state machine (one single variable for current state) |
make_clickable_callback [line 823]
string make_clickable_callback(
$text, [ $moredelim = '&amp;']
)
|
|
Callback function for make_clickable().
original function: phpBB, extended here for AIM & ICQ fplanque restricted :// to http:// and mailto:// Fixed to not include trailing dot and comma. fp> I'm thinking of moving this into the autolinks plugin (only place where it's used) and break it up into something more systematic.
Parameters:
API Tags:
| Return: | The clickable text. |
modules_call_method [line 63]
void modules_call_method(
$method_name
)
|
|
Call a method for all modules in a row
Parameters:
void mysql2date(
string $dateformatstring, string $mysqlstring, [boolean $useGM = false]
)
|
|
Format a MYSQL date.
Parameters:
|
string |
$dateformatstring: |
enhanced format string |
|
string |
$mysqlstring: |
MYSQL date YYYY-MM-DD HH:MM:SS |
|
boolean |
$useGM: |
true to use GM time |
mysql2datestamp [line 865]
void mysql2datestamp(
$m
)
|
|
Convert a MYSQL date -- WITHOUT the time -- to a UNIX timestamp
Parameters:
mysql2localedate [line 875]
void mysql2localedate(
string $mysqlstring
)
|
|
Format a MYSQL date to current locale date format.
Parameters:
|
string |
$mysqlstring: |
MYSQL date YYYY-MM-DD HH:MM:SS |
mysql2localedatetime [line 885]
void mysql2localedatetime(
$mysqlstring
)
|
|
Parameters:
mysql2localedatetime_spans [line 890]
void mysql2localedatetime_spans(
$mysqlstring, [ $datefmt = NULL], [ $timefmt = NULL]
)
|
|
Parameters:
|
|
$mysqlstring: |
|
|
|
$datefmt: |
|
|
|
$timefmt: |
|
mysql2localetime [line 880]
void mysql2localetime(
$mysqlstring
)
|
|
Parameters:
mysql2timestamp [line 857]
void mysql2timestamp(
$m
)
|
|
Convert a MYSQL date to a UNIX timestamp
Parameters:
void pre_dump(
$var__var__var__var__,... $var__var__var__var__
)
|
|
Wrap pre tag around http://www.php.net/var_dump for better debugging.
Parameters:
|
$var__var__var__var__,... |
$var__var__var__var__: |
mixed variable(s) to dump |
send_javascript_message [line 3155]
void send_javascript_message(
[array $methods = array()], [boolean $send_as_html = false], [string $target = '']
)
|
|
Send a result as javascript automatically includes any Messages ( @see Log::display() ) no return from function as it terminates processing
Parameters:
|
array |
$methods: |
javascript funtions to call with array of parameters format : 'function_name' => array( param1, parm2, param3 ) |
|
boolean |
$send_as_html: |
Wrap the script into an html page with script tag; default is to send as js file |
|
string |
$target: |
prepended to function calls : blank or window.parent |
Information Tags:
| Author: | Yabba |
| Todo: | dh> Move this out into some more specific (not always included) file. |
boolean send_mail(
string $to, string $to_name, string $subject, string $message, [string $from = NULL], [string $from_name = NULL], [array $headers = array()]
)
|
|
Sends a mail, wrapping PHP's mail() function.
$current_locale will be used to set the charset. Note: we use a single \n as line ending, though it does not comply to RFC2822, but seems to be safer, because some mail transfer agents replace \n by \r\n automatically.
Parameters:
|
string |
$to: |
Recipient email address. (Caould be multiple comma-separated addresses.) |
|
string |
$to_name: |
Recipient name. (Only use if sending to a single address) |
|
string |
$subject: |
Subject of the mail |
|
string |
$message: |
The message text |
|
string |
$from: |
From address, being added to headers (we'll prevent injections); see http://securephp.damonkohler.com/index.php/Email_Injection. Defaults to $notify_from if NULL. |
|
string |
$from_name: |
From name. |
|
array |
$headers: |
Additional headers ( headername => value ). Take care of injection! |
API Tags:
| Return: | True if mail could be sent (not necessarily delivered!), false if not - (return value of http://www.php.net/mail) |
Information Tags:
| Todo: | Unit testing with "nice addresses" This gets broken over and over again. |
Shutdown function: update session!
This is registered in _main.inc.php with register_shutdown_function() This is called by PHP at the end of the script.
string strmaxlen(
string $str, [int $maxlen = 50]
)
|
|
Crop string to maxlen with … at the end if needed.
Parameters:
|
string |
$str: |
|
|
int |
$maxlen: |
Maximum length |
string strmaxwords(
string $str, [int $maxwords = 50], [mixed $params = array()]
)
|
|
Crop string to maxwords preserving tags.
Parameters:
|
string |
$str: |
|
|
int |
$maxwords: |
Maximum number words |
|
mixed |
$params: |
array Optional parameters |
void unautobrize(
$content
)
|
|
Parameters:
unautobrize_callback [line 385]
string unautobrize_callback(
string $content
)
|
|
Removes 's from non code blocks
Parameters:
API Tags:
| Return: | content with 's removed |
xmlrpc_displayresult [line 1291]
void xmlrpc_displayresult(
object XMLRPC $result, [boolean $display = true], [mixed $log = '']
)
|
|
Echo the XML-RPC call Result and optionally log into file
Parameters:
|
object XMLRPC |
$result: |
response object |
|
boolean |
$display: |
true to echo |
|
mixed |
$log: |
File resource or == '' for no file logging. |
xmlrpc_getpostcategories [line 1255]
false|array xmlrpc_getpostcategories(
$content
)
|
|
Extract categories out of "<category>" tag from $content.
NOTE: w.bloggar sends something like "<category>00000013,00000001,00000004,</category>" to blogger.newPost.
Parameters:
xmlrpc_getpostcategory [line 1236]
void xmlrpc_getpostcategory(
$content
)
|
|
Also used by post by mail
Parameters:
API Tags:
| Deprecated: | by xmlrpc_getpostcategories() |
Information Tags:
| Todo: | EdB: this is used only by qp_srvc/getmail.php in v0.0.0 (EdB) |
xmlrpc_getposttitle [line 1215]
void xmlrpc_getposttitle(
$content
)
|
|
Parameters:
xmlrpc_logresult [line 1338]
boolean xmlrpc_logresult(
object XMLRPC $result, Log &$message_Log, [ $log_payload = true]
)
|
|
Log the XML-RPC call Result into LOG object
Parameters:
|
object XMLRPC |
$result: |
response object |
|
Log |
&$message_Log: |
object to add messages to |
|
|
$log_payload: |
|
API Tags:
| Return: | true = success, false = error |
xmlrpc_removepostdata [line 1275]
void xmlrpc_removepostdata(
$content
)
|
|
Parameters:
string zeroise(
string $number, integer $threshold
)
|
|
Add leading zeroes to a number when necessary.
Parameters:
|
string |
$number: |
The original number. |
|
integer |
$threshold: |
How many digits shall the number have? |
API Tags:
| Return: | The padded number. |
|
|