Moodle PHP Documentation 4.2
Moodle 4.2.8 (Build: 20240610) (2d41ac46f45)
backup_controller Class Reference

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

Inheritance diagram for backup_controller:
base_controller backup loggable checksumable

Public Member Functions

 __construct ($type, $id, $format, $interactive, $mode, $userid, $releasesession=backup::RELEASESESSION_NO)
 Constructor for the backup controller class.
 
 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.
 
 debug_display_all_settings_values ()
 For debug only.
 
 destroy ()
 Clean structures used by the backup_controller.
 
 execute_plan ()
 Executes the backup.
 
 finish_ui ()
 Declare that all user interaction with the backup controller is complete.
 
 get_backupid ()
 Gets the unique identifier for this backup controller.
 
 get_copy ()
 Get the course copy data.
 
 get_courseid ()
 Gets the course that the item being backed up is in.
 
 get_execution ()
 Get if the backup will be executed immediately, or later.
 
 get_executiontime ()
 Get when the backup will be executed.
 
 get_format ()
 Gets the format the backup is stored in.
 
 get_id ()
 Gets the instance id of the item being backed up.
 
 get_include_files ()
 Returns the current value of the include_files setting.
 
 get_interactive ()
 Gets if user interaction is expected during the backup.
 
 get_logger ()
 Gets first logger in logging chain.
 
 get_mode ()
 Gets the mode that the backup will be performed in.
 
 get_operation ()
 Gets if this is a backup or restore.
 
 get_plan ()
 Gets the plan that will be run during the backup.
 
 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_results ()
 Gets the results of the plan execution for this backup.
 
 get_status ()
 Get the current status of the backup.
 
 get_type ()
 Gets the type of backup to be performed.
 
 get_userid ()
 Get the id of the user who started the backup.
 
 is_checksum_correct ($checksum)
 Given one checksum, returns if matches object's checksum (true) or no (false)
 
 log ($message, $level, $a=null, $depth=null, $display=false)
 Logs data to the logger chain.
 
 process_ui_event ()
 Validates the backup is valid after any user changes.
 
 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)
 Sets if the backup will be processed immediately, or later.
 
 set_kept_roles (array $roleids)
 Sets the user roles that should be kept in the destination course for a course copy operation.
 
 set_progress (\core\progress\base $progress)
 Sets the progress reporter.
 
 set_status ($status)
 Sets the new status of the backup.
 

Static Public Member Functions

static load_controller ($backupid)
 Loads a backup controller from the database.
 

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.2'
 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 = 2023042400
 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 ()
 Sets default values for the backup controller.
 
 calculate_backupid ()
 Creates a unique id for this backup.
 
 get_include_files_default ()
 Returns the default value for $this->includefiles before we consider any settings.
 
 load_plan ()
 Builds the plan for this backup job so that it may be executed.
 
 set_include_files (bool $includefiles)
 Set the initial value for the include_files setting.
 

Protected Attributes

string $backupid
 Unique identifier for this backup.
 
string $checksum
 Cache {.
 
stdClass $copy
 Holds the relevant destination information for course copy operations.
 
false int $courseid
 The id of the course the backup belongs to, or false if no course.
 
null $destination
 Destination chain object (fs_moodle, fs_os, db, email...).
 
int $execution
 Immediate/delayed execution type.
 
int $executiontime
 Epoch time when we want the backup to be executed (requires cron to run).
 
string $format
 Format of backup (moodle, imscc).
 
int $id
 Course/section/course_module id to backup.
 
int $includefiles
 Whether this backup includes files (1) or not (0).
 
bool $interactive
 Whether this backup will require user interaction.
 
array $keptroles = array()
 The role ids to keep in a copy operation.
 
base_logger $logger
 Logging chain object (moodle, inline, fs, db, syslog)
 
int $mode
 Purpose of the backup (default settings)
 
string $operation
 Type of operation (backup/restore)
 
backup_plan $plan
 Backup execution plan.
 
core progress base $progress
 Progress reporting object.
 
bool $releasesession = backup::RELEASESESSION_NO
 Whether this backup should release the session.
 
int $status
 Current status of the controller (created, planned, configured...)
 
string $type
 Type of item that is being stored in the backup.
 
int $userid
 The id of the user executing the backup.
 

Detailed Description

Class implementing the controller of any backup process.

This final class is in charge of controlling all the backup architecture, for any type of backup. Based in type, format, interactivity and target, it stores the whole execution plan and settings that will be used later by the @backup_worker, applies all the defaults, performs all the security contraints and is in charge of handling the ui if necessary. Also logging strategy is defined here.

Note the class is 100% neutral and usable for any backup. It just stores/requests all the needed information from other backup classes in order to have everything well structured in order to allow the @backup_worker classes to do their job.

In other words, a mammoth class, but don't worry, practically everything is delegated/ aggregated!)

Constructor & Destructor Documentation

◆ __construct()

backup_controller::__construct ( $type,
$id,
$format,
$interactive,
$mode,
$userid,
$releasesession = backup::RELEASESESSION_NO )

Constructor for the backup controller class.

Parameters
string$typeType of the backup; One of backup\TYPE_1COURSE, TYPE_1SECTION, TYPE_1ACTIVITY
int$idThe ID of the item to backup; e.g the course id
string$formatThe backup format to use; Most likely backup\FORMAT_MOODLE
bool$interactiveWhether this backup will require user interaction; backup\INTERACTIVE_YES or INTERACTIVE_NO
int$modeOne of backup\MODE_GENERAL, MODE_IMPORT, MODE_SAMESITE, MODE_HUB, MODE_AUTOMATED
int$useridThe id of the user making the backup
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()

backup_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()

backup_controller::debug_display_all_settings_values ( )

For debug only.

Get a simple test display of all the settings.

Return values
string

◆ destroy()

backup_controller::destroy ( )

Clean structures used by the backup_controller.

This method clean various structures used by the backup_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_plan()

backup_controller::execute_plan ( )

Executes the backup.

Return values
voidThrows and exception of completes

◆ finish_ui()

backup_controller::finish_ui ( )

Declare that all user interaction with the backup controller is complete.

After this the backup controller is waiting for processing.

◆ get_backupid()

backup_controller::get_backupid ( )

Gets the unique identifier for this backup controller.

Return values
string

◆ get_copy()

base_controller::get_copy ( )
inherited

Get the course copy data.

Return values
stdClass
Deprecated
since Moodle 4.1 MDL-74548 - please do not use this method anymore.
Todo
MDL-75026 This method will be deleted in Moodle 4.5
See also
restore_controller\get_copy()

Reimplemented in restore_controller.

◆ get_courseid()

backup_controller::get_courseid ( )

Gets the course that the item being backed up is in.

Return values
false|int

◆ get_execution()

backup_controller::get_execution ( )

Get if the backup will be executed immediately, or later.

Return values
int

◆ get_executiontime()

backup_controller::get_executiontime ( )

Get when the backup will be executed.

Return values
int0 means now, otherwise a Unix timestamp

◆ get_format()

backup_controller::get_format ( )

Gets the format the backup is stored in.

Return values
string

◆ get_id()

backup_controller::get_id ( )

Gets the instance id of the item being backed up.

It's meaning is related to the type of backup {

See also
backup_controller\get_type()}.
Return values
int

