Skip to main content

FV Kinesis Support

All the topics, resources needed for FV Kinesis.

FocusVision Knowledge Base

PHP Functions

Conditional functions are allowed PHP functions that give more flexibilty to conditional logic. These can also be found within the Help menu on the survey install. Click the function name to review details on third party site php.net.

1:  Array functions

1.1:  arrays

 

$USER_array=array(1,2,3,4,5);

$USER_names = array("Dave","Jim","Bob");
These allow you to create and utilize lists of data or answers for various functions.

1.2:  implode

The implode function allows you to join a list of items and make a string--you can separate these items in the new string with whatever you wish. The "," designated in the second line describes what will separate the array items in the new string. Here is an example using this function that will return the text "lastname,email,phone":
$USER_array = array('lastname', 'email', 'phone');
$USER_comma_separated = implode(",", $array);

return $USER_comma_separated;

1.3:  explode

The explode function does just the opposite of an implosion--you can convert a list of items into an array.

1.4:  count

Will count the number of elements in an array.
$USER_names = array("Dave","Jim","Bob");
return count($USER_names);
The function above will return 3, the count of elements in the given array.

1.5:  reset

Resets the internal pointer of a given array.

1.6:  list

$USER_info = array('coffee', 'brown', 'caffeine');
list($USER_drink, $USER_color, $USER_power) = $USER_info;
return "$USER_drink is $USER_color and $USER_power makes it special.";
This function allows you to assign variables to items in an array in one function. An example is below (the bottom line will return "coffee is brown and caffeine makes it special"):

1.7:  in_array

$USER_os = array("Mac", "NT", "Irix", "Linux");
if (in_array("Irix", $USER_os)) {
return "Got Irix";
}
if (in_array("mac", $USER_os)) {
return "Got mac";
}
This function allows you to search for a string or number within a given array. This example will return "Got Irix" (note--"Got mac" will not be found because of the capitalization discrepancy):

1.8:  array_sum

Returns the sum of values in an array. This example will return "sum(USER_a) = 10", where Q5, Q6 and Q7 add up to 10.
$USER_a = array($Q5, $Q6, $Q7);
return "sum(USER_a) = " . array_sum($USER_a);

1.9:  array_pop

This function will remove and return the last element in an array. It is most often used with the shuffle function to return a random element in an array of text or numbers. The example below shuffles an array of numbers and pops the last number off the bottom (which is then classified as $USER_rand):
$USER_numbers = array(1, 2, 3, 4, 5);
shuffle($USER_numbers);
$USER_rand= array_pop($USER_numbers);
return $USER_rand;
$USER_colors= array("green", "black", "blue", "yellow", "red", "orange");
shuffle($USER_colors);
$USER_rand_color= array_pop($USER_colors);
return $USER_rand_color;
This command can also be used with textual items in an array.

1.10:  array_push

$USER_check = array();
 
if($Q1==1) array_push($USER_check, 1);
if($Q1==2) array_push($USER_check, 2);
if($Q1==3) array_push($USER_check, 3);
 
return $USER_check;
Will push a specified variable into an existing array.

1.11:  array_key_exists

Will submit a check to see if a certain key is present in an array.
$USER_array = array('first' => 1, 'second' => 4);
if (array_key_exists('first', $USER_array))
return "The 'first' element is in the array";

1.12:  array_unique

Will remove duplicate values from a given array. This example results in an array consisting of green, red and blue:
$USER_colors = array("a" => "green", "red", "b" => "green", "blue", "red");
$USER_result = array_unique($USER_colors);

1.13:  array_reverse

Takes an input array and reverses the order of the elements. This function will preserve the keys if the preserve_keys boolean is true (see "true" in the example below):
$USER_input = array("php", "html", "WML");
$USER_result = array_reverse($USER_input);
$USER_result_keyed = array_reverse($USER_input, true);

1.14:  asort

Used for sorting arrays while maintaining array indices with their correlating elements.

1.15:  arsort

Used for reverse sorting arrays while maintaining array indices with their correlating elements.

1.16:  shuffle

This shuffles the items in an array. Shuffle is often used in conjunction with array_pop to return a random item from an array (see the array_pop entry for examples).

1.17:  array_rand

Returns one or more random elements from a given array.

1.18:  min

Will get the minimal value from an array or from a set of values.
return min($Qcheckbox);
return min($USER_array);
return min($Q1,$Q2,$Q3);

1.19:  max

Will get the maximal value from an array or from a set of values.
return max($Qcheckbox);
return max($USER_array);
return max($Q1,$Q2,$Q3);

1.20:  array_search

Will search an array for a given element.

1.21:  array_diff

Will return an array of elements from the first array that are not in the second array.

1.22:  ksort

Sorts the given array by key.

1.23:  krsort

Sorts the given array by key in reverse order.

1.24:  rsort

