MDL-30981 Upgrade API: Added related phpdocs
authorEloy Lafuente (stronk7) <stronk7@moodle.org>
Sun, 1 Apr 2012 20:48:17 +0000 (22:48 +0200)
committerEloy Lafuente (stronk7) <stronk7@moodle.org>
Sun, 1 Apr 2012 22:40:13 +0000 (00:40 +0200)
lib/db/access.php
lib/db/events.php
lib/db/install.php
lib/db/log.php
lib/db/messages.php
lib/db/services.php
lib/db/upgrade.php
lib/db/upgradelib.php
lib/moodlelib.php
lib/upgradelib.php

index 8fe0b86..76ebc66 100644 (file)
  *
  * The variable name for the capability definitions array is $capabilities
  *
- * @package    core_access
- * @category   access
- * @copyright  2006 onwards Martin Dougiamas  http://dougiamas.com
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * For more information, take a look to the documentation available:
+ *     - Access API: {@link http://docs.moodle.org/dev/Access_API}
+ *     - Upgrade API: {@link http://docs.moodle.org/dev/Upgrade_API}
+ *
+ * @package   core_access
+ * @category  access
+ * @copyright 2006 onwards Martin Dougiamas  http://dougiamas.com
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
index 768691b..51a8958 100644 (file)
 /**
  * Definition of core event handler and description of all events throws from core.
  *
- * @package core
- * @category event
+ * The handlers defined on this file are processed and registered into
+ * the Moodle DB after any install or upgrade operation. All plugins
+ * support this.
+ *
+ * For more information, take a look to the documentation available:
+ *     - Events API: {@link http://docs.moodle.org/dev/Events_API}
+ *     - Upgrade API: {@link http://docs.moodle.org/dev/Upgrade_API}
+ *
+ * @package   core
+ * @category  event
  * @copyright 2007 onwards Martin Dougiamas  http://dougiamas.com
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
index 8ad8f1a..f0bb45d 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
 /**
  * This file is executed right after the install.xml
  *
- * @package    core
- * @subpackage admin
- * @copyright  2009 Petr Skoda (http://skodak.org)
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * For more information, take a look to the documentation available:
+ *     - Upgrade API: {@link http://docs.moodle.org/dev/Upgrade_API}
+ *
+ * @package   core_install
+ * @category  upgrade
+ * @copyright 2009 Petr Skoda (http://skodak.org)
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
 
+/**
+ * Main post-install tasks to be executed after the BD schema is available
+ *
+ * This function is automatically executed after Moodle core DB has been
+ * created at initial install. It's in charge of perform the initial tasks
+ * not covered by the {@link install.xml} file, like create initial users,
+ * roles, templates, moving stuff from other plugins...
+ *
+ * Note that the function is only invoked once, at install time, so if new tasks
+ * are needed in the future, they will need to be added both here (for new sites)
+ * and in the corresponding {@link upgrade.php} file (for existing sites).
+ *
+ * All plugins within Moodle (modules, blocks, reports...) support the existence of
+ * their own install.php file, using the "Frankenstyle" component name as
+ * defined at {@link http://docs.moodle.org/dev/Frankenstyle}, for example:
+ *     - {@link xmldb_page_install()}. (modules don't require the plugintype ("mod_") to be used.
+ *     - {@link xmldb_enrol_meta_install()}.
+ *     - {@link xmldb_workshopform_accumulative_install()}.
+ *     - ....
+ *
+ * Finally, note that it's also supported to have one uninstall.php file that is
+ * executed also once, each time one plugin is uninstalled (before the DB schema is
+ * deleted). Those uninstall files will contain one function, using the "Frankenstyle"
+ * naming conventions, like {@link xmldb_enrol_meta_uninstall()} or {@link xmldb_workshop_uninstall()}.
+ */
 function xmldb_main_install() {
     global $CFG, $DB, $SITE, $OUTPUT;
 
-    /// Make sure system context exists
+    // Make sure system context exists
     $syscontext = context_system::instance(0, MUST_EXIST, false);
     if ($syscontext->id != SYSCONTEXTID) {
         throw new moodle_exception('generalexceptionmessage', 'error', '', 'Unexpected new system context id!');
     }
 
 
-    /// Create site course
+    // Create site course
     if ($DB->record_exists('course', array())) {
         throw new moodle_exception('generalexceptionmessage', 'error', '', 'Can not create frontpage course, courses already exist.');
     }
@@ -69,7 +96,7 @@ function xmldb_main_install() {
     $SITE = $DB->get_record('course', array('id'=>$newsite->id), '*', MUST_EXIST);
 
 
-    /// Create default course category
+    // Create default course category
     if ($DB->record_exists('course_categories', array())) {
         throw new moodle_exception('generalexceptionmessage', 'error', '', 'Can not create default course category, categories already exist.');
     }
@@ -105,7 +132,7 @@ function xmldb_main_install() {
     }
 
 
-    /// Bootstrap mnet
+    // Bootstrap mnet
     $mnethost = new stdClass();
     $mnethost->wwwroot    = $CFG->wwwroot;
     $mnethost->name       = '';
@@ -160,7 +187,7 @@ function xmldb_main_install() {
     $mnetallhosts->id                 = $DB->insert_record('mnet_host', $mnetallhosts, true);
     set_config('mnet_all_hosts_id', $mnetallhosts->id);
 
-    /// Create guest record - do not assign any role, guest user gets the default guest role automatically on the fly
+    // Create guest record - do not assign any role, guest user gets the default guest role automatically on the fly
     if ($DB->record_exists('user', array())) {
         throw new moodle_exception('generalexceptionmessage', 'error', '', 'Can not create default users, users already exist.');
     }
@@ -186,7 +213,7 @@ function xmldb_main_install() {
     context_user::instance($guest->id);
 
 
-    /// Now create admin user
+    // Now create admin user
     $admin = new stdClass();
     $admin->auth         = 'manual';
     $admin->firstname    = get_string('admin');
@@ -209,13 +236,13 @@ function xmldb_main_install() {
         echo $OUTPUT->notification('Nonconsecutive id generated for the Admin account. Your database configuration or clustering setup may not be fully supported.', 'notifyproblem');
     }
 
-    /// Store list of admins
+    // Store list of admins
     set_config('siteadmins', $admin->id);
     // Make sure user context exists
     context_user::instance($admin->id);
 
 
-    /// Install the roles system.
+    // Install the roles system.
     $managerrole        = create_role(get_string('manager', 'role'), 'manager', get_string('managerdescription', 'role'), 'manager');
     $coursecreatorrole  = create_role(get_string('coursecreators'), 'coursecreator', get_string('coursecreatorsdescription'), 'coursecreator');
     $editteacherrole    = create_role(get_string('defaultcourseteacher'), 'editingteacher', get_string('defaultcourseteacherdescription'), 'editingteacher');
@@ -225,10 +252,10 @@ function xmldb_main_install() {
     $userrole           = create_role(get_string('authenticateduser'), 'user', get_string('authenticateduserdescription'), 'user');
     $frontpagerole      = create_role(get_string('frontpageuser', 'role'), 'frontpage', get_string('frontpageuserdescription', 'role'), 'frontpage');
 
-    /// Now is the correct moment to install capabilities - after creation of legacy roles, but before assigning of roles
+    // Now is the correct moment to install capabilities - after creation of legacy roles, but before assigning of roles
     update_capabilities('moodle');
 
-    /// Default allow assign
+    // Default allow assign
     $defaultallowassigns = array(
         array($managerrole, $managerrole),
         array($managerrole, $coursecreatorrole),
@@ -244,7 +271,7 @@ function xmldb_main_install() {
         allow_assign($fromroleid, $toroleid);
     }
 
-    /// Default allow override
+    // Default allow override
     $defaultallowoverrides = array(
         array($managerrole, $managerrole),
         array($managerrole, $coursecreatorrole),
@@ -264,7 +291,7 @@ function xmldb_main_install() {
         allow_override($fromroleid, $toroleid); // There is a rant about this in MDL-15841.
     }
 
-    /// Default allow switch.
+    // Default allow switch.
     $defaultallowswitch = array(
         array($managerrole, $editteacherrole),
         array($managerrole, $noneditteacherrole),
@@ -283,7 +310,7 @@ function xmldb_main_install() {
         allow_switch($fromroleid, $toroleid);
     }
 
-    /// Set up the context levels where you can assign each role.
+    // Set up the context levels where you can assign each role.
     set_role_contextlevels($managerrole,        get_default_contextlevels('manager'));
     set_role_contextlevels($coursecreatorrole,  get_default_contextlevels('coursecreator'));
     set_role_contextlevels($editteacherrole,    get_default_contextlevels('editingteacher'));
index 7549e34..f404e01 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Definition of log events
+ * Definition of log events associated with the current component
+ *
+ * The log events defined on this file are processed and stored into
+ * the Moodle DB after any install or upgrade operation. All plugins
+ * support this.
+ *
+ * For more information, take a look to the documentation available:
+ *     - Logging API: {@link http://docs.moodle.org/dev/Logging_API}
+ *     - Upgrade API: {@link http://docs.moodle.org/dev/Upgrade_API}
  *
- * @package    core
- * @subpackage admin
- * @copyright  2010 Petr Skoda (http://skodak.org)
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package   core
+ * @category  log
+ * @copyright 2010 Petr Skoda (http://skodak.org)
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
index db087fb..30bc820 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
 /**
  * Defines message providers (types of messages being sent)
  *
- * @package    core
- * @subpackage message
- * @copyright  2008 onwards Martin Dougiamas  http://dougiamas.com
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * The providers defined on this file are processed and registered into
+ * the Moodle DB after any install or upgrade operation. All plugins
+ * support this.
+ *
+ * For more information, take a look to the documentation available:
+ *     - Message API: {@link http://docs.moodle.org/dev/Message_API}
+ *     - Upgrade API: {@link http://docs.moodle.org/dev/Upgrade_API}
+ *
+ * @package   core
+ * @category  message
+ * @copyright 2008 onwards Martin Dougiamas  http://dougiamas.com
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
 
 $messageproviders = array (
 
-/// Notices that an admin might be interested in
+    // Notices that an admin might be interested in
     'notices' => array (
          'capability'  => 'moodle/site:config'
     ),
 
-/// Important errors that an admin ought to know about
+    // Important errors that an admin ought to know about
     'errors' => array (
          'capability'  => 'moodle/site:config'
     ),
@@ -49,17 +56,17 @@ $messageproviders = array (
         'capability'  => 'moodle/site:config'
     ),
 
-    //course creation request notification
+    // Course creation request notification
     'courserequested' => array (
         'capability'  => 'moodle/site:approvecourse'
     ),
 
-    //course request approval notification
+    // Course request approval notification
     'courserequestapproved' => array (
          'capability'  => 'moodle/course:request'
     ),
 
-    //course request rejection notification
+    // Course request rejection notification
     'courserequestrejected' => array (
         'capability'  => 'moodle/course:request'
     )
index 328d29d..cdb6a57 100644 (file)
 /**
  * Core external functions and service definitions.
  *
+ * The functions and services defined on this file are
+ * processed and registered into the Moodle DB after any
+ * install or upgrade operation. All plugins support this.
+ *
+ * For more information, take a look to the documentation available:
+ *     - Webservices API: {@link http://docs.moodle.org/dev/Web_services_API}
+ *     - External API: {@link http://docs.moodle.org/dev/External_functions_API}
+ *     - Upgrade API: {@link http://docs.moodle.org/dev/Upgrade_API}
+ *
  * @package    core_webservice
  * @category   webservice
  * @copyright  2009 Petr Skodak
index 8d8ffff..8ead6e6 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
  * Please do not forget to use upgrade_set_timeout()
  * before any action that may take longer time to finish.
  *
- * @package    core
- * @subpackage admin
- * @copyright  2006 onwards Martin Dougiamas  http://dougiamas.com
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package   core_install
+ * @category  upgrade
+ * @copyright 2006 onwards Martin Dougiamas  http://dougiamas.com
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
 
 /**
+ * Main upgrade tasks to be executed on Moodle version bump
+ *
+ * This function is automatically executed after one bump in the Moodle core
+ * version is detected. It's in charge of perform the required tasks
+ * to raise core from the previous version to the next one.
+ *
+ * It's a collection of ordered blocks of code, named "upgrade steps",
+ * each one performing one isolated (from the rest of steps) task. Usual
+ * tasks involve creating new DB objects or performing manipulation of the
+ * information for cleanup/fixup purposes.
+ *
+ * Each upgrade step has a fixed structure, that can be summarised as follows:
+ *
+ * if ($oldversion < XXXXXXXXXX.XX) {
+ *     // Explanation of the update step, linking to issue in the Tracker, if necessary
+ *     upgrade_set_timeout(XX); // Optional for big tasks
+ *     // Code to execute goes here, usually the XMLDB Editor will
+ *     // help you here. See {@link http://docs.moodle.org/dev/XMLDB_editor}.
+ *     upgrade_main_savepoint(true, XXXXXXXXXX.XX);
+ * }
+ *
+ * All plugins within Moodle (modules, blocks, reports...) support the existence of
+ * their own upgrade.php file, using the "Frankenstyle" component name as
+ * defined at {@link http://docs.moodle.org/dev/Frankenstyle}, for example:
+ *     - {@link xmldb_page_upgrade($oldversion)}. (modules don't require the plugintype ("mod_") to be used.
+ *     - {@link xmldb_auth_manual_upgrade($oldversion)}.
+ *     - {@link xmldb_workshopform_accumulative_upgrade($oldversion)}.
+ *     - ....
+ *
+ * In order to keep the contents of this file reduced, it's allowed to create some helper
+ * functions to be used here in the {@link upgradelib.php} file at the same directory. Note
+ * that such file must be manually included from upgrade.php, and there are some restrictions
+ * about what can be used within it.
+ *
+ * For more information, take a look to the documentation available:
+ *     - Data definition API: {@link http://docs.moodle.org/dev/Data_definition_API}
+ *     - Upgrade API: {@link http://docs.moodle.org/dev/Upgrade_API}
  *
- * @global stdClass $CFG
- * @global stdClass $USER
- * @global moodle_database $DB
- * @global core_renderer $OUTPUT
  * @param int $oldversion
  * @return bool always true
  */
@@ -67,9 +99,8 @@ function xmldb_main_upgrade($oldversion) {
         upgrade_main_savepoint(true, 2011120500);
     }
 
-    ////////////////////////////////////////
-    ///upgrade supported only from 2.2.x ///
-    ////////////////////////////////////////
+    // Moodle v2.2.0 release upgrade line
+    // Put any upgrade step following this
 
     if ($oldversion < 2011120500.02) {
 
index 7960694..7696d06 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
  * because it might depend on db structures that are not yet present during upgrade.
  * (Do not use functions from accesslib.php, grades classes or group functions at all!)
  *
- * @package    core
- * @subpackage admin
- * @copyright  2007 Petr Skoda (http://skodak.org)
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package   core_install
+ * @category  upgrade
+ * @copyright 2007 Petr Skoda (http://skodak.org)
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
index fe642a9..1baadb8 100644 (file)
@@ -8692,8 +8692,9 @@ function moodle_needs_upgrading() {
  *
  * The script may be automatically aborted if upgrade times out.
  *
- * @global object
+ * @category upgrade
  * @param int $max_execution_time in seconds (can not be less than 60 s)
+ * @todo MDL-32293 - Move this function to lib/upgradelib.php
  */
 function upgrade_set_timeout($max_execution_time=300) {
     global $CFG;
index 4f25448..6db4216 100644 (file)
@@ -105,7 +105,7 @@ class plugin_defective_exception extends moodle_exception {
  * Please do not make large upgrade blocks with lots of operations,
  * for example when adding tables keep only one table operation per block.
  *
- * @global object
+ * @category upgrade
  * @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
@@ -146,7 +146,7 @@ function upgrade_main_savepoint($result, $version, $allowabort=true) {
  * It stores module version, resets upgrade timeout
  * and abort upgrade if user cancels page loading.
  *
- * @global object
+ * @category upgrade
  * @param bool $result false if upgrade step failed, true if completed
  * @param string or float $version main version
  * @param string $modname name of module
@@ -186,7 +186,7 @@ function upgrade_mod_savepoint($result, $version, $modname, $allowabort=true) {
  * It stores block version, resets upgrade timeout
  * and abort upgrade if user cancels page loading.
  *
- * @global object
+ * @category upgrade
  * @param bool $result false if upgrade step failed, true if completed
  * @param string or float $version main version
  * @param string $blockname name of block
@@ -226,6 +226,7 @@ function upgrade_block_savepoint($result, $version, $blockname, $allowabort=true
  * It stores plugin version, resets upgrade timeout
  * and abort upgrade if user cancels page loading.
  *
+ * @category upgrade
  * @param bool $result false if upgrade step failed, true if completed
  * @param string or float $version main version
  * @param string $type name of plugin