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    int        $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 = 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    int                $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 type_cast_helper_interface::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 = 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    int                $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 type_cast_helper_interface::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 = 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    int        $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 = 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    int        $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 = request_interface::REQUEST);
157
158	/**
159	* Returns the original array of the requested super global
160	*
161	* @param    int        $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 = 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	}