phpDocumentor pond
[ class tree: pond ] [ index: pond ] [ all elements ]

Procedural File: _param.funcs.php

Source Location: /qp_inc/_core/_param.funcs.php

Page Details

This file implements parameter handling functions.

This includes:

  • sanity checking of inputs
  • removing PHP's stupid "magic" quotes
  • validating specific inputs (urls, regexps...)
  • memorizing params
  • regenerating urls with the memorized params
  • manually reconstructing urls
This file is part of Quam Plures - http://quamplures.net/ See also https://launchpad.net/quam-plures.

Author:  cafelog (team)
Author:  blueyed: Daniel HAHLER.
Author:  fplanque: Francois PLANQUE.
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/
Filesource:  Source Code for this file
Functions
balance_tags  [line 1870]

string balance_tags( string $text  )

Balances Tags of string using a modified stack.

Parameters:
string   $text:  HTML to be balanced

API Tags:
Return:  Balanced HTML


[ Top ]
check_html_sanity  [line 1636]

boolean|string check_html_sanity( string $content, [string $context = 'posting'], [integer $autobr = false], [string $encoding = NULL], [boolean $escape_comments = false]  )

Check raw HTML input for different levels of sanity including:

  • XHTML validation
  • Javascript injection
  • antispam
Also cleans up the content on some levels:
  • trimming
  • balancing tags
WARNING: this does *NOT* (necessarilly) make the HTML code safe. It only checks on it and produces error messages. It is NOT (necessarily) safe to use the output.

Parameters:
string   $content:  The content to format
string   $context:  Context: "posting", "xmlrpc_posting" or "commenting"
integer   $autobr:  Create automated
tags?
string   $encoding:  Encoding (used for XHTML_Validator only!); defaults to $io_charset
boolean   $escape_comments:  When "posting" or "xmlrpc_posting", should comments be converted to visible HTML? Forced to true when "commenting".


[ Top ]
forget_param  [line 1206]

void forget_param( string $var  )

Forget a param so that is will not get included in subsequent regenerate_url() calls.

Parameters:
string   $var:  Param name


[ Top ]
format_to_post  [line 1601]

void format_to_post( $content, [ $autobr = 0], [ $is_comment = 0], [ $encoding = NULL]  )

DEPRECATED Stub for plugin compatibility:

Parameters:
   $content: 
   $autobr: 
   $is_comment: 
   $encoding: 


[ Top ]
get_memorized  [line 1264]

void get_memorized( [mixed $ignore = '']  )

Construct an array of memorized params which are not in the ignore list

Parameters:
mixed   $ignore:  string or array of ignore params


[ Top ]
get_param  [line 1248]

NULL|mixed get_param( $var  )

Get the value of a param.

Parameters:
   $var: 

API Tags:
Return:  The value of the param, if set. NULL otherwise.


[ Top ]
is_regexp  [line 1431]

boolean is_regexp( string $reg_exp, [boolean $includes_delim = false]  )

Checks if a given regular expression is valid.

It changes the error_handler and restores it.

Parameters:
string   $reg_exp:  the regular expression to test
boolean   $includes_delim:  does the regular expression includes delimiters (and optionally modifiers)?

Information Tags:
Author:  plenque at hotmail dot com http://php.net/manual/en/function.preg-match.php

[ Top ]
memorize_param  [line 1181]

void memorize_param( string $var, string $type, mixed $default, [mixed $value = NULL]  )

Set a param (global) & Memorize it for automatic future use in regenerate_url()

Parameters:
string   $var:  Variable to memorize
string   $type:  Type of the variable
mixed   $default:  Default value to compare to when regenerating url
mixed   $value:  Value to set


[ Top ]
param  [line 76]

mixed param( string $var, [string $type = ''], [mixed $default = ''], [boolean $memorize = false], [boolean $override = false], [boolean $use_default = true], [mixed $strict_typing = 'allow_empty']  )

Sets a parameter with values from the request or to provided default, except if param is already set!

