Moodle PHP Documentation 4.3
Moodle 4.3.5 (Build: 20240610) (7dcfaa79f78)
restore_controller Class Reference

Class implementing the controller of any restore process. More...

Inheritance diagram for restore_controller:
base_controller backup loggable checksumable

Public Member Functions

 __construct ($tempdir, $courseid, $interactive, $mode, $userid, $target, core\progress\base $progress=null, $releasesession=backup::RELEASESESSION_NO, ?\stdClass $copydata=null)
 Constructor.
 
 add_logger (base_logger $logger)
 Inserts a new logger at end of logging chain.
 
 calculate_checksum ()
 This function will return one unique and stable checksum for one instance of the class implementing it.
 
 convert ()
 Converts from current format to backup\MOODLE format.
 
 debug_display_all_settings_values ()
 For debug only.
 
 destroy ()
 Clean structures used by the restore_controller.
 
 execute_plan ()
 
 execute_precheck ($droptemptablesafter=false)
 Execute the restore prechecks to detect any problem before proceed with restore.
 
 finish_ui ()
 
 get_copy ()
 Get the course copy data.
 
 get_courseid ()
 
 get_execution ()
 
 get_executiontime ()
 
 get_format ()
 
 get_info ()
 
 get_interactive ()
 
 get_logger ()
 Gets first logger in logging chain.
 
 get_mode ()
 
 get_operation ()
 
 get_plan ()
 Returns the restore plan.
 
 get_precheck_results ()
 
 get_progress ()
 Gets the progress reporter, which can be used to report progress within the backup or restore process.
 
 get_releasesession ()
 Returns the set value of releasesession.
 
 get_restoreid ()
 
 get_results ()
 
 get_setting_value ($name, $default=false)
 Gets the value for the requested setting.
 
 get_status ()
 
 get_target ()
 
 get_tempdir ()
 
 get_type ()
 
 get_userid ()
 
 is_checksum_correct ($checksum)
 Given one checksum, returns if matches object's checksum (true) or no (false)
 
 is_samesite ()
 
 log ($message, $level, $a=null, $depth=null, $display=false)
 Logs data to the logger chain.
 
 precheck_executed ()
 Returns true if the prechecks have been executed.
 
 prepare_copy ()
 Do the necessary copy preparation actions.
 
 process_ui_event ()
 
 save_controller ($includeobj=true, $cleanobj=false)
 Save controller information.
 
 set_copy (\stdClass $data)
 Store extra data for course copy operations.
 
 set_execution ($execution, $executiontime=0)
 
 set_progress (\core\progress\base $progress)
 Sets the progress reporter.
 
 set_status ($status)
 

Static Public Member Functions

static get_tempdir_name ($courseid=0, $userid=0)
 class method to provide pseudo random unique "correct" tempdir names
 
static is_executing ()
 Checks whether restore is currently executing.
 
static load_controller ($restoreid)
 

Public Attributes

const CIPHER = 'aes-256-cbc'
 Cipher to be used in backup and restore operations.
 
const CIPHERKEYLEN = 32
 Bytes enforced for key, using the cypher above.
 
const ENROL_ALWAYS = 2
 
const ENROL_NEVER = 0
 
const ENROL_WITHUSERS = 1
 
const EXECUTION_DELAYED = 2
 
const EXECUTION_INMEDIATE = 1
 
const FORMAT_IMSCC1 = 'imscc1'
 
const FORMAT_IMSCC11 = 'imscc11'
 
const FORMAT_MOODLE = 'moodle2'
 
const FORMAT_MOODLE1 = 'moodle1'
 
const FORMAT_UNKNOWN = 'unknown'
 
const INTERACTIVE_NO = false
 
const INTERACTIVE_YES = true
 
const LOG_DEBUG = 50
 
const LOG_ERROR = 20
 
const LOG_INFO = 40
 
const LOG_NONE = 10
 
const LOG_WARNING = 30
 
const MODE_ASYNC = 70
 This mode is for asynchronous backups.
 
const MODE_AUTOMATED = 50
 
const MODE_CONVERTED = 60
 
const MODE_COPY = 80
 This mode is for course copies.
 
const MODE_GENERAL = 10
 
const MODE_HUB = 30
 
const MODE_IMPORT = 20
 This is used for importing courses, and for duplicating activities.
 
const MODE_SAMESITE = 40
 This mode is intended for duplicating courses and cases where the backup target is within the same site.
 
const OPERATION_BACKUP ='backup'
 
const OPERATION_RESTORE ='restore'
 
const RELEASE = '4.3'
 Usually same than major release zero version, mainly for informative/historic purposes.
 
const RELEASESESSION_NO = false
 Don't release the session during backup/restore.
 
const RELEASESESSION_YES = true
 Release the session during backup/restore.
 