Reverse the order of a given array.

1.25:  array_multisort

Sorts multipe arrays at once, or a multi-dimensional array by one or more dimensions.

1.26:  natsort

Sorts the given array by a "natural order" algorithm.

1.27:  natcasesort

Sorts the given array by a case insensitive "natural order" algorithm.

2:  String / Text functions

2.1:  strlen

Allows you return the length of a given string. This example will return the number 6, as there are 6 characters in the string:
$USER_str = 'abcdef';
 
return strlen($USER_str);

2.2:  strpos

Allows you to return the position of a character, word, number or combination thereof within a given text string. This will return the string "The string 'a' was found in the string 'abc' and exists at position 0":
$USER_mystring = 'abc';
$USER_findme = 'a';
$USER_pos = strpos($USER_mystring, $USER_findme);
 
if ($USER_pos === false) {
return "The string '$USER_findme' was not found in the string '$USER_mystring'";
}
else {
return "The string '$USER_findme' was found in the string '$USER_mystring' and exists at position $USER_pos";
}

2.3:  str_word_count

Allows you to count the number of words in a string. For this function, a word is a string of alphabetic characters. This example will return the number 7, because "fri3nd" is classified as two words (two sets of alphabetic strings):
$USER_str = "Hello fri3nd, you're looking good today!";
return str_word_count($USER_str);

2.4:  chr

Returns an ASCII one-character string. The following is an example of an ASCII character added to the end of a text string:
$USER_str = "The string ends with a tab:";
$USER_str .= chr(10);
Note how .= is used to represent the addition of something to the end of the variable ($USER_str). The 10 represents the ASCII number for "new line." For reference, visit www.asciitable.com

2.5:  ord

This is the complement of chr. In the following example, Q13 is a text question asking the respondent's current state.:
$USER_str = $Q13;
return ord($USER_str);
If the respondent answered "Texas" for Q13, this computational would return the number 84, signifying a capital "T" ASCII character..

2.6:  strtolower

Will convert a text string to all lower case characters.
$USER_str = $Q6;
$USER_str = strtolower($USER_str);
return $USER_str;
If $Q6 is a text question, and the respondent entered "The Sun is bigGER than MARS", the above computational will return "the sun is bigger than mars".

2.7:  strtoupper

This is the opposite of strtolower - it will convert all alphabetical characters in a text string to upper case.

2.8:  substr

Returns a specified portion of a string. The first number after the string indicates the starting position of the substring (where 0 is the first position and 1 is the second position) and the second number indicates the length of the substring. If no length is given, the substring will continue until the end of the original string.
return substr('abcdef', 1, 4);
The above will return "bcde"

2.9:  preg_match

Will perform a regular expressions match. The following example shows an if statement utilizing the preg_match function. Note how the regular expression goes at the beginning of the function ("/php/i") and the search material goes at the end (PHP is the web scripting language of choice.). The /i part of the regular expression signifies a case-insensitive search.
if (preg_match("/php/i", "PHP is the web scripting language of choice.")) return "A match was found.";
else return "A match was not found.";
This will return "A match was found", because the string "php" (case insensitive, as noted by the i) was found in the designated sentence.

2.10:  str_replace

This function is used to replace all occurrences of a given search string with a replacement string. The example below will generate "PHP is better than XPHP" (notice how ALL string occurrences are replaced):
$USER_bodytag = str_replace("HTML", "PHP", "HTML is better than XHTML");
return $USER_bodytag;

2.11:  rawurlencode

URL-encodes the given string according to RFC 1738

3:  Numerical functions

3.1:  rand

Will generate a random number. This example will return a random number between 1 and 10. Note the lower limit is entered first, followed by a comma and the the upper limit:
return rand(1,10);

3.2:  mt_rand

Will return a "better" random number than the regular rand function. Not only does this function generate numbers with a higher degree of randomness - it also generates them up to four times faster than the typical rand function.
return mt_rand(); (this will return a completely random number)
return mt_rand(1,10); (this will return a random number between 1 and 10)

3.3:  is_numeric

Will test if the given answer is numeric or not. This is useful for validating "other: specify" choices to make sure they are numbers (as number questions cannot be assigned as an "other: specify" choice). Here is an example used to validate that the other: specify question Q1o is a number:
!is_numeric($Q1o)
When the function above is used as validation for an other: specify, and the respondent enters a NON-number, he or she will get an error message.

3.4:  floor

Will round an value down if a decimal place is present.
return floor(4.3); // will yield 4<br>return floor(9.999); // will yield 9
return floor(-3.14); // will yield -4
$USER_length = 6.25;
$USER_length = floor($USER_length); // will make the USER_length variable 6

3.5:  ceil

Will round an value up if a decimal place is present.
return ceil(4.3); // will yield 5
return ceil(9.999); // will yield 10
return ceil(-3.14); // will yield -3

