Parameters

Every page can receive parameters from the user side/browsers. The CodKep can use 3 type of parameters:

All type of parameters above can access same way in CodKep.

Defining parameters

By security reasons you have to define each parameter before use it. The definition have to specify the type of the parameter which divided to security classes, and can tell other properties.

You can define a parameter with the following function:
par_def($name,$security_class,$source = 'all',$accept_empty = true,$default = NULL,$required = NULL)

Example definition of two get parameter 

function mypage()
{
  par_def("id","number0","url",false,NULL,"You have to specify the id of the item");
  par_def("name","text3");
  //...
  //parameters are accesible by par()
  print "Id: ".par("id");
  print "Name:".par("name");
}

Defining in route definition array

It is possible to do the parameter definition in route definition array.

You have to put an associative array under "parameters" index in route definition array. The structure of this array structured this way:

Note: The items of this array are passed to the par_def() function which define the parameters according to this array. Because the values of this array are passed to the par_def() see the documentation of that for further explanations.

An examample defineroute hook which defined two parameter "id" and "name" 

function hook_mymodule_defineroute()
{
    $r = [];
    $r[] = [
             'path' => 'showitem/{id}',
             'callback' => 'showitempage',
             'parameters' => [
                                'id' => ['security' => 'number0'
                                         'source' => 'url',
                                         'required' => 'You have to specify the id of the item',
                                        ],
                                'name' => 'text3',
                             ],
           ];
    return $r;
}

function showitempage()
{
    ob_start();
    //You can use par() function here to access parameters
    print "Id:".par("id");
    print "Name:".par("name");
    //...
    return ob_get_clean();
}

Using parameters

par($name, $autodefine_type = 'no')
Returns the value of the parameter $name. The parameter must be defined before the value is requested.

In case the $site_config->parameter_autodefine is set true in site settings the par() function can automatically define the parameter by the security class $autodefine_type.

par_ex($name, $autodefine_type = 'no')
Return true if the parameter is received, otherwise false. It does not raise error if the parameter is not defined.

par_is($name, $value,$autodefine_type = 'no')
Return true if the parameter is received and have same value as $value parameter, otherwise false. It does not raise error if the parameter is not defined. 

function mypage()
{
  par_def("id","number0","url",false,NULL,"You have to specify the id of the item");
  par_def("name","text3");

  ob_start();
  if(par_is("id","0"))
  {
    //Only displayed if the "id" parameter is "0"
    print "This is the first element!";
  }

  print "Id: ".par("id");

  if(par_ex("name"))
  {
    //Only displayed if the "name" parameter is received
    print "Name:".par("name");
  }

  return ob_get_clean();
}

There are some helper function to easy handle form date fields: (See forms)

par_date_def($name)
This function defines the three parameter of the specified form date field. It means that you call this function with "birth" it will define the "birth_year", "birth_month" and "birth_day" parameters with "number0" security class.

par_date_ex($name)
This function returns true if all three part of the specified form date field is passed. Otherwise returns false. (It uses par_ex() inside)

par_date($name,$define = false)
This function returns the isodate string (yyyy-mm-dd) from the parameter passed form date field if all parts is passed. If some parts are missing null value returned. If you pass true in parameter $define the function calls par_date_def($name) before the query.

Other parameter related functions

par_reset()
Erase all parameter definition.

parameters(array $change = [], array $infilter = [], array $outfilter = [])
Returns a key-value array with the defined and set parameters. The parameter name will be the index, the value is the current value of the parameter, except if modified by $change parameter.

is_par_defined($name)
Returns true if the $name named parameter is defined, otherwise false.

Security classes

Every parameter is received through the CodKep parameter system, must meet the restriction of a security class which is assigned to the parameter during the definition. Each security class is defined by a regex. (You can add your own security classes, see below)

Built-in security classes in CodKep:

code nameAllowed characters/contets
bool01onf
number00123456789
number0ne0123456789 (Not empty)
number1whitespaces 0123456789 . , -
number1ns0123456789 . , -
numberi0123456789 -
number2whitespaces 0123456789 . , ; + -
text0whitespaces a-z A-Z 0-9
text0nsa-z A-Z 0-9
text0nsnea-z A-Z 0-9 (Not empty)
text0sunea-z 0-9 _ (Not empty)
text0sdnea-z 0-9 - (Not empty)
text0sda-z 0-9 -
text0sudnea-z 0-9 _ - (Not empty)
text0suda-z 0-9 _ -
text1whitespaces a-z A-Z 0-9 - _
text1nsa-z A-Z 0-9 - _
text2whitespaces a-z A-Z 0-9 UnicodeLetters
text2nsa-z A-Z 0-9 UnicodeLetters
text3whitespaces a-z A-Z 0-9 UnicodeLetters - _
text3nsa-z A-Z 0-9 UnicodeLetters - _
text4whitespaces a-z A-Z 0-9 UnicodeLetters - _ . , : ? # / ! ( ) = +
text4mwhitespaces a-z A-Z 0-9 UnicodeLetters - _ . , : ? # / ! ( ) = + @
text4nsa-z A-Z 0-9 UnicodeLetters - _ . , : ? # / ! ( ) = +
text5whitespaces a-z A-Z 0-9 UnicodeLetters - _ . , : ? & # / ! ( ) = % + ; @ *
text6whitespaces a-z A-Z 0-9 UnicodeLetters - _ . , : ? & # / ! ( ) = % + ; @ * "
textemaila-z A-Z 0-9 UnicodeLetters - _ . @ "
textbase64a-z A-Z 0-9 =
tstwhitespaces a-z A-Z 0-9 UnicodeLetters - : . +
tstnsa-z A-Z 0-9 UnicodeLetters - : . +
isodateNNNN-NN-NN e.g: 2016-10-11
neuttextwhitespaces a-z A-Z 0-9 UnicodeLetters - _ ? ! . ()
ipv4addressIPv4 addresses eg: 192.168.1.12
freeno limitations
noonly match to empty string

You can define your own security classes with register_parameter_security_class(name,regex) function.
register_parameter_security_class($name,$regex)

A security class can be defined by a regex. See the following example which define the "user_id" security class in "mymodule" module. 

function hook_mymodule_init()
{
    register_parameter_security_class('user_id','/^user_[0-9]+$/');
}

function mypage()
{
  par_def("uid","user_id");
  $uid = par("uid");
  //...
}

Parameter handling relates settings

The settings which can set in site settings.

namedefaultdescription
$site_config->param_event_locations['undefined'] 'param_undefined_error' The built-in undefined parameter error page location.
$site_config->param_event_locations['missing'] 'missing_parameter_error' The built-in missing parameter error page location.
$site_config->param_event_locations['security'] 'param_security_error' The built-in parameter not match to the security class error page location.

Hooks

The following hooks can be implement related to the parameter system.

HookDescription
HOOK_parameter_missing($name,$required)The hook is activated when a required parameter is missing.
HOOK_parameter_undefined($name)The hook is activated when a parameter is queried but not defined.
HOOK_parameter_security_error($name,$sc)The hook is activated when a parameter does not fit in the defined security class.