netherphp/input

Input Handling.

v4.0.0 2021-01-07 01:36 UTC

This package is auto-updated.

Last update: 2021-11-07 03:35:25 UTC


README

nether.io Code Climate Build Status Packagist Packagist

An input filtering interface. It allows you to define a set of dynamic filters for input to be run applied just-in-time on your specified data source.

Super simple example:

$input = (new Nether\Input\Filter)
->Email(function($t){ return filter_var($t,FILTER_VALIDATE_EMAIL); });

// ... some time later...

$input->SetDataset($_POST);
if(!$input->Email) {
	throw new Exception('valid email address is required.');
}

To pull this off, things like your HTML form field names will need to follow the same rules as properties in PHP (alphanumeric and _ starting with a letter). By default it is case insensitive, so you can send all lowercase from your URL if you want and then reference them in whateverCase YouChoose to use. That can be disabled if you are on a performance powertrip.

You can pass any array or object to the constructor or use SetDataset(). Typical uses would be for _GET and _POST but you could apply it to any named dataset that needs looked at. You can also change datasets at will, keeping any predefined filters intact.

Another Simple Example:

Lets say we want to dump our POST data back into our form because there was some sort of validation error. This is the time where it is very easy to accidentally open yourself up to cross-site scripting problems. Input Filter can take care of that for you though by defining a default filter that all fields which do not have their own special filters for, get run through.

$data = (new Nether\Input\Filter($_POST))
->SetDefaultFunction(function($v){ return htmlspecialchars($v) });

// ... some time later...

<input type="text" name="Username" value="<?php echo $data->Username ?>" />

Creating a new interface.

Wrap any object or array in the OOP interface.

$input = new Nether\Input\Filter($_POST);

Retrieve a value.

Fetch the value from $_POST['myfield'], after running it through any filters we assigned to the field.

$val = $input->MyField

Set a value.

Note, this will not update the original source array. Writing back to the dataset will prompt the copy-on-write, so now you have your own unique dataset and in this example, will not affect the original $_POST['myfield'].

$input->MyField = 'ten';

Set a filter.

You call the field as a method, passing it a callable function with one argument which is the value.

$input->MyField(function($t){
	return str_repalce('a','@',$t);
});

Retrieve a filter.

You invoke the object directly, passing it a string that was the name of the field you originally defined the callback on. Here is an example reusing an existing callback on another field.

$input->MyOtherField($input('MyField'));

Installing

Require this package in your composer.json.

require {
	"netherphp/input": "~1.0.0"
}

Then install it or update into it.

$ composer install --no-dev
$ composer update --no-dev

Testing

This library uses Codeception for testing. Composer will handle it for you. Install or Update into it.

$ composer install --dev
$ composer update --dev

Then run the tests.

$ php vendor/bin/codecept run unit
$ vendor\bin\codecept run unit