yana

Description
  Class trees
  Index of elements
  Todo List
core
  Classes
    FormCreator
    Index
    Language
    Object
    Plugin
    PluginManager
    Singleton
    SmartTemplate
    SmartView
    Utility
    Yana
database
  Classes
    DbBlob
    DbCreator
    DbDesigner4
    DbExtractor
    DbQuery
    DbQueryParser
    DbServer
    DbStream
    DbStructure
    FileDb
error_reporting
  Classes
    Alert
    Error
    ErrorUtility
    Log
    Message
    Report
    Warning
file_system
  Classes
    DatFile
    Dir
    Executeable
    File
    FileReadonly
    FileSystemResource
    SML
javascript
  Classes
    AjaxRequest
  Functions
    preview
    yanaAddEventListener
    yanaAddIcon
    yanaCheckEmbTags
    yanaCloseAll
    yanaGetCookie
    yanaGetElementsByClassName
    yanaMaxLength
    yanaMenu
    yanaMenuCookie
    yanaSetCookie
mail
  Classes
    FormMailer
    Mailer
plugins
  Classes
    plugin_blog
    plugin_check
    plugin_db_admin
    plugin_db_tools
    plugin_default_library
    plugin_diagnostics
    plugin_guestbook
    plugin_guestbook_admin
    plugin_ipblock
    plugin_ipblock_admin
    plugin_rss
    plugin_rss_admin
    plugin_sdk
    plugin_search
    plugin_search_admin
    plugin_user
    plugin_user_admin
utilities
  Classes
    Brush
    Counter
    Hashtable
    Image
    Microsummary
    RSS
    RSSitem
    String
  Functions
    checkArgumentList
    cloneArray
    dirlist
    qSearchArray
    untaintInput
    XMLencode
vdrive
  Classes
    Registry
    VDrive
zip
  Classes
    PclZip

phpDocumentor v 1.4.0

YANA Framework for PHPDocs 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.

- license: http://www.gnu.org/licenses/gpl.txt

#### Functions

##### 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_INT, IS_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_INT, IS_MIXED, IS_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_INT, IS_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_INT, IS_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
- name: function_checkArgumentList()

##### 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
- name: function_cloneArray()

##### 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.

- name: function_dirlist()

##### 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 value 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", linear 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 'foo' in line $i.\n";
10. }
11. }

- name: function_qSearchArray()

##### Untaint user input taken from a web form

mixed untaintInput (
mixed $value, [string $type = ""], [int $length = 0], [int $escape = 0], [bool $doubleEncode = false], [int $precision = -1]
)

###### 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
$doubleEncode | bool | when false, existing codes will not be encoded again (currently only with $escape=YANA_ESCAPE_USERTEXT)
$precision | int | types float and double only - number of post

###### 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
- array, set
- 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

These constants can be combined! Examples of usage:

- YANA_ESCAPE_SLASHED = just slashes
- YANA_ESCAPE_SLASHED | YANA_ESCAPE_TOKEN = slashes and token
- YANA_ESCAPE_ALL & ~YANA_ESCAPE_USERTEXT = all but usertext

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 (without fraction) - this may be combined with argument $precision
- 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 integer 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=11.11,  $length=2 : return 11
     $value=111.11, $length=2 : return 99
     $value=10,     $length=1 : return 9

The argument $precision is the maximum number of digits for the decimal fraction of a number. This argument applies only to types float and double.
For type float see the following examples:

     $value=-3.1,   $length=1, $precision 0: return -3
     $value=3.4,    $length=1, $precision 0: return 3
     $value=3.5,    $length=1, $precision 0: return 4
     $value=3.21,   $length=1, $precision 1: return 3.2
     $value=13.5,   $length=1, $precision 1: return 9.9
     $value=11.11,  $length=2, $precision 1: return 11.1
     $value=111.11, $length=2, $precision 1: return 99.9
     $value=0.115,  $length=0, $precision 2: return .12
     $value=5.115,  $length=1, $precision 2: return 5.12

Note on compatibility: The argument $precision was introduced in version 2.9.7. This changes the interpretation of the argument $length. Versions BEFORE 2.9.7 interpreted float values as numeric strings. Thus $length was understood as the maximum length in characters (including fraction). This has changed in version 2.9.7, where float values are treated as numbers - as shown in the examples above. The argument $length is now interpreted as the maximum length of the full decimal number (excluding fraction).
For type "upload" see the following example:

1. $filename = untaintInput('file', 'upload', 1000000);
2. if (is_int($filename)) {
3. switch ($filename)
4. {
5. case UPLOAD_ERR_INI_SIZE:
6. exit('File exceeds upload_max_filesize in php.ini');
7. break;
8. case UPLOAD_ERR_FORM_SIZE:
9. exit('File bigger than 1000000 bytes');
10. break;
11. case UPLOAD_ERR_PARTIAL:
12. exit('File was only partially uploaded');
13. break;
14. case UPLOAD_ERR_NO_FILE:
15. exit('No file was uploaded');
16. break;
17. case UPLOAD_ERR_NO_TMP_DIR:
18. exit('Missing a temporary folder');
19. break;
20. case UPLOAD_ERR_CANT_WRITE:
21. exit('Failed to write file to disk');
22. break;
23. case UPLOAD_ERR_EXTENSION:
24. exit('File upload stopped by extension');
25. break;
26. }
27. } else {
28. move_uploaded_file($filename, "upload/foo.bar"));
29. }

Note: type "image" is only treated as string here. There is a specific function for this job in the Image

- class.

See the function Image::uploadFile() for more details.
For type "text" see the following example:

1. // this example will untaint text taken from a HTML form
3. // input taken from field 'message'
4. $unsaveInput = $_GET['message'];
5. // type of data
6. $type = 'text';
7. // max. number of characters
8. $length = 1000;
9. // escape input
10. $escape = YANA_ESCAPE_USERTEXT;
11. // untaint input
12. $saveInput = untaintInput($unsaveInput, $type, $length, $escape);

- name: function_untaintInput()

##### Create a XML string from a scalar variable, an object, or an array of data.

void XMLencode (
scalar|array|object $data, [string $name = "root"], [int $caseSensitive = CASE_MIXED], [int $indent = 0], [string $inputEncoding = null], [string $outputEncoding = null]
)

###### List of parameters:

Name | Type | Description
--- | --- | ---
$data | scalar|array|object | input data
$name | string | name of root element
$caseSensitive | int | CASE_UPPER, CASE_LOWER, CASE_MIXED
$indent | int | number of tabs to indent
$inputEncoding | string | detected automatically
$outputEncoding | string | detected automatically

###### Description:

The argument $name can be used to specify the id of the root node. If $name is omitted, the id will be "root".
Note that any tags from string inputs will be stripped. You should convert tags to entities, before submiting the input.
The argument $caseSensitive can be used to decide how keys should be treated.
Valid values for $caseSensitive are:

- CASE_UPPER upper-case all keys
- CASE_LOWER lower-case all keys
- CASE_MIXED leave keys in mixed case

An XML-header is created automatically. Encoding of input and output will run on auto-detect.

- since: 2.9.5
- access: public
- name: function_XMLencode()

Documentation generated on Sun, 04 Jan 2009 03:49:18 +0100 by phpDocumentor 1.4.0

yana author: Thomas Meyerwww.yanaframework.net