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.
PreselectFilter
Filters a value out of a list of preselected values. The list comes from a class named with the sourceDataClass property. The method stated with the sourceDataMethod will be invoked statically and needs to return an array containing of allowed values. If none of these equals the request input an error will with given errorId be set. Both sourceDataMethod and errorId are optional. If no sourceDataMethod is set it will fallback to a method getData() which needs to be defined within the given class. If no errorId is set it will fallback to FIELD_WRONG_VALUE. @Filter[PreselectFilter](sourceDataClass=my::own::package::ListProvider.class, sourceDataMethod='getCategories', errorId='INCORRECT_SELECTION')
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)
Overruling annotated filters
Sometimes it is required to have a different or modified filter instead of the annotated filter. The request broker allows overruling of annotated filters:
$overrulingFilters = array('prefix_my_fieldname' => stubFilterFactory::forType('string'));
$requestBroker->process($request, $object, 'prefix_', $overrulingFilters);
Here, the value for a property or method with a filter annotation for the request value prefix_my_fieldname will be overruled with the filter instance given with the array $overrulingFilters, the annotated filter will be ignored.
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.
