README

Morf was designed to filter request-parameters en masse but it is also useful in many other situations.

A Morf Filter is created from an array of definitions that describes each parameter you're interested in, and serves-up valid, type-cast values; it'll spit-out an exception when something's overtly wrong.

For safety's sake, Morf is strict and opinionated, and uses PHP built-ins whenever possible.

Example

It's pretty straightforward:

use DanBettles\Morf\Filter;

$definitions = [
    [
        'name' => 'anything',  // N.B. `name` is the only required element
        // 'type' => 'string',  // The default output-type
    ],
    [
        'name' => 'show_retirement',
        'type' => 'bool',  // Or use `"boolean"`
        // 'default' => false,  // The built-in default value of a Boolean
    ],
    [
        'name' => 'show_under_offer',
        'type' => 'bool',
        'default' => true,  // N.B. the same type as named in `type`
    ],
    [
        'name' => 'location_id',
        'type' => 'int',  // Or use `"integer"`
        'default' => 7,
        'validator' => 'positiveInteger',  // See Built-In Validators, below
    ],
    [
        'name' => 'num_rooms',
        'type' => 'int',
        'default' => -1,
        'validValues' => [-1, 1, 2, 3],  // `validValues` takes precedence over `validator`
    ],
    [
        'name' => 'a_floating_point_number',
        'type' => 'float',  // Or use `"double"`
    ],
    [
        'name' => 'an_array',
        'type' => 'array',
    ],
];

// Empty request, so defaults applied:

$actual = Filter::create($definitions)->filter([]);

$expected = [
    'anything' => '',
    'show_retirement' => false,
    'show_under_offer' => true,
    'location_id' => 7,
    'num_rooms' => -1,
    'a_floating_point_number' => 0.0,
    'an_array' => [],
];

assert($expected === $actual);

// Form submitted, say:

$actual = Filter::create($definitions)->filter([
    'anything' => 'Hello, World!',
    'show_retirement' => '0',
    'show_under_offer' => '0',
    'location_id' => '2',
    'num_rooms' => '2',
    'a_floating_point_number' => '3.142',
    'an_array' => ['foo', 'bar', 'baz'],
]);

$expected = [
    'anything' => 'Hello, World!',
    'show_retirement' => false,
    'show_under_offer' => false,
    'location_id' => 2,
    'num_rooms' => 2,
    'a_floating_point_number' => 3.142,
    'an_array' => ['foo', 'bar', 'baz'],
];

assert($expected === $actual);

Valid Inputs

Default Values

The built-in default values for each output-type—the values returned when parameters aren't set—are the same as those used in Symfony\Component\HttpFoundation\ParameterBag, which we think are intuitive. No problem if you disagree, or if your application requires something different, because you can specify parameter-level default values—see the example above.

Built-In Validators

Footnotes

1. We take the view that being explicit is better (safer) in the long run. So, for example, a Boolean parameter with a blank value is treated as invalid because you can easily represent a Boolean value using "1" or "0"—which we think is more intuitive in any case. ↩