[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  * An interface through which all application input can be accessed.
  18  */
  19  interface request_interface
  20  {
  21      /**#@+
  22      * Constant identifying the super global with the same name.
  23      */
  24      const POST = 0;
  25      const GET = 1;
  26      const REQUEST = 2;
  27      const COOKIE = 3;
  28      const SERVER = 4;
  29      const FILES = 5;
  30      /**#@-*/
  31  
  32      /**
  33      * This function allows overwriting or setting a value in one of the super global arrays.
  34      *
  35      * Changes which are performed on the super globals directly will not have any effect on the results of
  36      * other methods this class provides. Using this function should be avoided if possible! It will
  37      * consume twice the the amount of memory of the value
  38      *
  39      * @param    string    $var_name          The name of the variable that shall be overwritten
  40      * @param    mixed    $value              The value which the variable shall contain.
  41      *                                       If this is null the variable will be unset.
  42      * @param    string    $super_global    (\phpbb\request\request_interface::POST|GET|REQUEST|COOKIE)
  43      *                                     Specifies which super global shall be changed
  44      */
  45  	public function overwrite($var_name, $value, $super_global = \phpbb\request\request_interface::REQUEST);
  46  
  47      /**
  48      * Central type safe input handling function.
  49      * All variables in GET or POST requests should be retrieved through this function to maximise security.
  50      *
  51      * @param    string|array    $var_name    The form variable's name from which data shall be retrieved.
  52      *                                         If the value is an array this may be an array of indizes which will give
  53      *                                         direct access to a value at any depth. E.g. if the value of "var" is array(1 => "a")
  54      *                                         then specifying array("var", 1) as the name will return "a".
  55      * @param    mixed            $default    A default value that is returned if the variable was not set.
  56      *                                         This function will always return a value of the same type as the default.
  57      * @param    bool            $multibyte    If $default is a string this parameter has to be true if the variable may contain any UTF-8 characters
  58      *                                        Default is false, causing all bytes outside the ASCII range (0-127) to be replaced with question marks
  59      * @param    string    $super_global        (\phpbb\request\request_interface::POST|GET|REQUEST|COOKIE)
  60      *                                         Specifies which super global shall be changed
  61      *
  62      * @return    mixed    The value of $_REQUEST[$var_name] run through {@link set_var set_var} to ensure that the type is the
  63      *                    the same as that of $default. If the variable is not set $default is returned.
  64      */
  65  	public function variable($var_name, $default, $multibyte = false, $super_global = \phpbb\request\request_interface::REQUEST);
  66  
  67      /**
  68       * Get a variable without trimming strings and without escaping.
  69       * This method MUST NOT be used with queries.
  70       * Same functionality as variable(), except does not run trim() on strings
  71       * and does not escape input.
  72       * This method should only be used when the raw input is needed without
  73       * any escaping, i.e. for database password during the installation.
  74       *
  75       * @param    string|array    $var_name    The form variable's name from which data shall be retrieved.
  76       *                                         If the value is an array this may be an array of indizes which will give
  77       *                                         direct access to a value at any depth. E.g. if the value of "var" is array(1 => "a")
  78       *                                         then specifying array("var", 1) as the name will return "a".
  79       * @param    mixed            $default    A default value that is returned if the variable was not set.
  80       *                                         This function will always return a value of the same type as the default.
  81       * @param    string    $super_global        (\phpbb\request\request_interface::POST|GET|REQUEST|COOKIE)
  82       *                                         Specifies which super global shall be changed
  83       *
  84       * @return    mixed    The value of $_REQUEST[$var_name] run through {@link set_var set_var} to ensure that the type is the
  85       *                    the same as that of $default. If the variable is not set $default is returned.
  86       */
  87  	public function raw_variable($var_name, $default, $super_global = \phpbb\request\request_interface::REQUEST);
  88  
  89      /**
  90      * Shortcut method to retrieve SERVER variables.
  91      *
  92      * @param    string|array    $var_name        See \phpbb\request\request_interface::variable
  93      * @param    mixed            $default        See \phpbb\request\request_interface::variable
  94      *
  95      * @return    mixed    The server variable value.
  96      */
  97  	public function server($var_name, $default = '');
  98  
  99      /**
 100      * Shortcut method to retrieve the value of client HTTP headers.
 101      *
 102      * @param    string|array    $header_name    The name of the header to retrieve.
 103      * @param    mixed            $default        See \phpbb\request\request_interface::variable
 104      *
 105      * @return    mixed    The header value.
 106      */
 107  	public function header($header_name, $default = '');
 108  
 109      /**
 110      * Checks whether a certain variable was sent via POST.
 111      * To make sure that a request was sent using POST you should call this function
 112      * on at least one variable.
 113      *
 114      * @param    string    $name    The name of the form variable which should have a
 115      *                            _p suffix to indicate the check in the code that creates the form too.
 116      *
 117      * @return    bool            True if the variable was set in a POST request, false otherwise.
 118      */
 119  	public function is_set_post($name);
 120  
 121      /**
 122      * Checks whether a certain variable is set in one of the super global
 123      * arrays.
 124      *
 125      * @param    string    $var            Name of the variable
 126      * @param    string    $super_global    (\phpbb\request\request_interface::POST|GET|REQUEST|COOKIE)
 127      *                                     Specifies which super global shall be changed
 128      *
 129      * @return    bool                    True if the variable was sent as input
 130      */
 131  	public function is_set($var, $super_global = \phpbb\request\request_interface::REQUEST);
 132  
 133      /**
 134      * Checks whether the current request is an AJAX request (XMLHttpRequest)
 135      *
 136      * @return    bool            True if the current request is an ajax request
 137      */
 138  	public function is_ajax();
 139  
 140      /**
 141      * Checks if the current request is happening over HTTPS.
 142      *
 143      * @return    bool            True if the request is secure.
 144      */
 145  	public function is_secure();
 146  
 147      /**
 148      * Returns all variable names for a given super global
 149      *
 150      * @param    string    $super_global    (\phpbb\request\request_interface::POST|GET|REQUEST|COOKIE)
 151      *                                    The super global from which names shall be taken
 152      *
 153      * @return    array    All variable names that are set for the super global.
 154      *                    Pay attention when using these, they are unsanitised!
 155      */
 156  	public function variable_names($super_global = \phpbb\request\request_interface::REQUEST);
 157  
 158      /**
 159      * Returns the original array of the requested super global
 160      *
 161      * @param    string    $super_global    (\phpbb\request\request_interface::POST|GET|REQUEST|COOKIE)
 162      *                                    The super global which will be returned
 163      *
 164      * @return    array    The original array of the requested super global.
 165      */
 166  	public function get_super_global($super_global = \phpbb\request\request_interface::REQUEST);
 167  
 168      /**
 169       * Escape a string variable.
 170       *
 171       * @param mixed    $value        The contents to fill with
 172       * @param bool    $multibyte    Indicates whether string values may contain UTF-8 characters.
 173       *                             Default is false, causing all bytes outside the ASCII range (0-127) to be replaced with question marks.
 174       * @return string|array
 175       */
 176  	public function escape($value, $multibyte);
 177  }