Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]

(no description)

Copyright: 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 1913 lines (97 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 2 classes


Class: restore_dbops  - X-Ref

Base abstract class for all the helper classes providing DB operations

TODO: Finish phpdocs
get_included_tasks($restoreid)   X-Ref
Return one array containing all the tasks that have been included
in the restore process. Note that these tasks aren't built (they
haven't steps nor ids data available)


load_inforef_to_tempids($restoreid, $inforeffile,\core\progress\base $progress = null)   X-Ref
Load one inforef.xml file to backup_ids table for future reference

param: string $restoreid Restore id
param: string $inforeffile File path
param: \core\progress\base $progress Progress tracker

load_roles_to_tempids($restoreid, $rolesfile)   X-Ref
Load the needed role.xml file to backup_ids table for future reference


precheck_included_roles($restoreid, $courseid, $userid, $samesite, $rolemappings)   X-Ref
Precheck the loaded roles, return empty array if everything is ok, and
array with 'errors', 'warnings' elements (suitable to be used by restore_prechecks)
with any problem found. At the same time, store all the mapping into backup_ids_temp
and also put the information into $rolemappings (controller->info), so it can be reworked later by
post-precheck stages while at the same time accept modified info in the same object coming from UI


get_backup_ids_cached($restoreid, $itemname, $itemid)   X-Ref
Return cached backup id's

param: int $restoreid id of backup
param: string $itemname name of the item
param: int $itemid id of item
return: array backup id's

set_backup_ids_cached($restoreid, $itemname, $itemid, $extrarecord)   X-Ref
Cache backup ids'

param: int $restoreid id of backup
param: string $itemname name of the item
param: int $itemid id of item
param: array $extrarecord extra record which needs to be updated
return: void

update_backup_cached_record($record, $extrarecord, $key, $existingrecord = null)   X-Ref
Updates existing backup record

param: array $record record which needs to be updated
param: array $extrarecord extra record which needs to be updated
param: string $key unique key which is used to identify cached record
param: stdClass $existingrecord (optional) existing record

reset_backup_ids_cached()   X-Ref
Reset the ids caches completely

Any destructive operation (partial delete, truncate, drop or recreate) performed
with the backup_ids table must cause the backup_ids caches to be
invalidated by calling this method. See MDL-33630.

Note that right now, the only operation of that type is the recreation
(drop & restore) of the table that may happen once the prechecks have ended. All
the rest of operations are always routed via {@link set_backup_ids_record()}, 1 by 1,
keeping the caches on sync.


get_best_assignable_role($role, $courseid, $userid, $samesite)   X-Ref
Given one role, as loaded from XML, perform the best possible matching against the assignable
roles, using different fallback alternatives (shortname, archetype, editingteacher => teacher, defaultcourseroleid)
returning the id of the best matching role or 0 if no match is found


process_included_roles($restoreid, $courseid, $userid, $samesite, $rolemappings)   X-Ref
Process the loaded roles, looking for their best mapping or skipping
Any error will cause exception. Note this is one wrapper over
precheck_included_roles, that contains all the logic, but returns
errors/warnings instead and is executed as part of the restore prechecks


load_users_to_tempids($restoreid, $usersfile,\core\progress\base $progress = null)   X-Ref
Load the needed users.xml file to backup_ids table for future reference

param: string $restoreid Restore id
param: string $usersfile File path
param: \core\progress\base $progress Progress tracker

load_categories_and_questions_to_tempids($restoreid, $questionsfile)   X-Ref
Load the needed questions.xml file to backup_ids table for future reference


precheck_categories_and_questions($restoreid, $courseid, $userid, $samesite)   X-Ref
Check all the included categories and questions, deciding the action to perform
for each one (mapping / creation) and returning one array of problems in case
something is wrong.

There are some basic rules that the method below will always try to enforce:

Rule1: Targets will be, always, calculated for *whole* question banks (a.k.a. contexid source),
so, given 2 question categories belonging to the same bank, their target bank will be
always the same. If not, we can be incurring into "fragmentation", leading to random/cloze
problems (qtypes having "child" questions).

Rule2: The 'moodle/question:managecategory' and 'moodle/question:add' capabilities will be
checked before creating any category/question respectively and, if the cap is not allowed
into upper contexts (system, coursecat)) but in lower ones (course), the *whole* question bank
will be created there.