3.6:  round

Will round the value of an integer or variable to a specified number of digits. The default number of digits is zero, so the function will simply round a decimal into an integer. Below are some examples with their returned values on the right:
return round(3.4); // 3
return round(3.5); // 4
return round(3.6); // 4
return round(3.6, 0); // 4
return round(1.95583, 2); // 1.96
return round(1241757, -3); // 1242000
return round(5.045, 2); // 5.05
return round(5.055, 2); // 5.06
Note the number after the comma inside of the round function--these second numbers specify the digit to which you want to round (with negative numbers working left of the decimal and positive numbers going right).

3.7:  sqrt

Will return the square root of the given value.

3.8:  abs

Returns the absolute value of the give value.

3.9:  exp

Returns 'e' raised to the power of the give value.

4:  Control Structures and Loops

4.1:  if

These are basic conditional functions that are used in computationals for conditional logic. The "if" statement presents a boolean and the "then" statement presents a course of action. Be sure to follow basic bracketing and semicolon use, as seen in this example:
if ($Q1==2) {
return ("Residential");
}
else {
return ("Commercial");
}

4.2:  else

As seen in the previous example, the else function is suited to execute when boolean expressions are false. If the statement $Q1==2 was false, the computational would return "Commercial".

4.3:  elseif

This is similar to else, but instead of executing every time the if statement is false it will execute only if the elseif statement is true. Here's an example:
if ($Q1 > $Q2) {
return ("Q1 is bigger than Q2");
}
elseif ($Q1==$Q2) {
return ("Q1 is equal to Q2");
}
else {
return ("Q1 is smaller than Q2");
}

4.4:  while

Starts a while loop that executes a nested statement repeatedly as long as the while expression is true.

4.5:  break

A break will end any for or while statement loop.

4.6:  each

An each statement is used to loop through arrays. See the example below:
$USER_array=array("one","two","three");
 
while (list (,$USER_value) = each ($USER_array))
{
# Statements in here will be executed 3 times while $USER_value contains values one for the first loop, two for the second and three for the third
}

4.7:  for loop

Allows you to perform a task for a specified number of iterations
$USER_count = 0;
 
for ($USER_i = 0; $USER_i<10; $USER_i++) {
 
   if ($Q1[$USER_i]==1) $USER_count++;
 
}
 
return $USER_count;

4.8:  foreach loop

Loops through each element of an array executing the nested statement(s) repeatedly as long as the given array has elements.

5:  Date and Time functions

5.1:  date

The date function will return a string with the current time (or a given time if a timestamp is included) in a specified format. Visit the php.net link to see a full list of date parameters/formats.

return date('l h:i:s A');
Will return the current day of the week followed by the time and a capital AM or PM. An example: "Tuesday 5:45 PM".
return "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000));
Will return "July 1, 2000 is on a Monday", as the mktime function is used to look up the day of the week this date falls on.

5.2:  time

Time returns the unix timestamp value, which is the number of seconds from 1st of January 1970.

5.3:  mktime

mktime($USER_hour,$USER_minute,$USER_second,$USER_month,$USER_day,$USER_year);
Is used to create time values. The syntax is:
 
Mktime makes time calculation easy; for example, imagine a problem where you need to know what is the resulting date when you add 3000 minutes to a given time? This can be accomplished with mktime simply by adding $USER_minute+3000. The function always returns unix timestamp, which can be converted back to a human-readable date by using the date function. For example, 8am on 1st of January 2007 would be:
date("m/d/Y H:i",mktime(8,0,0,1,1,2007));

6:  Other functions

6.1:  true/false

Values used when referencing boolean expressions.

6.2:  sprintf

Is used to return formatted / padded presentations of strings or numbers.

6.3:  print_r

Will print all elements of an array.
$USER_array = array('color'=>'red','size'=>'33','orientation '=>'vertical');
return print_r($USER_array,true);
The above would return:
array
    (
        [color] => red
        [size] => 33
        [orientation] => vertical
    )

6.4:  isset

Determines if a variable is set and is not NULL. Useful for checking if a URL parameter was found on the incoming link:
isset($IN_source)

6.5:  set_random_sequence

Set any existing sequence to certain order. This function can be used to alter random sequences for example based on what a respondent answered.
# Create sequence array that matches the number of elements used in the sequence
$USER_sequence=array(4,3,2,1);
 
# Override sequence ID 1 with the created sequence
set_random_sequence(1,$USER_sequence);
Random sequence must be created by using random sequencer first. Each random sequence will initialize to random order when a new survey session is started. After this point, set_random_sequence function can be used to override the existing sequence. Sequence ID can be obtained from random sequencer main page that lists are sequences created.
Random sequences can be set in any condition being evaluated. Typically one would call this function from hidden computational value or default answer value condition.
  • Was this article helpful?