Easy validation, casting and authorization of HTTP query string parameters.
PHP
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
Annotation
DependencyInjection
EventListener
ParameterType
Resources/config
Tests/Units
.atoum.php
.bootstrap.atoum.php
.gitignore
.travis.yml
Caster.php
Filter.php
Gl3nHttpQueryStringFilterBundle.php
LICENSE
README.md
Validator.php
composer.json

README.md

HttpQueryStringFilterBundle Build Status

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 :

Name Required Description
type yes string, boolean or integer (see below for detail)
reg_exp no The regular expression to use for validation (default depends on the parameter type)
default no Default value (will be casted depending on the parameter type)
required no Boolean that indicates whether the parameter is required (default is false)
array no Boolean that indicates wheter expected parameter value is an array (default is false)
roles no An array of security roles allowed to use this parameter (default is an empty array)

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
Type Cast to Default reg exp
string PHP string ^.+$
boolean PHP boolean ``^true
integer PHP integer ^\d+$

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>