Also removes magic quotes if they are set automatically by PHP. Also forces type. Priority order: POST, GET, COOKIE, DEFAULT.

Parameters:
string   $var:  Variable to set
string   $type:  Force value type to one of:
  • integer
  • float, double
  • string (strips (HTML-)Tags, trims whitespace)
  • array (TODO: array/integer , array/array/string )
  • html (does nothing)
  • '' (does nothing)
  • '/^...$/' check regexp pattern match (string)
  • boolean (will force type to boolean, but you can't use 'true' as a default since it has special meaning. There is no real reason to pass booleans on a URL though. Passing 0 and 1 as integers seems to be best practice).
Value type will be forced only if resulting value (probably from default then) is !== NULL
mixed   $default:  Default value or TRUE if user input required
boolean   $memorize:  Do we need to memorize this to regenerate the URL for this page?
boolean   $override:  Override if variable already set
boolean   $use_default:  Force setting of variable to default if no param is sent and var wasn't set before
mixed   $strict_typing:  true will refuse illegal values, false will try to convert illegal to legal values, 'allow_empty' will refuse illegal values but will always accept empty values (This helps blocking dirty spambots or borked index bots. Saves a lot of processor time by killing invalid requests)

API Tags:
Return:  Final value of Variable, or false if we don't force setting and did not set
Usedby:  param_cookie()

Information Tags:
Todo:  when bad_request_die() gets called, the GLOBAL should not be left set to the invalid value! fp> Why? if the process dies anyway

[ Top ]
params_check_at_least_one  [line 880]

boolean params_check_at_least_one( array $vars, string $err_msg, [string|NULL $field_err_msg = NULL]  )
Parameters:
array   $vars:  of param names
string   $err_msg:  error message
string|NULL   $field_err_msg:  error message for form field ($err_msg gets used if === NULL).

API Tags:
Return:  true if OK


[ Top ]
param_action  [line 319]

string param_action( [mixed $default = ''], [ $memorize = false]  )

Get the action from params.

If we got no "action" param, we'll check for an "actionArray" param ( <input type="submit" name="actionArray[real_action]" ...> ). And the real $action will be found in the first key... When there are multiple submit buttons, this is smarter than checking the value which is a translated string. When there is an image button, this allows to work around IE not sending the value (it only sends X & Y coords of the click).

Parameters:
mixed   $default:  Default to use.
   $memorize: 


[ Top ]
param_add_message_to_Log  [line 1141]

void param_add_message_to_Log( string $var, string $err_msg, [ $log_category = 'error']  )

This function is used by param_error() and param_error_multiple().

If $link_param_err_messages_to_field_IDs is true, it will link those parts of the error message that are not already links, to the html IDs of the fields with errors.

Parameters:
string   $var:  param name
string   $err_msg:  error message
   $log_category: 


[ Top ]
param_arrayindex  [line 286]

string param_arrayindex( string $param_name, [mixed $default = '']  )

Get the param from an array param's first index instead of the value.

E.g., for "param[value]" as a submit button you can get the value with

  1. Request::param_arrayindex'param' )
.

Parameters:
string   $param_name:  Param name
mixed   $default:  Default to use

API Tags:
See:  param_action()


[ Top ]
param_check_date  [line 596]

boolean|string param_check_date( string $var, string $err_msg, [boolean $required = false], [string $date_format = NULL]  )

Check if param is an ISO date.

NOTE: for tokens like e.g. "D" (abbr. weekday), T_() gets used and it uses the current locale!

Parameters:
string   $var:  param name
string   $err_msg:  error message
boolean   $required:  Is a non-empty date required?
string   $date_format:  date format (php format)

API Tags:
Return:  false if not OK, ISO date if OK


[ Top ]
param_check_decimal  [line 421]

boolean param_check_decimal( string $var, string $err_msg, [ $required = false]  )

Checks if the param is a decimal number

Parameters:
string   $var:  param name
string   $err_msg:  error message
   $required: 