Rule3: Coursecat question banks not existing in the target site will be created as course
(lower ctx) question banks, never as "guessed" coursecat question banks base on depth or so.

Rule4: System question banks will be created at system context if user has perms to do so. Else they
will created as course (lower ctx) question banks (similary to rule3). In other words, course ctx
if always a fallback for system and coursecat question banks.

Also, there are some notes to clarify the scope of this method:

Note1: This method won't create any question category nor question at all. It simply will calculate
which actions (create/map) must be performed for each element and where, validating that all those
actions are doable by the user executing the restore operation. Any problem found will be
returned in the problems array, causing the restore process to stop with error.

Note2: To decide if one question bank (all its question categories and questions) is going to be remapped,
then all the categories and questions must exist in the same target bank. If able to do so, missing
qcats and qs will be created (rule2). But if, at the end, something is missing, the whole question bank
will be recreated at course ctx (rule1), no matter if that duplicates some categories/questions.

Note3: We'll be using the newitemid column in the temp_ids table to store the action to be performed
with each question category and question. newitemid = 0 means the qcat/q needs to be created and
any other value means the qcat/q is mapped. Also, for qcats, parentitemid will contain the target
context where the categories have to be created (but for module contexts where we'll keep the old
one until the activity is created)

Note4: All these "actions" will be "executed" later by {@link restore_create_categories_and_questions}

prechek_precheck_qbanks_by_level($restoreid, $courseid, $userid, $samesite, $contextlevel)   X-Ref
This function will process all the question banks present in restore
at some contextlevel (from CONTEXT_SYSTEM to CONTEXT_MODULE), finding
the target contexts where each bank will be restored and returning
warnings/errors as needed.

Some contextlevels (system, coursecat), will delegate process to
course level if any problem is found (lack of permissions, non-matching
target context...). Other contextlevels (course, module) will
cause return error if some problem is found.

At the end, if no errors were found, all the categories in backup_temp_ids
will be pointing (parentitemid) to the target context where they must be
created later in the restore process.

Note: at the time these prechecks are executed, activities haven't been
created yet so, for CONTEXT_MODULE banks, we keep the old contextid
in the parentitemid field. Once the activity (and its context) has been
created, we'll update that context in the required qcats

Caller {@link precheck_categories_and_questions} will, simply, execute
this function for all the contextlevels, acting as a simple controller
of warnings and errors.

The function returns 2 arrays, one containing errors and another containing
warnings. Both empty if no errors/warnings are found.

param: int $restoreid The restore ID
param: int $courseid The ID of the course
param: int $userid The id of the user doing the restore
param: bool $samesite True if restore is to same site
param: int $contextlevel (CONTEXT_SYSTEM, etc.)
return: array A separate list of all error and warnings detected

restore_get_question_banks($restoreid, $contextlevel = null)   X-Ref
Return one array of contextid => contextlevel pairs
of question banks to be checked for one given restore operation
ordered from CONTEXT_SYSTEM downto CONTEXT_MODULE
If contextlevel is specified, then only banks corresponding to
that level are returned


restore_get_question_categories($restoreid, $contextid, $contextlevel)   X-Ref
Return one array of question_category records for
a given restore operation and one restore context (question bank)

param: string $restoreid Unique identifier of the restore operation being performed.
param: int $contextid Context id we want question categories to be returned.
param: int $contextlevel Context level we want to restrict the returned categories.
return: array Question categories for the given context id and level.

restore_find_best_target_context($categories, $courseid, $contextlevel)   X-Ref
Calculates the best context found to restore one collection of qcats,
al them belonging to the same context (question bank), returning the
target context found (object) or false


restore_get_questions($restoreid, $qcatid)   X-Ref
Return one array of question records for
a given restore operation and one question category


