PHP-Functions

This chapter shows you the main functions of PHP-Code Elements which can be used. The Introduction in PHP-Code will help you to integrate all PHP functions for your questionnaire.

At the very end of this page will be a helpful information how the documentation of the PHP-functions can be read: Function in Detail

See also filter questions und filters.

• value() – Use answer of participant, e.g. for a filter question
• goToPage() – Jump to another page immediately
  • goToPage('end') – End the current interview
• repeatPage() – Show recent page again
• redirect() – Redirect the respondent to a different website
• question() – Display a question within the questionnaire
• text() – Display a text element within the questionnaire
• show() – Display a question, combined question or text or activate a feature element
• debug() – Show content of a data or PHP variable

• option() – Modify page display settings (buttons, progress bar)
• preset() – Preset a response for a question
• markFail() – Set the marker “response missing” for an input
• html() – Output of HTML-Code within questionnaire
• textlink() – Create a hyperlink that shows a text element in a pop-up window
• buttonToPage() – Button to jump within the questionnaire
• buttonCode() – Create-HTML-Code for next/back button
• buttonHide() – Do not show back/next buttons at the page's bottom
• library() – Make a JavaScript or PHP library available
• pageCSS() – Add CSS instructions to a single questionnaire page
• pageHead() – Store meta-information about the questionnaire page

SoSci Survey supports several functions for special random selections and random group assignments. For a simple experimental variation, we recommend a Random Generator (Randomization).

• put() – Save a value in the data set
• random() – Dice a random number (with replacement)
• random_p() – Random number in correlation to likelihood
• random_items() – Randomly select items from a list
• randomUse() – Storing slips of paper from a random number generator
• urnDraw() – Draw out from urn (random selection without replacement)
• urnPutAway() – Put away the chit drawn via urnDraw()
• urnStatus() – Retrieve current status of an urn

• replace() – Prepare a placeholder
• registerVariable() – Register PHP-Variable for following sites
• id() – Create a question or variable label from it's components
• getItems() – Order items of question by selected rules
• getQuestions() – Enlist a section's questions
• getItemtext() – Retrieve the text of a specific items or option
• getValueText() – Retrieve the label of a response code/option
• getTextElement() – Retrieve the content of a text element
• getVariables() – Return a list of variables from the dataset
• serialCheck() – Ask for serial number
• readGET() – Read converted variable from link
• sendJSON() – Send HTTP request in JSON format (REST API)
• sendPOST() – Send HTTP request in POST format (REST API)
• sendXML() – Send HTTP request in XML format (REST API)
• setNextPage() – Set side for click on ,,go further“
• setPageOrder() – Change the order to display subsequent questionnaire pages
• loopPage() – Show a page multiple times in a loop
• loopToPage() – Show multiple pages multiple times in a loop
• loopIndex() – Get the loopPage() or setPageOrder() page counter
• pageStop() – Do not show any further contents on the questionnaire page
• setLanguage() – Change language
• buttonDataCode() – Add a custom button on the page that sends additional information
• buttonDataGet() – Get the data sent via buttonDataCode()

• info() – Meta informationen int the current case or output configuration
• infoVars() – Information on variables in the dataset
• getRoute() – Tell if the next or back button was hit previously
• caseNumber() – Number of actual interviews
• caseSerial() – Serial number used in interview
• caseTime() – Show length of stay on one or more sites
• caseToken() – Identification of interview
• caseData() – Get all data collected in the current interview
• reference() – Ask for reference (within link to questionnaires)
• getAnswerMissing() – Information for site repeat if questions was obligated
• listFails() – List of not responded obligation questions
• getLanguage() – Determine language

• goToQuestionnaire() – Jump from one Questionaire to the next (once)
• goToParent() – Go back to the formerly Questionaire
• multiLevelDown() – Start a sub-questionaire inside the main questionaire (if necessary also several times)
• multiLevelData() – Get data specified in multiLevelDown()
• multiLevelReturn() – Return from the sub-questionnaire to the main questionnaire
• multiLevelResponse() – Get data specified in multiLevelReturn()
• multiLevelPut() – Write a value directly into the higher-level record
• multiLevelValue – Read a value directly from the higher-level record
• multiLevelURL() – Create a URL for a sub-questionnaire to be used later
• multiLevelPrepare() – Create a subordinate case and preset it with values, to be used with a Multi-Level Listing