API Tags:
Return:  true if OK


[ Top ]
param_check_email  [line 483]

boolean param_check_email( string $var, [ $required = false]  )
Parameters:
string   $var:  param name
   $required: 

API Tags:
Return:  true if OK


[ Top ]
param_check_filename  [line 529]

boolean param_check_filename( string $var, string $err_msg  )

Check if the value is a file name

Parameters:
string   $var:  param name
string   $err_msg:  error message

API Tags:
Return:  true if OK


[ Top ]
param_check_html  [line 1570]

boolean|string param_check_html( string $var, [string $err_msg = '#'], [ $field_err_msg = '#'], [ $autobr = 0]  )

Checks for sanitized code.

WARNING: this does *NOT* (necessarilly) make the HTML code safe. It only checks on it and produces error messages. It is NOT (necessarily) safe to use the output.

Parameters:
string   $var:  param name
string   $err_msg:  error message
   $field_err_msg: 
   $autobr: 


[ Top ]
param_check_isregexp  [line 548]

boolean param_check_isregexp( string $var, string $err_msg, [string|NULL $field_err_msg = NULL]  )

Check if the value of a param is a regular expression (syntax).

Parameters:
string   $var:  param name
string   $err_msg:  error message
string|NULL   $field_err_msg:  error message for form field ($err_msg gets used if === NULL).

API Tags:
Return:  true if OK


[ Top ]
param_check_not_empty  [line 380]

boolean param_check_not_empty( string $var, string $err_msg, [string|NULL $field_err_msg = NULL]  )
Parameters:
string   $var:  param name
string   $err_msg:  error message
string|NULL   $field_err_msg:  error message for form field ($err_msg gets used if === NULL).

API Tags:
Return:  true if OK


[ Top ]
param_check_number  [line 398]

boolean param_check_number( string $var, string $err_msg, [ $required = false]  )

Checks if the param is an integer (no float, e.g. 3.14).

Parameters:
string   $var:  param name
string   $err_msg:  error message
   $required: 

API Tags:
Return:  true if OK


[ Top ]
param_check_passwords  [line 990]

boolean param_check_passwords( string $var1, string $var2, [boolean $required = false]  )
Parameters:
string   $var1:  param name
string   $var2:  param name
boolean   $required:  Is a password required? (non-empty)

API Tags:
Return:  true if OK


[ Top ]
param_check_phone  [line 962]

boolean param_check_phone( string $var, [ $required = false]  )
Parameters:
string   $var:  param name
   $required: 

API Tags:
Return:  true if OK


[ Top ]
param_check_range  [line 463]

boolean param_check_range( string $var, integer $min, integer $max, string $err_msg, [boolean $required = true]  )

Checks if the param is a decimal number (no float, e.g. 3.14) in a given range.

