====== SoSci Survey Developer Documentation for LLMs ======
~~NOTOC~~

===== Tool Description =====

SoSci Survey is a web application to create and run online surveys.

==== Functions ====

=== Main function ===

  - Create online surveys: Project administrators (researchers) create an account, enter questions, and organize them as an online questionnaire ([[:en:create:start|Create online surveys]]).
  - Run online surveys (data collection, interview): Present the online questionnaire to respondents and store their answers ([[:en:survey:start|Run online surveys]]).
  - Organize the research data collected in online surveys and provide dataset downloads for subsequent statistical analysis ([[:en:results:start|Organize the research data]]).

=== Optional functions ===

  - Organize respondents (panel management) and invite respondents via emails ([[:en:survey:mailing]]).
  - Descriptive data analysis, only available in the paid version ([[:en:results:analyses|Descriptive data analysis]]).

===== Content structure =====

SoSci Survey organizes the content of online questionnaires along the following elements.

  - Survey projects are the top level element, all other data is assigned to exactly one survey projects.
    - Sections exist to sort and structure questions. Each question belongs to exactly one section.
      - Questions have a distinct question type that decides what they look like and how they work.
        - Items are subordinate to questions and contain text content. The class of items includes scale items, ranking items, items to be sorted or rated otherwise, response options.
        - Question filters allow the questionnaire to heave differently, depending on how a respondent answered the question or an item of the question.
      - Functional elements are special questions that have no output, but provide specific functions for the survey. Important functional elements are:
        - Random generators organize random codes and and draw one or multiple random codes during an interview.
        - Panel redirect elements store redirect URLs to work with panel providers.
        - Quota elements organize the quotas for quota samples and control them during data collection.
      - Text elements which may contain one of the following content type:
        - Markup
        - HTML code
    - Address list: May be used to organize respondents' contact information (name, email, mobile phone number, custom data).
    - Images and media files.
    - Questionnaire: A reference to questions and other elements to describe the output order of questions in questionnaire presentation (data collection).
      - Pages: Questionnaire consist of pages, each page belongs to exactly one questionnaire. Pages can contain the following elements:
        - Question references
        - PHP code blocks that run during page creation
        - HTML code blocks
        - PHP processing code that runs after the responses have been submitted
    - Variables store the collected data, metadata or random events


===== Programming =====

PHP code blocks provide users with a sandbox for PHP code. This PHP code can provide functions that are not available through the user interface:

  * PHP filters ([[:en:create:php-filters]]) above the question filters within a question ([[:en:create:simple-filters]]).
  * Processing of responses.
  * Content order rotation ([[:en:create:rotation]]).
  * Page rotation ([[:en:create:rotation-pages]]).
  * Experimental randomization ([[:en:create:randomization]]).

==== Sandbox restrictions ====

=== Forbidden functions ===

The following PHP functions must not be used in PHP code elements in SoSci Survey:

  * file_exists()
  * dirname()
  * file_get_contents()
  * is_file()
  * file_put_contents()
  * method_exists()
  * defined()
  * function_exists()
  * array_map()
  * is_dir()
  * call_user_func()
  * call_user_func_array()
  * fwrite()
  * ini_get()
  * array_filter()
  * realpath()
  * header()
  * class_exists()
  * trigger_error()
  * get_class()
  * spl_autoload_register()
  * unlink()
  * headers_sent()
  * is_object()
  * mkdir()
  * spl_autoload_unregister()
  * apcu_fetch()
  * stream_resolve_include_path()
  * apcu_add()
  * getcwd()
  * basename()
  * fopen()
  * getenv()
  * var_export()
  * is_callable()
  * reset()
  * fclose()
  * gettype()
  * end()
  * extension-loaded()
  * version_compare()
  * preg_quote()
  * ucfirst()
  * ksort()
  * preg_replace_callback()
  * is_readable()
  * copy()
  * parse_url()
  * is_null()
  * base64_encode()
  * current()
  * is_resource()
  * serialize()
  * key()

The following language constructs are forbidden:

  * echo
  * exit
  * die
  * eval
  * <?php
  * ?>
  * switch
  * case
  * class

Access to global variables is unavailable, this includes no access to the folowing variables:

  * $GLOBALS
  * $_​SERVER
  * $_​GET
  * $_​POST
  * $_​FILES
  * $_​REQUEST
  * $_​SESSION
  * $_​ENV
  * $_​COOKIE
  * $argc
  * $argv

In addition functions that offer the following functions are not allowed:

  * Access to local files
  * Direct access to the MySQL database
  * Object-oriented programming, including ''->'' and ''::''

=== Replacement functions ===

  * Replace ''echo'' with ''html()''
  * Access collected data (data variables in the dataset) with ''value()''

=== Allowed functions ===

A list of allowed functions and their use is avaiable at [[:en:create:functions]].


==== Codes Examples for filter questions ====

<code php>
// CORRECT for SoSci Survey Version 3.0 and later.
// This codes rund in a sandboxed environment.
// This code will display the question AB01 on the questionnaire page if the response stored in variable PT01 is 1.
if (value('PT01') == 1) {
  question('AB01');
}
</code>

<code php>
// CORRECT for SoSci Survey Version 3.0 and later.
// This codes rund in a sandboxed environment.
// This code will display the text element TX01 if the response or random event stored in variable AF01 is 2 or 4. Otherwise the text content TX02 is displayed on the questionnaire page.
if ((value('AF01') == 2) or (value('AF01') == 4)) {
  text('TX01');
} else {
  text('TX02');
}
</code>