MDL-30981 Upgrade API: Added related phpdocs
[moodle.git] / lib / db / install.php
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'));