[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3  *
   4  * This file is part of the phpBB Forum Software package.
   5  *
   6  * @copyright (c) phpBB Limited <https://www.phpbb.com>
   7  * @license GNU General Public License, version 2 (GPL-2.0)
   8  *
   9  * For full copyright and license information, please see
  10  * the docs/CREDITS.txt file.
  11  *
  12  */
  13  
  14  namespace phpbb\request;
  15  
  16  /**
  17  * All application input is accessed through this class.
  18  *
  19  * It provides a method to disable access to input data through super globals.
  20  * This should force MOD authors to read about data validation.
  21  */
  22  class request implements \phpbb\request\request_interface
  23  {
  24      /**
  25      * @var    array    The names of super global variables that this class should protect if super globals are disabled.
  26      */
  27      protected $super_globals = array(
  28          \phpbb\request\request_interface::POST => '_POST',
  29          \phpbb\request\request_interface::GET => '_GET',
  30          \phpbb\request\request_interface::REQUEST => '_REQUEST',
  31          \phpbb\request\request_interface::COOKIE => '_COOKIE',
  32          \phpbb\request\request_interface::SERVER => '_SERVER',
  33          \phpbb\request\request_interface::FILES => '_FILES',
  34      );
  35  
  36      /**
  37      * @var    array    Stores original contents of $_REQUEST array.
  38      */
  39      protected $original_request = null;
  40  
  41      /**
  42      * @var
  43      */
  44      protected $super_globals_disabled = false;
  45  
  46      /**
  47      * @var    array    An associative array that has the value of super global constants as keys and holds their data as values.
  48      */
  49      protected $input;
  50  
  51      /**
  52      * @var    \phpbb\request\type_cast_helper_interface    An instance of a type cast helper providing convenience methods for type conversions.
  53      */
  54      protected $type_cast_helper;
  55  
  56      /**
  57      * Initialises the request class, that means it stores all input data in {@link $input input}
  58      * and then calls {@link \phpbb\request\deactivated_super_global \phpbb\request\deactivated_super_global}
  59      */
  60  	public function __construct(\phpbb\request\type_cast_helper_interface $type_cast_helper = null, $disable_super_globals = true)
  61      {
  62          if ($type_cast_helper)
  63          {
  64              $this->type_cast_helper = $type_cast_helper;
  65          }
  66          else
  67          {
  68              $this->type_cast_helper = new \phpbb\request\type_cast_helper();
  69          }
  70  
  71          foreach ($this->super_globals as $const => $super_global)
  72          {
  73              $this->input[$const] = isset($GLOBALS[$super_global]) ? $GLOBALS[$super_global] : array();
  74          }
  75  
  76          // simulate request_order = GP
  77          $this->original_request = $this->input[\phpbb\request\request_interface::REQUEST];
  78          $this->input[\phpbb\request\request_interface::REQUEST] = $this->input[\phpbb\request\request_interface::POST] + $this->input[\phpbb\request\request_interface::GET];
  79  
  80          if ($disable_super_globals)
  81          {
  82              $this->disable_super_globals();
  83          }
  84      }
  85  
  86      /**
  87      * Getter for $super_globals_disabled
  88      *
  89      * @return    bool    Whether super globals are disabled or not.
  90      */
  91  	public function super_globals_disabled()
  92      {
  93          return $this->super_globals_disabled;
  94      }
  95  
  96      /**
  97      * Disables access of super globals specified in $super_globals.
  98      * This is achieved by overwriting the super globals with instances of {@link \phpbb\request\deactivated_super_global \phpbb\request\deactivated_super_global}
  99      */
 100  	public function disable_super_globals()
 101      {
 102          if (!$this->super_globals_disabled)
 103          {
 104              foreach ($this->super_globals as $const => $super_global)
 105              {
 106                  unset($GLOBALS[$super_global]);
 107                  $GLOBALS[$super_global] = new \phpbb\request\deactivated_super_global($this, $super_global, $const);
 108              }
 109  
 110              $this->super_globals_disabled = true;
 111          }
 112      }
 113  
 114      /**
 115      * Enables access of super globals specified in $super_globals if they were disabled by {@link disable_super_globals disable_super_globals}.
 116      * This is achieved by making the super globals point to the data stored within this class in {@link $input input}.
 117      */
 118  	public function enable_super_globals()
 119      {
 120          if ($this->super_globals_disabled)
 121          {
 122              foreach ($this->super_globals as $const => $super_global)
 123              {
 124                  $GLOBALS[$super_global] = $this->input[$const];
 125              }
 126  
 127              $GLOBALS['_REQUEST'] = $this->original_request;
 128  
 129              $this->super_globals_disabled = false;
 130          }
 131      }
 132  
 133      /**
 134      * This function allows overwriting or setting a value in one of the super global arrays.
 135      *
 136      * Changes which are performed on the super globals directly will not have any effect on the results of
 137      * other methods this class provides. Using this function should be avoided if possible! It will
 138      * consume twice the the amount of memory of the value
 139      *
 140      * @param    string    $var_name    The name of the variable that shall be overwritten
 141      * @param    mixed    $value        The value which the variable shall contain.
 142      *                                 If this is null the variable will be unset.
 143      * @param    \phpbb\request\request_interface::POST|GET|REQUEST|COOKIE    $super_global
 144      *                                 Specifies which super global shall be changed
 145      */
 146  	public function overwrite($var_name, $value, $super_global = \phpbb\request\request_interface::REQUEST)
 147      {
 148          if (!isset($this->super_globals[$super_global]))
 149          {
 150              return;
 151          }
 152  
 153          $this->type_cast_helper->add_magic_quotes($value);
 154  
 155          // setting to null means unsetting
 156          if ($value === null)
 157          {
 158              unset($this->input[$super_global][$var_name]);
 159              if (!$this->super_globals_disabled())
 160              {
 161                  unset($GLOBALS[$this->super_globals[$super_global]][$var_name]);
 162              }
 163          }
 164          else
 165          {
 166              $this->input[$super_global][$var_name] = $value;
 167              if (!$this->super_globals_disabled())
 168              {
 169                  $GLOBALS[$this->super_globals[$super_global]][$var_name] = $value;
 170              }
 171          }
 172      }
 173  
 174      /**
 175      * Central type safe input handling function.
 176      * All variables in GET or POST requests should be retrieved through this function to maximise security.
 177      *
 178      * @param    string|array    $var_name    The form variable's name from which data shall be retrieved.
 179      *                                         If the value is an array this may be an array of indizes which will give
 180      *                                         direct access to a value at any depth. E.g. if the value of "var" is array(1 => "a")
 181      *                                         then specifying array("var", 1) as the name will return "a".
 182      * @param    mixed            $default    A default value that is returned if the variable was not set.
 183      *                                         This function will always return a value of the same type as the default.
 184      * @param    bool            $multibyte    If $default is a string this paramater has to be true if the variable may contain any UTF-8 characters
 185      *                                        Default is false, causing all bytes outside the ASCII range (0-127) to be replaced with question marks
 186      * @param    \phpbb\request\request_interface::POST|GET|REQUEST|COOKIE    $super_global
 187      *                                         Specifies which super global should be used
 188      *
 189      * @return    mixed    The value of $_REQUEST[$var_name] run through {@link set_var set_var} to ensure that the type is the
 190      *                    the same as that of $default. If the variable is not set $default is returned.
 191      */
 192  	public function variable($var_name, $default, $multibyte = false, $super_global = \phpbb\request\request_interface::REQUEST)
 193      {
 194          return $this->_variable($var_name, $default, $multibyte, $super_global, true);
 195      }
 196  
 197      /**
 198      * Get a variable, but without trimming strings.
 199      * Same functionality as variable(), except does not run trim() on strings.
 200      * This method should be used when handling passwords.
 201      *
 202      * @param    string|array    $var_name    The form variable's name from which data shall be retrieved.
 203      *                                         If the value is an array this may be an array of indizes which will give
 204      *                                         direct access to a value at any depth. E.g. if the value of "var" is array(1 => "a")
 205      *                                         then specifying array("var", 1) as the name will return "a".
 206      * @param    mixed            $default    A default value that is returned if the variable was not set.
 207      *                                         This function will always return a value of the same type as the default.
 208      * @param    bool            $multibyte    If $default is a string this paramater has to be true if the variable may contain any UTF-8 characters
 209      *                                        Default is false, causing all bytes outside the ASCII range (0-127) to be replaced with question marks
 210      * @param    \phpbb\request\request_interface::POST|GET|REQUEST|COOKIE    $super_global
 211      *                                         Specifies which super global should be used
 212      *
 213      * @return    mixed    The value of $_REQUEST[$var_name] run through {@link set_var set_var} to ensure that the type is the
 214      *                    the same as that of $default. If the variable is not set $default is returned.
 215      */
 216  	public function untrimmed_variable($var_name, $default, $multibyte = false, $super_global = \phpbb\request\request_interface::REQUEST)
 217      {
 218          return $this->_variable($var_name, $default, $multibyte, $super_global, false);
 219      }
 220  
 221      /**
 222      * Shortcut method to retrieve SERVER variables.
 223      *
 224      * Also fall back to getenv(), some CGI setups may need it (probably not, but
 225      * whatever).
 226      *
 227      * @param    string|array    $var_name        See \phpbb\request\request_interface::variable
 228      * @param    mixed            $Default        See \phpbb\request\request_interface::variable
 229      *
 230      * @return    mixed    The server variable value.
 231      */
 232  	public function server($var_name, $default = '')
 233      {
 234          $multibyte = true;
 235  
 236          if ($this->is_set($var_name, \phpbb\request\request_interface::SERVER))
 237          {
 238              return $this->variable($var_name, $default, $multibyte, \phpbb\request\request_interface::SERVER);
 239          }
 240          else
 241          {
 242              $var = getenv($var_name);
 243              $this->type_cast_helper->recursive_set_var($var, $default, $multibyte);
 244              return $var;
 245          }
 246      }
 247  
 248      /**
 249      * Shortcut method to retrieve the value of client HTTP headers.
 250      *
 251      * @param    string|array    $header_name    The name of the header to retrieve.
 252      * @param    mixed            $default        See \phpbb\request\request_interface::variable
 253      *
 254      * @return    mixed    The header value.
 255      */
 256  	public function header($header_name, $default = '')
 257      {
 258          $var_name = 'HTTP_' . str_replace('-', '_', strtoupper($header_name));
 259          return $this->server($var_name, $default);
 260      }
 261  
 262      /**
 263      * Shortcut method to retrieve $_FILES variables
 264      *
 265      * @param string $form_name The name of the file input form element
 266      *
 267      * @return array The uploaded file's information or an empty array if the
 268      * variable does not exist in _FILES.
 269      */
 270  	public function file($form_name)
 271      {
 272          return $this->variable($form_name, array('name' => 'none'), true, \phpbb\request\request_interface::FILES);
 273      }
 274  
 275      /**
 276      * Checks whether a certain variable was sent via POST.
 277      * To make sure that a request was sent using POST you should call this function
 278      * on at least one variable.
 279      *
 280      * @param    string    $name    The name of the form variable which should have a
 281      *                            _p suffix to indicate the check in the code that creates the form too.
 282      *
 283      * @return    bool            True if the variable was set in a POST request, false otherwise.
 284      */
 285  	public function is_set_post($name)
 286      {
 287          return $this->is_set($name, \phpbb\request\request_interface::POST);
 288      }
 289  
 290      /**
 291      * Checks whether a certain variable is set in one of the super global
 292      * arrays.
 293      *
 294      * @param    string    $var    Name of the variable
 295      * @param    \phpbb\request\request_interface::POST|GET|REQUEST|COOKIE    $super_global
 296      *                            Specifies the super global which shall be checked
 297      *
 298      * @return    bool            True if the variable was sent as input
 299      */
 300  	public function is_set($var, $super_global = \phpbb\request\request_interface::REQUEST)
 301      {
 302          return isset($this->input[$super_global][$var]);
 303      }
 304  
 305      /**
 306      * Checks whether the current request is an AJAX request (XMLHttpRequest)
 307      *
 308      * @return    bool            True if the current request is an ajax request
 309      */
 310  	public function is_ajax()
 311      {
 312          return $this->header('X-Requested-With') == 'XMLHttpRequest';
 313      }
 314  
 315      /**
 316      * Checks if the current request is happening over HTTPS.
 317      *
 318      * @return    bool            True if the request is secure.
 319      */
 320  	public function is_secure()
 321      {
 322          $https = $this->server('HTTPS');
 323          $https = $this->server('HTTP_X_FORWARDED_PROTO') === 'https' ? 'on' : $https;
 324          return !empty($https) && $https !== 'off';
 325      }
 326  
 327      /**
 328      * Returns all variable names for a given super global
 329      *
 330      * @param    \phpbb\request\request_interface::POST|GET|REQUEST|COOKIE    $super_global
 331      *                    The super global from which names shall be taken
 332      *
 333      * @return    array    All variable names that are set for the super global.
 334      *                    Pay attention when using these, they are unsanitised!
 335      */
 336  	public function variable_names($super_global = \phpbb\request\request_interface::REQUEST)
 337      {
 338          if (!isset($this->input[$super_global]))
 339          {
 340              return array();
 341          }
 342  
 343          return array_keys($this->input[$super_global]);
 344      }
 345  
 346      /**
 347      * Helper function used by variable() and untrimmed_variable().
 348      *
 349      * @param    string|array    $var_name    The form variable's name from which data shall be retrieved.
 350      *                                         If the value is an array this may be an array of indizes which will give
 351      *                                         direct access to a value at any depth. E.g. if the value of "var" is array(1 => "a")
 352      *                                         then specifying array("var", 1) as the name will return "a".
 353      * @param    mixed            $default    A default value that is returned if the variable was not set.
 354      *                                         This function will always return a value of the same type as the default.
 355      * @param    bool            $multibyte    If $default is a string this paramater has to be true if the variable may contain any UTF-8 characters
 356      *                                        Default is false, causing all bytes outside the ASCII range (0-127) to be replaced with question marks
 357      * @param    \phpbb\request\request_interface::POST|GET|REQUEST|COOKIE    $super_global
 358      *                                         Specifies which super global should be used
 359      * @param    bool            $trim        Indicates whether trim() should be applied to string values.
 360      *
 361      * @return    mixed    The value of $_REQUEST[$var_name] run through {@link set_var set_var} to ensure that the type is the
 362      *                    the same as that of $default. If the variable is not set $default is returned.
 363      */
 364  	protected function _variable($var_name, $default, $multibyte = false, $super_global = \phpbb\request\request_interface::REQUEST, $trim = true)
 365      {
 366          $path = false;
 367  
 368          // deep direct access to multi dimensional arrays
 369          if (is_array($var_name))
 370          {
 371              $path = $var_name;
 372              // make sure at least the variable name is specified
 373              if (empty($path))
 374              {
 375                  return (is_array($default)) ? array() : $default;
 376              }
 377              // the variable name is the first element on the path
 378              $var_name = array_shift($path);
 379          }
 380  
 381          if (!isset($this->input[$super_global][$var_name]))
 382          {
 383              return (is_array($default)) ? array() : $default;
 384          }
 385          $var = $this->input[$super_global][$var_name];
 386  
 387          if ($path)
 388          {
 389              // walk through the array structure and find the element we are looking for
 390              foreach ($path as $key)
 391              {
 392                  if (is_array($var) && isset($var[$key]))
 393                  {
 394                      $var = $var[$key];
 395                  }
 396                  else
 397                  {
 398                      return (is_array($default)) ? array() : $default;
 399                  }
 400              }
 401          }
 402  
 403          $this->type_cast_helper->recursive_set_var($var, $default, $multibyte, $trim);
 404  
 405          return $var;
 406      }
 407  
 408      /**
 409      * {@inheritdoc}
 410      */
 411  	public function get_super_global($super_global = \phpbb\request\request_interface::REQUEST)
 412      {
 413          return $this->input[$super_global];
 414      }
 415  
 416      /**
 417       * {@inheritdoc}
 418       */
 419  	public function escape($var, $multibyte)
 420      {
 421          if (is_array($var))
 422          {
 423              $result = array();
 424              foreach ($var as $key => $value)
 425              {
 426                  $this->type_cast_helper->set_var($key, $key, gettype($key), $multibyte);
 427                  $result[$key] = $this->escape($value, $multibyte);
 428              }
 429              $var = $result;
 430          }
 431          else
 432          {
 433              $this->type_cast_helper->set_var($var, $var, 'string', $multibyte);
 434          }
 435  
 436          return $var;
 437      }
 438  }