>> YANA 4 PHP Framework >> Docs for page toolbox.php

/includes/toolbox.php

Description

Common tools

This file contains a variety of tools that might be usefull to all applications, no matter wether the use the rest of the framework or not.

Functions

Lowercase or uppercase all keys of an associative array
array changeCaseArray (
array $input, [int|bool $case = CASE_LOWER]
)
List of parameters:
Name Type Description
$input array
$case int|bool CASE_UPPER or CASE_LOWER
Description:

This is a recursive implementation of the PHP function array_change_key_case(). It takes the same arguments: an array $input to work on and an optional argument $case. The argument $case can be one of two constants: CASE_LOWER and CASE_UPPER, where CASE_LOWER is the default.

As of version 2.8.8 this function was replaced by Hashtable::changeCase() and marked deprecated.

check the list of arguments for correct data types
bool(true)|string checkArgumentList (
array $arguments, array $types, [string $name = ""]
)
List of parameters:
Name Type Description
$arguments array list of arguments
$types array list of types, with the following values: IS_INT, IS_STRING, IS_FLOAT, IS_BOOL, IS_ARRAY, IS_SCALAR, IS_NUMERIC, IS_OBJECT, IS_RESOURCE, IS_NULL
$name string optional name of calling function
Description:

This function returns bool(true) on success, or a string containing an error message if it fails.

Example:

  1.  function foo1 ($int$number)
  2.  {
  3.  $chk checkArgumentList(func_num_args()array(IS_INTIS_INT IS_FLOAT));
  4.  $chk === true || die($chk);
  5.  // ...
  6.  }
  7.  // You may exclude an argument from the check by using IS_MIXED
  8.   function foo2 ($int$mixed$bool)
  9.  {
  10.  $chk checkArgumentList(func_num_args()array(IS_INTIS_MIXEDIS_BOOL));
  11.  $chk === true || die($chk);
  12.  // ...
  13.  }
  14.  // You may have an optional argument by using IS_NULL
  15.   function foo3 ($int$bool false)
  16.  {
  17.  $chk checkArgumentList(func_num_args()array(IS_INTIS_NULL|IS_BOOL));
  18.  $chk === true || die($chk);
  19.  // ...
  20.  }
  21.  // When checking a single argument you may shorten the function call by
  22.  // providing the second argument as an integer instead of an array.
  23.   function foo4 ($string)
  24.  {
  25.  $chk checkArgumentList(func_num_args()IS_STRING);
  26.  $chk === true || die($chk);
  27.  // ...
  28.  }
  29.  // As an option you may include the name of the calling function in error messages
  30.   function foo5 ($int$bool false)
  31.  {
  32.  $chk checkArgumentList(func_num_args()array(IS_INTIS_NULL|IS_BOOL)__FUNCTION__);
  33.  $chk === true || die($chk);
  34.  // ...
  35.  }

Note that you may combine types by using the '|' operator, like: IS_INT | IS_FLOAT.