send_files_to_pool($basepath, $restoreid, $component, $filearea,$oldcontextid, $dfltuserid, $itemname = null, $olditemid = null,$forcenewcontextid = null, $skipparentitemidctxmatch = false,\core\progress\base $progress = null)   X-Ref
Given one component/filearea/context and
optionally one source itemname to match itemids
put the corresponding files in the pool

If you specify a progress reporter, it will get called once per file with
indeterminate progress.

param: string $basepath the full path to the root of unzipped backup file
param: string $restoreid the restore job's identification
param: string $component
param: string $filearea
param: int $oldcontextid
param: int $dfltuserid default $file->user if the old one can't be mapped
param: string|null $itemname
param: int|null $olditemid
param: int|null $forcenewcontextid explicit value for the new contextid (skip mapping)
param: bool $skipparentitemidctxmatch
param: \core\progress\base $progress Optional progress reporter
return: array of result object

get_missing_file_result($file)   X-Ref
Returns suitable entry to include in log when there is a missing file.

param: stdClass $file File definition
return: stdClass Log entry

create_included_users($basepath, $restoreid, $userid,\core\progress\base $progress)   X-Ref
Given one restoreid, create in DB all the users present
in backup_ids having newitemid = 0, as far as
precheck_included_users() have left them there
ready to be created. Also, annotate their newids
once created for later reference.

This function will start and end a new progress section in the progress
object.

param: string $basepath Base path of unzipped backup
param: string $restoreid Restore ID
param: int $userid Default userid for files
param: \core\progress\base $progress Object used for progress tracking

precheck_user($user, $samesite, $siteid = null)   X-Ref
Given one user object (from backup file), perform all the neccesary
checks is order to decide how that user will be handled on restore.

Note the function requires $user->mnethostid to be already calculated
so it's caller responsibility to set it

This function is used both by @restore_precheck_users() and

precheck_included_users($restoreid, $courseid, $userid, $samesite,\core\progress\base $progress)   X-Ref
Check all the included users, deciding the action to perform
for each one (mapping / creation) and returning one array
of problems in case something is wrong (lack of permissions,
conficts)

param: string $restoreid Restore id
param: int $courseid Course id
param: int $userid User id
param: bool $samesite True if restore is to same site
param: \core\progress\base $progress Progress reporter

process_included_users($restoreid, $courseid, $userid, $samesite,\core\progress\base $progress = null)   X-Ref
Process the needed users in order to decide
which action to perform with them (create/map)

Just wrap over precheck_included_users(), returning
exception if any problem is found

param: string $restoreid Restore id
param: int $courseid Course id
param: int $userid User id
param: bool $samesite True if restore is to same site
param: \core\progress\base $progress Optional progress tracker

process_categories_and_questions($restoreid, $courseid, $userid, $samesite)   X-Ref
Process the needed question categories and questions
to check all them, deciding about the action to perform
(create/map) and target.

Just wrap over precheck_categories_and_questions(), returning
exception if any problem is found

set_backup_files_record($restoreid, $filerec)   X-Ref
No description

set_backup_ids_record($restoreid, $itemname, $itemid, $newitemid = 0, $parentitemid = null, $info = null)   X-Ref
No description

get_backup_ids_record($restoreid, $itemname, $itemid)   X-Ref
No description

calculate_course_names($courseid, $fullname, $shortname)   X-Ref
Given on courseid, fullname and shortname, calculate the correct fullname/shortname to avoid dupes


set_course_role_names($restoreid, $courseid)   X-Ref
For the target course context, put as many custom role names as possible


create_new_course($fullname, $shortname, $categoryid)   X-Ref
Creates a skeleton record within the database using the passed parameters
and returns the new course id.

param: string $fullname
param: string $shortname
param: int $categoryid
return: int The new course id

delete_course_content($courseid, array $options = null)   X-Ref
Deletes all of the content associated with the given course (courseid)

param: int $courseid
param: array $options
return: bool True for success

Class: restore_dbops_exception  - X-Ref

__construct($errorcode, $a=NULL, $debuginfo=null)   X-Ref
No description