GemsTracker library API
Back to top  

LimeSurvey1m9Database is a Source interface that enables the use of LimeSurvey 1.9.x installation as survey/answer source for Gems projects.

package Gems
subpackage Tracker
copyright Copyright (c) 2011 Erasmus MC
license New BSD License
since Class available since version 1.2
inherited_from \Gems_Tracker_Source_SourceAbstract

 Methods

Standard constructor for sources

__construct(array $sourceData, \Zend_Db_Adapter_Abstract $gemsDb) 
Inherited
inherited_from \Gems_Tracker_Source_SourceInterface::__construct()

Parameters

$sourceData

array

The information from gems__sources for this source.

$gemsDb

\Zend_Db_Adapter_Abstract

Do not want to copy db using registry because that is public and this should be private

Check if the tableprefix exists in the source database, and change the status of this adapter in the gems_sources table accordingly

checkSourceActive(integer $userId) : boolean

Parameters

$userId

integer

Id of the user who takes the action (for logging)

Returns

booleanTrue if the source is active

Survey source synchronization check function

checkSurvey(string $sourceSurveyId, integer $surveyId, integer $userId) : mixed

Parameters

$sourceSurveyId

string

$surveyId

integer

$userId

integer

Returns

mixedmessage string or array of messages

Inserts the token in the source (if needed) and sets those attributes the source wants to set.

copyTokenToSource(\Gems_Tracker_Token $token, string $language, integer $surveyId, string $sourceSurveyId = null) : integer

Parameters

$token

\Gems_Tracker_Token

$language

string

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Exceptions

\Gems_Tracker_Source_SurveyNotFoundException

Returns

integer1 of the token was inserted or changed, 0 otherwise

Returns a field from the raw answers as a date object.

getAnswerDateTime(string $fieldName, \Gems_Tracker_Token $token, integer $surveyId, string $sourceSurveyId = null) : \MUtil_Date

A seperate function as only the source knows what format the date/time value has.

Parameters

$fieldName

string

Name of answer field

$token

\Gems_Tracker_Token

Gems token object

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

\MUtil_Datedate time or null

getAttributes() 

getAttributes() 

Bulk check token completion

getCompletedTokens(array $tokenIds, integer $sourceSurveyId) : array

Returns all tokens from the input array that are completed, by doing this in bulk we saved overhead and only do a deep check on the completed tokens.

Parameters

$tokenIds

array

$sourceSurveyId

integer

Returns

array

Gets the time the survey was completed according to the source

getCompletionTime(\Gems_Tracker_Token $token, integer $surveyId, string $sourceSurveyId = null) : \MUtil_Date

A source always return null when it does not know this time (or does not know it well enough). In the case \Gems_Tracker_Token will do it's best to keep track by itself.

Parameters

$token

\Gems_Tracker_Token

Gems token object

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

\MUtil_Datedate time or null

Returns an array containing fieldname => label for each date field in the survey.

getDatesList(string $language, integer $surveyId, string $sourceSurveyId = null) : array

Used in dropdown list etc..

Parameters

$language

string

(ISO) language string

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

arrayfieldname => label

Returns an array of arrays with the structure: question => string, class => question|question_sub group => is for grouping type => (optional) source specific type answers => string for single types, array for selection of, nothing for no answer

getFullQuestionList(string $language, integer $surveyId, string $sourceSurveyId = null) : array

Parameters

$language

string

(ISO) language string

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

arrayNested array

getId() 

getId() : integer
Inherited
inherited_from \Gems_Tracker_Source_SourceInterface::getId()

Returns

integerThe source Id of this source

Returns an array of arrays with the structure: question => string, class => question|question_sub group => is for grouping type => (optional) source specific type answers => string for single types, array for selection of, nothing for no answer

getQuestionInformation(string $language, integer $surveyId, string $sourceSurveyId = null) : array

Parameters

$language

string

(ISO) language string

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

arrayNested array

Returns an array containing fieldname => label for each answerable question in the survey.

getQuestionList(string $language, integer $surveyId, string $sourceSurveyId = null) : array

Used in dropdown list etc..

Parameters

$language

string

(ISO) language string

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

arrayfieldname => label

Returns the answers in simple raw array format, without value processing etc.

getRawTokenAnswerRow(string $tokenId, integer $surveyId, string $sourceSurveyId = null) : array

Function may return more fields than just the answers.

Parameters

$tokenId

string

Gems Token Id

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

arrayField => Value array

Returns the answers of multiple tokens in simple raw nested array format, without value processing etc.

