README

Easy validation, casting and authorization of HTTP query string parameters.

1. Installation

Install the bundle through composer, then add it to your AppKernel.php file :

$bundles = array(
    // ...
    new Gl3n\HttpQueryStringFilterBundle\Gl3nHttpQueryStringFilterBundle(),
);

2. Configuration

Here is a sample filters configuration :

gl3n_http_query_string_filter:
    filters:
        list:
            params:
                size: { type: string, reg_exp: '^s|m|l$', default: 's' }
        blog_post_list:
            include: [list]
            params:
                userId:  { type: integer }
                isDraft: { type: boolean, roles: [ROLE_ADMIN] }
                tagIds:  { type: integer, array: true, default: '[]' }

A filter has parameters (params node). It can also include other filters' parameters (include node).

2.1. Parameter configuration

Each parameter configuration has 6 options :

Parameter types

Definition

A parameter type defines :

1. how the value (or the values in the case of a parameter configured as an array) will be casted,
2. the default regular expression.

Reference

Default value in the case of array parameters

In this special case, default value is evaluated through Symfony Expression Language component. Then if the result in an array : each value is casted depending on the configured parameter type.

You can see an example of this case in the sample configuration above.

3. Usage

Add a query string filter on an action thanks to the annotation :

use Gl3n\HttpQueryStringFilterBundle\Annotation\HttpQueryStringFilter;
// ...

class BlogPostController
{
    /**
     * @HttpQueryStringFilter(name="blog_post_list")
     */
    public function listAction(Request $request)
    {
        // Now your request query is filtered
        $parameters = $request->query->all();
    }
}

4. How to write a custom parameter type

Your parameter type class must implement ParameterType\ParameterTypeInterface with 2 methods :

1. castValue($value)
2. getDefaultRegExp()

Then declare it as a service, and add the tag gl3n_http_query_string_filter.parameter_type with the property type.

Here is an example of XML declaration :

<service
    id="gl3n_http_query_string_filter.parameter_type.boolean"
    class="Gl3n\HttpQueryStringFilterBundle\ParameterType\BooleanParameterType"
>
    <tag name="gl3n_http_query_string_filter.parameter_type" type="boolean"/>
</service>