const STATUS_AWAITING = 700
 
const STATUS_CONFIGURED = 400
 
const STATUS_CREATED = 100
 
const STATUS_EXECUTING = 800
 
const STATUS_FINISHED_ERR = 900
 
const STATUS_FINISHED_OK =1000
 
const STATUS_NEED_PRECHECK =600
 
const STATUS_PLANNED = 300
 
const STATUS_REQUIRE_CONV = 200
 
const STATUS_SETTING_UI = 500
 
const TARGET_CURRENT_ADDING = 1
 
const TARGET_CURRENT_DELETING = 0
 
const TARGET_EXISTING_ADDING = 4
 
const TARGET_EXISTING_DELETING = 3
 
const TARGET_NEW_COURSE = 2
 
const TYPE_1ACTIVITY = 'activity'
 
const TYPE_1COURSE = 'course'
 
const TYPE_1SECTION = 'section'
 
const VAR_ACTIVITYID = -21
 
const VAR_BACKUPID = -1001
 
const VAR_BASEPATH = -1011
 
const VAR_BLOCKID = -51
 
const VAR_BLOCKNAME = -61
 
const VAR_CONTEXTID = -71
 
const VAR_COURSEID = -1
 
const VAR_MODID = -31
 
const VAR_MODNAME = -41
 
const VAR_PARENTID = -81
 
const VAR_SECTIONID = -11
 
const VERSION = 2023100900
 Usually same than major release version, this is used to mark important point is backup when some behavior/approach channged, in order to allow conditional coding based on it.
 

Protected Member Functions

 apply_defaults ()
 Apply defaults from the global admin settings.
 
 calculate_restoreid ()
 
 load_plan ()
 

Protected Attributes

 $checksum
 
stdClass $copy
 Holds the relevant destination information for course copy operations.
 
 $courseid
 
integer $execution
 Immediate/delayed execution type.
 
 $executiontime
 
 $format
 
 $info
 
 $interactive
 
base_logger $logger
 Logging chain object (moodle, inline, fs, db, syslog)
 
 $mode
 
 $operation
 
restore_plan $plan
 
 $precheck
 
core progress base $progress
 Progress reporting object.
 
bool $releasesession = backup::RELEASESESSION_NO
 Whether this backup should release the session.
 
 $restoreid
 
 $samesite
 
 $status
 
 $target
 
 $tempdir
 
 $type
 
 $userid
 

Static Protected Attributes

static int $executing = 0
 Number of restore_controllers that are currently executing.
 

Detailed Description

Class implementing the controller of any restore process.

This final class is in charge of controlling all the restore architecture, for any type of backup.

TODO: Finish phpdocs

Constructor & Destructor Documentation

◆ __construct()

restore_controller::__construct ( $tempdir,
$courseid,
$interactive,
$mode,
$userid,
$target,
core\progress\base $progress = null,
$releasesession = backup::RELEASESESSION_NO,
?\stdClass $copydata = null )

Constructor.

If you specify a progress monitor, this will be used to report progress while loading the plan, as well as for future use. (You can change it for a different one later using set_progress.)

Parameters
string$tempdirDirectory under $CFG->backuptempdir awaiting restore
int$courseidCourse id where restore is going to happen
bool$interactivebackup\INTERACTIVE_YES[true] or backup\INTERACTIVE_NO[false]
int$modebackup\MODE_[ GENERAL | HUB | IMPORT | SAMESITE ]
int$userid
int$targetbackup\TARGET_[ NEW_COURSE | CURRENT_ADDING | CURRENT_DELETING | EXISTING_ADDING | EXISTING_DELETING ]
core\progress\base$progressOptional progress monitor
stdClass$copydataCourse copy data, required when in MODE_COPY
bool$releasesessionShould release the session? backup\RELEASESESSION_YES or backup\RELEASESESSION_NO

Member Function Documentation

◆ add_logger()

base_controller::add_logger ( base_logger $logger)
inherited

Inserts a new logger at end of logging chain.

Parameters
base_logger$loggerNew logger to add

◆ calculate_checksum()

restore_controller::calculate_checksum ( )

This function will return one unique and stable checksum for one instance of the class implementing it.

It's each implementation responsibility to do it recursively if needed and use optional store (caching) of the checksum if necessary/possible

Implements checksumable.

◆ debug_display_all_settings_values()

restore_controller::debug_display_all_settings_values ( )

For debug only.

Get a simple test display of all the settings.

Return values
string

◆ destroy()

restore_controller::destroy ( )

Clean structures used by the restore_controller.

This method clean various structures used by the restore_controller, destroying them in an ordered way, so their memory will be gc properly by PHP (mainly circular references).

Note that, while it's not mandatory to execute this method, it's highly recommended to do so, specially in scripts performing multiple operations (like the automated backups) or the system will run out of memory after a few dozens of backups)