getRawTokenAnswerRows(array $filter, integer $surveyId, string $sourceSurveyId = null) : array

Function may return more fields than just the answers.

Parameters

$filter

array

XXXXX

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

arrayOf nested Field => Value arrays indexed by tokenId

Returns the recordcount for a given filter

getRawTokenAnswerRowsCount(array $filter, integer $surveyId, string $sourceSurveyId = null) : integer

Abstract implementation is not efficient, sources should handle this as efficient as possible.

inherited_from \Gems_Tracker_Source_SourceAbstract::getRawTokenAnswerRowsCount()

Parameters

$filter

array

filter array

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

integer

Returns the recordcount for a given filter

getRawTokenAnswerRowsCount(array $filter, integer $surveyId, string $sourceSurveyId = null) : integer
Inherited

Abstract implementation is not efficient, sources should handle this as efficient as possible.

inherited_from \Gems_Tracker_Source_SourceInterface::getRawTokenAnswerRowsCount()

Parameters

$filter

array

filter array

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

integer

Get the select object to use for RawTokenAnswerRows

getRawTokenAnswerRowsSelect(array $filter, \type $surveyId, \type $sourceSurveyId = null) : \Zend_Db_Select

Parameters

$filter

array

$surveyId

\type

$sourceSurveyId

\type

Returns

\Zend_Db_Select

Get the db adapter for this source

getSourceDatabase() : \Zend_Db_Adapter_Abstract
Inherited
inherited_from \Gems_Tracker_Source_SourceInterface::getSourceDatabase()

Returns

\Zend_Db_Adapter_Abstract

Gets the time the survey was started according to the source

getStartTime(\Gems_Tracker_Token $token, integer $surveyId, string $sourceSurveyId = null) : \MUtil_Date

A source always return null when it does not know this time (or does not know it well enough). In the case \Gems_Tracker_Token will do it's best to keep track by itself.

Parameters

$token

\Gems_Tracker_Token

Gems token object

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

\MUtil_Datedate time or null

Returns a model for the survey answers

getSurveyAnswerModel(\Gems_Tracker_Survey $survey, string $language = null, string $sourceSurveyId = null) : \MUtil_Model_ModelAbstract

Parameters

$survey

\Gems_Tracker_Survey

$language

string

Optional (ISO) language string

$sourceSurveyId

string

Optional Survey Id used by source

Returns

\MUtil_Model_ModelAbstract

Retrieve all fields stored in the token table, and store them in the tokencache

getTokenInfo(\Gems_Tracker_Token $token, \type $surveyId, \type $sourceSurveyId, array $fields = null) : \type

Parameters

$token

\Gems_Tracker_Token

$surveyId

\type

$sourceSurveyId

\type

$fields

array

Returns

\type

Returns the url that (should) start the survey for this token

getTokenUrl(\Gems_Tracker_Token $token, string $language, integer $surveyId, string $sourceSurveyId) : string

Parameters

$token

\Gems_Tracker_Token

Gems token object

$language

string

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

stringThe url to start the survey

Checks whether the token is in the source.

inSource(\Gems_Tracker_Token $token, integer $surveyId, string $sourceSurveyId = null) : boolean

Parameters

$token

\Gems_Tracker_Token

Gems token object

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

boolean

Returns true if the survey was completed according to the source

isCompleted(\Gems_Tracker_Token $token, integer $surveyId, string $sourceSurveyId = null) : boolean

Parameters

$token

\Gems_Tracker_Token

Gems token object

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

booleanTrue if the token has completed

Sets the answers passed on.

setRawTokenAnswers(\Gems_Tracker_Token $token, array $answers, integer $surveyId, string $sourceSurveyId = null) : true

Parameters

$token

\Gems_Tracker_Token

Gems token object

$answers

array

Field => Value array

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

trueWhen answers changed

Sets the completion time.

setTokenCompletionTime(\Gems_Tracker_Token $token, \Zend_Date|null $completionTime, integer $surveyId, string $sourceSurveyId = null) 

Parameters

$token

\Gems_Tracker_Token

Gems token object

$completionTime

\Zend_Datenull

\Zend_Date or null

$surveyId

integer

Gems Survey Id (actually required)

$sourceSurveyId

string

Optional Survey Id used by source

Updates the gems database with the latest information about the surveys in this source adapter

synchronizeSurveyBatch(\Gems_Task_TaskRunnerBatch $batch, integer $userId) : array
Inherited
inherited_from \Gems_Tracker_Source_SourceInterface::synchronizeSurveyBatch()

Parameters

$batch

\Gems_Task_TaskRunnerBatch

$userId

integer

