PhpBB3.1/RFC/Request class

A class to contain all request data and provide a clear interface to interact with that data. Preventing direct access to $_GET/$_POST/$_REQUEST/$_COOKIE. Also additional functionality to the existing request_var. The request_var function has several limitations. It is still required to use super globals to perform some operations, like isset. The new request class should be fully backwards compatible and allow for the complete removal of any super global access.

Allows for better decoupling of components and thus easier testing and reuse.

Instantiation
The default instance of \phpbb\request\request is defined in common.php and can be passed to your classes via the service container. The constructor takes two arguments. The first argument is a type cast helper, which must implement the \phpbb\request\type_cast_helper_interface, if none is supplied, the default implementation will be used. The second argument is a boolean $disable_super_globals which defaults to true. When enabled, it will replace super globals ($_*) with instances of \phpbb\request\deactivated_super_global, which will throw an error on any direct access to those variables with the exception of $request, request_var and isset. This means that you cannot use empty.

It is highly preferred to use the service container for obtaining the \phpbb\request\request class. You can however create your own instance using this command: $request = new \phpbb\request\request;

In order to retain backward compatibility with request_var, request_var allows injection of a \phpbb\request\request instance.

Variable
$request::variable is the replacement for request_var. For any new code you should use it instead. The usage is almost identical to request_var, but some new capabilities were added. Here are some basic calls:

$forum_id = $request->variable('forum_id', 0); $field_name = $request->variable('field_name', '');

Where request_var had a cookie parameter, you can now specify a _$super_global_, which is one of the constants on the \phpbb\request\request_interface: GET, POST, COOKIE or REQUEST.

$session_id = $request->variable('sid', 0, false,\phpbb\request\request_interface::POST);

Another change is with regard to unicode handling. You no longer have to run the result through utf8_normalize_nfc, this is done automatically if _$multibyte_ is set to true:

$message = $request->variable('message', '', true);

In olympus the _$default_ parameter had a limitation of nesting. For ascraeus this is no longer the case, you can nest arrays as deep as you want.

$user_notes_per_forum = $request->variable('user_notes_per_forum', array(/* forum_id */ 0 => array(/* user_id */ 0 => array(/* note contents */ ''))), true);

An additional capability is the path syntax. This allows you to access a single value at a deep location (nested input) while making sure the types are still correct. You use it by passing an array as the _$var_name_ parameter. Each entry in this array represents an array key, nesting increases with each entry.

// INPUT: $_POST['user_notes_per_forum'] = array(10 => array(2 => array('A fun note', 'Yet another fun note'))); $note = $request->variable(array('user_notes_per_forum', 1, 2, 1), '', true);

This example will fetch the second note (the first one has an index of 0) from user_id 2 within forum_id 10.

Is_set
While isset($_*[$var]) will still work, any new code should use $request::is_set instead. The first argument is the var name, the second, which is optional, specifies the super global. By default it will use REQUEST, which uses both POST and GET.

if ($request->is_set('f')) {   // do something interesting }

Is_set_post
Since issset($_POST[$var]) is often used to check submission of POST forms, there is a special helper for that.

if ($request->is_set_post('submit')) {   // process the form }

Variable_names
While you will hardly ever need this, there are one or two locations where we need to iterate over input variables. request::variable_names allows you to specify a super global (defaults to REQUEST) and will return the names (keys) that exist for that super global.

General
For any new code $request should be used. Where possible, instead of using the global instance of $request, that instance should be passed in (dependency injection). This mostly makes sense for new controller-style classes.

Implementation
@todo