Search moodle.org's
Developer Documentation
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.
/lib/ -> upgradelib.php (source)
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]
Various upgrade/install related functions and classes.
| Copyright: | 1999 onwards Martin Dougiamas (http://dougiamas.com) |
| License: | http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later |
| File Size: | 2837 lines (107 kb) |
| Included or required: | 0 times |
| Referenced: | 1 time |
| Includes or requires: | 3 files lib/db/upgrade.php lib/db/install.php version.php |
Defines 8 classes
upgrade_exception:: (1 method):
__construct()
downgrade_exception:: (1 method):
__construct()
upgrade_requires_exception:: (1 method):
__construct()
plugin_incompatible_exception:: (1 method):
__construct()
plugin_defective_exception:: (1 method):
__construct()
plugin_misplaced_exception:: (1 method):
__construct()
core_upgrade_time:: (15 methods):
record_start()
record_end()
record_savepoint()
record_detail()
get_elapsed()
upgrade_set_timeout()
upgrade_main_savepoint()
upgrade_mod_savepoint()
upgrade_block_savepoint()
upgrade_plugin_savepoint()
upgrade_stale_php_files_present()
upgrade_component_updated()
upgrade_plugins()
upgrade_plugins_modules()
upgrade_plugins_blocks()
file:: (43 methods):
log_update_descriptions()
external_update_descriptions()
external_update_services()
upgrade_handle_exception()
upgrade_log()
upgrade_started()
upgrade_finished_handler()
upgrade_finished()
upgrade_setup_debug()
print_upgrade_separator()
print_upgrade_part_start()
print_upgrade_part_end()
upgrade_init_javascript()
upgrade_language_pack()
upgrade_themes()
install_core()
upgrade_core()
upgrade_noncore()
core_tables_exist()
upgrade_plugin_mnet_functions()
admin_mnet_method_profile()
admin_mnet_method_get_docblock()
admin_mnet_method_get_help()
check_database_storage_engine()
check_slasharguments()
check_database_tables_row_format()
check_mysql_file_format()
check_mysql_file_per_table()
check_mysql_large_prefix()
check_mysql_incomplete_unicode_support()
check_is_https()
check_sixtyfour_bits()
check_igbinary322_version()
check_db_prefix_length()
check_upgrade_key()
upgrade_install_plugins()
check_unoconv_version()
check_tls_libraries()
check_libcurl_version()
check_max_input_vars()
check_admin_dir_usage()
check_xmlrpc_usage()
check_mod_assignment()
Class: upgrade_exception - X-Ref
Exception indicating unknown error during upgrade.| __construct($plugin, $version, $debuginfo=NULL) X-Ref |
| No description |
Class: downgrade_exception - X-Ref
Exception indicating downgrade error during upgrade.| __construct($plugin, $oldversion, $newversion) X-Ref |
| No description |
Class: upgrade_requires_exception - X-Ref
| __construct($plugin, $pluginversion, $currentmoodle, $requiremoodle) X-Ref |
| No description |
Class: plugin_incompatible_exception - X-Ref
Exception thrown when attempting to install a plugin that declares incompatibility with moodle version| __construct($plugin, $pluginversion) X-Ref |
| Constructor function for exception param: \core\plugininfo\base $plugin The plugin causing the exception param: int $pluginversion The version of the plugin causing the exception |
Class: plugin_misplaced_exception - X-Ref
Misplaced plugin exception.Note: this should be used only from the upgrade/admin code.
| __construct($component, $expected, $current) X-Ref |
| Constructor. param: string $component the component from version.php param: string $expected expected directory, null means calculate param: string $current plugin directory path |
Class: core_upgrade_time - X-Ref
Static class monitors performance of upgrade steps.| record_start(bool $installation = false) X-Ref |
| Records current time at the start of the current upgrade item, e.g. plugin. param: bool $installation True if this is an installation (of this item) not upgrade |
| record_end(bool $verbose = true) X-Ref |
| Records the end of the current upgrade item. param: bool $verbose If true, displays output |
| record_savepoint($version) X-Ref |
| Records current time at the end of a given numbered step. param: float $version Version number (may have decimals, or not) |
| record_detail(string $detail, bool $showalways = false) X-Ref |
| Records time taken by a detail of the install process. Time is only displayed if longer than threshold, and if in developer debug mode. param: string $detail Text e.g. file or function name param: bool $showalways If true, shows time even if quick |
| get_elapsed() X-Ref |
| Gets the time since the record_start function was called, rounded to 2 digits. return: float Elapsed time |
| upgrade_set_timeout($max_execution_time=300) X-Ref |
| Sets maximum expected time needed for upgrade task. Please always make sure that upgrade will not run longer! The script may be automatically aborted if upgrade times out. param: int $max_execution_time in seconds (can not be less than 60 s) |
| upgrade_main_savepoint($result, $version, $allowabort=true) X-Ref |
| Upgrade savepoint, marks end of each upgrade block. It stores new main version, resets upgrade timeout and abort upgrade if user cancels page loading. Please do not make large upgrade blocks with lots of operations, for example when adding tables keep only one table operation per block. param: bool $result false if upgrade step failed, true if completed param: string or float $version main version param: bool $allowabort allow user to abort script execution here return: void |
| upgrade_mod_savepoint($result, $version, $modname, $allowabort=true) X-Ref |
| Module upgrade savepoint, marks end of module upgrade blocks It stores module version, resets upgrade timeout and abort upgrade if user cancels page loading. param: bool $result false if upgrade step failed, true if completed param: string or float $version main version param: string $modname name of module param: bool $allowabort allow user to abort script execution here return: void |
| upgrade_block_savepoint($result, $version, $blockname, $allowabort=true) X-Ref |
| Blocks upgrade savepoint, marks end of blocks upgrade blocks It stores block version, resets upgrade timeout and abort upgrade if user cancels page loading. param: bool $result false if upgrade step failed, true if completed param: string or float $version main version param: string $blockname name of block param: bool $allowabort allow user to abort script execution here return: void |
| upgrade_plugin_savepoint($result, $version, $type, $plugin, $allowabort=true) X-Ref |
| Plugins upgrade savepoint, marks end of blocks upgrade blocks It stores plugin version, resets upgrade timeout and abort upgrade if user cancels page loading. param: bool $result false if upgrade step failed, true if completed param: string or float $version main version param: string $type The type of the plugin. param: string $plugin The name of the plugin. param: bool $allowabort allow user to abort script execution here return: void |
| upgrade_stale_php_files_present() X-Ref |
| Detect if there are leftovers in PHP source files. During main version upgrades administrators MUST move away old PHP source files and start from scratch (or better use git). return: bool true means borked upgrade, false means previous PHP files were properly removed |
| upgrade_component_updated(string $component, string $messageplug = '',bool $coreinstall = false) X-Ref |
| After upgrading a module, block, or generic plugin, various parts of the system need to be informed. param: string $component Frankenstyle component or 'moodle' for core param: string $messageplug Set to the name of a message plugin if this is one param: bool $coreinstall Set to true if this is the core install |
| upgrade_plugins($type, $startcallback, $endcallback, $verbose) X-Ref |
| Upgrade plugins param: string $type The type of plugins that should be updated (e.g. 'enrol', 'qtype') |
| upgrade_plugins_modules($startcallback, $endcallback, $verbose) X-Ref |
| Find and check all modules and load them up or upgrade them if necessary |
| upgrade_plugins_blocks($startcallback, $endcallback, $verbose) X-Ref |
| This function finds all available blocks and install them into blocks table or do all the upgrade process if newer. |
| log_update_descriptions($component) X-Ref |
| Log_display description function used during install and upgrade. param: string $component name of component (moodle, mod_assignment, etc.) return: void |
| external_update_descriptions($component) X-Ref |
| Web service discovery function used during install and upgrade. param: string $component name of component (moodle, mod_assignment, etc.) return: void |
| external_update_services() X-Ref |
| Allow plugins and subsystems to add external functions to other plugins or built-in services. This function is executed just after all the plugins have been updated. |
| upgrade_handle_exception($ex, $plugin = null) X-Ref |
| upgrade logging functions |
| upgrade_log($type, $plugin, $info, $details=null, $backtrace=null) X-Ref |
| Adds log entry into upgrade_log table param: int $type UPGRADE_LOG_NORMAL, UPGRADE_LOG_NOTICE or UPGRADE_LOG_ERROR param: string $plugin frankenstyle component name param: string $info short description text of log entry param: string $details long problem description param: string $backtrace string used for errors only return: void |
| upgrade_started($preinstall=false) X-Ref |
| Marks start of upgrade, blocks any other access to site. The upgrade is finished at the end of script or after timeout. |
| upgrade_finished_handler() X-Ref |
| Internal function - executed if upgrade interrupted. |
| upgrade_finished($continueurl=null) X-Ref |
| Indicates upgrade is finished. This function may be called repeatedly. |
| upgrade_setup_debug($starting) X-Ref |
| print_upgrade_separator() X-Ref |
| No description |
| print_upgrade_part_start($plugin, $installation, $verbose) X-Ref |
| Default start upgrade callback param: string $plugin param: bool $installation true if installation, false means upgrade |
| print_upgrade_part_end($plugin, $installation, $verbose) X-Ref |
| Default end upgrade callback param: string $plugin param: bool $installation true if installation, false means upgrade |
| upgrade_init_javascript() X-Ref |
| Sets up JS code required for all upgrade scripts. |
| upgrade_language_pack($lang = null) X-Ref |
| Try to upgrade the given language pack (or current language) param: string $lang the code of the language to update, defaults to the current language |
| upgrade_themes() X-Ref |
| Build the current theme so that the user doesn't have to wait for it to build on the first page load after the install / upgrade. |
| install_core($version, $verbose) X-Ref |
| Install core moodle tables and initialize param: float $version target version param: bool $verbose return: void, may throw exception |
| upgrade_core($version, $verbose) X-Ref |
| Upgrade moodle core param: float $version target version param: bool $verbose return: void, may throw exception |
| upgrade_noncore($verbose) X-Ref |
| Upgrade/install other parts of moodle param: bool $verbose return: void, may throw exception |
| core_tables_exist() X-Ref |
| Checks if the main tables have been installed yet or not. Note: we can not use caches here because they might be stale, use with care! return: bool |
| upgrade_plugin_mnet_functions($component) X-Ref |
| upgrades the mnet rpc definitions for the given component. this method doesn't return status, an exception will be thrown in the case of an error param: string $component the plugin to upgrade, eg auth_mnet |
| admin_mnet_method_profile(ReflectionFunctionAbstract $function) X-Ref |
| Given some sort of reflection function/method object, return a profile array, ready to be serialized and stored param: ReflectionFunctionAbstract $function reflection function/method object from which to extract information return: array associative array with function/method information |
| admin_mnet_method_get_docblock(ReflectionFunctionAbstract $function) X-Ref |
| Given some sort of reflection function/method object, return an array of docblock lines, where each line is an array of keywords/descriptions param: ReflectionFunctionAbstract $function reflection function/method object from which to extract information return: array docblock converted in to an array |
| admin_mnet_method_get_help(ReflectionFunctionAbstract $function) X-Ref |
| Given some sort of reflection function/method object, return just the help text param: ReflectionFunctionAbstract $function reflection function/method object from which to extract information return: string docblock help text |
| check_database_storage_engine(environment_results $result) X-Ref |
| This function verifies that the database is not using an unsupported storage engine. param: environment_results $result object to update, if relevant return: environment_results|null updated results object, or null if the storage engine is supported |
| check_slasharguments(environment_results $result) X-Ref |
| Method used to check the usage of slasharguments config and display a warning message. param: environment_results $result object to update, if relevant. return: environment_results|null updated results or null if slasharguments is disabled. |
| check_database_tables_row_format(environment_results $result) X-Ref |
| This function verifies if the database has tables using innoDB Antelope row format. param: environment_results $result return: environment_results|null updated results object, or null if no Antelope table has been found. |
| check_mysql_file_format(environment_results $result) X-Ref |
| This function verfies that the database has tables using InnoDB Antelope row format. param: environment_results $result return: environment_results|null updated results object, or null if no Antelope table has been found. |
| check_mysql_file_per_table(environment_results $result) X-Ref |
| This function verfies that the database has a setting of one file per table. This is required for 'utf8mb4'. param: environment_results $result return: environment_results|null updated results object, or null if innodb_file_per_table = 1. |
| check_mysql_large_prefix(environment_results $result) X-Ref |
| This function verfies that the database has the setting of large prefix enabled. This is required for 'utf8mb4'. param: environment_results $result return: environment_results|null updated results object, or null if innodb_large_prefix = 1. |
| check_mysql_incomplete_unicode_support(environment_results $result) X-Ref |
| This function checks the database to see if it is using incomplete unicode support. param: environment_results $result $result return: environment_results|null updated results object, or null if unicode is fully supported. |
| check_is_https(environment_results $result) X-Ref |
| Check if the site is being served using an ssl url. Note this does not really perform any request neither looks for proxies or other situations. Just looks to wwwroot and warn if it's not using https. param: environment_results $result $result return: environment_results|null updated results object, or null if the site is https. |
| check_sixtyfour_bits(environment_results $result) X-Ref |
| Check if the site is using 64 bits PHP. param: environment_results $result return: environment_results|null updated results object, or null if the site is using 64 bits PHP. |
| check_igbinary322_version(environment_results $result) X-Ref |
| Check if the igbinary extension installed is buggy one There are a few php-igbinary versions that are buggy and return any unserialised array with wrong index. This defeats key() and next() operations on them. This library is used by MUC and also by memcached and redis when available. Let's inform if there is some problem when: - php 7.2 is being used (php 7.3 and up are immune). - the igbinary extension is installed. - the version of the extension is between 3.2.2 and 3.2.4. - the buggy behaviour is reproduced. param: environment_results $result object to update, if relevant. return: environment_results|null updated results or null. |
| check_db_prefix_length(environment_results $result) X-Ref |
| This function checks that the database prefix ($CFG->prefix) is <= 10 param: environment_results $result return: environment_results|null updated results object, or null if the prefix check is passing ok. |
| check_upgrade_key($upgradekeyhash) X-Ref |
| Assert the upgrade key is provided, if it is defined. The upgrade key can be defined in the main config.php as $CFG->upgradekey. If it is defined there, then its value must be provided every time the site is being upgraded, regardless the administrator is logged in or not. This is supposed to be used at certain places in /admin/index.php only. param: string|null $upgradekeyhash the SHA-1 of the value provided by the user |
| upgrade_install_plugins(array $installable, $confirmed, $heading='', $continue=null, $return=null) X-Ref |
| Helper procedure/macro for installing remote plugins at admin/index.php Does not return, always redirects or exits. param: array $installable list of \core\update\remote_info param: bool $confirmed false: display the validation screen, true: proceed installation param: string $heading validation screen heading param: moodle_url|string|null $continue URL to proceed with installation at the validation screen param: moodle_url|string|null $return URL to go back on cancelling at the validation screen |
| check_unoconv_version(environment_results $result) X-Ref |
| Method used to check the installed unoconv version. param: environment_results $result object to update, if relevant. return: environment_results|null updated results or null if unoconv path is not executable. |
| check_tls_libraries(environment_results $result) X-Ref |
| Checks for up-to-date TLS libraries. NOTE: this is not currently used, see MDL-57262. param: environment_results $result object to update, if relevant. return: environment_results|null updated results or null if unoconv path is not executable. |
| check_libcurl_version(environment_results $result) X-Ref |
| Check if recommended version of libcurl is installed or not. param: environment_results $result object to update, if relevant. return: environment_results|null updated results or null. |
| check_max_input_vars(environment_results $result) X-Ref |
| Environment check for the php setting max_input_vars param: environment_results $result return: environment_results|null |
| check_admin_dir_usage(environment_results $result) X-Ref |
| Check whether the admin directory has been configured and warn if so. The admin directory has been deprecated since Moodle 4.0. param: environment_results $result return: null|environment_results |
| check_xmlrpc_usage(environment_results $result) X-Ref |
| Check whether the XML-RPC protocol is enabled and warn if so. The XML-RPC protocol will be removed in a future version (4.1) as it is no longer supported by PHP. See MDL-70889 for further information. param: environment_results $result return: null|environment_results |
| check_mod_assignment(environment_results $result) X-Ref |
| Check whether the mod_assignment is currently being used. param: environment_results $result return: environment_results|null |
