Skip to content
This repository was archived by the owner on Jan 16, 2019. It is now read-only.

Docs Request

Jump to bottom
Frank Kleine edited this page Apr 7, 2012 · 1 revision

Table of Contents

Working with request data

Applies to Stubbles 1.3.0 or greater. For Stubbles versions before 1.3.0 please see Filtering and validating user input.

One of the most often required features in web environments is accessing data from the request and filtering and/or validating user input. It is as well one of the most important features, because not doing so can result in security problems of applications which may compromise the data of the application. In order to make such a often recurring task easier to handle Stubbles offers a unique interface to user input and for filtering and validating it.

The request layer

The request layer provides access to user input which includes:

  • request parameters
  • input from forms
  • cookie values
  • request headers

They are available via an instance of the net::stubbles::ipo::request::stubRequest interface. A concrete implementation of this interface is the net::stubbles::ipo::request::stubWebRequest class. Please note that the request instance is available via dependency injection when the net::stubbles::ipo::ioc::stubIpoBindingModule is used. If you want to have another implementation of the request interface than the default one delivered with Stubbles you can tell this binding module via its setRequestClassName() method the full qualified class name of your own request implementation.

Check for presence of a request value

You can check if a certain request value is set: 

$request->hasParam($paramName); // checks whether a request parameter with given name is set
$request->hasHeader($headerName); // checks whether a request header with given name is set
$request->hasCookie($cookieName); // checks whether a request cookie with given name is set

Access to request parameters

Request parameters can accessed in two ways:

  1. Validating that the content of the request param fulfills certain requirements. This is useful if you don't need the value itself but want to ensure it is present in a certain form.
  2. Reading the content of the request param for further processing.

Reading the content of a request parameter

To read the content of a request parameter one can access it via the readParam($paramName) method. This will return an instance of net::stubbles::ipo::request::stubFilteringRequestValue which can then be used to get the real value: 

$int = $request->readParam('foo')->asInt();
$httpUrl = $request->readParam('bar')->asHttpUrl();

For a complete list of available methods on the returned instance see below. All methods named as* use filters. This means the returned value will be of a certain type - a real int for the asInt() method, and an instance of net::stubbles::peer::http::stubHTTPURL for the asHttpUrl() method. If the request value can not be read or violates given constrains the return value will be null.

Additionally the net::stubbles::ipo::request::stubFilteringRequestValue class offers several methods with ifIs*() methods. These methods use validators, and return the value if the validator approves the value. If the validator denies the value the return value of those methods is null or the value given with the parameter $default. 

$mailAddress = $request->readParam('user_mail')->ifIsMailAddress();
$otherValue = $request->readParam('other')->ifSatisfiesRegex('/[a-z]{30}/');

Finally one can access the raw value without any filtering or validating: 

$rawUnfilteredValue = $request->readParam('bar')->unsecure();

However this method should be used with greatest care. If possible one should always use the filtering or validating methods. If those provided by default are not enough you can use our own filter or validator implementation: 

$filteredValue = $request->readParam('anotherValue')->withFilter($myFilter);
$validatedValue = $request->readParam('oneMoreParam')->withValidator($myValidator);

Validating request parameters

If you don't require the complete value you can use the validateParam($paramName) method instead. This will return an instance of net::stubbles::ipo::request::stubValidatingRequestValue which can then be used to make the assertion: 

if ($request->validateParam('more')->isEqualTo('yes') === true) {
    # do something
}

if ($request->validateParam('more')->withValidator($myValidator) === true) {
    # do some more things
}

For a complete list of available methods on the returned instance see below. The return value of this validation is either true or false.

Access to cookie values

Cookie values can be accessed with the same scheme. Only difference is that the methods are readCookie($cookieName) and validateCookie($cookieName).

Access to request headers

Request header values can be accessed with the same scheme. Only difference is that the methods are readHeader($headerName) and validateHeader($headerName).

Access to request body

The request body can be accessed with readBody() and validateBody().

List of filtering methods on read*() 

$request->read*('user_mail')->asInt($min = null, $max = null, $default = null, $required = false)
$request->read*('user_mail')->asFloat($min = null, $max = null, $default = null, $required = false, $decimals = null)
$request->read*('user_mail')->asString($minLength = null, $maxLength = null, $default = null, $required = false)
$request->read*('user_mail')->asText($minLength = null, $maxLength = null, $default = null, $required = false)
$request->read*('user_mail')->asJson($default = null, $required = false)
$request->read*('user_mail')->asPassword($minDiffChars = 5, array $nonAllowedValues = array(), $required = false)
$request->read*('user_mail')->asHttpUrl($checkDns = false, stubHTTPURLContainer $default = null, $required = false)
$request->read*('user_mail')->asMailAddress($required = false)
$request->read*('user_mail')->asDate(stubDate $minDate = null, stubDate $maxDate = null, stubDate $default = null, $required = false)
$request->read*('user_mail')->asType($type)
$request->read*('user_mail')->withFilter(stubFilter $filter)

List of validating methods on read*() with return value 

$request->read*('user_mail')->ifContains($contained, $default = null)
$request->read*('user_mail')->ifIsEqualTo($expected, $default = null)
$request->read*('user_mail')->ifIsHttpUrl($checkDns = false, $default = null)
$request->read*('user_mail')->ifIsIpAddress($default = null)
$request->read*('user_mail')->ifIsMailAddress($default = null)
$request->read*('user_mail')->ifIsOneOf(array $allowedValues, $default = null)
$request->read*('user_mail')->ifSatisfiesRegex($regex, $default = null)
$request->read*('user_mail')->withValidator(stubValidator $validator, $default = null)

The $default allows to define the return value in case the validation fails. By default in such cases the return value is null.

List of validating methods on validate*() 

$request->validate*('user_mail')->contains($contained)
$request->validate*('user_mail')->isEqualTo($expected)
$request->validate*('user_mail')->isHttpUrl($checkDns = false)
$request->validate*('user_mail')->isIpAddress()
$request->validate*('user_mail')->isMailAddress()
$request->validate*('user_mail')->isOneOf(array $allowedValues)
$request->validate*('user_mail')->satisfiesRegex($regex)
$request->validate*('user_mail')->withValidator(stubValidator $validator)

Retrieve a list of all request values

In order to retrieve a list of all request values there are three different methods: 

$request->getParamNames(); // returns a list of all request parameter names
$request->getHeaderNames(); // returns a list of all request header names
$request->getCookieNames(); // returns a list of all request cookie names

Cancelling the request

In case something is very wrong with the request it can be cancelled via cancel().

Subsequently the method isCancelled() will always return true. Please be aware that there is no possibility to undo the cancellation!

Clone this wiki locally