Login   Register  
PHP Classes
elePHPant
Icontem

File: doc.txt

Recommend this page to a friend!
Stumble It! Stumble It! Bookmark in del.icio.us Bookmark in del.icio.us
  Classes of Joshua Townsend  >  Request Data  >  doc.txt  >  Download  
File: doc.txt
Role: Documentation
Content type: text/plain
Description: Documentation on all methods
Class: Request Data
Retrieve and process request parameters
Author: By
Last change:
Date: 7 years ago
Size: 10,228 bytes
 

Contents

Class file image Download
Table of Contents:

0 Preface

1 Constructor
1.1 request::request()

2 Parsing
2.1 request::parse_mode()
2.2 request::parse_http_headers()

3 Magic Quotes
3.1 request::magic_quotes()
3.2 request::fix_magic_quotes()

4 Retrieving Data
4.1 request::get_value()
4.2 request::get_bool()
4.3 request::get_int()
4.4 request::get_float()
4.5 request::get_string()
4.6 request::get_array()
4.7 request::get_typed_array()

5 File Uploads
5.1 request::file_tempname()
5.2 request::file_size()
5.3 request::file_error()
5.4 request::file_name()

6 Custom Modes
6.1 request::add_mode()
6.2 request::remove_mode()
6.3 request::set_default_mode()
6.4 request::allow_mode_override()
6.5 request::clear_mode_cache()

7 Special-Purpose
7.1 request::get_html_string()
7.2 request::get_clean_string()
7.3 request::is_checked()
7.4 request::check_session_cookie()
7.5 request::get_header()


0 Preface
This file is part of a package for the request class, written by and Copyright (C) 2007 Joshua Townsend. <http://www.gamingg.net>

1 Constructor

1.1 request::request()
    request( void )
This method is the contructor of the request class.  This function makes a call to request::magic_quotes() and request::parse_http_headers().
You will not need to call this function, as it is automatically called for you when you create a new instance of the request class.


2 Parsing
These methods perform parsing of different data and do not need to be publically called.

2.1 request::parse_mode()
    array parse_mode( string $mode )
This method takes a string, $mode, as its only parameter and parses it into an array containing the arrays of data for use in request::get_value().

2.2 request::parse_http_headers()
    void parse_http_headers( void )
This method parses all of the HTTP headers from the $_SERVER superglobal array (all keys beginning with HTTP_) and prepares them to be called from the request::get_header() method


3 Magic Quotes
These methods revert the effects of having magic_quotes on.

3.1 request::magic_quotes()
    void magic_quotes( void )
This method calls request::fix_magic_quotes() on every superglobal if magic quotes is on and has not already been fixed by this class instance.

3.2 request::fix_magic_quotes()
    void fix_magic_quotes( mixed &$arr )
This method recursively removes the effects of magic quotes (by calling stripslashes()) on each string in the array $arr.


4 Retrieving Data
These methods retrieve data named $name from the data sources given by the $mode argument.  $mode is a string that is parsed by the rules of variables.order of php.ini.  For instance, if $mode is "gpc", then the $_COOKIE superglobal will have the highest precedence.  If the value is not found in $_COOKIE, then $_POST has the next highest precedence, then $_GET.  If none of the data sources referred to by $mode contain the data requested, then the value of the $default argument will be returned.
Here is a table showing all of the default $mode values:

e - $_ENV
g - $_GET
p - $_POST
c - $_COOKIE
s - $_SERVER
r - $_REQUEST
Or any combination of more than one

Additionally, using the Custom Modes methods, you can add and remove your own modes pointing to your own data, as long as the mode is a single character and not reserved.  See section 6 and the included examples for more information.

$mode always defaults to "r" ($_REQUEST) and $default defaults to null if not given; however, many functions will cast null to the type they are supposed to return.  (i.e. request::get_bool() would return false by default, because (bool)null is false).

4.1 request::get_value()
    mixed get_value( string $name [, string $mode [, mixed $default ]] )
This method returns the value of $name in the data sources specified by $mode, or $default if not found.
Note: Use of this method is not recommended, because you cannot control what type of data is being returned.  It is best to use request::get_string() if no other data type is required.

4.2 request::get_bool()
    bool get_bool( string $name [, string $mode [, bool $default ]] )
This method returns the value of request::get_value(), but always returns a boolean.

4.3 request::get_int()
    int get_int( string $name [, string $mode [, int $default ]] )
This method returns the value of request::get_value(), but always returns an integer.

4.4 request::get_float()
    float get_float( string $name [, string $mode [, float $default ]] )
