Wiki Navigation

Using the request broker

When working with forms you often find yourself in doing the same work again and again: Reading data from the request, checking for validity and filtering the request values, and if the data is correct putting it into the right classes. Why not simplify this process for simple input stuff? This is the basic idea of the request broker.

How the request broker works

The request broker takes any object, checks each public non-static property and method for an annotation of type stubFilterAnnotation which in turn can create the filter object used by the broker to pull the data from the request. If anything other then null is returned from the request (null will be returned if the request value is not present or in case the filter detected errors) it the property will be populated with the value (or the method will be called with the value as its argument).

Example

See request broker example on our examples page.

Available annotations

See net::stubbles::request::broker::annotations for a complete list of available annotations.

FloatFilter

Filters floats. Can be customized with minValue and maxValue, but both are optional: @Filter[FloatFilter](minValue=2, maxValue=40)

Used error ids can be customized with minErrorId and maxErrorId, both are optional: @Filter[FloatFilter](minValue=2, maxValue=40, minErrorId='FOO_ERROR_ID', maxErrorId='BAR_ERROR_ID')

IntegerFilter

Filters integers. Can be customized with minValue and maxValue, but both are optional: @Filter[IntegerFilter](minValue=2, maxValue=40)

Used error ids can be customized with minErrorId and maxErrorId, both are optional: @Filter[IntegerFilter](minValue=2, maxValue=40, minErrorId='FOO_ERROR_ID', maxErrorId='BAR_ERROR_ID')

HTTPURLFilter

Filters URLs of type HTTP and HTTPS: @Filter[HTTPURLFilter]

MailFilter

Filters mail addresses: @Filter[MailFilter]

PasswordFilter

Filters passwords. Can be customized with minLength. If this value is not set the minimum length of the password will default to 6. @Filter[PasswordFilter](minLength=8)

The type of the password encoding can be changed with the encoder property: @Filter[PasswordFilter](encoder=my.own.package.MyOwnEncoder.class) If not set the default encoding of a password will be md5.

StringFilter

Filters strings. Removes line breaks and tags. Can be customized with minLength and maxLength. A regular expression must be supplied with regex. @Filter[StringFilter](minLength=4, maxLength=10, regex='/([a-z]*)/') Can also be used as: @Filter[StringFilter](regex='/^[a-z]{4,10}$/')

The error ids for min length and max length validation are customizable: @Filter[StringFilter](minLength=4, minLengthErrorId='FOO_ERROR_ID', maxLength=10, maxLengthErrorId='BAR_ERROR_ID', regex='/([a-z]*)/') Both are optional.

The filter can apply an encoder onto the value to filter with the encoder property: @Filter[StringFilter](regex='/^[a-z]{4,10}$/', encoder=my::own::package::MyOwnEncoder.class, encoderMode=stubStringEncoder::MODE_ENCODE) If not set no encoder will be applied. The encoderMode property is optional, if not set the value will default to stubStringEncoder::MODE_DECODE. If any other value than stubStringEncoder::MODE_DECODE or stubStringEncoder::MODE_ENCODE is set the annotation API will throw an exception when retrieving the annotation.

TextFilter

Filters texts. Removes line breaks of type \r. Removes tags, but it is possible to supply a list of allowed tags. However this option should be used very careful. Allowing certain tags does not protect against cross-site-scripting attacks! @Filter[TextFilter] - no tags allowed. @Filter[TextFilter](allowedTags='b,i,em,bold') - strips all tags except <b>, <i>, <em> and <bold> and their closing counterparts.

The filter can apply an encoder onto the value to filter with the encoder property: @Filter[TextFilter](encoder=my::own::package::MyOwnEncoder.class, encoderMode=stubStringEncoder::MODE_ENCODE) If not set no encoder will be applied. The encoderMode property is optional, if not set the value will default to stubStringEncoder::MODE_DECODE. If any other value than stubStringEncoder::MODE_DECODE or stubStringEncoder::MODE_ENCODE is set the annotation API will throw an exception when retrieving the annotation.

Required or not?

All filters are set to require the value by default, but every filter annotation can be set as required or not: @Filter[IntegerFilter](required=false)

Please bear in mind that this decision is static due to the behaviour of annotations which means you can not define cases where a value is required and cases where it is not. If you have such issues you still need to do the checks manually.

Define your own filter annotation

As it is possible to define your own filters it is possible to define your own filter annotations. Basically you just need to implement the stubFilterAnnotation interface. To save some work you may extend the stubAbstractFilterAnnotation class. If you do this you just have to implement protected function doGetFilter() where the filter instance is created.

class ExampleFilterAnnotation extends stubAbstractFilterAnnotation
{
    /**
     * returns the filter defined by the annotation
     *
     * @return  stubFilter
     * @throws  stubRequestBrokerException
     */
    protected function doGetFilter()
    {
        $exampleFilter = new ExampleFilter($this->createRVEFactory());
        return $exampleFilter;
    }
}

Afterwards, you can use the annotation: @Filter[ExampleFilter]

Please bear in mind that you have to load the annotation before you try to use the request broker. The request broker is only capable of loading the default filter annotations supplied by Stubbles.

Download in other formats:

Plain Text