danbettles/morf

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 o

v2.0.0 2025-06-18 09:17 UTC

Requires

• php: ^8.3

Requires (Dev)

• danbettles/codesniffer-standard: ^2.0
• phpstan/phpstan: ^1.12.27
• phpunit/phpunit: ^9.6.23
• squizlabs/php_codesniffer: ^3.13.2

ISC

• Daniel Bettles

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

Type	Valid Input
bool, boolean	"1", "0"1
int, integer	Any integer in string form
float, double	Any float/integer in string form
string	Any string
array	Any array

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

Name	Valid Value
positiveInteger	Integer > 0
nonNegativeInteger	Integer >= 0

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. ↩