This method returns the value of request::get_value(), but always returns a float.

4.5 request::get_string()
    string get_string( string $name [, string $mode [, string $default ]] )
This method returns the value of request::get_value(), but always returns a string.

4.6 request::get_array()
    array get_array( string $name [, string $mode [, array $default ]] )
This method returns the value of request::get_value(), but always returns an array.
Note: The values in the array can be of any type.  See request::get_typed_array()

4.7 request::get_typed_array()
    array get_typed_array( string $name [, string $mode [, string $type [, array $default ]]] )
This method returns the value of request::get_array(), but the elements are casted to type $type.  $type can be one of "bool", "int", "float", "string", or "array".  If $type is null or not given then no type casting is done, and the same value as request::get_array() will be returned, but at a slight performance loss.
Note: If $type is "array", then the values of the arrays within the returned array are arbitrary data types and are not casted.


5 File Uploads
These methods provide data about files that have been uploaded through POST.

5.1 request::file_tempname()
    string file_tempname( string $name )
This method returns the temporary location of the uploaded file named by $name, or an empty string if the file does not exist.
    
5.2 request::file_size()
    int file_tempname( string $name )
This method returns the size of the uploaded file named by $name, or 0 if the file does not exist.
    
5.3 request::file_error()
    int file_tempname( string $name )
This method returns the error code of the uploaded file named by $name, or 0 (UPLOAD_ERR_OK) if there is no error.
    
5.4 request::file_name()
    string file_tempname( string $name )
This method returns the file name (what the file was named on the user's computer) of the uploaded file named by $name, or an empty string if the file does not exist.


6 Custom Modes
These methods allow you to add your own custom modes to be used with any method in the request class that supports the argument $mode.  You could add, for instance, data retrieved from a database about the current user.  The data must be in an array.  The contents of the array do not matter; it could even have objects of other classes in it.  Examples of the use of custom modes is included with this package.

6.1 request::add_mode()
    bool add_mode ( string $mode, array $data )
This method adds the mode $mode for use in any function in the request class that requires a mode.  The data that $mode will point to is defined by the array $data.  $mode must be a single character, and cannot be a reserved mode (currently, the reserved modes are e, g, p, c, and s).  If a mode already exists by the name given, then it will be overridden with the new data.  This method returns true on success and false on failure.

6.2 request::remove_mode()
    bool remove_mode ( string $mode )
This method removes the mode $mode from the list of modes.  This method CANNOT be used to remove the default modes.  This method returns true if the mode exists and it was successfully removed, or false if it does not exist.

6.3 request::set_default_mode()
    bool set_default_mode ( string $mode )
This method sets the default mode to be used if the $mode parameter is not specified by any function that retrieves data from the data pointed to by a mode.

6.3 request::allow_mode_override()
    bool allow_mode_override ( [ bool $value ] )
This method changes the default rules of disallowing the override of default modes to the value of $value.  This method returns the current setting.
Note that custom modes can always be overriden and are not affected by this method.

6.4 request::clear_mode_cache()
    void clear_mode_cache ( string $mode )
This method is used internally to clear the cache for a mode that has just been added (to prevent problems with overriding) or removed (as garbage collection).


7 Special-Purpose
These methods have a special purpose, but are not categorized in any of the other sections.


7.1 request::get_html_string()
    string get_html_string( string $name [, string $mode [, string $default ]] )
This method returns the same value as request::get_string(), except that it is html-safe, to prevent against XSS-related attacks (such as injections of the <script> tag).  Use this method if no sanitizing is to be done to data that will be outputted directly to the user.

7.2 request::get_clean_string()
    string get_html_string( string $name [, string $mode [, string $default ]] )
This method returns the same value as request::get_string(), except that excess whitespace from the beginning and end of the string is removed.

7.3 request::is_checked()
    bool is_checked ( string $name )
This method returns true if a value is set (even if it is null), or false if not.  This method will most likely be used to see if check boxes have been checked or not.

7.4 request::check_session_cookie()
    bool check_session_cookie ( void )
This method returns if the user has accepted the session cookie set by PHP's session_start(), or false if not.  This method will most likely be used to check if the session id should be appended to URLs or not.

7.5 request::get_header()
    string get_header ( string $name [, string $default ] )
This method returns the value for the HTTP header given by $name, or $default if $name is not found in the list of HTTP headers.  Note that standard HTTP-header syntax must be used ("X-Forwarded-For", not "x-forwarded-for" or "X_FORWARDED_FOR", for instance).