Participant API Documentation
SoPHIE Participant API Class
The Participant API provides participant related functionality within
the execution context.
Init: $participantApi = $api->get('sophie_participant');
Method: $participantApi->translateLabel(...)
Translates a participant special label considering the context into a label of a specific participant.
The method supports the special labels %current%, %partner% and %localPartner%.
%current% translates to the label of the participant which is currently active within the procedural context.
%partner% translates to the label of a second participant within the current group besides the curretly active participant within the current procedural context.
%localPartner% translates to the label of a second participant within the group of a specified procedural context besides the curretly active participant. The procedural context is defined by passing stepgroupLabel and stepgroupLoop as options in an array as a second parameter to the method.
Parameters:
- String $label Participant special label to be translated. Defaults to %current%.
- Array $options Array of options stepgroupLabel and stepgroupLoop for %localPartner%
Returns String|null Participant Label
Method: $participantApi->getParticipantLabels(...)
Get an array of labels of participants within the session.
The method returns an array of labels of all participants within a session. The array can be restricted to participants matching certain criteria by passing an option array with criteria elements to the method.
Parameters:
- Array $options Array of options. Available filter options: typeLabel, state, stepgroupLabel, stepgroupLoop, stepLabel, maxSinceLastContact (int), minSinceLastContact (int). Also available is the order option
Returns Array Array of participant labels
Method: $participantApi->getParticipantCodes(...)
Get an array of codes of participants within the session.
The method returns an array of labels of all participants within a session. The array can be restricted to participants matching certain criteria by passing an option array with criteria elements to the method.
Parameters:
- Array $options Array of options. Available filter options: typeLabel, state, stepgroupLabel, stepgroupLoop, stepLabel, maxSinceLastContact (int), minSinceLastContact (int). Also available is the order option
Returns Array Array of participant labels
Method: $participantApi->getParticipantCodesAssoc(...)
Get an associative array of codes of participants within the session.
The method returns an array of labels of all participants within a session. The array can be restricted to participants matching certain criteria by passing an option array with criteria elements to the method.
Parameters:
- Array $options Array of options. Available filter options: typeLabel, state, stepgroupLabel, stepgroupLoop, stepLabel, maxSinceLastContact (int), minSinceLastContact (int).
Returns Array Array of participant labels
Method: $participantApi->getParticipants(...)
Get an array of the participants within the session.
The method returns an array all participants within a session. The array can be restricted to participants matching certain criteria by passing an option array with criteria elements to the method.
Parameters:
- Array $options Array of options. Available filter options: typeLabel, state (array), stepgroupLabel (String), stepgroupLoop (int), stepLabel (String), maxSinceLastContact (int), minSinceLastContact (int). Also available is the order option with valid values rand, number/numberAsc/numberDesc and code/codeAsc/codeDesc
Returns Array Array of participants
Method: $participantApi->get(...)
Get participant details.
Returns an array of information for a participant. If no label is passed the details for the current participant is returned.
Parameters:
- String $label Participant label or special label to be translated. Defaults to %current%.
Returns Array|null Participant details
Method: $participantApi->getCode(...)
Get participant code.
Returns the unique participant code which is used to login participants. Returns the code of the current participant if no label parameter is passed.
Parameters:
- String $label Participant label or special label to be translated. Defaults to %current%.
Returns String|null Participant code
Method: $participantApi->setCode(...)
Set participant code.
Sets the participant code
Parameters:
- String $label Participant label or special label to be translated. Defaults to %current%.
- String $code Participant code to be set
Method: $participantApi->getTypeLabel(...)
Get participant type label.
Returns the participant type label. Returns the type label of the current participant if no label parameter is passed.
Parameters:
- String $label Participant label or special label to be translated. Defaults to %current%.
Returns String|null Participant type label
Method: $participantApi->setTypeLabel(...)
Set participant type label.
Sets the participant type
Parameters:
- String $label Participant label or special label to be translated. Defaults to %current%.
- String $typeLabel Participant label or special label to be translated. Defaults to %current%.
Method: $participantApi->getNumber(...)
Get participant number.
Returns the unique participant number which is incremented with each participant added to the session. Returns the number of the current participant if no label parameter is passed.
Parameters:
- String $label Participant label or special label to be translated. Defaults to %current%.
Returns int|null Participant number
Method: $participantApi->setParticipantsStep(...)
Set step for all participants.
Returns true when setting steps for all participants to the given step succeeds, false otherwise.
Parameters:
- String $stepLabel The label of the step you want the participant to be set to. No default value.
- String $stepgroupLoop The loop number you want the participant to be set to. Defaults to %current% for steps within the same stepgroup, 1 otherwise.
Returns Boolean True when setting the step for all participants suceeded, false otherwise.
Method: $participantApi->setParticipantsTypeStep(...)
Set step for all participants.
Returns true when setting steps for all participants to the given step succeeds, false otherwise.
Parameters:
- String $stepLabel The label of the step you want the participant to be set to. No default value.
- String $stepgroupLoop The loop number you want the participant to be set to. Defaults to %current% for steps within the same stepgroup, 1 otherwise.
Returns Boolean True when setting the step for all participants suceeded, false otherwise.
Method: $participantApi->setStep(...)
Set participant step.
Returns true when setting participant to the given step succeeds, false otherwise.
Parameters:
- String $stepLabel The label of the step you want the participant to be set to. No default value.
- String $stepgroupLoop The loop number you want the participant to be set to. Defaults to %current% for steps within the same stepgroup, 1 otherwise.
- String $label Participant label or special label to be translated. Defaults to %current%.
Returns Boolean True when setting the participant to the step suceeded, false otherwise.
Method: $participantApi->setState(...)
Set participant state.
Returns true when setting participant state succeeds, false otherwise.
Parameters:
- String $state State too set participant to (new, started, excluded, finished)
- String $label Participant label or special label to be translated. Defaults to %current%.
Returns Boolean True when setting the participant state succeeded, false otherwise.
Method: $participantApi->exclude(...)
Set participant state to excluded.
Returns true when setting participant state to excluded succeeds, false otherwise.
Parameters:
- String $label Participant label or special label to be translated. Defaults to %current%.
Returns Boolean True when setting the participant state succeeded, false otherwise.