• dbGet() – Read data from date base
• dbKeys() – List key for data base
• dbLoad() – Call all entries with defined prefix from the contents database
• dbRetrieve() – Get data from the data base (associative, nested array)
• dbSet() – Safe data in data base
• dbStore() – Store data in the data base (associative, nested array)
• dbTouch() – Refresh time-stamp for data base entry
• dbDelete() – Delete entries from the data base, selected by a prefix

• dropValue() – Delete a single variable from the current interview
• dropUpload() – Delete a file uploaded by the respondent
• dropCase() – Mark the current interview for deletion
• dropHistory() – Delete the page history of the current interview

• statistic() – Simple statistical analysis of all data
• diagram() – Simple diagram (e. g. frequency) for all analyzed data
• panelRecords() – Access other records with the same person ID (SERIAL)

• answers() – Show a question including the respondent's answers
• answersOption() – Adjust display of answers via answers() or answersPrint()
• answersPrint() – Display all questions of a questionnaire segment including the respondent's answers
• valueSum() – Compute sum over scale or variables
• valueMean() – Compute mean over scale or variable
• valueSD() – Compute standard deviation over scale or variable
• valueVar() – Compute variance over scale or variable
• valueList() – Get multiple responses to multiple items in a question as array
• convertDateTime() – Convert date/time texts (strings) and timestamps
• calcMean(), calcSD(), ... – Simple calcuations based on the current interview's responses
• uploadAsTable() – Get am Excel or CSV table uploaded by the respondent as array
• uploadRawData() – Get an uploaded file as binary string

• diagram2() – Create diagram with set data
• getQRCodeImage() – Integrate QR Code in the questionnaire
• imagepng_embed() – Include a PNG graphic without storing it to a file

• mailResume() – Resume an interview after a given delay
• mailSchedule() – Schedule to send a mailing to a single recipient
• mailRevoke() – Cancel continuation mail(s) or a scheduled mailing
• mailSend() – Send an email to an address that is not in the list of contacts
• panelAdd() – Create a new address record
• panelData() – Get information from an existing address entry
• panelUpdate() – Update information on the address record
• panelDelete() – Delete records from the address list
• accessCount() – Limit trial to enter a code
• setStatus() – Set the interview status and eventually trigger panel redirects

Furthermore, PHP itself provides numerous functions, some of which can be very helpful in the questionnaire. These functions are documented in the PHP Manual.

• Generally useful functions
  • implode - Join array elements into a string
  • explode - Split a string into an array
  • preg_split - Split a string into an array by means of a regular expression
• Mathematical functions
  • round - Round a decimal number
  • ceil - Round a number up
  • floor - Round a number down
  • abs - Get the absolute value of a number
• Array functions
  • array_diff - Subtract array elements
  • array_fill - Fill an array with (identical) values
  • array_flip - Exchange keys and values in an array
  • array_intersect - Intersection of arrays
  • array_keys - Get the keys of an array
  • array_key_exists - Check whether a key exists in an array
  • array_merge - Merge arrays
  • array_pop - Remove and return the last element of an array
  • array_push - Append element(s) to the end of an array
  • array_rand - Randomly select one or more entries of an array
  • array_reverse - Return an array in reverse order
  • array_search - Search an array for a value
  • array_shift - Remove and return the first element of an array
  • array_slice - Write a slice of an array into a new array
  • array_sum - Sum up the elements of an array
  • array_unique - Remove duplicate elements from an array
  • array_unshift - Insert value(s) at the beginning of an array
  • array_values - Convert an associative array into an indexed array
  • arsort - Sort an array in descending order and keep the keys
  • asort - Sort an array in ascending order and keep the keys
  • count - Return the number of elements in an array
  • in_array - Check whether a value occurs in an array
  • is_array - Check whether a variable is an array
  • krsort - Sort an array by key in descending order
  • ksort - Sort an array by key in ascending order
  • list - Assign an array to several variables
  • rsort - Sort an array in descending order
  • shuffle - Shuffle an array randomly
  • sort - Sort an array in ascending order