◆ execute_precheck()

restore_controller::execute_precheck ( $droptemptablesafter = false)

Execute the restore prechecks to detect any problem before proceed with restore.

This function checks various parts of the restore (versions, users, roles...) returning true if everything was ok or false if any warning/error was detected. Any warning/error is returned by the get_precheck_results() method. Note: if any problem is found it will, automatically, drop all the restore temp tables as far as the next step is to inform about the warning/errors. If no problem is found, then default behaviour is to keep the temp tables so, in the same request restore will be executed, saving a lot of checks to be executed again. Note: If for any reason (UI to show after prechecks...) you want to force temp tables to be dropped always, you can pass true to the $droptemptablesafter parameter

◆ get_copy()

restore_controller::get_copy ( )

Get the course copy data.

Return values
stdClass

Reimplemented from base_controller.

◆ get_logger()

base_controller::get_logger ( )
inherited

Gets first logger in logging chain.

Return values
base_loggerLogger

◆ get_plan()

restore_controller::get_plan ( )

Returns the restore plan.

Return values
restore_plan

◆ get_progress()

base_controller::get_progress ( )
inherited

Gets the progress reporter, which can be used to report progress within the backup or restore process.

Return values
core\progress\baseProgress reporting object

◆ get_releasesession()

base_controller::get_releasesession ( )
inherited

Returns the set value of releasesession.

This is used to indicate if the session should be closed during the backup/restore.

Return values
boolIndicates whether the session should be released.

◆ get_setting_value()

restore_controller::get_setting_value ( $name,
$default = false )

Gets the value for the requested setting.

Parameters
string$name
bool$default
Return values
mixed

◆ is_checksum_correct()

restore_controller::is_checksum_correct ( $checksum)

Given one checksum, returns if matches object's checksum (true) or no (false)

Implements checksumable.

◆ is_executing()

static restore_controller::is_executing ( )
static

Checks whether restore is currently executing.

Certain parts of code that is called during restore, but not directly part of the restore system, may need to behave differently during restore (e.g. do not bother resetting a cache because we know it will be reset at end of operation).

Return values
boolTrue if any restore is currently executing

◆ log()

base_controller::log ( $message,
$level,
$a = null,
$depth = null,
$display = false )
inherited

Logs data to the logger chain.

See also
loggable\log()

Implements loggable.

◆ precheck_executed()

restore_controller::precheck_executed ( )

Returns true if the prechecks have been executed.

Return values
bool

◆ prepare_copy()

restore_controller::prepare_copy ( )

Do the necessary copy preparation actions.

This method should only be called once the backup of a copy operation is completed.

Exceptions
restore_controller_exception

◆ save_controller()

restore_controller::save_controller ( $includeobj = true,
$cleanobj = false )

Save controller information.

Parameters
bool$includeobjto decide if the object itself must be updated (true) or no (false)
bool$cleanobjto decide if the object itself must be cleaned (true) or no (false)

◆ set_copy()

base_controller::set_copy ( \stdClass $data)
inherited

Store extra data for course copy operations.

For a course copying these is data required to be passed to the restore step. We store this data in its own section of the backup controller

Parameters
stdClass$dataThe course copy data.
Exceptions
backup_controller_exception
Deprecated
since Moodle 4.1 MDL-74548 - please do not use this method anymore.
Todo
MDL-75025 This method will be deleted in Moodle 4.5
See also
restore_controller\__construct()

◆ set_progress()

base_controller::set_progress ( \core\progress\base $progress)
inherited

Sets the progress reporter.

Parameters
core\progress\base$progressProgress reporting object

Member Data Documentation

◆ CIPHERKEYLEN

const backup::CIPHERKEYLEN = 32
inherited

Bytes enforced for key, using the cypher above.

Restrictive? Yes, but better than unsafe lengths

◆ MODE_ASYNC

const backup::MODE_ASYNC = 70
inherited

This mode is for asynchronous backups.

These backups will run via adhoc scheduled tasks.

◆ MODE_COPY

const backup::MODE_COPY = 80
inherited

This mode is for course copies.

It is similar to async, but identifies back up and restore tasks as course copies.

These copies will run via adhoc scheduled tasks.

◆ MODE_IMPORT

const backup::MODE_IMPORT = 20
inherited

This is used for importing courses, and for duplicating activities.

This mode will ensure that files are not included in the backup generation, and during a restore they are copied from the existing file record.

◆ MODE_SAMESITE

const backup::MODE_SAMESITE = 40
inherited

This mode is intended for duplicating courses and cases where the backup target is within the same site.

This mode will ensure that files are not included in the backup generation, and during a restore they are copied from the existing file record.

For creating a backup for archival purposes or greater longevity, use MODE_GENERAL.


The documentation for this class was generated from the following file: