lib/locallib.php

   1 <?php
   2 /**
   3  * This file provides hooks from moodle core into custom code.
   4  *
   5  * Important note
   6  * --------------
   7  *
   8  * If at all possible, the facilities provided here should not be used.
   9  * Wherever possible, customisations should be written using one of the
  10  * standard plug-in points like modules, blocks, auth plugins, themes, ...
  11  *
  12  * However, sometimes that is just not possible, because of the nature
  13  * of the change you want to make. In which case the second best plan is
  14  * to implement your feature in a generally useful way, which can
  15  * be contributed back to the moodle project so that everyone benefits.
  16  *
  17  * But supposing you are forced to implement some nasty hack that only
  18  * you will ever want, then the local folder is for you. The idea is that
  19  * instead of scattering your changes throughout the code base, you
  20  * put them all in a folder called 'local'. Then you won't have to
  21  * deal with merging problems when you upgrade the rest of your moodle
  22  * installation.
  23  *
  24  *
  25  * Available hooks
  26  * ===============
  27  *
  28  * These are similar to the module interface, however, not all the the
  29  * facilities that are available to modules are available to local code (yet).
  30  * See also http://docs.moodle.org/en/Development:Local_customisation for more
  31  * information.
  32  *
  33  *
  34  * Local database customisations
  35  * -----------------------------
  36  *
  37  * If your local customisations require changes to the database, use the files:
  38  *
  39  * local/version.php
  40  * local/db/upgrade.php
  41  *
  42  * In the file version.php, set the variable $local_version to a versionstamp
  43  * value like 2006030300 (a concatenation of year, month, day, serial).
  44  *
  45  * In the file upgrade.php, implement the
  46  * function xmldb_local_upgrade($oldversion) to make the database changes.
  47  *
  48  * Note that you don't need to have an install.xml file. Instead,
  49  * when your moodle instance is first installed, xmldb_local_upgrade() will be called
  50  * with $oldversion set to 0, so that all the updates run.
  51  *
  52  * Local capabilities
  53  * ------------------
  54  *
  55  * If your local customisations require their own capabilities, use
  56  *
  57  * local/db/access.php
  58  *
  59  * You should create an array called $local_capabilities, which looks like:
  60  *
  61  * $local_capabilities = array(
  62  *         'moodle/local:capability' => array(
  63  *         'captype' => 'read',
  64  *         'contextlevel' => CONTEXT_SYSTEM,
  65  *      ),
  66  * );
  67  *
  68  * Note that for all local capabilities you add, you'll need to add language strings.
  69  * Moodle will expect to find them in local/lang/en_utf8/local.php (eg for English)
  70  * with a key (following the above example) of local:capability
  71  * See the next section for local language support.
  72  *
  73  *
  74  * Local language support
  75  * ----------------------
  76  *
  77  * Moodle already supports local overriding of any language strings, or the
  78  * creation of new strings. Just create a folder lang/XX_utf8_local where XX is
  79  * a language code. Any language files you put in there will be used before
  80  * the standard files. So, for example, can can create a file
  81  * lang/en_utf8_local/moodle.php containing
  82  *   $strings['login'] = 'Sign in';
  83  * and that will change the string 'Login' to 'Sign in'. (See also
  84  * http://docs.moodle.org/en/Language_editing for another way to achieve this.)
  85  *
  86  * This mechanism can also be used to create completely new language files. For
  87  * example, suppose you have created some code in local/myfeature.php that needs
  88  * some language strings. You can put those strings in the file
  89  * lang/en_utf8_local/local_myfeature.php, and then access then using
  90  * get_string('mystring', 'local_myfeature'). (Note that you do not have to call
  91  * the file local_myfeature.php, you can call it anything you like, however,
  92  * the convention of calling lang files for local/ code local_somthing is recommended.)
  93  *
  94  * In addition, there is one other mechanism that is available. Strings from the
  95  * 'local' langauge file (for example get_string('mystring', 'local') will be
  96  * found if the string is found in the file local/lang/en_utf8/local.php. Since
  97  * the lang file 'local' is used for a lot of things like capability names, you
  98  * can use this file for things like that.
  99  *
 100  *
 101  * Local admin menu items
 102  * ----------------------
 103  *
 104  * It is possible to add new items to the admin_tree block.
 105  * To do this, create a file, local/settings.php
 106  * which can access the $ADMIN variable directly and add things to it.
 107  * You might do something like:
 108  * $ADMIN->add('root', new admin_category($name, $title);
 109  * $ADMIN->add('foo', new admin_externalpage($name, $title, $url, $cap);
 110  *
 111  *
 112  * Course deletion
 113  * ---------------
 114  *
 115  * To have your local customisations notified when a course is deleted,
 116  * make a file called
 117  *
 118  * local/lib.php
 119  *
 120  * In there, implement the function local_delete_course($courseid). This
 121  * function will then be called whenever the functions remove_course_contents()
 122  * or delete_course() from moodlelib are called.
 123  */
 124
 125 /**
 126  * This function checks to see whether local database customisations are up-to-date
 127  * by comparing $CFG->local_version to the variable $local_version defined in
 128  * local/version.php. If not, it looks for a function called 'xmldb_local_upgrade'
 129  * in a file called 'local/db/upgrade.php', and if it's there calls it with the
 130  * appropiate $oldversion parameter. Then it updates $CFG->local_version.
 131  * On success it prints a continue link. On failure it prints an error.
 132  *
 133  * @uses $CFG
 134  * @uses $db to do something really evil with the debug setting that should probably be eliminated. TODO!
 135  * @param string $continueto a URL passed to print_continue() if the local upgrades succeed.
 136  */
 137 function upgrade_local_db($continueto) {
 138
 139     global $CFG, $db;
 140
 141     // if we don't have code version or a db upgrade file, just return true, we're unneeded
 142     if (!file_exists($CFG->dirroot.'/local/version.php') || !file_exists($CFG->dirroot.'/local/db/upgrade.php')) {
 143         return true;
 144     }
 145
 146     require_once ($CFG->dirroot .'/local/version.php');  // Get code versions
 147
 148     if (empty($CFG->local_version)) { // normally we'd install, but just replay all the upgrades.
 149         $CFG->local_version = 0;
 150     }
 151
 152     if ($local_version > $CFG->local_version) { // upgrade!
 153         $strdatabaseupgrades = get_string('databaseupgrades');
 154         print_header($strdatabaseupgrades, $strdatabaseupgrades,
 155             build_navigation(array(array('name' => $strdatabaseupgrades, 'link' => null, 'type' => 'misc'))), '', upgrade_get_javascript());
 156
 157         upgrade_log_start();
 158         require_once ($CFG->dirroot .'/local/db/upgrade.php');
 159
 160         $db->debug=true;
 161         if (xmldb_local_upgrade($CFG->local_version)) {
 162             $db->debug=false;
 163             if (set_config('local_version', $local_version)) {
 164                 notify(get_string('databasesuccess'), 'notifysuccess');
 165                 notify(get_string('databaseupgradelocal', '', $local_version), 'notifysuccess');
 166                 print_continue($continueto);
 167                 print_footer('none');
 168                 exit;
 169             } else {
 170                 error('Upgrade of local database customisations failed! (Could not update version in config table)');
 171             }
 172         } else {
 173             $db->debug=false;
 174             error('Upgrade failed!  See local/version.php');
 175         }
 176
 177     } else if ($local_version < $CFG->local_version) {
 178         upgrade_log_start();
 179         notify('WARNING!!!  The local version you are using is OLDER than the version that made these databases!');
 180     }
 181
 182     /// Capabilities
 183     if (!update_capabilities('local')) {
 184         error('Could not set up the capabilities for local!');
 185     }
 186
 187     upgrade_log_finish();
 188 }
 189
 190 /**
 191  * Notify local code that a course is being deleted.
 192  * Look for a function local_delete_course() in a file called
 193  * local/lib.php andn call it if it is there.
 194  *
 195  * @param int $courseid the course that is being deleted.
 196  * @param bool $showfeedback Whether to display notifications on success.
 197  * @return false if local_delete_course failed, or true if
 198  *          there was noting to do or local_delete_course succeeded.
 199  */
 200 function notify_local_delete_course($courseid, $showfeedback) {
 201     global $CFG;
 202     $localfile = $CFG->dirroot .'/local/lib.php';
 203     if (file_exists($localfile)) {
 204         require_once($localfile);
 205         if (function_exists('local_delete_course')) {
 206             if (local_delete_course($courseid)) {
 207                 if ($showfeedback) {
 208                     notify(get_string('deleted') . ' local data');
 209                 }
 210             } else {
 211                 return false;
 212             }
 213         }
 214     }
 215     return true;
 216 }
 217 ?>