• Date and time
  • date - Format a timestamp as a date
  • mktime - Convert a date/time into a timestamp
  • microtime - Return a timestamp with microseconds
  • time - Return a timestamp in seconds
• String processing
  • htmlentities - Convert all characters that have an HTML entity into that entity
  • htmlspecialchars - Convert HTML syntax characters (quotation marks, angle brackets) into HTML entities
  • ltrim - Remove whitespace from the beginning of a string
  • number_format - Format a number with decimals and/or thousands separators
  • rtrim - Remove whitespace from the end of a string
  • str_pad - Pad a string to a certain length with a fill character
  • str_replace - Search and replace a substring
  • strlen - Get the length of a string
  • strtolower - Convert a string to lowercase
  • strtoupper - Convert a string to uppercase
  • substr_count - Count the occurrences of a substring
  • substr - Get a substring
  • trim - Remove whitespace from the beginning and end
  • The following functions are allowed as well: nl2br, str_repeat, str_shuffle, str_word_count, strip_tags, stripos, stristr, strpos, strrev, strripos, strrpos, strstr, strtr, substr_replace, wordwrap
    
• Drawing images (e.g., charts)
  • imagecolorallocate - Allocate a color for an image
  • imagecreate - Create a new image
  • imagecreatetruecolor - Create a new true color image (16 million colors)
  • imageellipse - Draw an ellipse or circle
  • imagefill - Fill an image (area) with a color
  • imagefilledarc - Draw a filled circle sector
  • imagefilledellipse - Draw a filled ellipse or circle
  • imagefilledpolygon - Draw a filled polygon
  • imagefilledrectangle - Draw a filled rectangle
  • imagefilltoborder - Fill an image with a color up to a border line
  • imageline - Draw a straight line
  • imagepolygon - Draw a polygon
  • imagerectangle - Draw a rectangle
  • imagesetbrush - Set the brush
  • imagesetpixel - Draw a pixel
  • imagesetstyle - Set the style for lines
  • imagesetthickness - Set the width of lines
  • imagestring - Draw text (horizontally)
  • The following functions are allowed as well: image_type_to_extension, image_type_to_mime_type, imagearc, imagechar, imagecharup, imagecolorallocatealpha, imagecolorat, imagecolorclosest, imagecolorclosestalpha, imagecolorclosesthwb, imagecolordeallocate, imagecolorexact, imagecolorresolve, imagecolorset, imagecopy, imagecopymerge, imagecopymergegray, imagecopyresampled, imagecopyresized, imagedashedline, imagedestroy, imagefilter, imagefontheight, imagefontwidth, imageinterlace, imagepalettecopy, imagerotate, imagesavealpha, imagesettile, imagestringup, imagesx, imagesy, imagetruecolortopalette
  • The following functions can be used in a slightly modified form: imagepng, imagettftext, imagecreatefrompng
• Miscellaneous
  • intval - Convert a variable into an integer value
  • md5 - Calculate the MD5 hash of a value

Some functions pose a security risk or do not work as expected in the context of the questionnaire. Alternatives are listed below. If you need additional features, please let SoSci Survey know.

• echo
  • html()
  • text()
• mysqld_query()
  • Content Database
  • datasetRetrieve()

Reference-syntax for each function, e.g.:

void set(mixed Value, [string Memory])

This reference-syntax describes the argumentation of functions and it's data type.

• At the beginning return function of data type is shown void, meaning: function is acting but does not return values.
• Arguments listed in braces. Optional arguments in angled braces. Function set() has o have at least one argument Value than it is allowed to use another (second) argument Memory .
• Type of data stands in front of argument:
  • mixed means different types of data are allowed
  • int is a number
  • string text with inverted comma
  • array List of values (Arrays)