◆ get_include_files()

backup_controller::get_include_files ( )

Returns the current value of the include_files setting.

This setting is intended to ensure that files are not included in generated backups.

Return values
intIndicates whether files should be included in backups.

◆ get_include_files_default()

backup_controller::get_include_files_default ( )
protected

Returns the default value for $this->includefiles before we consider any settings.

Return values
bool
Exceptions
dml_exception

◆ get_interactive()

backup_controller::get_interactive ( )

Gets if user interaction is expected during the backup.

Return values
bool

◆ get_logger()

base_controller::get_logger ( )
inherited

Gets first logger in logging chain.

Return values
base_loggerLogger

◆ get_mode()

backup_controller::get_mode ( )

Gets the mode that the backup will be performed in.

Return values
int

◆ get_operation()

backup_controller::get_operation ( )

Gets if this is a backup or restore.

Return values
string

◆ get_plan()

backup_controller::get_plan ( )

Gets the plan that will be run during the backup.

Return values
backup_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_results()

backup_controller::get_results ( )

Gets the results of the plan execution for this backup.

Return values
array

◆ get_status()

backup_controller::get_status ( )

Get the current status of the backup.

Return values
int

◆ get_type()

backup_controller::get_type ( )

Gets the type of backup to be performed.

Use {

See also
backup_controller\get_id()} to find the instance being backed up.
Return values
string

◆ get_userid()

backup_controller::get_userid ( )

Get the id of the user who started the backup.

Return values
int

◆ is_checksum_correct()

backup_controller::is_checksum_correct ( $checksum)

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

Implements checksumable.

◆ load_controller()

static backup_controller::load_controller ( $backupid)
static

Loads a backup controller from the database.

Parameters
string$backupidThe id of the backup controller.
Return values
backup_controller

◆ 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.

◆ process_ui_event()

backup_controller::process_ui_event ( )

Validates the backup is valid after any user changes.

A backup_controller_exception will be thrown if there is an issue.

◆ save_controller()

backup_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_execution()

backup_controller::set_execution ( $execution,
$executiontime = 0 )

Sets if the backup will be processed immediately, or later.

Parameters
int$executionUse backup\EXECUTION_INMEDIATE or backup\EXECUTION_DELAYED
int$executiontimeThe timestamp in the future when the task should be executed, or 0 for immediately.

◆ set_include_files()

backup_controller::set_include_files ( bool $includefiles)
protected

Set the initial value for the include_files setting.

Parameters
bool$includefiles
See also
backup_controller\get_include_files for further information on the purpose of this setting.

◆ set_kept_roles()

backup_controller::set_kept_roles ( array $roleids)

Sets the user roles that should be kept in the destination course for a course copy operation.

Parameters
array$roleids
Exceptions
backup_controller_exception

◆ set_progress()

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

Sets the progress reporter.

Parameters
core\progress\base$progressProgress reporting object

◆ set_status()

backup_controller::set_status ( $status)

Sets the new status of the backup.

Parameters
int$status

Member Data Documentation

◆ $checksum

string backup_controller::$checksum
protected

Cache {.

See also
checksumable} results for lighter {
backup_controller\is_checksum_correct()} uses.

◆ $format

string backup_controller::$format
protected

Format of backup (moodle, imscc).

Should be one of the backup\FORMAT_ constants. for example backup\FORMAT_MOODLE

◆ $interactive

bool backup_controller::$interactive
protected

Whether this backup will require user interaction.

Should be one of backup\INTERACTIVE_YES or INTERACTIVE_NO

◆ $mode

int backup_controller::$mode
protected

Purpose of the backup (default settings)

Should be one of the the backup\MODE_ constants, for example backup\MODE_GENERAL

◆ $operation

string backup_controller::$operation
protected

Type of operation (backup/restore)

Should be selected from: backup\OPERATION_BACKUP or OPERATION_RESTORE

◆ $status

int backup_controller::$status
protected

Current status of the controller (created, planned, configured...)

It should be one of the backup\STATUS_ constants, for example backup\STATUS_AWAITING.

◆ $type

string backup_controller::$type
protected

Type of item that is being stored in the backup.

Should be selected from one of the backup\TYPE_ constants for example backup\TYPE_1ACTIVITY

◆ 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: