README

关于

此包提供用于验证和清理用户输入数据的过滤器。

需求

此包需要 php 7.2

安装

使用 composer

composer require linna/filter

可用过滤器

过滤器

一个规则可以用名称或别名调用。别名有助于更快速地编写规则。

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

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

运算符

过滤器类型

过滤器可以分为两种类型：验证过滤器或清理过滤器。验证过滤器仅检查数据是否满足某些标准，而清理过滤器会修改通过的数据，使其符合给定的规则。

本包中仅包含清理过滤器 数字 和 转义

注意：出于安全原因，应首选验证过滤器，不要尝试清理不良用户输入，直接丢弃！

使用方法

过滤器可以通过两种不同的方式使用。

过滤一个字段

对一个值应用一个或多个规则

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());

过滤多个字段

对多个值应用一个或多个规则，这对于验证表单非常有用

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());

检索结果

有两种方式从过滤器获取结果。

使用 Filter 实例的方法。

use Linna\Filter\Filter;

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

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

使用结果对象

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();

规则语法

解析器可以接受各种格式的规则。

第一个单词必须是输入的名称，与输入数组中的索引相同。

//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',
];

可以使用以下字符分隔规则中的单词和参数： : ; ,

输入名称分隔符 :

$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"',
];

$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\'',
];

自定义规则

自定义规则提供了扩展过滤器预定义规则集的可能。

验证

$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());

自定义规则应有

• 至少一个别名。

对于回调函数

• 至少一个参数，代表接收到的值。
• 返回类型，bool 或 void。

注意：为了实现清理自定义规则，闭包必须只有一个参数，并且该参数必须通过引用传递。