Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
  • Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
  • PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.x is supported too.
/lib/ -> upgradelib.php (source)

Differences Between: [Versions 310 and 402] [Versions 311 and 402] [Versions 39 and 402] [Versions 400 and 402] [Versions 401 and 402] [Versions 402 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: 2864 lines (109 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 3 files
 lib/db/upgrade.php
 version.php
 lib/db/install.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.

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.


Class: file  - X-Ref

log_update_descriptions($component)   X-Ref
Log_display description function used during install and upgrade.

param: string $component name of component (moodle, 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, 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