====== PHP-Functions ======

This chapter shows you the main functions of //PHP-Code// Elements which can be used. The [[php|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|Function in Detail]]

===== Basic Fuctions for Filtering, Questions and Text =====

See also [[filters|filter questions und filters]].

  * ''[[:en:create:functions:value|value()]]'' -- Use answer of participant, e.g. for a filter question
  * ''[[:en:create:functions:gotopage|goToPage()]]'' -- Jump to another page immediately
    * ''[[:en:create:functions:gotopage#finish_interview|goToPage('end')]]'' -- End the current interview
  * ''[[:en:create:functions:repeatpage|repeatPage()]]'' -- Show recent page again
  * ''[[:en:create:functions:redirect|redirect()]]'' -- Redirect the respondent to a different website
  * ''[[:en:create:functions:question|question()]]'' -- Display a question within the questionnaire
  * ''[[:en:create:functions:text|text()]]'' -- Display a text element within the questionnaire
  * ''[[:en:create:functions:debug|debug()]]'' -- Show content of a data or PHP variable


===== Modify How to Display a Questionnaire Page =====

  * ''[[:en:create:functions:option|option()]]'' -- Modify page display settings (buttons, progress bar)
  * ''[[:en:create:functions:preset|preset()]]'' -- Preset a response for a question
  * ''[[:en:create:functions:markfail|markFail()]]'' -- Set the marker "response missing" for an input
  * ''[[:en:create:functions:prepare_input|prepare_input()]]'' -- Prepare an input to be shown within another question
  * ''[[:en:create:functions:html|html()]]'' -- Output of HTML-Code within questionnaire
  * ''[[:en:create:functions:textlink|textlink()]]'' -- Create a hyperlink that shows a text element in a pop-up window
  * ''[[:en:create:functions:buttontopage|buttonToPage()]]'' -- Button to jump within the questionnaire
  * ''[[:en:create:functions:buttoncode|buttonCode()]]'' -- Create-HTML-Code for next/back button
  * ''[[:en:create:functions:buttonhide|buttonHide()]]'' -- Do not show back/next buttons at the page's bottom
  * ''​[[:en:create:functions:library|library()]]''​ -- Make a JavaScript or PHP library available
  * ''[[:en:create:functions:pagecss|pageCSS()]]'' -- Add CSS instructions to a single questionnaire page
  * ''[[:en:create:functions:pagehead]]'' -- Store meta-information about the questionnaire page

===== Functions for Randomization =====

SoSci Survey supports several functions for random sampling or random group assignment ([[randomization|Randomization]]).

  * ''[[:en:create:functions:put|put()]]'' -- Save a value in the data set
  * ''[[:en:create:functions:random|random()]]'' -- Dice a random number (with replacement)
  * ''[[:en:create:functions:random_p|random_p()]]'' -- Random number in correlation to likelihood
  * ''[[:en:create:functions:random_items|random_items()]]'' -- Randomly select items from a list
  * ''[[:en:create:functions:randomuse]]'' -- Storing slips of paper from a random number generator
  * ''[[:en:create:functions:urndraw|urnDraw()]]'' -- Draw out from urn (random selection without replacement)
  * ''[[:en:create:functions:urnputaway|urnPutAway()]]'' -- Put away the chit drawn via ''urnDraw()''
  * ''[[:en:create:functions:urnstatus|urnStatus()]]'' -- Retrieve current status of an urn


===== Advanced Programming =====

  * ''[[:en:create:functions:registervariable|registerVariable()]]'' -- Register PHP-Variable for following sites
  * ''​[[:​de:​create:​functions:​id|id()]]''​ -- Create a question or variable label from it's components
  * ''[[:en:create:functions:replace|replace()]]'' -- Prepare a placeholder
  * ''[[:en:create:functions:getitems|getItems()]]'' -- Order items of question by selected rules
  * ''[[:en:create:functions:getquestions|getQuestions()]]'' -- Enlist a section's questions
  * ''[[:en:create:functions:getitemtext|getItemtext()]]'' -- Retrieve the text of a specific items or option
  * ''[[:en:create:functions:getvaluetext|getValueText()]]'' -- Retrieve the label of a response code/option
  * ''[[:en:create:functions:gettextelement|getTextElement()]]'' -- Retrieve the content of a text element
  * ''[[:en:create:functions:getroute|getRoute()]]'' -- Tell if the next or back button was hit previously
  * ''[[:en:create:functions:casenumber|caseNumber()]]'' -- Number of actual interviews
  * ''[[:en:create:functions:caseserial|caseSerial()]]'' -- Serial number used in interview
  * ''[[:en:create:functions:casetime|caseTime()]]'' -- Show length of stay on one or more sites
  * ''[[:en:create:functions:casetoken|caseToken()]]'' -- Identification of interview
  * ''[[:en:create:functions:reference|reference()]]'' -- Ask for reference (within link to questionnaires)
  * ''[[:en:create:functions:serialcheck|serialCheck()]]'' -- Ask for serial number
  * ''[[:en:create:functions:readget|readGET()]]'' -- Read converted variable from link
  * ''[[:en:create:functions:sendjson|sendJSON()]]'' -- Send HTTP request in JSON format (REST API)
  * ''[[:en:create:functions:sendjson|sendPOST()]]'' -- Send HTTP request in POST format (REST API)
  * ''[[:en:create:functions:sendjson|sendXML()]]'' -- Send HTTP request in XML format (REST API)
  * ''[[:en:create:functions:getanswermissing|getAnswerMissing()]]'' -- Information for site repeat if questions was obligated
  * ''[[:en:create:functions:listfails|listFails()]]'' -- List of not responded obligation questions
  * ''[[:en:create:functions:setnextpage|setNextPage()]]'' -- Set side for click on ,,go further"
  * ''[[:en:create:functions:setpageorder|setPageOrder()]]'' -- Change the order to display subsequent questionnaire pages 
  * ''[[:en:create:functions:looppage|loopPage()]]'' -- Show a page multiple times in a loop
  *  ''​[[:​en:​create:​functions:​looptopage|loopToPage()]]''​ -- Show multiple pages multiple times in a loop
  * ''[[:en:create:functions:pagestop|pageStop()]]'' -- Do not show any further contents on the questionnaire page
  * ''[[:en:create:functions:getlanguage|getLanguage()]]'' -- Determine language
  * ''[[:en:create:functions:setlanguage|setLanguage()]]'' -- Change language


===== Coordination of Several Questionnaires ======

  * ''[[:en:create:functions:gotoquestionnaire]]'' -- Jump from one Questionaire to the next (once)
  * ''[[:en:create:functions:gotoparent]]'' -- Go back to the formerly Questionaire
  * ''[[:en:create:functions:multileveldown]]'' -- Start a sub-questionaire inside the main questionaire (if necessary also several times)
  * ''[[:en:create:functions:multileveldata]]'' -- Get data specified in ''multiLevelDown()''
  * ''[[:en:create:functions:multilevelreturn]]'' -- Return from the sub-questionnaire to the main questionnaire  
  * ''[[:en:create:functions:multilevelresponse]]'' -- Get data specified in ''multiLevelReturn()'' 
  * ''[[:en:create:functions:multilevelput]]'' -- Write a value directly into the higher-level record
  * ''[[:en:create:functions:multilevelurl]]'' -- Create a URL for a sub-questionnaire to be used later


===== Databank for Contents =====

  * ''[[:en:create:functions:dbget|dbGet()]]'' -- Read data from date base
  * ''[[:en:create:functions:dbkeys|dbKeys()]]'' -- List key for data base
  * ''[[:en:create:functions:dbload|dbLoad()]]'' -- Call all entries with defined prefix from the contents database 
  * ''[[:en:create:functions:dbset|dbSet()]]'' -- Safe data in data base
  * ''[[:en:create:functions:dbtouch|dbTouch()]]'' -- Refresh time-stamp for data base entry


=====Record Control =====

  * ''[[:en:create:functions:dropvalue]]'' -- Delete a single variable from the current interview
  * ''[[:en:create:functions:dropcase]]'' -- Mark the current interview for deletion
  * ''[[:en:create:functions:drophistory]]'' -- Delete the page history of the current interview

===== Analysis of all data =====

  * ''[[:en:create:functions:statistic|statistic()]]'' -- Simple statistical analysis of all data
  * ''[[:en:create:functions:diagram|diagram()]]'' -- Simple diagram (e. g. frequency) for all analyzed data


===== Analyses and Data Handling During an Interview =====

  * ''[[:en:create:functions:answers|answers()]]'' -- Show a question including the respondent's answers
  * ''[[:en:create:functions:answersoption|answersOption()]]'' -- Adjust display of answers via ''answers()'' or ''answersPrint()''
  * ''[[:en:create:functions:answersprint|answersPrint()]]'' -- Display all questions of a questionnaire segment including the respondent's answers
  * ''[[:en:create:functions:info]]'' -- Meta informationen about the current interview case or the display mode
  * ''[[:en:create:functions:valuesum|valueSum()]]'' -- Compute sum over scale or variables
  * ''[[:en:create:functions:valuemean|valueMean()]]'' -- Compute mean over scale or variable
  * ''[[:en:create:functions:valuesd|valueSD()]]'' -- Compute standard deviation over scale or variable
  * ''[[:en:create:functions:valuevar|valueVar()]]'' -- Compute variance over scale or variable
  * ''[[:en:create:functions:convertdatetime|convertDateTime()]]'' -- Convert date/time texts (strings) and timestamps

===== Data Visualization =====

  * ''[[:en:create:functions:diagram2|diagram2()]]'' -- Create diagram with set data
  * ''[[:en:create:functions:getqrcodeimage|getQRCodeImage()]]'' -- Integrate QR Code in the questionnaire
  * ''[[:en:create:functions:imagepng_embed|imagepng_embed()]]'' -- Include a PNG graphic without storing it to a file

===== Respondent and Mailing Management =====

  * ''[[:en:create:functions:mailresume]]'' -- Resume an interview after a given delay
  * ''[[:en:create:functions:mailschedule]]'' -- Schedule to send a mailing to a single recipient
  * ''[[:en:create:functions:mailrevoke]]'' -- Cancel a scheduled mailing
  * ''[[:en:create:functions:paneldata]]'' -- Resolve information on the address record

===== PHP-internal functions =====

PHP provides a number of helpful functions, which can easily be used during questionnaire [[http://php.net/manual/en/index.php|PHP Manual]] documented.

  * Useful functions in general
    * [[http://php.net/manual/en/function.implode.php|implode]] - Array-Fusion of elements to string
    * [[http://php.net/manual/en/function.explode.php|explode]] - Split string into array
    * [[http://php.net/manual/en/function.preg-split.php|preg_split]] - Split string with regular expression into array

  * Mathematical functions
    * [[http://php.net/manual/en/function.round.php|round]] - Circular from comma
    * [[http://php.net/manual/en/function.ceil.php|ceil]] - Round up	
    * [[http://php.net/manual/en/function.floor.php|floor]] - Round down
    * [[http://php.net/manual/en/function.abs.php|abs]] - Find amount of number

  * Array-Functions
    * [[http://php.net/manual/en/function.array-diff.php|array_diff]] - Subtract array-elements
    * [[http://php.net/manual/en/function.array-fill.php|array_fill]] - Fill array with (same) values
    * [[http://php.net/manual/en/function.array-flip.php|array_flip]] - Exchange key and values within array
    * [[http://php.net/manual/en/function.array-intersect.php|array_intersect]] - Intersection between arrays
    * [[http://php.net/manual/en/function.array-keys.php|array_keys]] - determine key of arrays
    * [[http://php.net/manual/en/function.array-key-exists.php|array_key_exists]] - Check if function array-key exists
    * [[http://php.net/manual/en/function.array-merge.php|array_merge]] - Merge arrays
    * [[http://php.net/manual/en/function.array-pop.php|array_pop]] - Delete last element of arrays and show output
    * [[http://php.net/manual/en/function.array-push.php|array_push]] - Insert element(s) at the end of arrays
    * [[http://php.net/manual/en/function.array-rand.php|array_rand]] - Random selection of one or more arrays
    * [[http://php.net/manual/en/function.array-reverse.php|array_reverse]] - Reversed output of arrays
    * [[http://php.net/manual/en/function.array-search.php|array_search]] - Search value within array
    * [[http://php.net/manual/en/function.array-shift.php|array_shift]] - Cut element at the beginning of array and provide output
    * [[http://php.net/manual/en/function.array-slice.php| array_slice]] - Write array slice into new array
    * [[http://php.net/manual/en/function.array-sum.php|array_sum]] - Sum elements in array
    * [[http://php.net/manual/en/function.array-unique.php|array_unique]] - Delete counterpart elements from array
    * [[http://php.net/manual/en/function.array-unshift.php| array_unshift]] - Set value(s) on top of the array
    * [[http://php.net/manual/en/function.array-values.php|array_values]] - Transform associative into indexed array
    * [[http://php.net/manual/en/function.arsort.php|arsort]] - Sort array downwards and keep key
    * [[http://php.net/manual/en/function.count.php|count]] - Output count of elements in array
    * [[http://php.net/manual/en/function.in-array.php|in_array]] - Check if value is available in array
    * [[http://php.net/manual/en/function.is-array.php|is_array]] - Check if variable is a array
    * [[http://php.net/manual/en/function.krsort.php|krsort]] - Sort array downwards by keys
    * [[http://php.net/manual/en/function.ksort.php|ksort]] - Sort array upwards by keys
    * [[http://php.net/manual/en/function.list.php|list]] - Spread array on several variables
    * [[http://php.net/manual/en/function.rsort.php|rsort]] - Sort array downwards
    * [[http://php.net/manual/en/function.shuffle.php|shuffle]] - Sort array randomly
    * [[http://php.net/manual/en/function.sort.php|sort]] - Sort array upwards
  * Date and Time
    * [[http://php.net/manual/en/function.date.php|date]] - Format timestamp as date output
    * [[http://php.net/manual/en/function.mktime.php|mktime]] - Code time measurement into timestamp
    * [[http://php.net/manual/en/function.microtime.php|microtime]] - Output of microseconds in timestamp
    * [[http://php.net/manual/en/function.time.php|time]] - Output of seconds in timestamp
  * String-Settings
    * [[http://php.net/manual/en/function.htmlentities.php|htmlentities]] - Transform all characters which have HTML entities
    * [[http://php.net/manual/en/function.htmlspecialchars.php|htmlspecialchars]] - Transform HTML-Syntax-codes (inverted comma, top brackets) into HTML entities
    * [[http://php.net/manual/en/function.ltrim.php|ltrim]] - Delete space at the beginning of strings
    * [[http://php.net/manual/en/function.number-format.php|number_format]] - Format number after comma
    * [[http://php.net/manual/en/function.rtrim.php|rtrim]] - Delete space at the end of strings
    * [[http://php.net/manual/en/function.str-pad.php|str_pad]] - Fill string length to individual size
    * [[http://php.net/manual/en/function.str-replace.php|str_replace]] - Search part string and replace
    * [[http://php.net/manual/en/function.strlen.php|strlen]] - Determine string length
    * [[http://php.net/manual/en/function.strtolower.php|strtolower]] - transform sting into lower case
    * [[http://php.net/manual/en/function.strtoupper.php|strtoupper]] - Transform string in capitals
    * [[http://php.net/manual/en/function.substr-count.php|substr_count]] - Count frequency of part strings
    * [[http://php.net/manual/en/function.substr.php|substr]] - Detect part strings
    * [[http://php.net/manual/en/function.trim.php|trim]] - Delete space at beginning and end
    * Also allowed are the functions: [[http://php.net/manual/en/function.nl2br.php|nl2br]], [[http://php.net/manual/en/function.str-repeat.php|str_repeat]], [[http://php.net/manual/en/function.str-shuffle.php|str_shuffle]], [[http://php.net/manual/en/function.str-word-count.php|str_word_count]], [[http://php.net/manual/en/function.strip-tags.php|strip_tags]], [[http://php.net/manual/en/function.stripos.php|stripos]], [[http://php.net/manual/en/function.stristr.php|stristr]], [[http://php.net/manual/en/function.strpos.php|strpos]], [[http://php.net/manual/en/function.strrev.php|strrev]], [[http://php.net/manual/en/function.strripos.php|strripos]], [[http://php.net/manual/en/function.strrpos.php|strrpos]], [[http://php.net/manual/en/function.strstr.php|strstr]], [[http://php.net/manual/en/function.substr-replace.php|substr_replace]], [[http://php.net/manual/en/function.wordwrap.php|wordwrap]]\\   
  * Drawings (e.g.  diagrams)
    * [[http://php.net/manual/en/function.imagecolorallocate.php|imagecolorallocate]] - Use color for graphic
    * [[http://php.net/manual/en/function.imagecreate.php|imagecreate]] - Create new picture
    * [[http://php.net/manual/en/function.imagecreatetruecolor.php|imagecreatetruecolor]] - New picture in real color (16 Mio.) sings
    * [[http://php.net/manual/en/function.imageellipse.php|imageellipse]] - Draw ellipse or circle
    * [[http://php.net/manual/en/function.imagefill.php|imagefill]] - Fill picture (range) with color
    * [[http://php.net/manual/en/function.imagefilledarc.php| imagefilledarc]] - Draw filled circle (sector)
    * [[http://php.net/manual/en/function.imagefilledellipse.php|imagefilledellipse]] - Draw filled ellipse or circle
    * [[http://php.net/manual/en/function.imagefilledpolygon.php|imagefilledpolygon]] - Draw filled polygon
    * [[http://php.net/manual/en/function.imagefilledrectangle.php|imagefilledrectangle]] - Draw filled rectangle
    * [[http://php.net/manual/en/function.imagefilltoborder.php|imagefilltoborder]] - Fill picture with color until line
    * [[http://php.net/manual/en/function.imageline.php|imageline]] - Draw straight line
    * [[http://php.net/manual/en/function.imagepolygon.php|imagepolygon]] - Draw polygon
    * [[http://php.net/manual/en/function.imagerectangle.php|imagerectangle]] - Draw rectangle
    * [[http://php.net/manual/en/function.imagesetbrush.php|imagesetbrush]] - Set brush
    * [[http://php.net/manual/en/function.imagesetpixel.php|imagesetpixel]] - Pixel sign
    * [[http://php.net/manual/en/function.imagesetstyle.php|imagesetstyle]] - Set line style
    * [[http://php.net/manual/en/function.imagesetthickness.php|imagesetthickness]] - Set line width
    * [[http://php.net/manual/en/function.imagestring.php|imagestring]] - Text sign (horizontal)
    * More allowed functions: [[http://php.net/manual/en/function.image-type-to-extension.php|image_type_to_extension]], [[http://php.net/manual/en/function.image-type-to-mime-type.php|image_type_to_mime_type]], [[http://php.net/manual/en/function.imagearc.php|imagearc]], [[http://php.net/manual/en/function.imagechar.php|imagechar]], [[http://php.net/manual/en/function.imagecharup.php|imagecharup]], [[http://php.net/manual/en/function.imagecolorallocatealpha.php|imagecolorallocatealpha]], [[http://php.net/manual/en/function.imagecolorat.php|imagecolorat]], [[http://php.net/manual/en/function.imagecolorclosest.php|imagecolorclosest]], [[http://php.net/manual/en/function.imagecolorclosestalpha.php|imagecolorclosestalpha]], [[http://php.net/manual/en/function.imagecolorclosesthwb.php|imagecolorclosesthwb]], [[http://php.net/manual/en/function.imagecolordeallocate.php|imagecolordeallocate]], [[http://php.net/manual/en/function.imagecolorexact.php|imagecolorexact]], [[http://php.net/manual/en/function.imagecolorresolve.php|imagecolorresolve]], [[http://php.net/manual/en/function.imagecolorset.php|imagecolorset]], [[http://php.net/manual/en/function.imagecopy.php|imagecopy]], [[http://php.net/manual/en/function.imagecopymerge.php|imagecopymerge]], [[http://php.net/manual/en/function.imagecopymergegray.php|imagecopymergegray]], [[http://php.net/manual/en/function.imagecopyresampled.php|imagecopyresampled]], [[http://php.net/manual/en/function.imagecopyresized.php| imagecopyresized]], [[http://php.net/manual/en/function.imagedashedline.php| imagedashedline]], [[http://php.net/manual/en/function.imagedestroy.php|imagedestroy]], [[http://php.net/manual/en/function.imagefilter.php|imagefilter]], [[http://php.net/manual/en/function.imagefontheight.php|imagefontheight]], [[http://php.net/manual/en/function.imagefontwidth.php| imagefontwidth]], [[http://php.net/manual/en/function.imageinterlace.php|imageinterlace]], [[http://php.net/manual/en/function.imagepalettecopy.php|imagepalettecopy]], [[http://php.net/manual/en/function.imagerotate.php|imagerotate]], [[http://php.net/manual/en/function.imagesavealpha.php|imagesavealpha]], [[http://php.net/manual/en/function.imagesettile.php|imagesettile]], [[http://php.net/manual/en/function.imagestringup.php|imagestringup]], [[http://php.net/manual/en/function.imagesx.php|imagesx]], [[http://php.net/manual/en/function.imagesy.php|imagesy]], [[http://php.net/manual/en/function.imagetruecolortopalette.php|imagetruecolortopalette]]
    * Following functions can be used in modified version: [[http://php.net/manual/en/function.imagepng.php|imagepng]], [[http://php.net/manual/en/function.imagettftext.php|imagettftext]], [[http://php.net/manual/en/function.imagecreatefrompng.php|imagecreatefrompng]]
  * Miscellaneous
    * [[http://php.net/manual/en/function.intval.php|intval]] - Convert Variable into integer value
    * [[http://php.net/manual/en/function.md5.php|md5]] - Compute MD5-hash 


===== Restricted Functions =====

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''
    * ''[[:en:create:functions:html]]''
    * ''[[:en:create:functions:text]]''
  * ''mysqld_query()''
    * ''[[:en:create:databank]]''
    * ''[[:en:create:functions::datasetretrieve|datasetRetrieve()]]''


===== Detailed Functions =====

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 ([[filter-items#arrays|Arrays]])