This package provide filters for validate and sanitize user input data.
This package require php 7.2
With composer:
composer require linna/filter
| Rule Name | Aliases | Description | Rule Arguments | Operators | Example Data from $_POST |
Example Rule |
|---|---|---|---|---|---|---|
| date | dat, d | check for a valid date | 1 | none | ['born'] = '1980-06-01' |
'born: date Y-m-d' |
| datecompare | datcmp, dc | compare one date with another | 3 | >, <, >=, <=, = | ['born'] = '1980-06-01' |
'born: datecompare < Y-m-d 1990-01-01' |
| mail, e@ | check for a valid email | 0 | none | ['email'] = 'foo@mail.com' |
'email: email' |
|
| escape | escp, es | convert special chars in html entities | 0 | none | ['name'] = 'foo<script>' |
'name: escape' |
| ip | ip | check for a valid ip (ipv4 and ipv4) | 0 | none | ['host'] = 192.168.0.1 |
'host: ip' |
| iprange | iprng, ipr | check if provided ipv4 or ipv6 is in CIDR range | 1 | none | ['host'] = 192.168.0.1 |
'host: iprange 192.168.0.1/24' |
| number | num, n | check for a valid number and cast to number | 0 | none | ['age'] = 25 |
'age: number' |
| numbercompare | numcmp, nc | compare one number with another | 2 | >, <, >=, <=, = | ['age'] = 25 |
'age: numbercompare > 18' |
| numberinterval | numint, ni | check if a number is included or not on interval | 3 | <>, ><, <=>, >=< | ['age'] = 25 |
'age: numberinterval >< 18 80' |
| required | req, rq | check for null values | 0 | none | ['name'] = 'foo' |
'name: required' |
| str | string, s | cast to string | 0 | none | ['name'] = 'foo' |
'name: str' |
| stringlencompare | strlencmp, strlen, slc | check the length of a string | 2 | >, <, >=, <=, =, != | ['name'] = 'foo' |
'name: stringlencompare > 2' |
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';| Rule Name | Operator | Description | Notes |
|---|---|---|---|
| DateCompare | < | less than | |
| > | greater than | ||
| <= | less than or equal | ||
| >= | greater than or equal | ||
| = | equal | PHP === equal | |
| NumberCompare | < | less than | |
| > | greater than | ||
| <= | less than or equal | ||
| >= | greater than or equal | ||
| NumberInterval | <> | out interval, exclusive | 8-10: 7, 11 true - 8, 9, 10 false |
| >< | in interval, exclusive | 8-10: 9 true - 7, 8, 10, 11 false | |
| <=> | out interval, inclusive | 8-10: 7, 8, 10, 11 true - 9 false | |
| >=< | in interval, inclusive | 8-10: 8, 9, 10 true - 7, 11 false | |
| StringLenCompare | < | length less than | PHP strlen(string) < number |
| > | length greater than | PHP strlen(string) > number | |
| <= | length less than or equal | PHP strlen(string) <= number | |
| >= | length greather than or equal | PHP strlen(string) >= number | |
| = | length equal | PHP strlen(string) === number | |
| != | length not equal | PHP strlen(string) !== number |
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!
Filters can be used in two different ways.
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());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());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();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 give the possibility of expand the filter predefined ruleset.
$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());$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.