[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    \phpbb\request\request_interface::POST|GET|REQUEST|COOKIE    $super_global
  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 paramater 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    \phpbb\request\request_interface::POST|GET|REQUEST|COOKIE    $super_global
  60      *                                         Specifies which super global should be used
  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      * Shortcut method to retrieve SERVER variables.
  69      *
  70      * @param    string|array    $var_name        See \phpbb\request\request_interface::variable
  71      * @param    mixed            $default        See \phpbb\request\request_interface::variable
  72      *
  73      * @return    mixed    The server variable value.
  74      */
  75  	public function server($var_name, $default = '');
  76  
  77      /**
  78      * Shortcut method to retrieve the value of client HTTP headers.
  79      *
  80      * @param    string|array    $header_name    The name of the header to retrieve.
  81      * @param    mixed            $default        See \phpbb\request\request_interface::variable
  82      *
  83      * @return    mixed    The header value.
  84      */
  85  	public function header($var_name, $default = '');
  86  
  87      /**
  88      * Checks whether a certain variable was sent via POST.
  89      * To make sure that a request was sent using POST you should call this function
  90      * on at least one variable.
  91      *
  92      * @param    string    $name    The name of the form variable which should have a
  93      *                            _p suffix to indicate the check in the code that creates the form too.
  94      *
  95      * @return    bool            True if the variable was set in a POST request, false otherwise.
  96      */
  97  	public function is_set_post($name);
  98  
  99      /**
 100      * Checks whether a certain variable is set in one of the super global
 101      * arrays.
 102      *
 103      * @param    string    $var    Name of the variable
 104      * @param    \phpbb\request\request_interface::POST|GET|REQUEST|COOKIE    $super_global
 105      *                            Specifies the super global which shall be checked
 106      *
 107      * @return    bool            True if the variable was sent as input
 108      */
 109  	public function is_set($var, $super_global = \phpbb\request\request_interface::REQUEST);
 110  
 111      /**
 112      * Checks whether the current request is an AJAX request (XMLHttpRequest)
 113      *
 114      * @return    bool            True if the current request is an ajax request
 115      */
 116  	public function is_ajax();
 117  
 118      /**
 119      * Checks if the current request is happening over HTTPS.
 120      *
 121      * @return    bool            True if the request is secure.
 122      */
 123  	public function is_secure();
 124  
 125      /**
 126      * Returns all variable names for a given super global
 127      *
 128      * @param    \phpbb\request\request_interface::POST|GET|REQUEST|COOKIE    $super_global
 129      *                    The super global from which names shall be taken
 130      *
 131      * @return    array    All variable names that are set for the super global.
 132      *                    Pay attention when using these, they are unsanitised!
 133      */
 134  	public function variable_names($super_global = \phpbb\request\request_interface::REQUEST);
 135  
 136      /**
 137      * Returns the original array of the requested super global
 138      *
 139      * @param    \phpbb\request\request_interface::POST|GET|REQUEST|COOKIE    $super_global
 140      *                    The super global which will be returned
 141      *
 142      * @return    array    The original array of the requested super global.
 143      */
 144  	public function get_super_global($super_global = \phpbb\request\request_interface::REQUEST);
 145  
 146      /**
 147       * Escape a string variable.
 148       *
 149       * @param mixed    $value        The contents to fill with
 150       * @param bool    $multibyte    Indicates whether string values may contain UTF-8 characters.
 151       *                             Default is false, causing all bytes outside the ASCII range (0-127) to be replaced with question marks.
 152       * @return string|array
 153       */
 154  	public function escape($value, $multibyte);
 155  }