This release adds a change to the StringParser to improve autocompletion, contributed by @larrydahooster.

This release adds a new string length validator contributed by @kasitmp:

• ->string()->lengthBetween(3, 10)->required()
• ->string()-> lengthLargerThan(3)->required()
• ->string()-> lengthLargerThanOrEqualTo(3)->required()
• ->string()-> lengthSmallerThan(10)->required()
• ->string()-> lengthSmallerThanOrEqualTo(10)->required()

This release fixes that InvalidValueException is being thrown instead of NotFoundException by the ->required() calls.

This release adds ->trim() support to strings and ->between($start, $end) support to numeric types:

// full trim:
$this->queryParameter('someQueryParam')->string()->trim()->required();
// right trim:
$this->queryParameter('anotherQueryParam')->string()->rightTrim()->required();
// left trim:
$this->bodyParameter('someBodyParam')->string()->leftTrim()->required();
// Only accept integers between 0 and 100
$this->bodyParameter('progress')->int()->between(0, 100)->required();
// Only accept floats between 0 and 1
$this->bodyParameter('progress')->float()->between(0, 1)->required();

What's new?

1. Validation Errors
2. Custom Inline Exception Messages
3. CSV Parsers
4. Url Parser
5. Email Parser
6. New Approach To Exceptions
7. Other Minor changes

Validation Errors:

$this->queryParameter('id')->int()->required()

Calling this via GET /?id=not_an_integer will now throw a exception with the message

Invalid value for parameter "id". Expected an integer, but got "not_an_integer"

Previously, Parameter id not found was the default exception message. That was not very insightful, as does not indicate that the validation failed.

The exception class in this case is \MPScholten\RequestParser\InvalidValueException if not specified otherwise. It's a subclass of \MPScholten\RequestParser\NotFoundException for b.c. reasons.

If you're using a custom exception or a custom exception message, you need to migrate your code to use this feature. More on that below.

Custom Inline Exception 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():

$this->queryParameter('id')->int()->required("invalid id", "id not found in the request");

• The above code will throw an exception with the message invalid id instead of the default message if an invalid id parameter is provided.
• If no id parameter is provided at all, the message is id not found in the request instead of the default message.

If you're using a custom exception or a custom exception message, you need to migrate your code to use this feature. More on that below.

CSV Parsers:

The library now supports comma separated values:

$names = $this->queryParameter('names')->commaSeparated()->string()->required();

GET /?names=John,Oliver

As expected it also supports ->defaultsTo.

There is also ->commaSeparated()->int()->, ->commaSeparated()->float()-> and many more. Take a look at the documentation for a list of all supported parsers

Url Parser:

$url = $this->queryParameter('url')->string()->url()->required();

It uses php's filter_var for validation.

Email Parser:

$email = $this->queryParameter('email')->string()->email()->required();

It uses php's filter_var for validation.

New Approach To Exceptions:

To better support the new features, like validation errors, the internal handling of exceptions was changed. This is only interesting to you if you're using custom exceptions with the library.

The old approach worked as follows:

$this->initRequestParser($request, function ($parameter) {
    return new CustomException("The parameter $parameter was not found");
});

If you're still using that approach, you need to migrate to support newer features like validation errors. Check Using Custom Exception Classes and Using Custom Exception Messages to learn how the new way of configuring custom exceptions works.

Keep in mind that the old callback-based approach still works (so you don't need to upgrade it now), but then you cannot take advantage of validation errors and inline exception messages.

Minor changes:

• The default not found message got reworded from Parameter $name not found to Parameter "$name" not found
• The README now has a table of contents

This release adds first-class Psr7 support:

Just use the Psr7\ControllerHelperTrait and call initRequestParser with a ServerRequestInterface object and you can use the library as expected:

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

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

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

Take a look at the docs to learn more.

Several Documentation Updates:

• A new section "Is It Production Ready?"
• Some small fixes

This release includes several new types contributed by @yuvalherziger

• boolean ("0"/"1", "true", "false" => true/false)
• yesNoBoolean ("yes", "no" => true/false)
• float ("0.1" => 0.1

There's also a new way to deal with empty strings. You can now tell the string() parser to also use the provided default value when the given string is empty (currently the default value is only used when the string is not given at all). So $value = $this->queryParameter(..)->string()->defaultsToIfEmpty('empty') is equivalent to

$value = $this->queryParameter(..)->string()->defaultsTo('empty');
if ($value == "")
    $value = 'empty';

🎉