Id of the user who takes the action (for logging)

Returns

arrayReturns an array of messages

Updates the consent code of the the token in the source (if needed)

updateConsent(\Gems_Tracker_Token $token, integer $surveyId, string $sourceSurveyId = null, string $consentCode = null) : integer

Parameters

$token

\Gems_Tracker_Token

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

$consentCode

string

Optional consent code, otherwise code from token is used.

Returns

integer1 of the token was inserted or changed, 0 otherwise

Checks the return URI in LimeSurvey and sets it to the correct one when needed

_checkReturnURI(string $sourceSurveyId, \Gems_Tracker_Survey $survey, array $messages) 
see

Parameters

$sourceSurveyId

string

$survey

\Gems_Tracker_Survey

$messages

array

Check a token table for any changes needed by this version.

_checkTokenTable(array $tokenTable) : array

Parameters

$tokenTable

array

Returns

arrayFieldname => change field commands

Returns a list of field names that should be set in a newly inserted token.

_fillAttributeMap(\Gems_Tracker_Token $token) : array

Parameters

$token

\Gems_Tracker_Token

Returns

arrayOf fieldname => value type

Filters an answers array, return only those fields that where answered by the user.

_filterAnswersOnly(integer $sourceSurveyId, array $answers) : array

Parameters

$sourceSurveyId

integer

Survey ID

$answers

array

Returns

array

Return a fieldmap object

_getFieldMap(integer $sourceSurveyId, string $language = null) : \Gems_Tracker_Source_LimeSurvey1m9FieldMap

Parameters

$sourceSurveyId

integer

Survey ID

$language

string

Optional (ISO) Language, uses default language for survey when null

Returns

\Gems_Tracker_Source_LimeSurvey1m9FieldMap

Returns all surveys for synchronization

_getGemsSurveysForSynchronisation() : array
Inherited

Returns

arrayPairs gemsId => sourceId

Returns the langauge to use for the survey when this language is specified.

_getLanguage(integer $sourceSurveyId, string $language) : string

Uses the requested language if it exists for the survey, the default language for the survey otherwise

Parameters

$sourceSurveyId

integer

Survey ID

$language

string

(ISO) Language

Returns

string(ISO) Language

Get the return URI to return from LimeSurvey to GemsTracker

_getReturnURI() : string

Returns

string

Get the return URI description to set in LimeSurvey

_getReturnURIDescription(string $language) : string

Parameters

$language

string

Returns

string

Looks up the LimeSurvey Survey Id

_getSid(integer $surveyId) : integer

Parameters

$surveyId

integer

Returns

integer

Returns all surveys for synchronization

_getSourceSurveysForSynchronisation() : array
inherited_from \Gems_Tracker_Source_SourceAbstract::_getSourceSurveysForSynchronisation()

Returns

arrayof sourceId values or false

Returns all surveys for synchronization

_getSourceSurveysForSynchronisation() : array
Inherited

Returns

arrayof sourceId values or false

The survey languages table contains the survey level texts per survey

_getSurveyLanguagesTableName() : string

Returns

stringName of survey languages table

There exists a survey table for each active survey. The table contains the answers to the survey

_getSurveyTableName(integer $sourceSurveyId) : string

Parameters

$sourceSurveyId

integer

Survey ID

Returns

stringName of survey table for this survey

The survey table contains one row per each survey in LS

_getSurveysTableName() : string

Returns

stringName of survey table

Replaces hyphen with underscore so LimeSurvey won't choke on it

_getToken($tokenId, boolean $reverse = false) : string

Parameters

$tokenId

$reverse

boolean

Reverse the action to go from limesurvey to GemsTracker token (default is false)

Returns

string

Creates a where filter statement for tokens that do not have a correct name and are in a tokens table

_getTokenFromSqlWhere(string $from, string $fieldName) : string
Inherited

Parameters

$from

string

The tokens that should not occur

$fieldName

string

Name of database field to use

Returns

string

Creates a SQL update statement for tokens that do not have a correct name and are in a tokens table.

_getTokenFromToSql(string $from, string $to, string $fieldName) : string
Inherited

Parameters

$from

string

The tokens that should not occur

$to

string

The tokens that replace them

$fieldName

string

Name of database field to use

Returns

string

There exists a token table for each active survey with tokens.

_getTokenTableName(integer $sourceSurveyId) : string

Parameters

$sourceSurveyId

integer

Survey ID

Returns

stringName of token table for this survey

Check if the specified language is available in Lime Survey

_isLanguage(integer $sourceSurveyId, string $language) : boolean

Parameters

