README

About

This package provide filters for validate and sanitize user input data.

Requirements

This package require php 7.2

Installation

With composer:

composer require linna/filter

Available Filters

Filters

A rule could be called with the name or with the alias. An alias help to write rules more quickly.

//using rule name
$rule = 'age: number, numbercompare < 30';

//using alias
$rule = 'age: n, nc < 30';

Operators

Type of filters

Filters can be of two types: Validation filters or Sanitization filters. Validation filters check only if the data respect a certain criterion, instead sanitization filters alter passed data to make them conform to a given rule.

In this package are sanitization filters only Number and Escape

Note: For security reasons a Validation filter should be preferred, don't try to sanitize a bad user input, discard it!

Usage

Filters can be used in two different ways.

Filter one field

Apply one or more rules to one value:

use Linna\Filter\Filter;

$f = new Filter();
$f->filter(20, 'number numberinterval >< 15 25');

//int 0
var_dump($f->getErrors());

//array (size=1)
//  'data' => 
//    array (size=0)
//      empty
var_dump($f->getMessages());

//array (size=1)
//  'data' => int 20
var_dump($f->getData());

Filter multiple fields

Apply one or more rules to many values, it is useful for validating forms:

use Linna\Filter\Filter;

//override $_POST superglobal for simulate data from user form
$_POST = [
    'email' => 'user@email.com',
    'password' => 'p4ssw0rd200!',
    'age' => '25',
    'born' => '1980-06-01',
];

//create instance
$fm = new Filter();
$fm->filter($_POST, [
    'email: required, email',
    'password: required, stringlencompare >= 12',
    'age: number, numbercompare < 30',
    'born: date Y-m-d, datecompare <= Y-m-d 1990-12-31',
]);

//int 0
var_dump($fm->getErrors());

//array (size=4)
//  'email' => 
//    array (size=0)
//      empty
//  'password' => 
//    array (size=0)
//      empty
//  'age' => 
//    array (size=0)
//      empty
//  'born' => 
//    array (size=0)
//      empty
var_dump($fm->getMessages());

//array (size=4)
//  'email' => string 'pippo@gmail.com' (length=15)
//  'password' => string 'p4ssw0rd200!' (length=12)
//  'age' => int 25
//  'born' => string '1980-06-01' (length=10)
var_dump($fm->getData());

Retriving results

There are two ways for get results from filter.

Using methods from Filter instance.

use Linna\Filter\Filter;

$f = new Filter();
$f->filter(20, 'number numberinterval >< 15 25');

$errors = $filter->getErrors();
$messages = $filter->getMessages();
$data = $filter->getData();

Using result object:

use Linna\Filter\Filter;

$f = new Filter();
$result = $f->filter(20, 'number numberinterval >< 15 25');

//or with a single expression
$result = (new Filter())->filter(20, 'number numberinterval >< 15 25');

$errors = $result->errors();
$messages = $result->messages();
$data = $result->data();

Rule syntax

Parser can accept rules formatted in varius way.

First word must be the name of the input, same present as index in input array.

//override $_POST superglobal for simulate data from user form
$_POST = [
    'email' => 'pippo@gmail.com',
    'password' => 'p4ssw0rd200!',
    'age' => '25',
    'born' => '1980-06-01',
];

$rules = [
    'email required email',
    'password required stringlencompare >= 12',
    'age number numberinterval >=< 20 30',
    'born date Y-m-d datecompare <= Y-m-d 1990-12-31',
];

Can be used for separate the words and params of rules this chars: : ; ,

Input name separator :

$rules = [
    'email: required email',
    'password: required stringlencompare >= 12',
    'age: number numberinterval >=< 20 30',
    'born: date Y-m-d datecompare <= Y-m-d 1990-12-31',
];

Input name separator : Rules separator ,

$rules = [
    'email: required, email',
    'password: required, stringlencompare >= 12',
    'age: number, numberinterval >=< 20 30',
    'born: date Y-m-d, datecompare <= Y-m-d 1990-12-31',
];

Input name separator : Rules separator ; Rule arguments separator ,

$rules = [
    'email: required; email',
    'password: required; stringlencompare >=, 12',
    'age: number; numberinterval >=<, 20, 30',
    'born: date Y-m-d; datecompare <=, Y-m-d, 1990-12-31',
];

Must be used for params that contain spaces one of this chars: " '

$rules = [
    'email: required email',
    'password: required stringlencompare >= 12',
    'age: number numberinterval >=< 20 30',
    'born: date "Y m d" datecompare <= "Y m d" "1990 12 31"',
];

$rules = [
    "email: required email",
    "password: required stringlencompare >= 12",
    "age: number numberinterval >=< 20 30",
    "born: date \"Y m d\" datecompare <= \"Y m d\" \"1990 12 31\"",
];

$rules = [
    "email: required email",
    "password: required stringlencompare >= 12",
    "age: number numberinterval >=< 20 30",
    "born: date 'Y m d' datecompare <= 'Y m d' '1990 12 31'",
];

$rules = [
    'email: required email',
    'password: required stringlencompare >= 12',
    'age: number numberinterval >=< 20 30',
    'born: date \'Y m d\' datecompare <= \'Y m d\' \'1990 12 31\'',
];

Custom Rules

Custom rules give the possibility of expand the filter predefined ruleset.

Validate

$customRules = [];
$customRules[] = new CustomRule(
    //alias
    ['hellocheck'],
    //callback
    //check if word hello is inside of a phrase
    function (string $received): bool {
        if (strpos(strtolower($received), 'hello') === false) {
            return false;
        }

        return true;
    }
);

$filter = new Filter();
$filter->addCustomRules($customRules);

//test passed
$r = $filter->filter('Hello World', 'hellocheck');

//array (size=1)
//  'data' => string 'Hello World' (length=11)
var_dump($r->data());

//int 0
var_dump($r->errors());

//array (size=1)
//  'data' => 
//    array (size=0)
//      empty
var_dump($r->messages());


//test fails
$r = $filter->filter('Heo World', 'hellocheck');

//array (size=1)
//  'data' => string 'Heo World' (length=9)
var_dump($r->data());

//int 1
var_dump($r->errors());

//array (size=1)
//  'data' => 
//    array (size=1)
//      0 => string 'Value provided not pass CustomRule (hellocheck) test' (length=52)
var_dump($r->messages());

Sanitize

$customRules = [];
$customRules[] = new CustomRule(
    //alias
    ['emailtoletters'],
    //callback
    //replace dot and at chars with literal name
    function (string &$received): void {
        $received = str_replace('@', ' at ', $received);
        $received = str_replace('.', ' dot ', $received);
    }
);

$filter = new Filter();
$filter->addCustomRules($customRules);

$r = $filter->filter('sebastian.rapetti@alice.it', 'emailtoletters');

//array (size=1)
//  'data' => string 'sebastian dot rapetti at alice dot it' (length=37)
var_dump($r->data());

//int 0
var_dump($r->errors());

//array (size=1)
//  'data' => 
//    array (size=0)
//      empty
var_dump($r->messages());

Custom Rule should have:

At least one alias.

And for callback function:

At least one argument, rapresenting the received value.
Return type, bool or void.

Note: For implementing a sanitize custom rule, closure must have only one argument and this argument must be passed for reference.

linna / filter

Maintainers

Details