Source for file Request.class.php

Documentation is available at Request.class.php

  1. <?php
  2. /**
  3.  * Gumbo Library Framework
  4.  *
  5.  * LICENSE
  6.  * This library is being released under the terms of the New BSD License.  A
  7.  * copy of the license is packaged with the software (LICENSE.txt).  If no
  8.  * copy is found, a copy of the license template can be found at:
  9.  * http://www.opensource.org/licenses/bsd-license.php
  10.  * 
  11.  * @category Gumbo
  12.  * @package Http
  13.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  14.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  15.  * @author Michael Luster <mluster79@yahoo.com>
  16.  * @link http://sourceforge.net/projects/phpgumbo
  17.  * @version 0.0.1
  18.  */
  19.  
  20. /**
  21.  * Http Request Class
  22.  *
  23.  * @category Gumbo
  24.  * @package Http
  25.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  26.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  27.  * @author Michael Luster <mluster79@yahoo.com>
  28.  * @link http://sourceforge.net/projects/phpgumbo
  29.  * @desc Http Request Class
  30.  * @version 0.0.1
  31.  */
  32.  
  33. gumbo_load ("Interface_Singleton");
  34. gumbo_load ("Interface_Http_Request");
  35. gumbo_load ("Http_Input");
  36.  
  37. class Gumbo_Http_Request implements Gumbo_Interface_Http_Request, Gumbo_Interface_Singleton {
  38.     
  39.     /** @var Gumbo_Interface_Http_Request $_instance */
  40.     private static $_instance = null;
  41.     
  42.     /** @var string $_method HTTP request method */
  43.     private $_method;
  44.     /** @var string $_mode get mode */
  45.     private $_mode = "request";
  46.     
  47.     /** @var array $_fields list of fields that have been checked */
  48.     private $_fields = array ();
  49.     
  50.     /** @var array $_map map of REQUEST data */
  51.     private $_map = null;
  52.     
  53.     
  54.     
  55.     /**
  56.      * Constructor
  57.      */
  58.     private function __construct () {
  59.         $this->_method = $_SERVER ['REQUEST_METHOD'];
  60.         
  61.         // sets all data to 'raw'
  62.         foreach (array_keys ($_REQUEST) as $fld) {
  63.             $this->addField ($fld);
  64.         }
  65.     }
  66.     
  67.     /**
  68.      * Singleton Pattern Method
  69.      * @return Gumbo_Interface_Http_Request 
  70.      */
  71.     public static function instance () {
  72.         if (self::$_instance == null) {
  73.             self::$_instance = new Gumbo_Http_Request ();
  74.         }
  75.         return self::$_instance;
  76.     }
  77.     
  78.     
  79.     
  80.     /** OVERLOAD METHODS **/
  81.     /**
  82.      * Returns the value of the $_REQUEST field based on the mode
  83.      * @param string $fld 
  84.      * @return mixed 
  85.      */
  86.     public function __get ($fld) {
  87.         return $this->get ($fld);
  88.     }
  89.     
  90.     /**
  91.      * Returns if the field exists in the REQUEST array
  92.      * @param string $fld 
  93.      * @return mixed 
  94.      */
  95.     public function __isset ($fld) {
  96.         return isset ($_REQUEST [$fld]);
  97.     }
  98.     
  99.     
  100.     
  101.     /** ACTION METHODS **/
  102.     /**
  103.      * Validates the $_REQUEST variable Constraints (if null, validates all)
  104.      * @param string $field 
  105.      * @throws Gumbo_Exception
  106.      * @uses Gumbo_Http_Input
  107.      */
  108.     public function validate ($field=null) {
  109.         try {
  110.             // verify precondition
  111.             if (!is_null ($field) && !is_string ($field)) {
  112.                 throw new Gumbo_Exception ("Invalid Argument 'field:str' => {$field}:" . gettype ($field));
  113.             }
  114.             
  115.             // validates ALL fields through recursion
  116.             if (is_null ($field)) {
  117.                 foreach ($this->getAllFields () as $fld) {
  118.                     $this->validate ($fld);
  119.                 }
  120.                 return;
  121.             }
  122.             
  123.             // loop through Constraints, if any
  124.             $input = Gumbo_Http_Input::instance ();
  125.             
  126.             $status = $input->toIgnoreConstraints ();
  127.             if ($input->hasInput ($field)) {
  128.                 $input->$field->setData ($this->getRaw ($field));
  129.                 $status = $input->$field->clean ();
  130.             }
  131.             
  132.             // set the status code
  133.             if ($status) {
  134.                 $this->setField ($field, "clean");
  135.             } else {
  136.                 $this->setField ($field, "dirty");
  137.             }
  138.         } catch (Gumbo_Exception $e) {
  139.             $e->setFunction (__METHOD__);
  140.             gumbo_trigger ($e);
  141.         }
  142.     }
  143.     
  144.     /**
  145.      * Adds a status to the $_REQUEST field
  146.      * @param string $field 
  147.      * @throws Gumbo_Exception
  148.      */
  149.     protected function addField ($field) {
  150.         try {
  151.             // verify precondition
  152.             if (!is_string ($field)) {
  153.                 throw new Gumbo_Exception ("Invalid Argument 'field:str' => {$field}:" . gettype ($field));
  154.             }
  155.             if (!isset ($this->$field)) {
  156.                 throw new Gumbo_Exception ("Invalid REQUEST Field: {$field}");
  157.             }
  158.             
  159.             $this->_fields [$field] = "raw";
  160.         } catch (Gumbo_Exception $e) {
  161.             $e->setFunction (__METHOD__);
  162.             gumbo_trigger ($e);
  163.         }
  164.     }
  165.     
  166.     
  167.     
  168.     /** MUTATOR METHODS **/
  169.     /**
  170.      * Sets the default return mode (request|cookie|post|get)
  171.      * @param string $mode 
  172.      * @throws Gumbo_Exception
  173.      */
  174.     public function setMode ($mode) {
  175.         try {
  176.             // verify precondition
  177.             if (!is_string ($mode)) {
  178.                 throw new Gumbo_Exception ("Invalid Argument 'mode:str' => {$mode}:" . gettype ($mode));
  179.             }
  180.             $mode = strtolower ($mode);
  181.             
  182.             switch ($mode) {
  183.                 case "request" : break;
  184.                 case "cookie" : break;
  185.                 case "post" : break;
  186.                 case "get" : break;
  187.                 default : throw new Gumbo_Exception ("Invalid Argument 'mode:request|cookie|post|get' => {$mode}");
  188.             }
  189.             
  190.             $this->_mode = $mode;
  191.         } catch (Gumbo_Exception $e) {
  192.             $e->setFunction (__METHOD__);
  193.             gumbo_trigger ($e);
  194.         }
  195.     }
  196.     
  197.     /**
  198.      * Sets a status code for a $_REQUEST field
  199.      * @param string $field 
  200.      * @param string $code status code [raw|dirty|clean]
  201.      * @throws Gumbo_Exception
  202.      */
  203.     protected function setField ($field, $code) {
  204.         try {
  205.             // verify precondition
  206.             if (!is_string ($field)) {
  207.                 throw new Gumbo_Exception ("Invalid Argument 'field:str' => {$field}:" . gettype ($field));
  208.             }
  209.             if (!isset ($this->$field)) {
  210.                 throw new Gumbo_Exception ("Invalid REQUEST Field: {$field}");
  211.             }
  212.             if (!is_string ($code)) {
  213.                 throw new Gumbo_Exception ("Invalid Argument 'code:str' => {$code}:" . gettype ($code));
  214.             }
  215.             $code = strtolower ($code);
  216.             if ($code != "raw" && $code != "dirty" && $code != "clean") {
  217.                 throw new Gumbo_Exception ("Invalid Argument 'code:raw|dirty|clean' => {$code}");
  218.             }
  219.             
  220.             $this->_fields [$field] = $code;
  221.         } catch (Gumbo_Exception $e) {
  222.             $e->setFunction (__METHOD__);
  223.             gumbo_trigger ($e);
  224.         }
  225.     }
  226.     
  227.     
  228.     
  229.     /** ACCESSOR METHODS **/
  230.     /**
  231.      * Returns the value of the $_REQUEST field
  232.      * @param string $field 
  233.      * @param string $mode 
  234.      * @return mixed 
  235.      * @throws Gumbo_Exception
  236.      * @uses Gumbo_Http_Input
  237.      */
  238.     public function get ($field, $mode=null) {
  239.         try {
  240.             // verify precondition
  241.             if (!is_string ($field)) {
  242.                 throw new Gumbo_Exception ("Invalid Argument 'field:str' => {$field}:" . gettype ($field));
  243.             }
  244.             if (!isset ($this->$field)) {
  245.                 throw new Gumbo_Exception ("Invalid REQUEST Field: {$field}");
  246.             }
  247.             if (!is_null ($mode) && !is_string ($mode)) {
  248.                 throw new Gumbo_Exception ("Invalid Argument 'mode:str|null' => {$mode}:" . gettype ($mode));
  249.             }
  250.             
  251.             // set data to return
  252.             $data = $this->getRaw ($field, $mode);
  253.             
  254.             // verify data can be sent
  255.             $input = Gumbo_Http_Input::instance ();
  256.             if (!$input->toIgnoreConstraints ()) {
  257.                 if ($this->getField ($field) == "raw") {
  258.                     $this->validate ($field);
  259.                 }
  260.                 
  261.                 $status = $this->getField ($field);
  262.                 if (!$status || $status == "dirty" || $status == "raw") {
  263.                     throw new Gumbo_Exception ("REQUEST Data Failed Input Constraints: {$field}");
  264.                 }
  265.                 
  266.                 // filter the data through Constraints
  267.                 if ($input->hasInput ($field)) {
  268.                     if ($input->$field->isClean ()) {
  269.                         $data = $input->$field->getData ();
  270.                     }
  271.                 }
  272.             }
  273.             
  274.             return $data;
  275.         } catch (Gumbo_Exception $e) {
  276.             $e->setFunction (__METHOD__);
  277.             gumbo_trigger ($e);
  278.         }
  279.         return null;
  280.     }
  281.     
  282.     /**
  283.      * Returns the raw data value from $_REQUEST, $_POST, $_GET, or $_COOKIE
  284.      * @param string $field 
  285.      * @param string $mode 
  286.      * @return mixed 
  287.      * @throws Gumbo_Exception
  288.      */
  289.     protected function getRaw ($field, $mode=null) {
  290.         try {
  291.             // verify precondition
  292.             if (!is_string ($field)) {
  293.                 throw new Gumbo_Exception ("Invalid Argument 'field:str' => {$field}:" . gettype ($field));
  294.             }
  295.             if (!isset ($this->$field)) {
  296.                 throw new Gumbo_Exception ("Invalid REQUEST Field: {$field}");
  297.             }
  298.             
  299.             if (!is_null ($mode) && !is_string ($mode)) {
  300.                 $mode = null;
  301.             }
  302.             if (!is_null ($mode)) {
  303.                 $mode = strtolower ($mode);
  304.                 if ($mode != "request" && $mode != "cookie" && $mode != "post" && $mode != "get") {
  305.                     $mode = null;
  306.                 }
  307.             }
  308.             if (is_null ($mode)) {
  309.                 $mode = $this->getMode ();
  310.             }
  311.             
  312.             // return the value
  313.             $val = false;
  314.             switch ($mode) {
  315.                 case "request" : if (isset ($_REQUEST [$field])) { $val = $_REQUEST [$field]; } break;
  316.                 case "cookie" : if (isset ($_COOKIE [$field])) { $val = $_COOKIE [$field]; } break;
  317.                 case "post" : if (isset ($_POST [$field])) { $val = $_POST [$field]; } break;
  318.                 case "get" : if (isset ($_GET [$field])) { $val = $_GET [$field]; } break;
  319.             }
  320.             return $val;
  321.         } catch (Gumbo_Exception $e) {
  322.             $e->setFunction (__METHOD__);
  323.             gumbo_trigger ($e);
  324.         }
  325.         return null;
  326.     }
  327.     
  328.     /**
  329.      * Returns an array map of User Input
  330.      * @param bool $reload reloads the map
  331.      * @return array 
  332.      * @throws Gumbo_Exception
  333.      */
  334.     public function getMap ($reload=false) {
  335.         try {
  336.             // verify precondition
  337.             if (!is_bool ($reload)) {
  338.                 throw new Gumbo_Exception ("Invalid Argument 'reload:bool' => {$reload}:" . gettype ($reload));
  339.             }
  340.         } catch (Gumbo_Exception $e) {
  341.             $e->setFunction (__METHOD__);
  342.             gumbo_trigger ($e);
  343.             $reload = false;
  344.         }
  345.         
  346.         // check if the map was previously created
  347.         if (is_null ($this->_map) || $reload) {
  348.             foreach (array_keys ($_REQUEST) as $val) {
  349.                 $this->_map [$val] = $this->get ($val);
  350.             }
  351.         }
  352.         
  353.         return $this->_map;
  354.     }
  355.     
  356.     /**
  357.      * Returns the HTTP request method
  358.      * @return string 
  359.      */
  360.     public function getMethod () {
  361.         return $this->_method;
  362.     }
  363.     
  364.     /**
  365.      * Returns the mode return values will be retrieved from
  366.      * @return string 
  367.      */
  368.     public function getMode () {
  369.         return $this->_mode;
  370.     }
  371.     
  372.     /**
  373.      * Returns the status of the $_REQUEST field
  374.      * @param string $field 
  375.      * @return string 
  376.      * @throws Gumbo_Exception
  377.      */
  378.     protected function getField ($field) {
  379.         try {
  380.             // verify precondition
  381.             if (!is_string ($field)) {
  382.                 throw new Gumbo_Exception ("Invalid Argument 'field:str' => {$field}:" . gettype ($field));
  383.             }
  384.             if (!isset ($this->$field)) {
  385.                 throw new Gumbo_Exception ("Invalid REQUEST Argument: {$field}");
  386.             }
  387.             if (!$this->isField ($field)) {
  388.                 throw new Gumbo_Exception ("Field Undefined: {$field}");
  389.             }
  390.             
  391.             return $this->_fields [$field];
  392.         } catch (Gumbo_Exception $e) {
  393.             $e->setFunction (__METHOD__);
  394.             gumbo_trigger ($e);
  395.         }
  396.         return null;
  397.     }
  398.     
  399.     /**
  400.      * Returns all the fields status codes
  401.      * @return array 
  402.      */
  403.     protected function getAllFields () {
  404.         return $this->_fields;
  405.     }
  406.     
  407.     
  408.     
  409.     /**
  410.      * Returns if the field has been registered
  411.      * @param string $field 
  412.      * @return bool 
  413.      * @throws Gumbo_Exception
  414.      */
  415.     protected function isField ($field) {
  416.         try {
  417.             // verify precondition
  418.             if (!is_string ($field)) {
  419.                 throw new Gumbo_Exception ("Invalid Argument 'field:str' => {$field}:" . gettype ($field));
  420.             }
  421.             if (!isset ($this->$field)) {
  422.                 throw new Gumbo_Exception ("Invalid REQUEST Field: {$field}");
  423.             }
  424.             
  425.             return isset ($this->_fields [$field]);
  426.         } catch (Gumbo_Exception $e) {
  427.             $e->setFunction (__METHOD__);
  428.             gumbo_trigger ($e);
  429.         }
  430.         return false;
  431.     }
  432.     
  433. }
  434.  
  435. ?>