Parameters:
string   $var:  param name
integer   $min:  min value
integer   $max:  max value
string   $err_msg:  error message (gets printf'ed with $min and $max)
boolean   $required:  Is the param required?

API Tags:
Return:  true if OK


[ Top ]
param_check_url  [line 504]

boolean param_check_url( string $var, string $context, [ $field_err_msg = NULL]  )
Parameters:
string   $var:  param name
string   $context: 
   $field_err_msg: 

API Tags:
Return:  true if OK


[ Top ]
param_child_select_value  [line 940]

void param_child_select_value( string $var  )

set a parameter with the second part(X2) of the value from request ( X1-X2 )

Parameters:
string   $var:  Variable to set


[ Top ]
param_combo  [line 909]

string param_combo( string $var, mixed $default, boolean $allow_none, [string $err_msg = '']  )

Sets a combo parameter with values from the request, => the value of the select option and the input text value if new is selected Display an error if the new value is selected that the input text has a value

Parameters:
string   $var:  Variable to set
mixed   $default:  Default value or TRUE if user input required
boolean   $allow_none:  true: allows to select new without entring a value in the input combo text
string   $err_msg:  error message

API Tags:
Return:  position status ID or 'new' or '' if new is seleted but not input text value


[ Top ]
param_compact_date  [line 714]

string param_compact_date( string $var, [mixed $default = ''], [boolean $memorize = false], string $err_msg, [boolean $required = false]  )

Sets a date parameter with values from the request or to provided default, And check we have a compact date (numbers only) ( used for URL filtering )

Parameters:
string   $var:  Variable to set
mixed   $default:  Default value or TRUE if user input required
boolean   $memorize:  memorize ( see param() )
string   $err_msg:  error message
boolean   $required:  'required': Is non-empty date required? Default: true.

API Tags:
Return:  the compact date value ( yyyymmdd )


[ Top ]
param_compile_cat_array  [line 857]

void param_compile_cat_array( [ $restrict_to_blog = 0], [ $cat_default = NULL], [ $catsel_default = array()]  )

Compiles the cat array from $cat (recursive + optional modifiers) and $catsel[] (non recursive)

and keeps those values available for future reference (category widget)

Parameters:
   $restrict_to_blog: 
   $cat_default: 
   $catsel_default: 


[ Top ]
param_cookie  [line 344]

void param_cookie( $var, [ $type = ''], [ $default = ''], [ $memorize = false], [ $override = false], [ $use_default = true], [ $strict_typing = 'allow_empty']  )

Get a param from cookie.

Parameters:
   $var: 
   $type: 
   $default: 
   $memorize: 
   $override: 
   $use_default: 
   $strict_typing: 

API Tags:
See:  param()
Uses:  param()


[ Top ]
param_date  [line 570]

void param_date( string $var, string $err_msg, boolean $required, [string $default = ''], [string $date_format = NULL]  )

Sets a date parameter by converting locale date (if valid) to ISO date.

If the date is not valid, it is set to the param unchanged (unconverted).

Parameters:
string   $var:  param name
string   $err_msg:  error message
boolean   $required:  Is a non-empty date required?
string   $default:  Default (in the format of $date_format)
string   $date_format:  date format (php format), defaults to locale_datefmt()


[ Top ]
param_error  [line 1081]

void param_error( string $var, string|NULL $err_msg, [string|NULL $field_err_msg = NULL]  )

Add an error for a variable, either to the Form's field and/or the global $Messages object.

Parameters:
string   $var:  param name
string|NULL   $err_msg:  error message (by using NULL you can only add an error to the field, but not the $Message object)
string|NULL   $field_err_msg:  error message for form field ($err_msg gets used if === NULL).


[ Top ]
param_errors_detected  [line 1037]

integer param_errors_detected( )

Check if there have been validation errors

We play it safe here and check for all kind of errors, not just those from this particular class.



[ Top ]
param_error_multiple  [line 1108]

void param_error_multiple( array $vars, string|NULL $err_msg, [string|NULL $field_err_msg = NULL]  )

Add an error for multiple variables, either to the Form's field and/or the global $Messages object.

Parameters:
array   $vars:  of param names
string|NULL   $err_msg:  error message (by using NULL you can only add an error to the field, but not the $Message object)
string|NULL   $field_err_msg:  error message for form fields ($err_msg gets used if === NULL).


[ Top ]
param_extend_list  [line 804]

void param_extend_list( string $var, string $var_ext_array, [boolean $save_prefix = true]  )

Extend a LIST parameter with an ARRAY param.

Will be used for author/authorsel[], etc. Note: cannot be used for catsel[], because catsel is NON-recursive.

Parameters:
string   $var:  Variable to extend
string   $var_ext_array:  Name of array Variable to use as an extension
boolean   $save_prefix:  Save non numeric prefix? ( 1 char -- can be used as a modifier, e-g: - + * )

API Tags:
See:  param_compile_cat_array()


[ Top ]
param_get_error_msg  [line 1061]

string param_get_error_msg( $var  )

Get error message for a param

Parameters:
   $var: 


[ Top ]
param_has_error  [line 1048]

void param_has_error( $var  )

Tell if there is an error on given field.

Parameters:
   $var: 


[ Top ]
param_html  [line 1553]

string param_html( string $var, [mixed $default = ''], [boolean $memorize = false], string $err_msg  )

Sets an HTML parameter and checks for sanitized code.

WARNING: this does *NOT* (necessarilly) make the HTML code safe. It only checks on it and produces error messages. It is NOT (necessarily) safe to use the output.

Parameters:
string   $var:  Variable to set
mixed   $default:  Default value or TRUE if user input required
boolean   $memorize:  memorize ( see param() )
string   $err_msg:  error message

Information Tags:
Todo:  dh> Not implemented?!

[ Top ]
param_integer_range  [line 446]

boolean param_integer_range( string $var, integer $min, integer $max, string $err_msg, [ $required = true]  )

Gets a param and makes sure it's a decimal number (no float, e.g. 3.14) in a given range.

Parameters:
string   $var:  param name
integer   $min:  min value
integer   $max:  max value
string   $err_msg:  error message (gets printf'ed with $min and $max)
   $required: 

API Tags:
Return:  true if OK


[ Top ]
param_ismemorized  [line 1219]

void param_ismemorized( $var  )

Has the param already been memorized?

Parameters:
   $var: 


[ Top ]
param_string_not_empty  [line 367]

boolean param_string_not_empty( string $var, string $err_msg, [string|NULL $field_err_msg = NULL]  )
Parameters:
string   $var:  param name
string   $err_msg:  error message
string|NULL   $field_err_msg:  error message for form field ($err_msg gets used if === NULL).

API Tags:
Return:  true if OK


[ Top ]
param_time  [line 751]

mixed param_time( string $var, [mixed $default = ''], [boolean $memorize = false], [boolean $override = false], [boolean $forceset = true]  )

Sets a time parameter with the value from the request of the var argument or of the concat of the var argument_h: var argument_mn: var argument_s , except if param is already set!

Parameters:
string   $var:  Variable to set
mixed   $default:  Default value or TRUE if user input required
boolean   $memorize:  Do we need to memorize this to regenerate the URL for this page?
boolean   $override:  Override if variable already set
boolean   $forceset:  Force setting of variable to default?

API Tags:
Return:  Final value of Variable, or false if we don't force setting and did not set


[ Top ]
regenerate_url  [line 1307]

void regenerate_url( [mixed|string $ignore = ''], [array|string $set = ''], [mixed|string $pagefileurl = ''], [string $glue = '&amp;amp;']  )

Regenerate current URL from parameters This may clean it up But it is also useful when generating static pages: you cannot rely on $_REQUEST[]

Parameters:
mixed|string   $ignore:  (delimited by commas) or array of params to ignore (can be regexps in /.../)
array|string   $set:  Param(s) to set
mixed|string   $pagefileurl:  Alternative URL we want to point to if not the current URL (may be absolute if BASE tag gets used)
string   $glue:  Delimiter to use for multiple params (typically '&amp;' or '&')


[ Top ]
remove_magic_quotes  [line 1505]

mixed remove_magic_quotes( mixed $mixed  )

Remove quotes from input.

This handles magic_quotes_gpc and magic_quotes_sybase PHP settings/variants.

NOTE: you should not use it directly, but one of the param-functions!

Parameters:
mixed   $mixed:  string or array (function is recursive)

API Tags:
Return:  Value, with magic quotes removed


[ Top ]
set_param  [line 1236]

mixed set_param( string $var, mixed $value  )

Set the value of a param (by force! :P)

Same as setting a global, except you don't need a global declaration in your function.

Parameters:
string   $var:  Param name
mixed   $value:  Value

API Tags:
Return:  Value


[ Top ]
_trapError  [line 1450]

integer _trapError( [ $reset = 1]  )

Meant to replace error handler temporarily.

Parameters:
   $reset: 

API Tags:
Return:  number of errors


[ Top ]