phpBB/includes/core/request.php

   1 <?php
   2 /**
   3 *
   4 * @package core
   5 * @version $Id$
   6 * @copyright (c) 2008 phpBB Group
   7 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
   8 *
   9 */
  10
  11 /**
  12 * @ignore
  13 */
  14 if (!defined('IN_PHPBB'))
  15 {
  16         exit;
  17 }
  18
  19 /**
  20 * Replacement for a superglobal (like $_GET or $_POST) which calls
  21 * trigger_error on any operation, overloads the [] operator using SPL.
  22 *
  23 * @package core
  24 * @author naderman
  25 */
  26 class deactivated_super_global implements ArrayAccess, Countable, IteratorAggregate
  27 {
  28         /**
  29         * @var string Holds the error message
  30         */
  31         private $message;
  32
  33         /**
  34         * Constructor generates an error message fitting the super global to be used within the other functions.
  35         *
  36         * @param string $name   Name of the super global this is a replacement for - e.g. '_GET'
  37         */
  38         public function __construct($name)
  39         {
  40                 $this->message = 'Illegal use of $' . $name . '. You must use the request class or request_var() to access input data. Found in %s on line %d. This error message was generated';
  41         }
  42
  43         /**
  44         * Calls trigger_error with the file and line number the super global was used in
  45         *
  46         * @access private
  47         */
  48         private function error()
  49         {
  50                 $file = '';
  51                 $line = 0;
  52
  53                 $backtrace = debug_backtrace();
  54                 if (isset($backtrace[1]))
  55                 {
  56                         $file = $backtrace[1]['file'];
  57                         $line = $backtrace[1]['line'];
  58                 }
  59                 trigger_error(sprintf($this->message, $file, $line), E_USER_ERROR);
  60         }
  61
  62         /**#@+
  63         * Part of the ArrayAccess implementation, will always result in a FATAL error
  64         *
  65         * @access public
  66         */
  67         public function offsetExists($offset)
  68         {
  69                 $this->error();
  70         }
  71
  72         public function offsetGet($offset)
  73         {
  74                 $this->error();
  75         }
  76
  77         public function offsetSet($offset, $value)
  78         {
  79                 $this->error();
  80         }
  81
  82         public function offsetUnset($offset)
  83         {
  84                 $this->error();
  85         }
  86         /**#@-*/
  87
  88         /**
  89         * Part of the Countable implementation, will always result in a FATAL error
  90         *
  91         * @access public
  92         */
  93         public function count()
  94         {
  95                 $this->error();
  96         }
  97
  98         /**
  99         * Part of the Traversable/IteratorAggregate implementation, will always result in a FATAL error
 100         *
 101         * @access public
 102         */
 103         public function getIterator()
 104         {
 105                 $this->error();
 106         }
 107 }
 108
 109 /**
 110 * All application input is accessed through this class.
 111 *
 112 * It provides a method to disable access to input data through super globals.
 113 * This should force MOD authors to read about data validation.
 114 *
 115 * @package core
 116 * @author naderman
 117 */
 118 class phpbb_request
 119 {
 120         /**#@+
 121         * Constant defining the super global
 122         */
 123         const POST = 0;
 124         const GET = 1;
 125         const REQUEST = 2;
 126         const COOKIE = 3;
 127         /**#@-*/
 128
 129         /**
 130         * @var
 131         */
 132         protected static $initialised = false;
 133
 134         /**
 135         * @var
 136         */
 137         protected static $super_globals_disabled = false;
 138
 139         /**
 140         * @var array The names of super global variables that this class should protect if super globals are disabled
 141         */
 142         protected static $super_globals = array(phpbb_request::POST => '_POST', phpbb_request::GET => '_GET', phpbb_request::REQUEST => '_REQUEST', phpbb_request::COOKIE => '_COOKIE');
 143
 144         /**
 145         * @var array An associative array that has the value of super global constants as keys and holds their data as values.
 146         */
 147         protected static $input;
 148
 149         /**
 150         * Initialises the request class, that means it stores all input data in {@link $input self::$input}
 151         *
 152         * @access public
 153         */
 154         public static function init()
 155         {
 156                 if (!self::$initialised)
 157                 {
 158                         foreach (self::$super_globals as $const => $super_global)
 159                         {
 160                                 if ($const == phpbb_request::REQUEST)
 161                                 {
 162                                         continue;
 163                                 }
 164
 165                                 self::$input[$const] = isset($GLOBALS[$super_global]) ? $GLOBALS[$super_global] : array();
 166                         }
 167
 168                         // @todo far away from ideal... just a quick hack to let request_var() work again. The problem is that $GLOBALS['_REQUEST'] no longer exist.
 169                         self::$input[phpbb_request::REQUEST] = array_merge(self::$input[phpbb_request::POST], self::$input[phpbb_request::GET]);
 170
 171                         self::$initialised = true;
 172                 }
 173         }
 174
 175         /**
 176         * Resets the request class.
 177         * This will simply forget about all input data and read it again from the
 178         * super globals, if super globals were disabled, all data will be gone.
 179         *
 180         * @access public
 181         */
 182         public static function reset()
 183         {
 184                 self::$input = array();
 185                 self::$initialised = false;
 186                 self::$super_globals_disabled = false;
 187         }
 188
 189         /**
 190         * Getter for $super_globals_disabled
 191         *
 192         * @return bool  Whether super globals are disabled or not.
 193         * @access public
 194         */
 195         public static function super_globals_disabled()
 196         {
 197                 return self::$super_globals_disabled;
 198         }
 199
 200         /**
 201         * Disables access of super globals specified in $super_globals.
 202         * This is achieved by overwriting the super globals with instances of {@link deactivated_super_global deactivated_super_global}
 203         *
 204         * @access public
 205         */
 206         public static function disable_super_globals()
 207         {
 208                 if (!self::$initialised)
 209                 {
 210                         self::init();
 211                 }
 212
 213                 foreach (self::$super_globals as $const => $super_global)
 214                 {
 215                         unset($GLOBALS[$super_global]);
 216                         $GLOBALS[$super_global] = new deactivated_super_global($super_global);
 217                 }
 218
 219                 self::$super_globals_disabled = true;
 220         }
 221
 222         /**
 223         * Enables access of super globals specified in $super_globals if they were disabled by {@link disable_super_globals disable_super_globals}.
 224         * This is achieved by making the super globals point to the data stored within this class in {@link $input input}.
 225         *
 226         * @access public
 227         */
 228         public static function enable_super_globals()
 229         {
 230                 if (!self::$initialised)
 231                 {
 232                         self::init();
 233                 }
 234
 235                 if (self::$super_globals_disabled)
 236                 {
 237                         foreach (self::$super_globals as $const => $super_global)
 238                         {
 239                                 $GLOBALS[$super_global] = self::$input[$const];
 240                         }
 241
 242                         self::$super_globals_disabled = false;
 243                 }
 244         }
 245
 246         /**
 247         * Recursively applies addslashes to a variable.
 248         *
 249         * @param mixed  &$var   Variable passed by reference to which slashes will be added.
 250         * @access protected
 251         */
 252         protected static function addslashes_recursively(&$var)
 253         {
 254                 if (is_string($var))
 255                 {
 256                         $var = addslashes($var);
 257                 }
 258                 else if (is_array($var))
 259                 {
 260                         $var_copy = $var;
 261                         foreach ($var_copy as $key => $value)
 262                         {
 263                                 if (is_string($key))
 264                                 {
 265                                         $key = addslashes($key);
 266                                 }
 267                                 self::addslashes_recursively($var[$key]);
 268                         }
 269                 }
 270         }
 271
 272         /**
 273         * This function allows overwriting or setting a value in one of the super global arrays.
 274         *
 275         * Changes which are performed on the super globals directly will not have any effect on the results of
 276         * other methods this class provides. Using this function should be avoided if possible! It will
 277         * consume twice the the amount of memory of the value
 278         *
 279         * @param string $var_name       The name of the variable that shall be overwritten
 280         * @param mixed  $value          The value which the variable shall contain.
 281         *                                                       If this is null the variable will be unset.
 282         * @param phpbb_request::POST|phpbb_request::GET|phpbb_request::REQUEST|phpbb_request::COOKIE    $super_global   Specifies which super global shall be changed
 283         *
 284         * @access public
 285         */
 286         public static function overwrite($var_name, $value, $super_global = phpbb_request::REQUEST)
 287         {
 288                 if (!self::$initialised)
 289                 {
 290                         self::init();
 291                 }
 292
 293                 if (!isset(self::$super_globals[$super_global]))
 294                 {
 295                         return;
 296                 }
 297
 298                 if (STRIP)
 299                 {
 300                         self::addslashes_recursively($value);
 301                 }
 302
 303                 // setting to null means unsetting
 304                 if ($value === null)
 305                 {
 306                         unset(self::$input[$super_global][$var_name]);
 307                         if (!self::super_globals_disabled())
 308                         {
 309                                 unset($GLOBALS[self::$super_globals[$super_global]][$var_name]);
 310                         }
 311                 }
 312                 else
 313                 {
 314                         self::$input[$super_global][$var_name] = $value;
 315                         if (!self::super_globals_disabled())
 316                         {
 317                                 $GLOBALS[self::$super_globals[$super_global]][$var_name] = $value;
 318                         }
 319                 }
 320
 321                 if (!self::super_globals_disabled())
 322                 {
 323                         unset($GLOBALS[self::$super_globals[$super_global]][$var_name]);
 324                         $GLOBALS[self::$super_globals[$super_global]][$var_name] = $value;
 325                 }
 326         }
 327
 328         /**
 329         * Set variable $result. Used by {@link request_var() the request_var function}
 330         *
 331         * @param mixed  &$result        The variable to fill
 332         * @param mixed  $var            The contents to fill with
 333         * @param mixed  $type           The variable type. Will be used with {@link settype()}
 334         * @param bool   $multibyte      Indicates whether string values may contain UTF-8 characters.
 335         *                                                       Default is false, causing all bytes outside the ASCII range (0-127) to be replaced with question marks.
 336         *
 337         * @access public
 338         */
 339         public static function set_var(&$result, $var, $type, $multibyte = false)
 340         {
 341                 settype($var, $type);
 342                 $result = $var;
 343
 344                 if ($type == 'string')
 345                 {
 346                         $result = trim(utf8_htmlspecialchars(str_replace(array("\r\n", "\r", "\0"), array("\n", "\n", ''), $result)));
 347
 348                         if (!empty($result))
 349                         {
 350                                 // Make sure multibyte characters are wellformed
 351                                 if ($multibyte)
 352                                 {
 353                                         if (!preg_match('/^./u', $result))
 354                                         {
 355                                                 $result = '';
 356                                         }
 357                                 }
 358                                 else
 359                                 {
 360                                         // no multibyte, allow only ASCII (0-127)
 361                                         $result = preg_replace('/[\x80-\xFF]/', '?', $result);
 362                                 }
 363                         }
 364
 365                         $result = (STRIP) ? stripslashes($result) : $result;
 366                 }
 367         }
 368
 369         /**
 370         * Recursively sets a variable to a given type using {@link set_var() set_var}
 371         * This function is only used from within {@link phpbb_request::variable phpbb_request::variable}.
 372         *
 373         * @param string $var            The value which shall be sanitised (passed by reference).
 374         * @param mixed  $default        Specifies the type $var shall have.
 375         *                                                       If it is an array and $var is not one, then an empty array is returned.
 376         *                                                       Otherwise var is cast to the same type, and if $default is an array all keys and values are cast recursively using this function too.
 377         * @param bool   $multibyte      Indicates whether string values may contain UTF-8 characters.
 378         *                                                       Default is false, causing all bytes outside the ASCII range (0-127) to be replaced with question marks.
 379         *
 380         * @access protected
 381         */
 382         protected static function recursive_set_var(&$var, $default, $multibyte)
 383         {
 384                 if (is_array($var) !== is_array($default))
 385                 {
 386                         $var = (is_array($default)) ? array() : $default;
 387                         return;
 388                 }
 389
 390                 if (!is_array($default))
 391                 {
 392                         $type = gettype($default);
 393                         self::set_var($var, $var, $type, $multibyte);
 394                 }
 395                 else
 396                 {
 397                         // make sure there is at least one key/value pair to use get the
 398                         // types from
 399                         if (!sizeof($default))
 400                         {
 401                                 $var = array();
 402                                 return;
 403                         }
 404
 405                         list($default_key, $default_value) = each($default);
 406                         $value_type = gettype($default_value);
 407                         $key_type = gettype($default_key);
 408
 409                         $_var = $var;
 410                         $var = array();
 411
 412                         foreach ($_var as $k => $v)
 413                         {
 414                                 self::set_var($k, $k, $key_type, $multibyte);
 415
 416                                 self::recursive_set_var($v, $default_value, $multibyte);
 417                                 self::set_var($var[$k], $v, $value_type, $multibyte);
 418                         }
 419                 }
 420         }
 421
 422         /**
 423         * Central type safe input handling function.
 424         * All variables in GET or POST requests should be retrieved through this function to maximise security.
 425         *
 426         * @param string|array   $var_name       The form variable's name from which data shall be retrieved.
 427         *                                                                       If the value is an array this may be an array of indizes which will give
 428         *                                                                       direct access to a value at any depth. E.g. if the value of "var" is array(1 => "a")
 429         *                                                                       then specifying array("var", 1) as the name will return "a".
 430         * @param mixed                  $default        A default value that is returned if the variable was not set.
 431         *                                                                       This function will always return a value of the same type as the default.
 432         * @param bool                   $multibyte      If $default is a string this paramater has to be true if the variable may contain any UTF-8 characters
 433         *                                                                       Default is false, causing all bytes outside the ASCII range (0-127) to be replaced with question marks
 434         * @param phpbb_request::POST|phpbb_request::GET|phpbb_request::REQUEST|phpbb_request::COOKIE    $super_global   Specifies which super global should be used
 435         *
 436         * @return mixed The value of $_REQUEST[$var_name] run through {@link set_var set_var} to ensure that the type is the
 437         *                               the same as that of $default. If the variable is not set $default is returned.
 438         * @access public
 439         */
 440         public static function variable($var_name, $default, $multibyte = false, $super_global = phpbb_request::REQUEST)
 441         {
 442                 $path = false;
 443
 444                 if (!self::$initialised)
 445                 {
 446                         self::init();
 447                 }
 448
 449                 // deep direct access to multi dimensional arrays
 450                 if (is_array($var_name))
 451                 {
 452                         $path = $var_name;
 453                         // make sure at least the variable name is specified
 454                         if (!sizeof($path))
 455                         {
 456                                 return (is_array($default)) ? array() : $default;
 457                         }
 458                         // the variable name is the first element on the path
 459                         $var_name = array_shift($path);
 460                 }
 461
 462                 if (!isset(self::$input[$super_global][$var_name]))
 463                 {
 464                         return (is_array($default)) ? array() : $default;
 465                 }
 466                 $var = self::$input[$super_global][$var_name];
 467
 468                 // make sure cookie does not overwrite get/post
 469                 if ($super_global != phpbb_request::COOKIE && isset(self::$input[phpbb_request::COOKIE][$var_name]))
 470                 {
 471                         if (!isset(self::$input[phpbb_request::GET][$var_name]) && !isset(self::$input[phpbb_request::POST][$var_name]))
 472                         {
 473                                 return (is_array($default)) ? array() : $default;
 474                         }
 475                         $var = isset(self::$input[phpbb_request::POST][$var_name]) ? self::$input[phpbb_request::POST][$var_name] : self::$input[phpbb_request::GET][$var_name];
 476                 }
 477
 478                 if ($path)
 479                 {
 480                         // walk through the array structure and find the element we are looking for
 481                         foreach ($path as $key)
 482                         {
 483                                 if (is_array($var) && isset($var[$key]))
 484                                 {
 485                                         $var = $var[$key];
 486                                 }
 487                                 else
 488                                 {
 489                                         return (is_array($default)) ? array() : $default;
 490                                 }
 491                         }
 492                 }
 493
 494                 self::recursive_set_var($var, $default, $multibyte);
 495
 496                 return $var;
 497         }
 498
 499         /**
 500         * Checks whether a certain variable was sent via POST.
 501         * To make sure that a request was sent using POST you should call this function
 502         * on at least one variable.
 503         *
 504         * @param string $name   The name of the form variable which should have a
 505         *                                               _p suffix to indicate the check in the code that creates the form too.
 506         *
 507         * @return bool  True if the variable was set in a POST request, false otherwise.
 508         * @access public
 509         */
 510         public static function is_set_post($name)
 511         {
 512                 return self::is_set($name, phpbb_request::POST);
 513         }
 514
 515         /**
 516         * Checks whether a certain variable is set in one of the super global
 517         * arrays.
 518         *
 519         * @param string $var    Name of the variable
 520         * @param phpbb_request::POST|phpbb_request::GET|phpbb_request::REQUEST|phpbb_request::COOKIE    $super_global
 521         *                                               Specifies the super global which shall be checked
 522         *
 523         * @return bool  True if the variable was sent as input
 524         * @access public
 525         */
 526         public static function is_set($var, $super_global = phpbb_request::REQUEST)
 527         {
 528                 if (!self::$initialised)
 529                 {
 530                         self::init();
 531                 }
 532
 533                 return isset(self::$input[$super_global][$var]);
 534         }
 535
 536         /**
 537         * Returns all variable names for a given super global
 538         *
 539         * @param phpbb_request::POST|phpbb_request::GET|phpbb_request::REQUEST|phpbb_request::COOKIE    $super_global
 540         *                                       The super global from which names shall be taken
 541         *
 542         * @return array All variable names that are set for the super global.
 543         *                               Pay attention when using these, they are unsanitised!
 544         * @access public
 545         */
 546         public static function variable_names($super_global = phpbb_request::REQUEST)
 547         {
 548                 if (!self::$initialised)
 549                 {
 550                         self::init();
 551                 }
 552
 553                 if (!isset(self::$input[$super_global]))
 554                 {
 555                         return array();
 556                 }
 557
 558                 return array_keys(self::$input[$super_global]);
 559         }
 560 }
 561
 562 ?>