Variable validation

PostNuke includes a transparent mechanism for variable validation. It's currently used by two API functions: pnUserValidateVar() and pnUserSetVar(). The validation works thanks to the Dynamic User Data architecture. As you saw in the above section, with Dynamic User Data you can register new user variables simply by providing its metadata. That metadata can also contain a special field denoted by the validation key. A powerful syntax has been invented for this field. All what you need to do is to follow the right syntax and write your own validator(s), later you register it with user variable metadata and now you can get rid of validation in your module functions. Simply when you call pnUserSetVar(), PostNuke will automatically apply your validator(s) and if the check fails you will be notified of that by the return value. To compensate for all this loss of control on validation, a new API function has been created. You can validate an user variable value with the pnUserValidateVar() function. That gives you the possibility to first validate all variables from user input and second update them if all validation checks have succeeded.

Here is the grammar for the validation string:

         validation_string := validator_list
         validator_list := validator [ + '&' + validator_list ]
         validator := ['!' +] type + ':' + operator + ':' + param
  

Reserved characters to be escaped with a preceeding '\' are: ':' and '&'

type can be one of these values: 'num', 'string', 'stringlen', 'func'.

operator is type-sensitive:

• valid operators for num type are: ==, !=, <, >, <=, >=

• valid operators for string type are: is, contains, starts, ends, regex

• valid operators for stringlen are the same as num type.

• there's only one valid operator for func type: it's a string composed from ModName + ',' + FuncName. FuncName MUST be exported as an user API function from ModName module.

param is the second parameter to be used with operator, except for the func type: here param is the second parameter that will be passed to FuncName function.

You can create complex validators simply by concatenating them with the logic & (AND) operator.

Here are some examples:

// validation string = "string:starts:foo bar"
// validation will succeed
pnUserSetVar("myVar", "foo bar is better than bar foo");
// validation will fail
pnUserSetVar("myVar", "bar foo is ugly");
// validation string = "string:starts:foo\\: bar&stringlen:<=:16"
// NOTE: if you need to use the ':' character you have to
//       escape it with a preceding '\'
// validation will succeed
pnUserSetVar("myVar", "foo: bar is good");
// validation will fail, the string is too long
pnUserSetVar("myVar", "foo: bar is better");
// validation string = "!string:regex:/(censored1|censored2)/"
// NOTE: the negation operator before the string type
// validation will succeed
pnUserSetVar("myVar", "i'm a good boy, i'm not posting something bad");
// validation will fail
pnUserSetVar("myVar", "i'm a bad boy, you are a censored1");
// validation string = "num:>=:1&num:<=:10"
// validation will succeed
pnUserSetVar("myVar", "5");
// validation will fail
pnUserSetVar("myVar", "12");
// validation string = "func:MyModule,MyFunc:none"
// IMPORTANT: if your validation function works only with the
//            variable value you must specify that param has not
//            to be passed to function.
//            You achieve that by simply setting it to 'none'
// validation will succeed
pnUserSetVar("myVar", "Homer Simpson");
// validation will fail
pnUserSetVar("myVar", "Marco Canini");
// MyModule user API
function MyModule_userapi_MyFunc($args)
{
    extract($args);  // $value
    $ssconn = StarShip::openConnection();
    return !$ssconn->isAlienLifeForm($value);
}