PHPackages                             mpscholten/request-parser - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. mpscholten/request-parser

ActiveLibrary

mpscholten/request-parser
=========================

v1.5.1(5y ago)5317.5k↓50%3[1 issues](https://github.com/mpscholten/request-parser/issues)[3 PRs](https://github.com/mpscholten/request-parser/pulls)MITPHPCI failing

Since Jun 20Pushed 5y ago6 watchersCompare

[ Source](https://github.com/mpscholten/request-parser)[ Packagist](https://packagist.org/packages/mpscholten/request-parser)[ RSS](/packages/mpscholten-request-parser/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (8)Dependencies (4)Versions (14)Used By (0)

request parser
==============

[](#request-parser)

[![Latest Stable Version](https://camo.githubusercontent.com/241b16b8f11698d0aa73863c0c1842ee52853e18da5c308ccfafd719bc7ce9b4/68747470733a2f2f706f7365722e707567782e6f72672f6d707363686f6c74656e2f726571756573742d7061727365722f76657273696f6e)](https://packagist.org/packages/mpscholten/request-parser)[![License](https://camo.githubusercontent.com/8b5538c8ba83095503e789d0e227318111998fc7b347fe356d21ff791d052b44/68747470733a2f2f706f7365722e707567782e6f72672f6d707363686f6c74656e2f726571756573742d7061727365722f6c6963656e7365)](https://packagist.org/packages/mpscholten/request-parser)[![Circle CI](https://camo.githubusercontent.com/dc33f0a60fe6b372c78971996051ec414995fad6b00c06e0bf49c34cc08dc2f8/68747470733a2f2f636972636c6563692e636f6d2f67682f6d707363686f6c74656e2f726571756573742d7061727365722e7376673f7374796c653d736869656c64)](https://circleci.com/gh/mpscholten/request-parser)[![Total Downloads](https://camo.githubusercontent.com/dbd23eb356593db9d29d919266149ec2e39a0bc1f71a3122df9a3bf4b509658c/68747470733a2f2f706f7365722e707567782e6f72672f6d707363686f6c74656e2f726571756573742d7061727365722f646f776e6c6f616473)](https://packagist.org/packages/mpscholten/request-parser)

Small PHP Library for type-safe input handling.

- [The Problem](https://github.com/mpscholten/request-parser/#the-problem)
- [Examples](https://github.com/mpscholten/request-parser/#examples)
- [Getting Started](https://github.com/mpscholten/request-parser/#getting-started)
- [Integrations](https://github.com/mpscholten/request-parser/#integrations)
- [Symfony HttpFoundation](https://github.com/mpscholten/request-parser/#symfony-httpfoundation)
- [Psr7](https://github.com/mpscholten/request-parser/#psr7)
- [Optional Parameters](https://github.com/mpscholten/request-parser/#additional-parameters)
- [Integers, Enums, DateTimes and Json Payloads](https://github.com/mpscholten/request-parser/#integers-enums-datetimes-and-json-payloads)
- [Supported Data Types](https://github.com/mpscholten/request-parser/#supported-data-types)
- [GET Requests](https://github.com/mpscholten/request-parser/#get-requests)
- [POST Requests](https://github.com/mpscholten/request-parser/#post-requests)
- [Autocompletion](https://github.com/mpscholten/request-parser/#autocompletion)
- [Static Analysis](https://github.com/mpscholten/request-parser/#static-analysis)
- [Error Handling](https://github.com/mpscholten/request-parser/#error-handling)
- [Using Custom Exception Classes](https://github.com/mpscholten/request-parser/#using-custom-exception-classes)
- [Using Custom Exception Messages](https://github.com/mpscholten/request-parser/#using-custom-exception-messages)
- [Is It Production Ready?](https://github.com/mpscholten/request-parser/#is-it-production-ready)
- [Tests](https://github.com/mpscholten/request-parser/#tests)
- [Contributing](https://github.com/mpscholten/request-parser/#contributing)

### The Problem

[](#the-problem)

Let's say you have an action which lists some entities. This includes paging, ascending or descending ordering and optional filtering by the time the entity was created. This action will have some kind of input parsing, which can look like this:

```
public function index()
{
    $page = $this->request->query->get('page');
    if ($page === null || !is_integer($page)) {
        throw new Exception("Parameter page not found");
    }

    $order = $this->request->query->get('order');
    if ($order === null || !in_array($order, ['asc', 'desc'])) {
        throw new Exception("Parameter order not found");
    }

    // Optional parameter
    $createdAt = $this->query->query->get('createdAt');
    if (is_string($createdAt)) {
        $createdAt = new DateTime($createdAt);
    } else {
        $createdAt = null;
    }
}
```

Obviously this code is not very nice to read because it is not very descriptive. It's also pretty verbose for what it's doing. And when you don't pay close attention you will probably miss a null check or a type check.

Now compare the above code to this version:

```
public function index()
{
    $page = $this->queryParameter('page')->int()->required();
    $order = $this->queryParameter('order')->oneOf(['asc', 'desc'])->required();
    $createdAt = $this->queryParameter('createdAt')->dateTime()->defaultsTo(null);
}
```

That's what this library offers. It allows you to express "*this action requires a page parameter of type int*" or "*this action has an optional parameter createdAt of type DateTime, and will be set to a default value if absent*".

### Examples

[](#examples)

If you'd like to go straight to the code now, you can just play around with the examples.

1. `cd /tmp`
2. `git clone git@github.com:mpscholten/request-parser.git`
3. `cd request-parser`
4. `composer install`
5. `cd examples`
6. `php -S localhost:8080`
7. Open it:

There are also several other php files inside the examples directory. To get your hands dirty, I suggest just modifying the examples a bit.

### Getting Started

[](#getting-started)

Install via composer

```
composer require mpscholten/request-parser

```

### Integrations

[](#integrations)

- If you're using `symfony/http-foundation`, [click here](#symfony-httpfoundation).
- If you're using a Psr7 `ServerRequestInterface` implementation, [click here](#psr7).
- If you're using some other `Request` abstraction (or maybe just plain old `$_GET` and friends), [check out this example](https://github.com/mpscholten/request-parser/blob/master/examples/not-symfony.php).

#### Symfony HttpFoundation

[](#symfony-httpfoundation)

The following example assumes you're using the symfony `Request`:

```
class MyController
{
    use \MPScholten\RequestParser\Symfony\ControllerHelperTrait;

    public function __construct(Request $request)
    {
        $this->initRequestParser($request);
    }
}
```

Then you can use the library like this:

```
class MyController
{
    use \MPScholten\RequestParser\Symfony\ControllerHelperTrait;

    public function __construct(Request $request)
    {
        $this->initRequestParser($request);
    }

    public function myAction()
    {
        $someParameter = $this->queryParameter('someParameter')->string()->required();
    }
}
```

When doing `GET /MyController/myAction?someParameter=example`, the `$someParameter` variable will contain the string `"example"`.

You might wonder what happens when we leave out the `?someParameter` part, like `GET /MyController/myAction`. In this case the `$this->queryParameter('someParameter')->string()->required()` will throw a `NotFoundException`. This exception can be handled by your application to show an error message.

Take a look at [the examples](https://github.com/mpscholten/request-parser/tree/master/examples).

#### Psr7

[](#psr7)

The following example assumes you're using the Psr7 `ServerRequestInterface`:

```
class MyController
{
    use \MPScholten\RequestParser\Psr7\ControllerHelperTrait;

    public function __construct(ServerRequestInterface $request)
    {
        $this->initRequestParser($request);
    }
}
```

Then you can use the library like this:

```
class MyController
{
    use \MPScholten\RequestParser\Psr7\ControllerHelperTrait;

    public function __construct(ServerRequestInterface $request)
    {
        $this->initRequestParser($request);
    }

    public function myAction()
    {
        $someParameter = $this->queryParameter('someParameter')->string()->required();
    }
}
```

When doing `GET /MyController/myAction?someParameter=example`, the `$someParameter` variable will contain the string `"example"`.

You might wonder what happens when we leave out the `?someParameter` part, like `GET /MyController/myAction`. In this case the `$this->queryParameter('someParameter')->string()->required()` will throw a `NotFoundException`. This exception can be handled by your application to show an error message.

Take a look at [the examples](https://github.com/mpscholten/request-parser/tree/master/examples).

#### Optional Parameters

[](#optional-parameters)

To make the `someParameter` optional, we can just replace `required()` with `defaultsTo($someDefaultValue)`:

```
class MyController
{
    use \MPScholten\RequestParser\Symfony\ControllerHelperTrait;

    public function __construct(Request $request)
    {
        $this->initRequestParser($request);
    }

    public function myAction()
    {
        $someParameter = $this->queryParameter('someParameter')->string()->defaultsTo('no value given');
    }
}
```

When doing `GET /MyController/myAction`, the `$someParameter` variable will now contain the string `"no value given"`. No exception will be thrown because we specified a default value.

In general you first specify the parameter name, followed by the type and then specify whether the parameter is required or is optional with a default value.

For more examples, check out the `examples/` directory of this repository. It contains several runnable examples.

##### Integers, Enums, DateTimes and Json Payloads

[](#integers-enums-datetimes-and-json-payloads)

Often we need more than just strings. *RequestParser* also provides methods for other data types:

```
class DashboardController
{
    public function show()
    {
        $dashboardId = $this->queryParameter('id')->int()->required();

        // GET /dashboard?name=Hello   =>   $dashboardName == "Hello"
        $dashboardName = $this->queryParameter('name')->string()->required();

        // Get /dashboard?name=   => $dashboardName == "default value"
        $dashboardName = $this->queryParameter('name')->string()->defaultsToIfEmpty("default value");

        // GET /dashboard?status=private  =>   $dashboardStatus == "private"
        // GET /dashboard?status=public   =>   $dashboardStatus == "public"
        // GET /dashboard?status=invalid  =>   A NotFoundException will be thrown
        $dashboardStatus = $this->queryParameter('status')->oneOf(['private', 'public'])->required();

        // GET /dashboard?createdAt=01.01.2016     =>   $dateTime == new DateTime("01.01.2016")
        // GET /dashboard?createdAt=invalid_date   =>   A NotFoundException will be thrown
        $dateTime = $this->queryParameter('createdAt')->dateTime()->required();

        // GET /dashboard?config={"a":true}     =>   $json == ['a' => true]
        $json = $this->queryParameter('config')->json()->required();

        // GET /dashboard?includeWidgets=true    =>   $includeWidgets == true
        // GET /dashboard?includeWidgets=false   =>   $includeWidgets == false
        // GET /dashboard?includeWidgets=0       =>   $includeWidgets == false
        // GET /dashboard?includeWidgets=abcde   =>   A NotFoundException will be thrown
        $includeWidgets = $this->queryParameter('includeWidgets')->boolean()->required();

        // GET /dashboard?includeWidgets=yes   =>   $includeWidgets == true
        // GET /dashboard?includeWidgets=no    =>   $includeWidgets == false
        $includeWidgets = $this->queryParameter('includeWidgets')->yesNoBoolean()->required();

        // GET /image?scale=2.5   =>   $scale == 2.5
        $scale = $this->queryParameter('scale')->float()->required();
    }
}
```

All of these types also provide a `defaultsTo` variant.

###### Supported Data Types

[](#supported-data-types)

TypeCode exampleInput example**String**`$this->queryParameter('name')->string()->required();``'John Doe'`**Comma-Separated String**`$this->queryParameter('names')->commaSeparated()->string()->required();``'John Doe,John Oliver'`**Integer**`$this->queryParameter('id')->int()->required();``'5'`**Comma-Separated Integer**`$this->queryParameter('groupIds')->commaSeparated()->int()->required();``'5,6,7,8'`**Float**`$this->queryParameter('ratio')->float()->required();``'0.98'`**Comma-Separated Float**`$this->queryParameter('precipitation')->commaSeparated()->float()->required();``'0.98,1.24,5.21'`**DateTime**`$this->queryParameter('timestamp')->dateTime()->required();``'2016-07-20'`**Comma-Separated DateTime**`$this->queryParameter('eventTimes')->commaSeparated()->dateTime()->required();``'2016-07-20 13:10:50,2016-07-21 12:01:07'`**Boolean**`$this->queryParameter('success')->boolean()->required();``'true'`**Comma-Separated Boolean**`$this->queryParameter('answers')->commaSeparated()->boolean()->required();``'1,0,0,1'`**Yes/No Boolean**`$this->queryParameter('success')->yesNoBoolean()->required();``'yes'`**Comma-Separated Yes/No Boolean**`$this->queryParameter('answers')->commaSeparated()->yesNoBoolean()->required();``'y,n,n,y,n'`**JSON**`$this->queryParameter('payload')->json()->required();``'{"event":"click","timestamp":"2016-07-20 13:10:50"}'`**Comma-Separated JSON**`$this->queryParameter('events')->commaSeparated()->json()->required();``'{"event":"click","timestamp":"2016-07-20 13:10:50"},{"event":"add_to_basket","timestamp":"2016-07-20 13:11:01"}'`##### GET Requests:

[](#get-requests)

`$this->queryParameter($name)` tells the controller that we want a query parameter ([everything after the "?" is called the query string](https://en.wikipedia.org/wiki/Query_string)). This is usually what we want when dealing with GET requests

##### POST Requests:

[](#post-requests)

When we're dealing with a POST request, we need to use `$this->bodyParameter($name)` to access form fields or the ajax payload.

### Autocompletion

[](#autocompletion)

The library allows you to take extensive use of autocompletion features of your IDE. E.g. after typing `$this->queryParameter('someParameter)->`your IDE will offer you all the possible input types, e.g. `string()` or `int()`. After picking a type, e.g. `string()`, your IDE will offer `required()` or `defaultsTo(defaultValue)` to specify the behavior when the parameter is not set.

[![](https://github.com/mpscholten/request-parser/raw/master/images/autocomplete-anim.gif?raw=true)](https://github.com/mpscholten/request-parser/blob/master/images/autocomplete-anim.gif?raw=true)

[![](https://github.com/mpscholten/request-parser/raw/master/images/autocompletion-type.png?raw=true)](https://github.com/mpscholten/request-parser/blob/master/images/autocompletion-type.png?raw=true)[![](https://github.com/mpscholten/request-parser/raw/master/images/autocompletion-required.png?raw=true)](https://github.com/mpscholten/request-parser/blob/master/images/autocompletion-required.png?raw=true)

### Static Analysis

[](#static-analysis)

The library supports static analysis by your IDE. E.g. when having a parameter like `$createdAt = $this->queryParameter('createdAt')->dateTime()->required();`, your IDE will know that `$createdAt` is a `DateTime` object. This allows you to detect type errors while editing and also decreases the maintenance cost of an action because the types improve legibility.

The library also decreases the risk of unexpected null values because parameters always have an explicit default value or are required.

### Error Handling

[](#error-handling)

When a parameter is required but not found or when validation fails, the library will throw an exception. The default exceptions are `\MPScholten\RequestParser\NotFoundException` and `\MPScholten\RequestParser\InvalidValueException`. The suggested way to handle the errors thrown by the library is to catch them inside your front controller:

```
try {
    $controller->$action();
} catch (NotFoundException $e) {
    echo $e->getMessage();
} catch (InvalidValueException $e) {
    echo $e->getMessage();
}
```

#### Using Custom Exception Classes

[](#using-custom-exception-classes)

```
class MyController
{
    use \MPScholten\RequestParser\Symfony\ControllerHelperTrait;

    public function __construct(Request $request)
    {
        $exceptionFactory = new ExceptionFactory(CustomNotFoundException::class, CustomInvalidValueException::class));

        $config = new \MPScholten\RequestParser\Config();
        $config->setExceptionFactory($exceptionFactory);

        $this->initRequestParser($request, $config);
    }
}
```

#### Using Custom Exception Messages

[](#using-custom-exception-messages)

##### Overriding Single Messages

[](#overriding-single-messages)

If you need to override the exception message thrown by the library just once or twice, you can do this by passing the exception messages as the first and second argument to `->required()`:

```
class DashboardController
{
    public function show()
    {
        $dashboardId = $this->queryParameter('id')->int()->required("The dashboard id has to be a valid number", "No dashboard id given");
    }
}
```

##### Overriding All Messages

[](#overriding-all-messages)

If you don't want to specify a custom exception message for all your actions, but still don't want to use the built-in exception messages, you can provide your own exception message generator:

```
class FriendlyExceptionMessageFactory extends \MPScholten\RequestParser\ExceptionMessageFactory
{
    protected function createNotFoundMessage($parameterName)
    {
        return "Looks like $parameterName is missing :)";
    }

    protected function createInvalidValueMessage($parameterName, $parameterValue, $expected)
    {
        return "Whoops :) $parameterName seems to be invalid. We're looking for $expected but you provided '$parameterValue'";
    }
}

class MyController
{
    use \MPScholten\RequestParser\Symfony\ControllerHelperTrait;

    public function __construct(Request $request)
    {
        $config = new \MPScholten\RequestParser\Config();
        $config->setExceptionMessageFactory(new FriendlyExceptionMessageFactory());

        $this->initRequestParser($request, $config);
    }
}
```

Check it out [this example about custom exceptions](https://github.com/mpscholten/request-parser/blob/master/examples/custom-exception.php).

### Is It Production Ready?

[](#is-it-production-ready)

Absolutely. This library was initially developed at [quintly](https://www.quintly.com) and is extensively used in production since april 2015. Using it at scale in production means there's a a big focus on backwards compatibility and not breaking stuff.

### Tests

[](#tests)

```
composer tests
composer tests-coverage

```

### Contributing

[](#contributing)

Feel free to send pull requests!

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity38

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity70

Established project with proven stability

 Bus Factor1

Top contributor holds 89.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~208 days

Recently: every ~353 days

Total

8

Last Release

2160d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/00ab5df48f62845d1e549e99c62eff4379d692bf8721f98dd4ee00275723692a?d=identicon)[mpscholten](/maintainers/mpscholten)

---

Top Contributors

[![mpscholten](https://avatars.githubusercontent.com/u/2072185?v=4)](https://github.com/mpscholten "mpscholten (41 commits)")[![kasitmp](https://avatars.githubusercontent.com/u/955104?v=4)](https://github.com/kasitmp "kasitmp (3 commits)")[![funivan](https://avatars.githubusercontent.com/u/425208?v=4)](https://github.com/funivan "funivan (1 commits)")[![larrydahooster](https://avatars.githubusercontent.com/u/4989851?v=4)](https://github.com/larrydahooster "larrydahooster (1 commits)")

---

Tags

inputphp-librarypsrpsr7-httpsymfony-httpfoundationtype-safety

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/mpscholten-request-parser/health.svg)

```
[![Health](https://phpackages.com/badges/mpscholten-request-parser/health.svg)](https://phpackages.com/packages/mpscholten-request-parser)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)