import_helper.php
Table of Contents
Functions
- XMLImportGroup() : mixed
- This function imports a LimeSurvey .lsg question group XML file
- XMLImportQuestion() : array<string|int, mixed>
- This function imports a LimeSurvey .lsq question XML file
- XMLImportLabelsets() : array<string|int, mixed>
- XMLImportLabelsets() Function resp[onsible to import a labelset from XML format.
- finalizeSurveyImportFile() : mixed
- getTableArchivesAndTimestamps() : array<string|int, mixed>
- Returns the tables which
- importSurveyFile() : array<string|int, mixed>|null
- Imports a survey file into the application by dispatching to the appropriate importer according to file extension.
- createTableFromPattern() : int
- Creates a table based on another
- polyfillSUBSTRING_INDEX() : mixed
- generateTemporaryTableCreate() : string
- Generates a temporary table creation script
- generateTemporaryTableDrop() : string
- Generates a drop statement for a temporary table
- getUnchangedColumns() : array<string|int, mixed>
- Gets the unchanged columns
- generateTemporaryTableCreates() : array<string|int, mixed>
- Generates temporary table creation scripts from the arrays received and returns the scripts that were generated, we expect count($sourceTables) and count($destinationTables) to be the same
- generateTemporaryTableDrops() : array<string|int, mixed>
- Generates temporary table drops for the tables received and returns the scripts
- getDeactivatedArchives() : array<string|int, mixed>
- Finds the newest archive table from each kind
- copyFromOneTableToTheOther() : int
- Copying all data from source table to a target table having the same structure
- recoverSurveyResponses() : int
- Recovers archived survey responses
- XMLImportSurvey() : array<string|int, mixed>
- Import a LimeSurvey survey from an XML file or XML string into the database.
- checkWrongQuestionAttributes() : mixed
- This function checks if there are set wrong values ('Y' or 'N') into table question_attributes. These are set to 1 and 0 if needed.
- XMLImportTokens() : mixed
- XMLImportResponses() : mixed
- CSVImportResponses() : mixed
- This function imports a CSV file into the response table CSV file is deleted during process
- XMLImportTimings() : mixed
- TSVImportSurvey() : string
- Import survey from an TSV file template that does not require assigning of GID or QID values.
- createXMLfromData() : mixed
- importDefaultValues() : void
- Import default values inside $xml, record process in $results Also imports defaultvalue_l10ns.
- fileCsvToUtf8() : resource
- Read a csv file and return a tmp resources to same file in utf8 CSV file is deleted during process
- getInsertansSignature() : array<string|int, mixed>|null
- Generates the INSERTANS conversion queue signature for a model
- processPendingInsertansUpdates() : void
- Processes pending INSERTANS conversions for queued records
- fixText() : string
- Fixes old fieldname references
- savePendingInsertansUpdates() : mixed
- handleLegacyRankingAnswers() : mixed
- Handles the import of legacy ranking question answers as subquestions.
Functions
XMLImportGroup()
This function imports a LimeSurvey .lsg question group XML file
XMLImportGroup(string $sFullFilePath, int $iNewSID, bool $bTranslateLinksFields[, bool $supportArchivedFields = true ]) : mixed
Parameters
- $sFullFilePath : string
-
The full filepath of the uploaded file
- $iNewSID : int
-
The new survey ID - the page will always be added after the last page in the survey
- $bTranslateLinksFields : bool
- $supportArchivedFields : bool = true
-
whether we are looking for old fieldnames
XMLImportQuestion()
This function imports a LimeSurvey .lsq question XML file
XMLImportQuestion(string $sFullFilePath, int $iNewSID, $iNewGID[, array<string|int, bool> $options = array('autorename' => false, 'translinkfields' => true) ][, bool $supportArchivedFields = true ]) : array<string|int, mixed>
Parameters
- $sFullFilePath : string
-
The full filepath of the uploaded file
- $iNewSID : int
-
The new survey ID
- $iNewGID :
- $options : array<string|int, bool> = array('autorename' => false, 'translinkfields' => true)
- $supportArchivedFields : bool = true
-
whether we are looking for old fieldnames
Tags
Return values
array<string|int, mixed>XMLImportLabelsets()
XMLImportLabelsets() Function resp[onsible to import a labelset from XML format.
XMLImportLabelsets(string $sFullFilePath, mixed $options) : array<string|int, mixed>
Parameters
- $sFullFilePath : string
- $options : mixed
Return values
array<string|int, mixed> —Array with count of imported labelsets, labels, warning, etc.
finalizeSurveyImportFile()
finalizeSurveyImportFile(int|string $newsid, string|null $baselang) : mixed
Parameters
- $newsid : int|string
- $baselang : string|null
getTableArchivesAndTimestamps()
Returns the tables which
getTableArchivesAndTimestamps(int $sid) : array<string|int, mixed>
Parameters
- $sid : int
Return values
array<string|int, mixed>importSurveyFile()
Imports a survey file into the application by dispatching to the appropriate importer according to file extension.
importSurveyFile(string $sFullFilePath, bool $bTranslateLinksFields[, string|null $sNewSurveyName = null ][, int|null $DestSurveyID = null ][, string|null $baselang = null ][, string|null $targetSurveyGroup = null ]) : array<string|int, mixed>|null
Handles .lss (survey XML), .txt/.tsv (TSV template) and .lsa (LimeSurvey archive) files, performing post-import integrity fixes and optional base-language finalization. For .lsa archives, imports contained survey, responses, tokens and timings files when present.
Parameters
- $sFullFilePath : string
-
Path to the input file.
- $bTranslateLinksFields : bool
-
If true, translate link/insertans fields during import.
- $sNewSurveyName : string|null = null
-
Optional survey title to assign to the imported survey.
- $DestSurveyID : int|null = null
-
Optional desired destination survey ID.
- $baselang : string|null = null
-
Optional base language to set or ensure on the imported survey.
- $targetSurveyGroup : string|null = null
-
Optional target survey group strategy (e.g., 'from_survey' to attempt using the source survey's group); when null defaults to standard group assignment.
Return values
array<string|int, mixed>|null —Result array containing counters, warnings and mappings (including 'newsid' on success), or null for unsupported file extensions.
createTableFromPattern()
Creates a table based on another
createTableFromPattern(string $table, string $pattern[, array<string|int, mixed> $columns = [] ][, array<string|int, mixed> $where = [] ]) : int
Parameters
- $table : string
- $pattern : string
- $columns : array<string|int, mixed> = []
- $where : array<string|int, mixed> = []
Tags
Return values
int —number of rows affected by the execution.
polyfillSUBSTRING_INDEX()
polyfillSUBSTRING_INDEX(mixed $driver) : mixed
Parameters
- $driver : mixed
generateTemporaryTableCreate()
Generates a temporary table creation script
generateTemporaryTableCreate(string $source, string $destination, int $sid) : string
Parameters
- $source : string
- $destination : string
- $sid : int
Return values
stringgenerateTemporaryTableDrop()
Generates a drop statement for a temporary table
generateTemporaryTableDrop(string $name, int $sid) : string
Parameters
- $name : string
- $sid : int
Return values
stringgetUnchangedColumns()
Gets the unchanged columns
getUnchangedColumns(int $sid, int $sTimestamp, int $qTimestamp) : array<string|int, mixed>
Parameters
- $sid : int
- $sTimestamp : int
- $qTimestamp : int
Tags
Return values
array<string|int, mixed> —all rows of the query result. Each array element is an array representing a row. An empty array is returned if the query results in nothing.
generateTemporaryTableCreates()
Generates temporary table creation scripts from the arrays received and returns the scripts that were generated, we expect count($sourceTables) and count($destinationTables) to be the same
generateTemporaryTableCreates(array<string|int, mixed> $sourceTables, array<string|int, mixed> $destinationTables, int $sid) : array<string|int, mixed>
Parameters
- $sourceTables : array<string|int, mixed>
- $destinationTables : array<string|int, mixed>
- $sid : int
Return values
array<string|int, mixed>generateTemporaryTableDrops()
Generates temporary table drops for the tables received and returns the scripts
generateTemporaryTableDrops(array<string|int, mixed> $tables, int $sid) : array<string|int, mixed>
Parameters
- $tables : array<string|int, mixed>
- $sid : int
Return values
array<string|int, mixed>getDeactivatedArchives()
Finds the newest archive table from each kind
getDeactivatedArchives(int $sid) : array<string|int, mixed>
Parameters
- $sid : int
Tags
Return values
array<string|int, mixed> —all rows of the query result. Each array element is an array representing a row. An empty array is returned if the query results in nothing.
copyFromOneTableToTheOther()
Copying all data from source table to a target table having the same structure
copyFromOneTableToTheOther(string $source, string $destination[, bool $preserveIDs = false ]) : int
Parameters
- $source : string
- $destination : string
- $preserveIDs : bool = false
Tags
Return values
int —number of rows affected by the execution.
recoverSurveyResponses()
Recovers archived survey responses
recoverSurveyResponses(int $surveyId, string $archivedResponseTableName, bool $preserveIDs[, array<string|int, mixed> $validatedColumns = [] ]) : int
Parameters
- $surveyId : int
-
survey ID
- $archivedResponseTableName : string
-
archived response table name to be imported
- $preserveIDs : bool
-
if archived response IDs should be preserved
- $validatedColumns : array<string|int, mixed> = []
-
the columns that are validated and can be inserted again
Tags
Return values
int —number of rows affected by the execution.
XMLImportSurvey()
Import a LimeSurvey survey from an XML file or XML string into the database.
XMLImportSurvey(string $sFullFilePath[, string|null $sXMLdata = null ][, string|null $sNewSurveyName = null ][, int|null $iDesiredSurveyId = null ][, bool $bTranslateInsertansTags = true ][, bool $bConvertInvalidQuestionCodes = true ][, string|null $targetSurveyGroup = null ][, bool $supportArchivedFields = true ]) : array<string|int, mixed>
Processes the provided LimeSurvey Survey XML and inserts survey metadata, languages, groups, questions (main and subquestions), answers, attributes, quotas, conditions, themes, plugin settings, and other related records while remapping IDs and translating legacy field values as needed.
Parameters
- $sFullFilePath : string
-
Path to the XML file; optional when $sXMLdata is provided.
- $sXMLdata : string|null = null
-
XML data string to import; optional when $sFullFilePath is provided.
- $sNewSurveyName : string|null = null
-
If provided, the survey is treated as a copy and this name is applied.
- $iDesiredSurveyId : int|null = null
-
Desired numeric survey ID to assign to the new survey (may be ignored if in use).
- $bTranslateInsertansTags : bool = true
-
When true, embedded insertans/link fields in text are translated to the new survey.
- $bConvertInvalidQuestionCodes : bool = true
-
When true, invalid or colliding question codes are adjusted to valid unique codes.
- $targetSurveyGroup : string|null = null
-
Controls assignment of the imported survey to a survey group when not copying; supported value 'from_survey' attempts to reuse the original survey group when accessible.
- $supportArchivedFields : bool = true
-
whether we are looking for old fieldnames
Tags
Return values
array<string|int, mixed> —An associative result array containing import counters and metadata, including:
- 'error' (string) on failure,
- 'newsid' (int) the new survey id,
- 'oldsid' (int) the original survey id from the XML,
- counters for imported entities (questions, groups, answers, etc.),
- 'importwarnings' (array) warnings produced during import,
- additional maps such as 'FieldReMap' when applicable.
checkWrongQuestionAttributes()
This function checks if there are set wrong values ('Y' or 'N') into table question_attributes. These are set to 1 and 0 if needed.
checkWrongQuestionAttributes( $questionId) : mixed
Parameters
XMLImportTokens()
XMLImportTokens(string $sFullFilePath, mixed $iSurveyID[, mixed $sCreateMissingAttributeFields = true ]) : mixed
Parameters
- $sFullFilePath : string
- $iSurveyID : mixed
- $sCreateMissingAttributeFields : mixed = true
XMLImportResponses()
XMLImportResponses(string $sFullFilePath, mixed $iSurveyID[, mixed $aFieldReMap = array() ]) : mixed
Parameters
- $sFullFilePath : string
- $iSurveyID : mixed
- $aFieldReMap : mixed = array()
CSVImportResponses()
This function imports a CSV file into the response table CSV file is deleted during process
CSVImportResponses(string $sFullFilePath, int $iSurveyId[, array<string|int, mixed> $aOptions = array() ]) : mixed
Parameters
- $sFullFilePath : string
- $iSurveyId : int
- $aOptions : array<string|int, mixed> = array()
-
Return array $result ("errors","warnings","success")
XMLImportTimings()
XMLImportTimings(string $sFullFilePath, mixed $iSurveyID[, mixed $aFieldReMap = array() ]) : mixed
Parameters
- $sFullFilePath : string
- $iSurveyID : mixed
- $aFieldReMap : mixed = array()
TSVImportSurvey()
Import survey from an TSV file template that does not require assigning of GID or QID values.
TSVImportSurvey(string $sFullFilePath) : string
If ID's are presented, they would be respected and used Multilanguage imports are supported Original function is changed to allow generating of XML instead of creating database objects directly Generated XML code is send to existing lss import function
Parameters
- $sFullFilePath : string
Tags
Return values
string —XML data
createXMLfromData()
createXMLfromData([mixed $aData = array() ]) : mixed
Parameters
- $aData : mixed = array()
importDefaultValues()
Import default values inside $xml, record process in $results Also imports defaultvalue_l10ns.
importDefaultValues(SimpleXMLElement $xml, array<string|int, mixed> $aLanguagesSupported, mixed $aQIDReplacements, array<string|int, mixed> &$results[, mixed $allImportedQuestions = [] ][, mixed $newOldQidMapping = [] ][, mixed $oldNewFieldRoots = [] ]) : void
Parameters
- $xml : SimpleXMLElement
- $aLanguagesSupported : array<string|int, mixed>
- $aQIDReplacements : mixed
- $results : array<string|int, mixed>
- $allImportedQuestions : mixed = []
- $newOldQidMapping : mixed = []
- $oldNewFieldRoots : mixed = []
fileCsvToUtf8()
Read a csv file and return a tmp resources to same file in utf8 CSV file is deleted during process
fileCsvToUtf8(string $fullfilepath[, string $encoding = 'auto' ]) : resource
Parameters
- $fullfilepath : string
- $encoding : string = 'auto'
-
from
Return values
resourcegetInsertansSignature()
Generates the INSERTANS conversion queue signature for a model
getInsertansSignature(string $modelClass, mixed $model) : array<string|int, mixed>|null
Different models have different primary key structures:
- QuestionL10n: ['id' => id, 'language' => language]
- SurveyLanguageSetting: ['surveyls_survey_id' => sid, 'surveyls_language' => language]
Parameters
- $modelClass : string
-
The model class name
- $model : mixed
-
The model instance or data
Return values
array<string|int, mixed>|null —The queue signature or null if model type not supported
processPendingInsertansUpdates()
Processes pending INSERTANS conversions for queued records
processPendingInsertansUpdates(array<string|int, mixed> &$pendingInsertansUpdates, array<string|int, mixed> $allImportedQuestions, array<string|int, mixed> $surveyQidMap[, array<string|int, mixed> $oldNewFieldRoot = [] ]) : void
This function handles the batch processing of INSERTANS tag conversions that need to be deferred until all question IDs are mapped.
Parameters
- $pendingInsertansUpdates : array<string|int, mixed>
-
Array of records with INSERTANS tags to convert
- $allImportedQuestions : array<string|int, mixed>
-
The cached imported questions
- $surveyQidMap : array<string|int, mixed>
-
Map of old question IDs to new question IDs
- $oldNewFieldRoot : array<string|int, mixed> = []
-
Mapping between old and new representations of deprecated fieldname roots
fixText()
Fixes old fieldname references
fixText(mixed $convertedValue, mixed $allImportedQuestions, mixed $oldNewFieldRoot) : string
Parameters
- $convertedValue : mixed
-
the input
- $allImportedQuestions : mixed
-
the cached questions
- $oldNewFieldRoot : mixed
-
the old and new fieldname mappings in the old format
Return values
string —the result
savePendingInsertansUpdates()
savePendingInsertansUpdates(mixed $pendingInsertansUpdates) : mixed
Parameters
- $pendingInsertansUpdates : mixed
handleLegacyRankingAnswers()
Handles the import of legacy ranking question answers as subquestions.
handleLegacyRankingAnswers(SimpleXMLElement &$xml, array<string|int, mixed> &$raids, array<string|int, mixed> $questionTypeMap, int $iNewSID, int $iGID, array<string|int, mixed> $aQIDReplacements[, array<string|int, mixed> $oldQIDGIDMap = [] ]) : mixed
Processes the 'answers' and 'answer_l10ns' sections of the XML for ranking questions, injecting new rows into the 'subquestions' and 'question_l10ns' XML sections so they are handled naturally by the existing import loops downstream.
For each ranking answer found:
- A new subquestions XML row is injected using the old answer ID (aid) as a qid placeholder, which allows the subquestions import loop to assign a real qid and register it in $aQIDReplacements.
- Corresponding question_l10ns XML rows are injected using the same aid placeholder as qid, which allows the question_l10ns import loop to remap them correctly via $aQIDReplacements.
In legacy XML formats that do not include an 'aid' field in the answers section (e.g. older .lss exports), a unique negative surrogate key is generated for each answer row so that every injected subquestion row gets a distinct placeholder qid. This prevents the subquestions import loop from treating all injected rows as the same question and saving only the first one.
Parameters
- $xml : SimpleXMLElement
-
The XML data containing answers and localizations (passed by reference so injected rows are visible to callers)
- $raids : array<string|int, mixed>
-
Reference to store mapping of old answer IDs to ['old_parent_qid' => int, 'code' => string], used by the caller to skip ranking answers in the regular answer_l10ns import loop
- $questionTypeMap : array<string|int, mixed>
-
Mapping of new question IDs to their types
- $iNewSID : int
-
The new survey ID
- $iGID : int
-
The group ID to inject into subquestion rows. Pass the old gid when the caller's subquestions loop remaps via $aGIDReplacements (XMLImportGroup), or the new gid when the caller sets it directly (XMLImportQuestion). Ignored when $oldQIDGIDMap is provided (survey import uses per-question gid).
- $aQIDReplacements : array<string|int, mixed>
-
Mapping of old question IDs to new question IDs
- $oldQIDGIDMap : array<string|int, mixed> = []
-
Optional mapping of old question IDs to their old group IDs. When provided each injected subquestion row uses the question's own old gid instead of the single $iGID value, which is required for survey-level import where questions across multiple groups are processed in one pass.