To conclude this, here is a brief "best-practice" example. This is a pattern I personally would suggest you to use.

  1.  $types array(
  2.  IS_STRING,          // argument 1
  3.   IS_NULL|IS_STRING,  // argument 2
  4.   IS_NULL|IS_INT      // argument 3
  5.   );
  6.  $chk checkArgumentList(func_get_args()$types__FUNCTION__);
  7.  if ($chk !== true{
  8.      trigger_error($chk);
  9.      return false;
  10.  }
Keep the "argument X" comments for better readability.

Be warned that this function is meant to be used for situations where you can live with a certain overhead to profit from additional means of security. If a function can only be called from another function, which already has checked the input arguments, you may want to use assertions and type casting instead.

  • since: 2.8.8
recursive deep-copy on arrays
array cloneArray (
array $array
)
List of parameters:
Name Type Description
$array array input array that should be cloned
Description:

This function creates a deep-copy of the input $array and returns it.

"Deep-copy" means, it tries to clone objects registered in the array by calling the function "copy()", if the object has any, or by using the keyword "clone" as of PHP 5.

Note that this will not work correctly, if the object has neither the one nor the other.

  • since: 2.8.5
list contents of a directory
array dirlist (
string $dir, [string $filter = ""], [int $switch = YANA_GET_ALL]
)
List of parameters:
Name Type Description
$dir string
$filter string
$switch int possible values YANA_GET_ALL, YANA_GET_DIRS, YANA_GET_FILES
Description:

The argument $filter may contain multiple file extension, use a pipe '|' sign to seperate them. Example: "*.xml|*.html" will find all xml- and html-files

The argument $switch may be used to get only subdirectories (YANA_GET_DIRS), or only files (YANA_GET_FILES), or all contents (YANA_GET_ALL), which is the default.

recursively merge two arrays to one
array mergeArrays (
array $A, array $B
)
List of parameters:
Name Type Description
$A array
$B array
Description:

This function is pretty much the same as the php function "array_merge_recursive" except for the way how duplicate keys are treated. Dupplicate keys get replaced in this implementation rather than being appended.

As of version 2.8.8 this function was replaced by Hashtable::merge() and marked deprecated.

search for a value in a sorted list
int|bool(false) qSearchArray (
array &$array, scalar $needle
)
List of parameters:
Name Type Description
&$array array
$needle scalar
Description:

If the array contains $needle, the key of $needle is returned. Otherwise this functions returns bool(false).

This function does something similar to PHP's in_array(), except, that it expects the input to be a numeric, unique, sorted array.

If the input is sorted, searching for a key is far more performant using this function than the original, especially for large arrays.

To be more technical: qSearchArray() performs the search on a sorted array in O(log(n)) running time, which is the same as searching for a key in a red-black tree. while a "normal", full scan of the array takes O(n) running time.

Example:

  1.  // Search through a large, sorted, numeric array of strings.
  2.  // E.g. a file where each line is representing a value.
  3.   $list file('large_file.txt');
  4.  if (is_array($list)) {
  5.      $i qSearchArray($list'foo');
  6.      if ($i === false{
  7.          print "Value 'foo' not found!\n";
  8.      else {
  9.          print "Found 'fooin line $i.\n";
  10.      }
  11.  }

Untaint user input taken from a web form
mixed untaintInput (
mixed $value, [string $type = ""], [int $length = 0], [int $escape = 0]
)
List of parameters:
Name Type Description
$value mixed the input data
$type string desired type, note that this should always be a scalar type
$length int maximum length
$escape int choose how special characters should be treated
Description:

This function scrubbs your user input data shiny and clean.

It ensures: the data has a given type, maximum length, and syntax. E.g. if the data comes out of an input-field use this function with the argument $escape set to YANA_ESCAPE_LINEBREAK, to enforce the input does not have any unexpected line breaks.

Valid values for parameter $type:

  • int, integer
  • float, double
  • boolean, bool
  • string
  • object
  • time = the input is an unix time code
  • mail = the input is a mail adress
  • ip = the input is an IP adress
  • select = the input is taken from a select field (treated as "string")
  • text = the input is taken from a textarea field (treated as "string")
  • upload = the input is the index of the uploaded file in the $_FILES-array

Note: type "upload" will return the path to the uploaded file on success and an integer error constant on error. See the PHP manual for details on these codes.

Valid values for parameter $escape:

  • YANA_ESCAPE_NONE = leave special chars alone (default)
  • YANA_ESCAPE_SLASHED = apply addslashes()
  • YANA_ESCAPE_TOKEN = replace template delimiters with html-entities
  • YANA_ESCAPE_CODED = convert all characters to html-entities
  • YANA_ESCAPE_LINEBREAK = revert all white-space to spaces
    (for security reasons you should ALWAYS use this setting if you
    expect data from any other field than textarea)
  • YANA_ESCAPE_USERTEXT = treat full-text message from an textarea element,
    prevents flooding by removing doubled elements

Interpretation of the $length parameter depends on the $type argument given.

  • no type = interpreted as maximum length of characters (implicit string conversion)
  • string = maximum length of characters
  • integer = maximum number of digits
  • float = maximum number of digits
  • upload = maximum size of file in bytes

For type float and integer, if the number of digits exceeds the maximum, the maximum number allowed will be returned instead.

For type float see the following examples:

 $value=-3,     $length=1 : return -3
 $value=3.2,    $length=1 : return 3
 $value=3.4,    $length=1 : return 3
 $value=3.5,    $length=1 : return 4
 $value=3.6,    $length=1 : return 4
 $value=9.9,    $length=1 : return 9
 $value=10,     $length=1 : return 9
 $value=1.11,   $length=2 : return 1.1
 $value=11.11,  $length=2 : return 11
 $value=111.11, $length=2 : return 99
 $value=0.115,  $length=2 : return .12

If type is "image", the input value should be the index of the file in the $_FILES array. The function will return the name of the file or an integer, to identify the error encountered. See the PHP manual at php.net/docs "Features / Handling file uploads / Error Messages Explained" for detailed information about the returned error codes. In addition the function will return bool(false) if the uploaded file is not an image.

  • uses: $saveInput - = untaintInput($_GET['message'], 'string', 1024, YANA_ESCAPE_USERTEXT)

Documentation generated on Sun, 11 Mar 2007 15:02:55 +0100 by phpDocumentor 1.3.1

yana author: Thomas MeyerHomepage: www.yanaframework.net