Moodle PHP Documentation 4.3
Moodle 4.3.5 (Build: 20240610) (7dcfaa79f78)
|
Class implementing the controller of any backup process. More...
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.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 () | |
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. | |
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!)
backup_controller::__construct | ( | $type, | |
$id, | |||
$format, | |||
$interactive, | |||
$mode, | |||
$userid, | |||
$releasesession = backup::RELEASESESSION_NO ) |
Constructor for the backup controller class.
string | $type | Type of the backup; One of backup\TYPE_1COURSE, TYPE_1SECTION, TYPE_1ACTIVITY |
int | $id | The ID of the item to backup; e.g the course id |
string | $format | The backup format to use; Most likely backup\FORMAT_MOODLE |
bool | $interactive | Whether this backup will require user interaction; backup\INTERACTIVE_YES or INTERACTIVE_NO |
int | $mode | One of backup\MODE_GENERAL, MODE_IMPORT, MODE_SAMESITE, MODE_HUB, MODE_AUTOMATED |
int | $userid | The id of the user making the backup |
bool | $releasesession | Should release the session? backup\RELEASESESSION_YES or backup\RELEASESESSION_NO |
|
inherited |
Inserts a new logger at end of logging chain.
base_logger | $logger | New logger to add |
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.
backup_controller::debug_display_all_settings_values | ( | ) |
For debug only.
Get a simple test display of all the settings.
string |
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)
backup_controller::execute_plan | ( | ) |
Executes the backup.
void | Throws and exception of completes |
backup_controller::finish_ui | ( | ) |
Declare that all user interaction with the backup controller is complete.
After this the backup controller is waiting for processing.
backup_controller::get_backupid | ( | ) |
Gets the unique identifier for this backup controller.
string |
|
inherited |
Get the course copy data.
stdClass |
Reimplemented in restore_controller.
backup_controller::get_courseid | ( | ) |
Gets the course that the item being backed up is in.
false|int |
backup_controller::get_execution | ( | ) |
Get if the backup will be executed immediately, or later.
int |
backup_controller::get_executiontime | ( | ) |
Get when the backup will be executed.
int | 0 means now, otherwise a Unix timestamp |
backup_controller::get_format | ( | ) |
Gets the format the backup is stored in.
string |
backup_controller::get_id | ( | ) |
Gets the instance id of the item being backed up.
It's meaning is related to the type of backup {
int |
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.
int | Indicates whether files should be included in backups. |
|
protected |
Returns the default value for $this->includefiles before we consider any settings.
bool |
dml_exception |
backup_controller::get_interactive | ( | ) |
Gets if user interaction is expected during the backup.
bool |
|
inherited |
Gets first logger in logging chain.
base_logger | Logger |
backup_controller::get_mode | ( | ) |
Gets the mode that the backup will be performed in.
int |
backup_controller::get_operation | ( | ) |
Gets if this is a backup or restore.
string |
backup_controller::get_plan | ( | ) |
Gets the plan that will be run during the backup.
backup_plan |
|
inherited |
Gets the progress reporter, which can be used to report progress within the backup or restore process.
core\progress\base | Progress reporting object |
|
inherited |
Returns the set value of releasesession.
This is used to indicate if the session should be closed during the backup/restore.
bool | Indicates whether the session should be released. |
backup_controller::get_results | ( | ) |
Gets the results of the plan execution for this backup.
array |
backup_controller::get_status | ( | ) |
Get the current status of the backup.
int |
backup_controller::get_type | ( | ) |
Gets the type of backup to be performed.
Use {
string |
backup_controller::get_userid | ( | ) |
Get the id of the user who started the backup.
int |
backup_controller::is_checksum_correct | ( | $checksum | ) |
Given one checksum, returns if matches object's checksum (true) or no (false)
Implements checksumable.
|
static |
Loads a backup controller from the database.
string | $backupid | The id of the backup controller. |
backup_controller |
|
inherited |
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.
backup_controller::save_controller | ( | $includeobj = true, | |
$cleanobj = false ) |
Save controller information.
bool | $includeobj | to decide if the object itself must be updated (true) or no (false) |
bool | $cleanobj | to decide if the object itself must be cleaned (true) or no (false) |
|
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
stdClass | $data | The course copy data. |
backup_controller_exception |
backup_controller::set_execution | ( | $execution, | |
$executiontime = 0 ) |
Sets if the backup will be processed immediately, or later.
int | $execution | Use backup\EXECUTION_INMEDIATE or backup\EXECUTION_DELAYED |
int | $executiontime | The timestamp in the future when the task should be executed, or 0 for immediately. |
|
protected |
Set the initial value for the include_files setting.
bool | $includefiles |
backup_controller::set_kept_roles | ( | array | $roleids | ) |
Sets the user roles that should be kept in the destination course for a course copy operation.
array | $roleids |
backup_controller_exception |
|
inherited |
Sets the progress reporter.
core\progress\base | $progress | Progress reporting object |
backup_controller::set_status | ( | $status | ) |
Sets the new status of the backup.
int | $status |
|
protected |
Cache {.
|
protected |
Format of backup (moodle, imscc).
Should be one of the backup\FORMAT_ constants. for example backup\FORMAT_MOODLE
|
protected |
Whether this backup will require user interaction.
Should be one of backup\INTERACTIVE_YES or INTERACTIVE_NO
|
protected |
Purpose of the backup (default settings)
Should be one of the the backup\MODE_ constants, for example backup\MODE_GENERAL
|
protected |
Type of operation (backup/restore)
Should be selected from: backup\OPERATION_BACKUP or OPERATION_RESTORE
|
protected |
Current status of the controller (created, planned, configured...)
It should be one of the backup\STATUS_ constants, for example backup\STATUS_AWAITING.
|
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
|
inherited |
Bytes enforced for key, using the cypher above.
Restrictive? Yes, but better than unsafe lengths
|
inherited |
This mode is for asynchronous backups.
These backups will run via adhoc scheduled tasks.
|
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.
|
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.
|
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.