$sourceSurveyId

integer

Survey ID

$language

string

(ISO) Language

Returns

booleanTrue when the language is an existing language

This helper function updates the surveys in the gems_surveys table that no longer exist in in the source and returns a list of their names.

_updateGemsSurveyExists(array $surveyorSids, integer $userId) : array
Inherited

Parameters

$surveyorSids

array

The gsu_surveyor_id's that ARE in the source

$userId

integer

Id of the user who takes the action (for logging)

Returns

arrayThe names of the surveys that no longer exist

Updates this source, both in the database and in memory.

_updateSource(array $values, integer $userId) : integer
Inherited

Parameters

$values

array

The values that this source should be set to

$userId

integer

The current user

Returns

integer1 if data changed, 0 otherwise

Adds database (if needed) and tablename prefix to the table name

addDatabasePrefix(\return $tableName, boolean $addDatabaseName = true) : string
Inherited

Parameters

$tableName

\return

$addDatabaseName

boolean

Optional, when true (= default) and there is a database name then it is prepended to the name.

Returns

string

Extract limit and offset from the filter and add it to a select

filterLimitOffset(array $filter, \Zend_Db_Select $select) 
Inherited

Parameters

$filter

array

$select

\Zend_Db_Select

getBaseUrl() 

getBaseUrl() : string
Inherited

Returns

stringBase url for source

Returns all info from the Gems surveys table for a givens Gems Survey Id

getSurveyData(integer $surveyId, string $field = null) : array
Inherited

Uses internal caching to prevent multiple db lookups during a program run (so no caching beyond page generation time)

Parameters

$surveyId

integer

$field

string

Optional field to retrieve data for

Returns

array

Updates the gems__tokens table so all tokens stick to the (possibly) new token name rules.

updateTokens(integer $userId, $updateTokens = true) : integer
Inherited

Parameters

$userId

integer

Id of the user who takes the action (for logging)

$updateTokens

Returns

integerThe number of tokens changed

_extractFieldLength() 

_extractFieldLength(string $typeDescr) : integer

Parameters

$typeDescr

string

E.g. int(11) or varchar(36)

Returns

integerIn case 11 or 36

 Properties

 

The LS version dependent field name for anonymized surveys

$_anonymizedField : string

Default

'private'
 

A map containing attributename => databasefieldname mappings

$_attributeMap : array

Default

array('respondentid' => 'attribute_1', 'organizationid' => 'attribute_2', 'consentcode' => 'attribute_3', 'resptrackid' => 'attribute_4')

Should contain maps for respondentid, organizationid and consentcode.

 

The default text length attribute fields should have.

$attributeSize : integer

Default

255
 

$locale

$locale : \Zend_Locale

Default

 

$logger

$logger : \Gems_Log

Default

 

$project

$project : \Gems_Project_ProjectSettings

Default

 

$request

$request : \Zend_Controller_Request_Abstract

Default

 

$tracker

$tracker : \Gems_Tracker

Default

 

$translate

$translate : \Zend_Translate

Default

 

$util

$util : \Gems_Util

Default

 

of \Gems_Tracker_Source_LimeSurvey1m9FieldMap

$_fieldMaps : array

Default

 

Holds the current batch if there is any

$_gemsDb : \Gems_Task_TaskRunnerBatch: \Zend_Db_Adapter_Abstract

Default

 

of string

$_languageMap : array

Default

 

The information from the gems__sources for this source

$_sourceData : array

Default

 

The database connection to the source, usedable by all implementations that use a database

$_sourceDb : \Zend_Db_Adapter_Abstract

Default

 Constants

 

CACHE_TOKEN_INFO

CACHE_TOKEN_INFO = 'tokenInfo' 
 

LS_DB_COMPLETION_FORMAT

LS_DB_COMPLETION_FORMAT = 'yyyy-MM-dd HH:mm' 
 

LS_DB_DATETIME_FORMAT

LS_DB_DATETIME_FORMAT = 'yyyy-MM-dd HH:mm:ss' 
 

LS_DB_DATE_FORMAT

LS_DB_DATE_FORMAT = 'yyyy-MM-dd' 
 

QUESTIONS_TABLE

QUESTIONS_TABLE = 'questions' 
 

SURVEYS_LANG_TABLE

SURVEYS_LANG_TABLE = 'surveys_languagesettings' 
 

SURVEYS_TABLE

SURVEYS_TABLE = 'surveys' 
 

SURVEY_TABLE

SURVEY_TABLE = 'survey_' 
 

TOKEN_TABLE

TOKEN_TABLE = 'tokens_'