Search moodle.org's
Developer Documentation

  • Bug fixes for general core bugs in 3.11.x will end 14 Nov 2022 (12 months plus 6 months extension).
  • Bug fixes for security issues in 3.11.x will end 13 Nov 2023 (18 months plus 12 months extension).
  • PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.
  • /lib/ -> upgradelib.php (source)

    Differences Between: [Versions 310 and 311] [Versions 311 and 400] [Versions 37 and 311] [Versions 38 and 311] [Versions 39 and 311]

    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: 2728 lines (104 kb)
    Included or required:0 times
    Referenced: 1 time
    Includes or requires: 3 files
     lib/db/install.php
     lib/db/upgrade.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:: (12 methods):
      record_start()
      record_savepoint()
      get_elapsed()
      upgrade_set_timeout()
      upgrade_main_savepoint()
      upgrade_mod_savepoint()
      upgrade_block_savepoint()
      upgrade_plugin_savepoint()
      upgrade_stale_php_files_present()
      upgrade_plugins()
      upgrade_plugins_modules()
      upgrade_plugins_blocks()

    file:: (40 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_upgrade_key()
      upgrade_install_plugins()
      check_unoconv_version()
      check_tls_libraries()
      check_libcurl_version()
      check_max_input_vars()
      check_admin_dir_usage()


    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()   X-Ref
    Records current time at the start of the current upgrade item, e.g. plugin.


    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)

    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_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, 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_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