README

支持深度数组的PHP白名单库

安装

composer require reliv/white-rat

使用

作为无状态服务使用

use Reliv\WhiteRat\Filter;

$filter = new Filter();

$rules = /* White-list rules go here; see further explanation below */;

// Optional safety check; throws an exception if $rules is not valid
$filter->validate($rules);

$subject = [/* Data to be filtered */];

$filteredSubject = $filter($subject, $rules);

预编译可调用的白名单作为可重用过滤器

use Reliv\WhiteRat\Whitelist;

$whitelist = new Whitelist([
    /* White-list rules go here; see further explanation below */
    /* The rules will be validated upon construction */
]);

$subject = [/* Data to be filtered */];

$filteredSubject = $whitelist($subject);

白名单规则

白名单规则集被设计为与它们应用到的数据结构紧密对应。规则集的形式是一个混合了关联和索引值的数组，尽管索引值的顺序无关紧要。当一个值作为索引值出现时，它必须是一个字符串。当它是关联的，它必须是一个数组或布尔值。每个字符串，无论它是键还是值，都与数据中的键相关联。

如果一个字符串作为索引值出现，则数据中的相关键以及所有下级字段都将被白名单。

如果一个字符串作为键出现，并且值是布尔值，这表示相关数据是否被白名单。

如果一个字符串作为键出现，并且值是一个数组，这表示对相关数据子键的更具体的白名单规则。白名单规则随后递归进行。

也可以白名单索引数组。要做到这一点，在数组中创建一个数组，其中子数组是其父数组的唯一子代，并且是索引子代。这看起来像一组双括号，我们称之为“双数组”。

白名单规则在白名单构造时进行验证。如果检测到规则中存在任何问题，将抛出类型为 Reliv\WhiteRat\WhitelistValidationException 的异常，并提供规则路径和错误解释。

默认情况下，没有字段被白名单，所有数据将被过滤，留下空数组。但是，在白名单中存在但在过滤数据中缺失的字段将被忽略。这意味着可以安全地白名单可选数据。

示例

$whitelist = new Whitelist([
    'foo',
    'bar' => true,
    'bob' => false,
    'baz' => [
        'flip' => true,
        'flop' => [ ['flummox'] ],
        'quux',
    ]
]);

$data = [
    'foo' => 'FOO!',
    'bar' => 'BAR!',
    'bob' => 'BOB!',
    'baz' => [
        'flip' => 'FLIP!',
        'flop' => [
            ['flimsy' => 111, 'flummox' => 222],
            ['flummox' => 333, 'flopsy' => 444]
        ]
    ]
]

$result = $whitelist($data);

var_dump($result);

输出

array(3) {
    ["foo"] => "FOO!"
    ["bar"] => "BAR!"
    ["baz"] => array(2) {
        ["flip"] => "FLIP!"
        ["flop"] => array(2) => {
            array(1) => {
                ["flummox"] => int(222)
            }
            array(1) => {
                ["flummox"] => int(333)
            }
        }
    }
}