lib/conditionlib.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 /**
  18  * Used to be used for tracking conditions that apply before activities are
  19  * displayed to students ('conditional availability').
  20  *
  21  * Now replaced by the availability API. This library is a stub; some functions
  22  * still work while others throw exceptions. New code should not rely on the
  23  * classes, functions, or constants defined here.
  24  *
  25  * @package core_availability
  26  * @copyright 2014 The Open University
  27  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  28  * @deprecated Since Moodle 2.7
  29  */
  30
  31 defined('MOODLE_INTERNAL') || die();
  32
  33 /**
  34  * CONDITION_STUDENTVIEW_HIDE - The activity is not displayed to students at all when conditions aren't met.
  35  */
  36 define('CONDITION_STUDENTVIEW_HIDE', 0);
  37 /**
  38  * CONDITION_STUDENTVIEW_SHOW - The activity is displayed to students as a greyed-out name, with
  39  * informational text that explains the conditions under which it will be available.
  40  */
  41 define('CONDITION_STUDENTVIEW_SHOW', 1);
  42
  43 /**
  44  * CONDITION_MISSING_NOTHING - The $item variable is expected to contain all completion-related data
  45  */
  46 define('CONDITION_MISSING_NOTHING', 0);
  47 /**
  48  * CONDITION_MISSING_EXTRATABLE - The $item variable is expected to contain the fields from
  49  * the relevant table (course_modules or course_sections) but not the _availability data
  50  */
  51 define('CONDITION_MISSING_EXTRATABLE', 1);
  52 /**
  53  * CONDITION_MISSING_EVERYTHING - The $item variable is expected to contain nothing except the ID
  54  */
  55 define('CONDITION_MISSING_EVERYTHING', 2);
  56
  57 /**
  58  * OP_CONTAINS - comparison operator that determines whether a specified user field contains
  59  * a provided variable
  60  */
  61 define('OP_CONTAINS', 'contains');
  62 /**
  63  * OP_DOES_NOT_CONTAIN - comparison operator that determines whether a specified user field does not
  64  * contain a provided variable
  65  */
  66 define('OP_DOES_NOT_CONTAIN', 'doesnotcontain');
  67 /**
  68  * OP_IS_EQUAL_TO - comparison operator that determines whether a specified user field is equal to
  69  * a provided variable
  70  */
  71 define('OP_IS_EQUAL_TO', 'isequalto');
  72 /**
  73  * OP_STARTS_WITH - comparison operator that determines whether a specified user field starts with
  74  * a provided variable
  75  */
  76 define('OP_STARTS_WITH', 'startswith');
  77 /**
  78  * OP_ENDS_WITH - comparison operator that determines whether a specified user field ends with
  79  * a provided variable
  80  */
  81 define('OP_ENDS_WITH', 'endswith');
  82 /**
  83  * OP_IS_EMPTY - comparison operator that determines whether a specified user field is empty
  84  */
  85 define('OP_IS_EMPTY', 'isempty');
  86 /**
  87  * OP_IS_NOT_EMPTY - comparison operator that determines whether a specified user field is not empty
  88  */
  89 define('OP_IS_NOT_EMPTY', 'isnotempty');
  90
  91 require_once($CFG->libdir.'/completionlib.php');
  92
  93 /**
  94  * Core class to handle conditional activities.
  95  *
  96  * This class is now deprecated and partially functional. Public functions either
  97  * work and output deprecated messages or (in the case of the more obscure ones
  98  * which weren't really for public use, or those which can't be implemented in
  99  * the new API) throw exceptions.
 100  *
 101  * @copyright 2014 The Open University
 102  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 103  * @deprecated Since Moodle 2.7
 104  */
 105 class condition_info extends condition_info_base {
 106     /**
 107      * Constructs with course-module details.
 108      *
 109      * @global moodle_database $DB
 110      * @uses CONDITION_MISSING_NOTHING
 111      * @param object $cm Moodle course-module object. Required ->id, ->course
 112      *   will save time, using a full cm_info will save more time
 113      * @param int $expectingmissing Used to control whether or not a developer
 114      *   debugging message (performance warning) will be displayed if some of
 115      *   the above data is missing and needs to be retrieved; a
 116      *   CONDITION_MISSING_xx constant
 117      * @param bool $loaddata If you need a 'write-only' object, set this value
 118      *   to false to prevent database access from constructor
 119      * @deprecated Since Moodle 2.7
 120      */
 121     public function __construct($cm, $expectingmissing = CONDITION_MISSING_NOTHING,
 122             $loaddata=true) {
 123         global $DB;
 124         debugging('The condition_info class is deprecated; change to \core_availability\info_module',
 125                 DEBUG_DEVELOPER);
 126
 127         // Check ID as otherwise we can't do the other queries.
 128         if (empty($cm->id)) {
 129             throw new coding_exception('Invalid parameters; item ID not included');
 130         }
 131
 132         // Load cm_info object.
 133         if (!($cm instanceof cm_info)) {
 134             // Get modinfo.
 135             if (empty($cm->course)) {
 136                 $modinfo = get_fast_modinfo(
 137                         $DB->get_field('course_modules', 'course', array('id' => $cm->id), MUST_EXIST));
 138             } else {
 139                 $modinfo = get_fast_modinfo($cm->course);
 140             }
 141
 142             // Get $cm object.
 143             $cm = $modinfo->get_cm($cm->id);
 144         }
 145
 146         $this->item = $cm;
 147     }
 148
 149     /**
 150      * Adds the extra availability conditions (if any) into the given
 151      * course-module (or section) object.
 152      *
 153      * This function may be called statically (for the editing form) or
 154      * dynamically.
 155      *
 156      * @param object $cm Moodle course-module data object
 157      * @deprecated Since Moodle 2.7 (does nothing)
 158      */
 159     public static function fill_availability_conditions($cm) {
 160         debugging('Calls to condition_info::fill_availability_conditions should be removed',
 161                 DEBUG_DEVELOPER);
 162     }
 163
 164     /**
 165      * Gets the course-module object with full necessary data to determine availability.
 166      *
 167      * @return object Course-module object with full data
 168      * @deprecated Since Moodle 2.7
 169      */
 170     public function get_full_course_module() {
 171         debugging('Calls to condition_info::get_full_course_module should be removed',
 172                 DEBUG_DEVELOPER);
 173         return $this->item;
 174     }
 175
 176     /**
 177      * Used to update a table (which no longer exists) based on form data
 178      * (which is no longer used).
 179      *
 180      * Should only have been called from core code. Now removed (throws exception).
 181      *
 182      * @param object $cm Course-module with as much data as necessary, min id
 183      * @param object $fromform Data from form
 184      * @param bool $wipefirst If true, wipes existing conditions
 185      * @deprecated Since Moodle 2.7 (not available)
 186      * @throws Always throws a coding_exception
 187      */
 188     public static function update_cm_from_form($cm, $fromform, $wipefirst=true) {
 189         throw new coding_exception('Function no longer available');
 190     }
 191
 192     /**
 193      * Used to be used in course/lib.php because we needed to disable the
 194      * completion JS if a completion value affects a conditional activity.
 195      *
 196      * Should only have been called from core code. Now removed (throws exception).
 197      *
 198      * @global stdClass $CONDITIONLIB_PRIVATE
 199      * @param object $course Moodle course object
 200      * @param object $item Moodle course-module
 201      * @deprecated Since Moodle 2.7 (not available)
 202      * @throws Always throws a coding_exception
 203      */
 204     public static function completion_value_used_as_condition($course, $cm) {
 205         throw new coding_exception('Function no longer available');
 206     }
 207 }
 208
 209
 210 /**
 211  * Handles conditional access to sections.
 212  *
 213  * This class is now deprecated and partially functional. Public functions either
 214  * work and output deprecated messages or (in the case of the more obscure ones
 215  * which weren't really for public use, or those which can't be implemented in
 216  * the new API) throw exceptions.
 217  *
 218  * @copyright 2014 The Open University
 219  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 220  * @deprecated Since Moodle 2.7
 221  */
 222 class condition_info_section extends condition_info_base {
 223     /**
 224      * Constructs with course-module details.
 225      *
 226      * @global moodle_database $DB
 227      * @uses CONDITION_MISSING_NOTHING
 228      * @param object $section Moodle section object. Required ->id, ->course
 229      *   will save time, using a full section_info will save more time
 230      * @param int $expectingmissing Used to control whether or not a developer
 231      *   debugging message (performance warning) will be displayed if some of
 232      *   the above data is missing and needs to be retrieved; a
 233      *   CONDITION_MISSING_xx constant
 234      * @param bool $loaddata If you need a 'write-only' object, set this value
 235      *   to false to prevent database access from constructor
 236      * @deprecated Since Moodle 2.7
 237      */
 238     public function __construct($section, $expectingmissing = CONDITION_MISSING_NOTHING,
 239             $loaddata=true) {
 240         global $DB;
 241         debugging('The condition_info_section class is deprecated; change to \core_availability\info_section',
 242                 DEBUG_DEVELOPER);
 243
 244         // Check ID as otherwise we can't do the other queries.
 245         if (empty($section->id)) {
 246             throw new coding_exception('Invalid parameters; item ID not included');
 247         }
 248
 249         // Load cm_info object.
 250         if (!($section instanceof section_info)) {
 251             // Get modinfo.
 252             if (empty($section->course)) {
 253                 $modinfo = get_fast_modinfo(
 254                         $DB->get_field('course_sections', 'course', array('id' => $section->id), MUST_EXIST));
 255             } else {
 256                 $modinfo = get_fast_modinfo($section->course);
 257             }
 258
 259             // Get $cm object.
 260             foreach ($modinfo->get_section_info_all() as $possible) {
 261                 if ($possible->id === $section->id) {
 262                     $section = $possible;
 263                     break;
 264                 }
 265             }
 266         }
 267
 268         $this->item = $section;
 269     }
 270
 271     /**
 272      * Adds the extra availability conditions (if any) into the given
 273      * course-module (or section) object.
 274      *
 275      * This function may be called statically (for the editing form) or
 276      * dynamically.
 277      *
 278      * @param object $section Moodle section data object
 279      * @deprecated Since Moodle 2.7 (does nothing)
 280      */
 281     public static function fill_availability_conditions($section) {
 282         debugging('Calls to condition_info_section::fill_availability_conditions should be removed',
 283                 DEBUG_DEVELOPER);
 284     }
 285
 286     /**
 287      * Gets the section object with full necessary data to determine availability.
 288      *
 289      * @return section_info Section object with full data
 290      * @deprecated Since Moodle 2.7
 291      */
 292     public function get_full_section() {
 293         debugging('Calls to condition_info_section::get_full_section should be removed',
 294                 DEBUG_DEVELOPER);
 295         return $this->item;
 296     }
 297
 298     /**
 299      * Utility function that used to be called by modedit.php; updated a
 300      * table (that no longer exists) based on the module form data.
 301      *
 302      * Should only have been called from core code. Now removed (throws exception).
 303      *
 304      * @param object $section Section object, must at minimum contain id
 305      * @param object $fromform Data from form
 306      * @param bool $wipefirst If true, wipes existing conditions
 307      * @deprecated Since Moodle 2.7 (not available)
 308      * @throws Always throws a coding_exception
 309      */
 310     public static function update_section_from_form($section, $fromform, $wipefirst=true) {
 311         throw new coding_exception('Function no longer available');
 312     }
 313 }
 314
 315
 316 /**
 317  * Base class to handle conditional items (course_modules or sections).
 318  *
 319  * This class is now deprecated and partially functional. Public functions either
 320  * work and output deprecated messages or (in the case of the more obscure ones
 321  * which weren't really for public use, or those which can't be implemented in
 322  * the new API) throw exceptions.
 323  *
 324  * @copyright 2012 The Open University
 325  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 326  * @deprecated Since Moodle 2.7
 327  */
 328 abstract class condition_info_base {
 329     /** @var cm_info|section_info Item with availability data */
 330     protected $item;
 331
 332     /**
 333      * The operators that provide the relationship
 334      * between a field and a value.
 335      *
 336      * @deprecated Since Moodle 2.7 (not available)
 337      * @throws Always throws a coding_exception
 338      */
 339     public static function get_condition_user_field_operators() {
 340         throw new coding_exception('Function no longer available');
 341     }
 342
 343     /**
 344      * Returns list of user fields that can be compared.
 345      *
 346      * If you specify $formatoptions, then format_string will be called on the
 347      * custom field names. This is necessary for multilang support to work so
 348      * you should include this parameter unless you are going to format the
 349      * text later.
 350      *
 351      * @param array $formatoptions Passed to format_string if provided
 352      * @deprecated Since Moodle 2.7 (not available)
 353      * @throws Always throws a coding_exception
 354      */
 355     public static function get_condition_user_fields($formatoptions = null) {
 356         throw new coding_exception('Function no longer available');
 357     }
 358
 359     /**
 360      * Adds to the database a condition based on completion of another module.
 361      *
 362      * Should only have been called from core and test code. Now removed
 363      * (throws exception).
 364      *
 365      * @global moodle_database $DB
 366      * @param int $cmid ID of other module
 367      * @param int $requiredcompletion COMPLETION_xx constant
 368      * @deprecated Since Moodle 2.7 (not available)
 369      * @throws Always throws a coding_exception
 370      */
 371     public function add_completion_condition($cmid, $requiredcompletion) {
 372         throw new coding_exception('Function no longer available');
 373     }
 374
 375     /**
 376      * Adds user fields condition
 377      *
 378      * Should only have been called from core and test code. Now removed
 379      * (throws exception).
 380      *
 381      * @param mixed $field numeric if it is a user profile field, character
 382      *                     if it is a column in the user table
 383      * @param int $operator specifies the relationship between field and value
 384      * @param char $value the value of the field
 385      * @deprecated Since Moodle 2.7 (not available)
 386      * @throws Always throws a coding_exception
 387      */
 388     public function add_user_field_condition($field, $operator, $value) {
 389         throw new coding_exception('Function no longer available');
 390     }
 391
 392     /**
 393      * Adds to the database a condition based on the value of a grade item.
 394      *
 395      * Should only have been called from core and test code. Now removed
 396      * (throws exception).
 397      *
 398      * @global moodle_database $DB
 399      * @param int $gradeitemid ID of grade item
 400      * @param float $min Minimum grade (>=), up to 5 decimal points, or null if none
 401      * @param float $max Maximum grade (<), up to 5 decimal points, or null if none
 402      * @param bool $updateinmemory If true, updates data in memory; otherwise,
 403      *   memory version may be out of date (this has performance consequences,
 404      *   so don't do it unless it really needs updating)
 405      * @deprecated Since Moodle 2.7 (not available)
 406      * @throws Always throws a coding_exception
 407      */
 408     public function add_grade_condition($gradeitemid, $min, $max, $updateinmemory=false) {
 409         throw new coding_exception('Function no longer available');
 410     }
 411
 412     /**
 413      * Erases from the database all conditions for this activity.
 414      *
 415      * Should only have been called from core and test code. Now removed
 416      * (throws exception).
 417      *
 418      * @deprecated Since Moodle 2.7 (not available)
 419      * @throws Always throws a coding_exception
 420      */
 421     public function wipe_conditions() {
 422         throw new coding_exception('Function no longer available');
 423     }
 424
 425     /**
 426      * Integration point with new API; obtains the new class for this item.
 427      *
 428      * @return \core_availability\info Availability info for item
 429      */
 430     protected function get_availability_info() {
 431         if ($this->item instanceof section_info) {
 432             return new \core_availability\info_section($this->item);
 433         } else {
 434             return new \core_availability\info_module($this->item);
 435         }
 436     }
 437
 438     /**
 439      * Obtains a string describing all availability restrictions (even if
 440      * they do not apply any more).
 441      *
 442      * @param course_modinfo|null $modinfo Usually leave as null for default. Specify when
 443      *   calling recursively from inside get_fast_modinfo()
 444      * @return string Information string (for admin) about all restrictions on
 445      *   this item
 446      * @deprecated Since Moodle 2.7
 447      */
 448     public function get_full_information($modinfo=null) {
 449         debugging('condition_info*::get_full_information() is deprecated, replace ' .
 450                 'with new \core_availability\info_module($cm)->get_full_information()',
 451                 DEBUG_DEVELOPER);
 452         return $this->get_availability_info()->get_full_information($modinfo);
 453     }
 454
 455     /**
 456      * Determines whether this particular item is currently available
 457      * according to these criteria.
 458      *
 459      * - This does not include the 'visible' setting (i.e. this might return
 460      *   true even if visible is false); visible is handled independently.
 461      * - This does not take account of the viewhiddenactivities capability.
 462      *   That should apply later.
 463      *
 464      * @uses COMPLETION_COMPLETE
 465      * @uses COMPLETION_COMPLETE_FAIL
 466      * @uses COMPLETION_COMPLETE_PASS
 467      * @param string $information If the item has availability restrictions,
 468      *   a string that describes the conditions will be stored in this variable;
 469      *   if this variable is set blank, that means don't display anything
 470      * @param bool $grabthelot Performance hint: if true, caches information
 471      *   required for all course-modules, to make the front page and similar
 472      *   pages work more quickly (works only for current user)
 473      * @param int $userid If set, specifies a different user ID to check availability for
 474      * @param course_modinfo|null $modinfo Usually leave as null for default. Specify when
 475      *   calling recursively from inside get_fast_modinfo()
 476      * @return bool True if this item is available to the user, false otherwise
 477      * @deprecated Since Moodle 2.7
 478      */
 479     public function is_available(&$information, $grabthelot=false, $userid=0, $modinfo=null) {
 480         debugging('condition_info*::is_available() is deprecated, replace ' .
 481                 'with new \core_availability\info_module($cm)->is_available()',
 482                 DEBUG_DEVELOPER);
 483         return $this->get_availability_info()->is_available(
 484                 $information, $grabthelot, $userid, $modinfo);
 485     }
 486
 487     /**
 488      * Checks whether availability information should be shown to normal users.
 489      *
 490      * This information no longer makes sense with the new system because there
 491      * are multiple show options. (I doubt anyone much used this function anyhow!)
 492      *
 493      * @return bool True if information about availability should be shown to
 494      *   normal users
 495      * @deprecated Since Moodle 2.7
 496      */
 497     public function show_availability() {
 498         debugging('condition_info*::show_availability() is deprecated and there ' .
 499                 'is no direct replacement (this is no longer a boolean value), ' .
 500                 'please refactor code',
 501                 DEBUG_DEVELOPER);
 502         return false;
 503     }
 504
 505     /**
 506      * Used to be called by grade code to inform the completion system when a
 507      * grade was changed.
 508      *
 509      * This function should not have ever been used outside the grade API, so
 510      * it now just throws an exception.
 511      *
 512      * @param grade_grade $grade
 513      * @param bool $deleted
 514      * @deprecated Since Moodle 2.7 (not available)
 515      * @throws Always throws a coding_exception
 516      */
 517     public static function inform_grade_changed($grade, $deleted) {
 518         throw new coding_exception('Function no longer available');
 519     }
 520
 521     /**
 522      * Used to be used for testing.
 523      *
 524      * @deprecated since 2.6
 525      */
 526     public static function wipe_session_cache() {
 527         debugging('Calls to completion_info::wipe_session_cache should be removed', DEBUG_DEVELOPER);
 528     }
 529
 530     /**
 531      * Initialises the global cache
 532      *
 533      * @deprecated Since Moodle 2.7
 534      */
 535     public static function init_global_cache() {
 536         debugging('Calls to completion_info::init_globa_cache should be removed', DEBUG_DEVELOPER);
 537     }
 538 }