Wiki: CMS Clean Helper v5.5 - 2016.08.08

Topnew Clean helper (cms/cms_clean.php) is a collection of PHP functions for Form data sanitization and validation.

Raw Data: $data = cms_form_data()

Call cms_form_data() after cms_form_cols() and before any cms_form() as form fields will need data for its fields.

By default $data = $_POST, however sometimes we need get data from _GET, or both, or even more:

$data = cms_form_data();//default $_POST

//The following 4 are same:
$data = cms_form_data('BOTH');//$_POST, then $_GET, the latter will overwrite any existing same key
$data = cms_form_data($_POST, $_GET);//same as 'BOTH'
$data = cms_form_data('POST', 'GET');
$data = cms_form_data('', 'GET');

$data = cms_form_data('GET');//get data from $_GET only

//The following 4 are same:
$data = cms_form_data('id;name:alias');//$_POST, then $id=$_GET[id], $name=$_GET[alias]
$data = cms_form_data($_POST, 'id;name:alias');
$data = cms_form_data('POST', 'id;name:alias');
$data = cms_form_data('', 'id;name:alias');

//The following will not parse $_POST, if not specified in the list
//A string will use $_GET
//unlimited, the latter will overwrite any existing same key
$data = cms_form_data($array1, $array2, $string, ...);

Data sanitization

Unless specified, all form fields will be treated as string to be sanitized, then all data will be validated according to validation rules set.

For values from an option list, it will be one of the options, so that you do not need to setup a data sanitization rule for this field.

For detailed rules please check cms_clean(), the following is a list of examples

$cols = [
    'id' => [
        'rule' => 'int',//bool;digits;int;...
    ],
    'name' => [
        'rule' => 'rule1;rule2;rule3;...',
        //'enum,defaultValue|val1|val2|...'
        //['enum', $options]
        //'minmax,min,max,default' eg 'minmax,0,999,50'
        //'num,decimal' eg 'num,2'
        //'date,out,in' eg 'date,Y-m-d,DMY'
        //'time,out'
        //'datetime,out,in'
        'rule' => [
            ['enum', [options list]],
            ['date', 'Y-m-d', 'DMY'],
            //rule can also be in array
        ],
    ],
];

Data Validation

Validation only happens when valid rules set, if validation failed, an error will be issued to form field accordingly.

$cols = [
    'id' => [
        'valid' => [
            'req' => 'optional err msg for a required field',
            'minmax' => [0, 999, 'optional err msg if invalid']],
    ],
    'email' => [
        'valid' => [
            'req',
            'email' => 'optional err msg',
            'email_unique' => $data['uid'],
        ]
    ],
    'password' => [
        'valid' => [
            'pwd'
        ],
    ],
    'password_retype' => [
        'valid' => [
            'same' => 'password'
        ],
    ],
    'name' => [
        'valid' => [
            'len' => [5, 20]
        ]
    ],
];

Unless cols.form.attr.token = -1, a POST form will be valiated against the dynamically generated form security tokens.

'req' => errMsg,
'email' => errMsg,
'pwd' => 'at least 8 chars at least 1 digit 1 upper case 1 lower case 1 special char',
email_unique' => [uid, errMsg],
'len' => [min, max, errMsg],
'minmax' => [min, max, errMsg],
'same' => [val, isV, errMsg]

All errMsg is optional, so you can either have:
'valid' => ['req', ...] or
'valid' => ['req' => 'err msg', ...]
'valid' => ['email_unique' => [$uid, $errMsg]] or
'valid' => ['email_unique' => $uid]

valid => ['len' => [minLength, maxLength, errMsg]]
minLength = 0+, maxLength = 0+
'valid' => ['len' => 5] = ['len' => [5, null]] = ['len' => [5, 0]]

'valid' => ['minmax' => 5] = ['minmax' > [5, null]] != ['minmax' => [5, 0]]

'valid' => ['same' => 'abc'] will valid against $data['abc'], abc is the column name
'valid' => ['same' => ['abc', 1]] will valid against value of 'abc'

'valid' => ['email_unique'] without any user_id pass in:
if email found in database, will be invalid
if email not found, it is valid unique email

'valid' => ['email_unique' => $uid] with a user_id pass in:
if email found in database with a different user_id, will be invalid
otherwide it is valid unique email

Additional settings with form validation

You have to set up $cols['field']['valid'] to start a validation, otherwise validation will be ignored

When to trigger the validation:

$cols['form']['valid']['valid_when'] = 'null | GET | LOAD | EACH | ...'

GET when $_GET is true
LOAD when a page is loaded even without any form submitted
EACH when $_GET OR $_POST is true
any other value will valid when $_POST is true [default]

cols['form']['valid']['stop_at_err'] = 1; //will stop when an error is found, otherwise validate against all rules.

Validation errors

Any validation error will be issued to

$cols['form']['err'] = [
    'field1' => ['err1', 'err2', ...],
    'field6' => 'errMsg',
    ...
]

You can echo cms_form('err') at any place of the page. You can also check if there is any error: if (cms_form('err')) { do some thing...}

If you have not registered $cols, you can issue a customized err msg by:

$err = [
    'field1' => ['err1', 'err2', ...],
    'field6' => 'errMsg',
    ...
];
echo cms_form('err', $err);

Finally, you can also echo err with any other form elements eg:
echo cms_form('err;form;id;name;cmd;end');

Projects - 其他项目:

bank BenSon Bank
Cash Manager

blog Blog Forum
Blog BBS Ticket

chart SVG Chart
PHP SVG Chart

save Page Maker
Page Maker

topnew SIDU DB GUI
Database tool