lib/deprecatedlib.php

   1 <?php // $Id$
   2
   3 ///////////////////////////////////////////////////////////////////////////
   4 //                                                                       //
   5 // NOTICE OF COPYRIGHT                                                   //
   6 //                                                                       //
   7 // Moodle - Modular Object-Oriented Dynamic Learning Environment         //
   8 //          http://moodle.org                                            //
   9 //                                                                       //
  10 // Copyright (C) 1999-2999  Martin Dougiamas, Moodle  http://moodle.com  //
  11 //                                                                       //
  12 // This program is free software; you can redistribute it and/or modify  //
  13 // it under the terms of the GNU General Public License as published by  //
  14 // the Free Software Foundation; either version 2 of the License, or     //
  15 // (at your option) any later version.                                   //
  16 //                                                                       //
  17 // This program is distributed in the hope that it will be useful,       //
  18 // but WITHOUT ANY WARRANTY; without even the implied warranty of        //
  19 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         //
  20 // GNU General Public License for more details:                          //
  21 //                                                                       //
  22 //          http://www.gnu.org/copyleft/gpl.html                         //
  23 //                                                                       //
  24 ///////////////////////////////////////////////////////////////////////////
  25
  26 /**
  27  * deprecatedlib.php - Old functions retained only for backward compatibility
  28  *
  29  * Old functions retained only for backward compatibility.  New code should not
  30  * use any of these functions.
  31  *
  32  * @author Martin Dougiamas
  33  * @version $Id$
  34  * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
  35  * @package moodlecore
  36  */
  37
  38
  39
  40
  41 /**
  42  * Ensure that a variable is set
  43  *
  44  * If $var is undefined throw an error, otherwise return $var.
  45  *
  46  * @param mixed $var the variable which may be unset
  47  * @param mixed $default the value to return if $var is unset
  48  */
  49 function require_variable($var) {
  50     global $CFG;
  51     if (!empty($CFG->disableglobalshack)) {
  52         error( 'The require_variable() function is deprecated.' );
  53     }
  54     if (! isset($var)) {
  55         error('A required parameter was missing');
  56     }
  57 }
  58
  59 /**
  60  * Ensure that a variable is set
  61  *
  62  * If $var is undefined set it (by reference), otherwise return $var.
  63  *
  64  * @param mixed $var the variable which may be unset
  65  * @param mixed $default the value to return if $var is unset
  66  */
  67 function optional_variable(&$var, $default=0) {
  68     global $CFG;
  69     if (!empty($CFG->disableglobalshack)) {
  70         error( "The optional_variable() function is deprecated ($var, $default)." );
  71     }
  72     if (! isset($var)) {
  73         $var = $default;
  74     }
  75 }
  76
  77 /**
  78  * Ensure that a variable is set
  79  *
  80  * Return $var if it is defined, otherwise return $default,
  81  * This function is very similar to {@link optional_variable()}
  82  *
  83  * @param    mixed $var the variable which may be unset
  84  * @param    mixed $default the value to return if $var is unset
  85  * @return   mixed
  86  */
  87 function nvl(&$var, $default='') {
  88     global $CFG;
  89
  90     if (!empty($CFG->disableglobalshack)) {
  91       error( "The nvl() function is deprecated ($var, $default)." );
  92     }
  93     return isset($var) ? $var : $default;
  94 }
  95
  96 /**
  97  * Determines if a user an admin
  98  *
  99  * @uses $USER
 100  * @param int $userid The id of the user as is found in the 'user' table
 101  * @staticvar array $admins List of users who have been found to be admins by user id
 102  * @staticvar array $nonadmins List of users who have been found not to be admins by user id
 103  * @return bool
 104  */
 105 function isadmin($userid=0) {
 106     global $USER, $CFG;
 107
 108     if (empty($CFG->rolesactive)) {    // Then the user is likely to be upgrading NOW
 109         if (!$userid) {
 110             if (empty($USER->id)) {
 111                 return false;
 112             }
 113             if (!empty($USER->admin)) {
 114                 return true;
 115             }
 116             $userid = $USER->id;
 117         }
 118
 119         return record_exists('user_admins', 'userid', $userid);
 120     }
 121
 122     $context = get_context_instance(CONTEXT_SYSTEM, SITEID);
 123
 124     return has_capability('moodle/legacy:admin', $context, $userid, false);
 125 }
 126
 127 /**
 128  * Determines if a user is a teacher (or better)
 129  *
 130  * @uses $CFG
 131  * @param int $courseid The id of the course that is being viewed, if any
 132  * @param int $userid The id of the user that is being tested against. Set this to 0 if you would just like to test against the currently logged in user.
 133  * @param bool $obsolete_includeadmin Not used any more
 134  * @return bool
 135  */
 136
 137 function isteacher($courseid=0, $userid=0, $obsolete_includeadmin=true) {
 138 /// Is the user able to access this course as a teacher?
 139     global $CFG;
 140
 141     if (empty($CFG->rolesactive)) {     // Teachers are locked out during an upgrade to 1.7
 142         return false;
 143     }
 144
 145     if ($courseid) {
 146         $context = get_context_instance(CONTEXT_COURSE, $courseid);
 147     } else {
 148         $context = get_context_instance(CONTEXT_SYSTEM, SITEID);
 149     }
 150
 151     return (has_capability('moodle/legacy:teacher', $context, $userid, false)
 152          or has_capability('moodle/legacy:editingteacher', $context, $userid, false)
 153          or has_capability('moodle/legacy:admin', $context, $userid, false));
 154 }
 155
 156 /**
 157  * Determines if a user is a teacher in any course, or an admin
 158  *
 159  * @uses $USER
 160  * @param int $userid The id of the user that is being tested against. Set this to 0 if you would just like to test against the currently logged in user.
 161  * @param bool $includeadmin Include anyone wo is an admin as well
 162  * @return bool
 163  */
 164 function isteacherinanycourse($userid=0, $includeadmin=true) {
 165     global $USER, $CFG;
 166
 167     if (empty($CFG->rolesactive)) {     // Teachers are locked out during an upgrade to 1.7
 168         return false;
 169     }
 170
 171     if (!$userid) {
 172         if (empty($USER->id)) {
 173             return false;
 174         }
 175         $userid = $USER->id;
 176     }
 177
 178     if (!record_exists('role_assignments', 'userid', $userid)) {    // Has no roles anywhere
 179         return false;
 180     }
 181
 182 /// If this user is assigned as an editing teacher anywhere then return true
 183     if ($roles = get_roles_with_capability('moodle/legacy:editingteacher', CAP_ALLOW)) {
 184         foreach ($roles as $role) {
 185             if (record_exists('role_assignments', 'roleid', $role->id, 'userid', $userid)) {
 186                 return true;
 187             }
 188         }
 189     }
 190
 191 /// If this user is assigned as a non-editing teacher anywhere then return true
 192     if ($roles = get_roles_with_capability('moodle/legacy:teacher', CAP_ALLOW)) {
 193         foreach ($roles as $role) {
 194             if (record_exists('role_assignments', 'roleid', $role->id, 'userid', $userid)) {
 195                 return true;
 196             }
 197         }
 198     }
 199
 200 /// Include admins if required
 201     if ($includeadmin) {
 202         $context = get_context_instance(CONTEXT_SYSTEM, SITEID);
 203         if (has_capability('moodle/legacy:admin', $context, $userid, false)) {
 204             return true;
 205         }
 206     }
 207
 208     return false;
 209 }
 210
 211 /**
 212  * Determines if a user is allowed to edit a given course
 213  *
 214  * @param int $courseid The id of the course that is being edited
 215  * @param int $userid The id of the user that is being tested against. Set this to 0 if you would just like to test against the currently logged in user.
 216  * @return bool
 217  */
 218 function isteacheredit($courseid, $userid=0, $obsolete_ignorestudentview=false) {
 219     global $CFG;
 220
 221     if (empty($CFG->rolesactive)) {
 222         return false;
 223     }
 224
 225     if (empty($courseid)) {
 226         $context = get_context_instance(CONTEXT_SYSTEM, SITEID);
 227     } else {
 228         $context = get_context_instance(CONTEXT_COURSE, $courseid);
 229     }
 230
 231     return (has_capability('moodle/legacy:editingteacher', $context, $userid, false)
 232          or has_capability('moodle/legacy:admin', $context, $userid, false));
 233 }
 234
 235 /**
 236  * Determines if a user can create new courses
 237  *
 238  * @param int $userid The user being tested. You can set this to 0 or leave it blank to test the currently logged in user.
 239  * @return bool
 240  */
 241 function iscreator ($userid=0) {
 242     global $CFG;
 243
 244     if (empty($CFG->rolesactive)) {
 245         return false;
 246     }
 247
 248     $context = get_context_instance(CONTEXT_SYSTEM, SITEID);
 249
 250     return (has_capability('moodle/legacy:coursecreator', $context, $userid, false)
 251          or has_capability('moodle/legacy:admin', $context, $userid, false));
 252 }
 253
 254 /**
 255  * Determines if a user is a student in the specified course
 256  *
 257  * If the course id specifies the site then this determines
 258  * if the user is a confirmed and valid user of this site.
 259  *
 260  * @uses $CFG
 261  * @uses SITEID
 262  * @param int $courseid The id of the course being tested
 263  * @param int $userid The user being tested. You can set this to 0 or leave it blank to test the currently logged in user.
 264  * @return bool
 265  */
 266 function isstudent($courseid=0, $userid=0) {
 267     global $CFG;
 268
 269     if (empty($CFG->rolesactive)) {
 270         return false;
 271     }
 272
 273     if ($courseid == 0) {
 274         $context = get_context_instance(CONTEXT_SYSTEM, SITEID);
 275     } else {
 276         $context = get_context_instance(CONTEXT_COURSE, $courseid);
 277     }
 278
 279     return has_capability('moodle/legacy:student', $context, $userid, false);
 280 }
 281
 282 /**
 283  * Determines if the specified user is logged in as guest.
 284  *
 285  * @param int $userid The user being tested. You can set this to 0 or leave it blank to test the currently logged in user.
 286  * @return bool
 287  */
 288 function isguest($userid=0) {
 289     global $CFG;
 290
 291     if (empty($CFG->rolesactive)) {
 292         return false;
 293     }
 294
 295     $context = get_context_instance(CONTEXT_SYSTEM);
 296
 297     return has_capability('moodle/legacy:guest', $context, $userid, false);
 298 }
 299
 300 /**
 301  * Enrols (or re-enrols) a student in a given course
 302  *
 303  * NOTE: Defaults to 'manual' enrolment - enrolment plugins
 304  * must set it explicitly.
 305  *
 306  * @uses $CFG
 307  * @param int $userid The id of the user that is being tested against. Set this to 0 if you would just like to test against the currently logged in user.
 308  * @param int $courseid The id of the course that is being viewed
 309  * @param int $timestart ?
 310  * @param int $timeend ?
 311  * @param string $enrol ?
 312  * @return bool
 313  */
 314 function enrol_student($userid, $courseid, $timestart=0, $timeend=0, $enrol='manual') {
 315
 316     global $CFG;
 317
 318     if (!$user = get_record('user', 'id', $userid)) {        // Check user
 319         return false;
 320     }
 321
 322     if (!$roles = get_roles_with_capability('moodle/legacy:student', CAP_ALLOW)) {
 323         return false;
 324     }
 325
 326     $role = array_shift($roles);      // We can only use one, let's use the first one
 327
 328     if (!$context = get_context_instance(CONTEXT_COURSE, $courseid)) {
 329         return false;
 330     }
 331
 332     return role_assign($role->id, $user->id, 0, $context->id, $timestart, $timeend, 0, $enrol);
 333 }
 334
 335 /**
 336  * Unenrols a student from a given course
 337  *
 338  * @param int $courseid The id of the course that is being viewed, if any
 339  * @param int $userid The id of the user that is being tested against.
 340  * @return bool
 341  */
 342 function unenrol_student($userid, $courseid=0) {
 343     global $CFG;
 344
 345     $status = true;
 346
 347     if ($courseid) {
 348         /// First delete any crucial stuff that might still send mail
 349         if ($forums = get_records('forum', 'course', $courseid)) {
 350             foreach ($forums as $forum) {
 351                 delete_records('forum_subscriptions', 'forum', $forum->id, 'userid', $userid);
 352             }
 353         }
 354         /// remove from all legacy student roles
 355         if ($courseid == SITEID) {
 356             $context = get_context_instance(CONTEXT_SYSTEM, SITEID);
 357         } else if (!$context = get_context_instance(CONTEXT_COURSE, $courseid)) {
 358             return false;
 359         }
 360         if (!$roles = get_roles_with_capability('moodle/legacy:student', CAP_ALLOW)) {
 361             return false;
 362         }
 363         foreach($roles as $role) {
 364             $status = role_unassign($role->id, $userid, 0, $context->id) and $status;
 365         }
 366     } else {
 367         // recursivelly unenroll student from all courses
 368         if ($courses = get_records('course')) {
 369             foreach($courses as $course) {
 370                 $status = unenrol_student($userid, $course->id) and $status;
 371             }
 372         }
 373     }
 374
 375     return $status;
 376 }
 377
 378 /**
 379  * Add a teacher to a given course
 380  *
 381  * @param int $userid The id of the user that is being tested against. Set this to 0 if you would just like to test against the currently logged in user.
 382  * @param int $courseid The id of the course that is being viewed, if any
 383  * @param int $editall Can edit the course
 384  * @param string $role Obsolete
 385  * @param int $timestart The time they start
 386  * @param int $timeend The time they end in this role
 387  * @param string $enrol The type of enrolment this is
 388  * @return bool
 389  */
 390 function add_teacher($userid, $courseid, $editall=1, $role='', $timestart=0, $timeend=0, $enrol='manual') {
 391     global $CFG;
 392
 393     if (!$user = get_record('user', 'id', $userid)) {        // Check user
 394         return false;
 395     }
 396
 397     $capability = $editall ? 'moodle/legacy:editingteacher' : 'moodle/legacy:teacher';
 398
 399     if (!$roles = get_roles_with_capability($capability, CAP_ALLOW)) {
 400         return false;
 401     }
 402
 403     $role = array_shift($roles);      // We can only use one, let's use the first one
 404
 405     if (!$context = get_context_instance(CONTEXT_COURSE, $courseid)) {
 406         return false;
 407     }
 408
 409     return role_assign($role->id, $user->id, 0, $context->id, $timestart, $timeend, 0, $enrol);
 410 }
 411
 412 /**
 413  * Removes a teacher from a given course (or ALL courses)
 414  * Does not delete the user account
 415  *
 416  * @param int $courseid The id of the course that is being viewed, if any
 417  * @param int $userid The id of the user that is being tested against.
 418  * @return bool
 419  */
 420 function remove_teacher($userid, $courseid=0) {
 421     global $CFG;
 422
 423     $roles = get_roles_with_capability('moodle/legacy:editingteacher', CAP_ALLOW);
 424
 425     if ($roles) {
 426         $roles += get_roles_with_capability('moodle/legacy:teacher', CAP_ALLOW);
 427     } else {
 428         $roles = get_roles_with_capability('moodle/legacy:teacher', CAP_ALLOW);
 429     }
 430
 431     if (empty($roles)) {
 432         return true;
 433     }
 434
 435     $return = true;
 436
 437     if ($courseid) {
 438
 439         if (!$context = get_context_instance(CONTEXT_COURSE, $courseid)) {
 440             return false;
 441         }
 442
 443         /// First delete any crucial stuff that might still send mail
 444         if ($forums = get_records('forum', 'course', $courseid)) {
 445             foreach ($forums as $forum) {
 446                 delete_records('forum_subscriptions', 'forum', $forum->id, 'userid', $userid);
 447             }
 448         }
 449
 450         /// No need to remove from groups now
 451
 452         foreach ($roles as $role) {    // Unassign them from all the teacher roles
 453             $newreturn = role_unassign($role->id, $userid, 0, $context->id);
 454             if (empty($newreturn)) {
 455                 $return = false;
 456             }
 457         }
 458
 459     } else {
 460         delete_records('forum_subscriptions', 'userid', $userid);
 461         $return = true;
 462         foreach ($roles as $role) {    // Unassign them from all the teacher roles
 463             $newreturn = role_unassign($role->id, $userid, 0, 0);
 464             if (empty($newreturn)) {
 465                 $return = false;
 466             }
 467         }
 468     }
 469
 470     return $return;
 471 }
 472
 473 /**
 474  * Add an admin to a site
 475  *
 476  * @uses SITEID
 477  * @param int $userid The id of the user that is being tested against.
 478  * @return bool
 479  * @TODO: remove from cvs
 480  */
 481 function add_admin($userid) {
 482     return true;
 483 }
 484
 485 function get_user_info_from_db($field, $value) {  // For backward compatibility
 486     return get_complete_user_data($field, $value);
 487 }
 488
 489
 490 /**
 491  * Get the guest user information from the database
 492  *
 493  * @return object(user) An associative array with the details of the guest user account.
 494  * @todo Is object(user) a correct return type? Or is array the proper return type with a note that the contents include all details for a user.
 495  */
 496 function get_guest() {
 497     return get_complete_user_data('username', 'guest');
 498 }
 499
 500 /**
 501  * Returns $user object of the main teacher for a course
 502  *
 503  * @uses $CFG
 504  * @param int $courseid The course in question.
 505  * @return user|false  A {@link $USER} record of the main teacher for the specified course or false if error.
 506  * @todo Finish documenting this function
 507  */
 508 function get_teacher($courseid) {
 509
 510     global $CFG;
 511
 512     $context = get_context_instance(CONTEXT_COURSE, $courseid);
 513
 514     if ($users = get_users_by_capability($context, 'moodle/course:update', 'u.*,ra.hidden', 'r.sortorder ASC',
 515                                          '', '', '', '', false)) {
 516         foreach ($users as $user) {
 517             if (!$user->hidden || has_capability('moodle/role:viewhiddenassigns', $context)) {
 518                 return $user;
 519             }
 520         }
 521     }
 522
 523     return false;
 524 }
 525
 526 /**
 527  * Searches logs to find all enrolments since a certain date
 528  *
 529  * used to print recent activity
 530  *
 531  * @uses $CFG
 532  * @param int $courseid The course in question.
 533  * @return object|false  {@link $USER} records or false if error.
 534  * @todo Finish documenting this function
 535  */
 536 function get_recent_enrolments($courseid, $timestart) {
 537
 538     global $CFG;
 539
 540     $context = get_context_instance(CONTEXT_COURSE, $courseid);
 541
 542     return get_records_sql("SELECT DISTINCT u.id, u.firstname, u.lastname, l.time
 543                             FROM {$CFG->prefix}user u,
 544                                  {$CFG->prefix}role_assignments ra,
 545                                  {$CFG->prefix}log l
 546                             WHERE l.time > '$timestart'
 547                               AND l.course = '$courseid'
 548                               AND l.module = 'course'
 549                               AND l.action = 'enrol'
 550                               AND l.info = u.id
 551                               AND u.id = ra.userid
 552                               AND ra.contextid ".get_related_contexts_string($context)."
 553                               ORDER BY l.time ASC");
 554 }
 555
 556 /**
 557  * Returns array of userinfo of all students in this course
 558  * or on this site if courseid is id of site
 559  *
 560  * @uses $CFG
 561  * @uses SITEID
 562  * @param int $courseid The course in question.
 563  * @param string $sort ?
 564  * @param string $dir ?
 565  * @param int $page ?
 566  * @param int $recordsperpage ?
 567  * @param string $firstinitial ?
 568  * @param string $lastinitial ?
 569  * @param ? $group ?
 570  * @param string $search ?
 571  * @param string $fields A comma separated list of fields to be returned from the chosen table.
 572  * @param string $exceptions ?
 573  * @return object
 574  * @todo Finish documenting this function
 575  */
 576 function get_course_students($courseid, $sort='ul.timeaccess', $dir='', $page='', $recordsperpage='',
 577                              $firstinitial='', $lastinitial='', $group=NULL, $search='', $fields='', $exceptions='') {
 578
 579     global $CFG;
 580
 581     // make sure it works on the site course
 582     $context = get_context_instance(CONTEXT_COURSE, $courseid);
 583
 584     /// For the site course, old way was to check if $CFG->allusersaresitestudents was set to true.
 585     /// The closest comparible method using roles is if the $CFG->defaultuserroleid is set to the legacy
 586     /// student role. This function should be replaced where it is used with something more meaningful.
 587     if (($courseid == SITEID) && !empty($CFG->defaultuserroleid) && empty($CFG->nodefaultuserrolelists)) {
 588         if ($roles = get_roles_with_capability('moodle/legacy:student', CAP_ALLOW, $context)) {
 589             $hascap = false;
 590             foreach ($roles as $role) {
 591                 if ($role->id == $CFG->defaultuserroleid) {
 592                     $hascap = true;
 593                     break;
 594                 }
 595             }
 596             if ($hascap) {
 597                 // return users with confirmed, undeleted accounts who are not site teachers
 598                 // the following is a mess because of different conventions in the different user functions
 599                 $sort = str_replace('s.timeaccess', 'lastaccess', $sort); // site users can't be sorted by timeaccess
 600                 $sort = str_replace('timeaccess', 'lastaccess', $sort); // site users can't be sorted by timeaccess
 601                 $sort = str_replace('u.', '', $sort); // the get_user function doesn't use the u. prefix to fields
 602                 $fields = str_replace('u.', '', $fields);
 603                 if ($sort) {
 604                     $sort = $sort .' '. $dir;
 605                 }
 606                 // Now we have to make sure site teachers are excluded
 607
 608                 if ($teachers = get_course_teachers(SITEID)) {
 609                     foreach ($teachers as $teacher) {
 610                         $exceptions .= ','. $teacher->userid;
 611                     }
 612                     $exceptions = ltrim($exceptions, ',');
 613
 614                 }
 615
 616                 return get_users(true, $search, true, $exceptions, $sort, $firstinitial, $lastinitial,
 617                                   $page, $recordsperpage, $fields ? $fields : '*');
 618             }
 619         }
 620     }
 621
 622     $LIKE      = sql_ilike();
 623     $fullname  = sql_fullname('u.firstname','u.lastname');
 624
 625     $groupmembers = '';
 626
 627     $select = "c.contextlevel=".CONTEXT_COURSE." AND "; // Must be on a course
 628     if ($courseid != SITEID) {
 629         // If not site, require specific course
 630         $select.= "c.instanceid=$courseid AND ";
 631     }
 632     $select.="rc.capability='moodle/legacy:student' AND rc.permission=".CAP_ALLOW." AND ";
 633
 634     $select .= ' u.deleted = \'0\' ';
 635
 636     if (!$fields) {
 637         $fields = 'u.id, u.confirmed, u.username, u.firstname, u.lastname, '.
 638                   'u.maildisplay, u.mailformat, u.maildigest, u.email, u.city, '.
 639                   'u.country, u.picture, u.idnumber, u.department, u.institution, '.
 640                   'u.emailstop, u.lang, u.timezone, ul.timeaccess as lastaccess';
 641     }
 642
 643     if ($search) {
 644         $search = ' AND ('. $fullname .' '. $LIKE .'\'%'. $search .'%\' OR email '. $LIKE .'\'%'. $search .'%\') ';
 645     }
 646
 647     if ($firstinitial) {
 648         $select .= ' AND u.firstname '. $LIKE .'\''. $firstinitial .'%\' ';
 649     }
 650
 651     if ($lastinitial) {
 652         $select .= ' AND u.lastname '. $LIKE .'\''. $lastinitial .'%\' ';
 653     }
 654
 655     if ($group === 0) {   /// Need something here to get all students not in a group
 656         return array();
 657
 658     } else if ($group !== NULL) {
 659         $groupmembers = "INNER JOIN {$CFG->prefix}groups_members gm on u.id=gm.userid";
 660         $select .= ' AND gm.groupid = \''. $group .'\'';
 661     }
 662
 663     if (!empty($exceptions)) {
 664         $select .= ' AND u.id NOT IN ('. $exceptions .')';
 665     }
 666
 667     if ($sort) {
 668         $sort = ' ORDER BY '. $sort .' ';
 669     }
 670
 671     $students = get_records_sql("SELECT $fields
 672                                 FROM {$CFG->prefix}user u INNER JOIN
 673                                      {$CFG->prefix}role_assignments ra on u.id=ra.userid INNER JOIN
 674                                      {$CFG->prefix}role_capabilities rc ON ra.roleid=rc.roleid INNER JOIN
 675                                      {$CFG->prefix}context c ON c.id=ra.contextid LEFT OUTER JOIN
 676                                      {$CFG->prefix}user_lastaccess ul on ul.userid=ra.userid
 677                                      $groupmembers
 678                                 WHERE $select $search $sort $dir", $page, $recordsperpage);
 679
 680     return $students;
 681 }
 682
 683 /**
 684  * Counts the students in a given course (or site), or a subset of them
 685  *
 686  * @param object $course The course in question as a course object.
 687  * @param string $search ?
 688  * @param string $firstinitial ?
 689  * @param string $lastinitial ?
 690  * @param ? $group ?
 691  * @param string $exceptions ?
 692  * @return int
 693  * @todo Finish documenting this function
 694  */
 695 function count_course_students($course, $search='', $firstinitial='', $lastinitial='', $group=NULL, $exceptions='') {
 696
 697     if ($students = get_course_students($course->id, '', '', 0, 999999, $firstinitial, $lastinitial, $group, $search, '', $exceptions)) {
 698         return count($students);
 699     }
 700     return 0;
 701 }
 702
 703 /**
 704  * Returns list of all teachers in this course
 705  *
 706  * If $courseid matches the site id then this function
 707  * returns a list of all teachers for the site.
 708  *
 709  * @uses $CFG
 710  * @param int $courseid The course in question.
 711  * @param string $sort ?
 712  * @param string $exceptions ?
 713  * @return object
 714  * @todo Finish documenting this function
 715  */
 716 function get_course_teachers($courseid, $sort='t.authority ASC', $exceptions='') {
 717
 718     global $CFG;
 719
 720     $sort = 'ul.timeaccess DESC';
 721
 722     $context = get_context_instance(CONTEXT_COURSE, $courseid);
 723
 724     /// For the site course, if the $CFG->defaultuserroleid is set to the legacy teacher role, then all
 725     /// users are teachers. This function should be replaced where it is used with something more
 726     /// meaningful.
 727     if (($courseid == SITEID) && !empty($CFG->defaultuserroleid) && empty($CFG->nodefaultuserrolelists)) {
 728         if ($roles = get_roles_with_capability('moodle/legacy:teacher', CAP_ALLOW, $context)) {
 729             $hascap = false;
 730             foreach ($roles as $role) {
 731                 if ($role->id == $CFG->defaultuserroleid) {
 732                     $hascap = true;
 733                     break;
 734                 }
 735             }
 736             if ($hascap) {
 737                 if (empty($fields)) {
 738                     $fields = '*';
 739                 }
 740                 return get_users(true, '', true, $exceptions, 'lastname ASC', '', '', '', '', $fields);
 741             }
 742         }
 743     }
 744
 745     return get_users_by_capability($context, 'moodle/course:update', 'u.*, ul.timeaccess as lastaccess, ra.hidden', $sort, '','','',$exceptions, false);
 746     /// some fields will be missing, like authority, editall
 747     /*
 748     return get_records_sql("SELECT u.id, u.username, u.firstname, u.lastname, u.maildisplay, u.mailformat, u.maildigest,
 749                                    u.email, u.city, u.country, u.lastlogin, u.picture, u.lang, u.timezone,
 750                                    u.emailstop, t.authority,t.role,t.editall,t.timeaccess as lastaccess
 751                             FROM {$CFG->prefix}user u,
 752                                  {$CFG->prefix}user_teachers t
 753                             WHERE t.course = '$courseid' AND t.userid = u.id
 754                               AND u.deleted = '0' AND u.confirmed = '1' $exceptions $sort");
 755     */
 756 }
 757
 758 /**
 759  * Returns all the users of a course: students and teachers
 760  *
 761  * @param int $courseid The course in question.
 762  * @param string $sort ?
 763  * @param string $exceptions ?
 764  * @param string $fields A comma separated list of fields to be returned from the chosen table.
 765  * @return object
 766  * @todo Finish documenting this function
 767  */
 768 function get_course_users($courseid, $sort='ul.timeaccess DESC', $exceptions='', $fields='') {
 769     global $CFG;
 770
 771     $context = get_context_instance(CONTEXT_COURSE, $courseid);
 772
 773     /// If the course id is the SITEID, we need to return all the users if the "defaultuserroleid"
 774     /// has the capbility of accessing the site course. $CFG->nodefaultuserrolelists set to true can
 775     /// over-rule using this.
 776     if (($courseid == SITEID) && !empty($CFG->defaultuserroleid) && empty($CFG->nodefaultuserrolelists)) {
 777         if ($roles = get_roles_with_capability('moodle/course:view', CAP_ALLOW, $context)) {
 778             $hascap = false;
 779             foreach ($roles as $role) {
 780                 if ($role->id == $CFG->defaultuserroleid) {
 781                     $hascap = true;
 782                     break;
 783                 }
 784             }
 785             if ($hascap) {
 786                 if (empty($fields)) {
 787                     $fields = '*';
 788                 }
 789                 return get_users(true, '', true, $exceptions, 'lastname ASC', '', '', '', '', $fields);
 790             }
 791         }
 792     }
 793     return get_users_by_capability($context, 'moodle/course:view', 'u.*, ul.timeaccess as lastaccess', $sort, '','','',$exceptions, false);
 794
 795 }
 796
 797 /**
 798  * Returns an array of user objects
 799  *
 800  * @uses $CFG
 801  * @param int $groupid The group(s) in question.
 802  * @param string $sort How to sort the results
 803  * @return object (changed to groupids)
 804  */
 805 function get_group_students($groupids, $sort='ul.timeaccess DESC') {
 806
 807     if (is_array($groupids)){
 808         $groups = $groupids;
 809         // all groups must be from one course anyway...
 810         $group = groups_get_group(array_shift($groups));
 811     } else {
 812         $group = groups_get_group($groupids);
 813     }
 814     if (!$group) {
 815         return NULL;
 816     }
 817
 818     $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
 819     return get_users_by_capability($context, 'moodle/legacy:student', 'u.*, ul.timeaccess as lastaccess', $sort, '','',$groupids, '', false);
 820 }
 821
 822 /**
 823  * Returns list of all the teachers who can access a group
 824  *
 825  * @uses $CFG
 826  * @param int $courseid The course in question.
 827  * @param int $groupid The group in question.
 828  * @return object
 829  */
 830 function get_group_teachers($courseid, $groupid) {
 831 /// Returns a list of all the teachers who can access a group
 832     if ($teachers = get_course_teachers($courseid)) {
 833         foreach ($teachers as $key => $teacher) {
 834             if ($teacher->editall) {             // These can access anything
 835                 continue;
 836             }
 837             if (($teacher->authority > 0) and ismember($groupid, $teacher->id)) {  // Specific group teachers
 838                 continue;
 839             }
 840             unset($teachers[$key]);
 841         }
 842     }
 843     return $teachers;
 844 }
 845
 846
 847
 848 ########### FROM weblib.php ##########################################################################
 849
 850
 851 /**
 852  * Print a message in a standard themed box.
 853  * This old function used to implement boxes using tables.  Now it uses a DIV, but the old
 854  * parameters remain.  If possible, $align, $width and $color should not be defined at all.
 855  * Preferably just use print_box() in weblib.php
 856  *
 857  * @param string $align, alignment of the box, not the text (default center, left, right).
 858  * @param string $width, width of the box, including units %, for example '100%'.
 859  * @param string $color, background colour of the box, for example '#eee'.
 860  * @param int $padding, padding in pixels, specified without units.
 861  * @param string $class, space-separated class names.
 862  * @param string $id, space-separated id names.
 863  * @param boolean $return, return as string or just print it
 864  */
 865 function print_simple_box($message, $align='', $width='', $color='', $padding=5, $class='generalbox', $id='', $return=false) {
 866     $output = '';
 867     $output .= print_simple_box_start($align, $width, $color, $padding, $class, $id, true);
 868     $output .= stripslashes_safe($message);
 869     $output .= print_simple_box_end(true);
 870
 871     if ($return) {
 872         return $output;
 873     } else {
 874         echo $output;
 875     }
 876 }
 877
 878
 879
 880 /**
 881  * This old function used to implement boxes using tables.  Now it uses a DIV, but the old
 882  * parameters remain.  If possible, $align, $width and $color should not be defined at all.
 883  * Even better, please use print_box_start() in weblib.php
 884  *
 885  * @param string $align, alignment of the box, not the text (default center, left, right).   DEPRECATED
 886  * @param string $width, width of the box, including % units, for example '100%'.            DEPRECATED
 887  * @param string $color, background colour of the box, for example '#eee'.                   DEPRECATED
 888  * @param int $padding, padding in pixels, specified without units.                          OBSOLETE
 889  * @param string $class, space-separated class names.
 890  * @param string $id, space-separated id names.
 891  * @param boolean $return, return as string or just print it
 892  */
 893 function print_simple_box_start($align='', $width='', $color='', $padding=5, $class='generalbox', $id='', $return=false) {
 894
 895     $output = '';
 896
 897     $divclasses = 'box '.$class.' '.$class.'content';
 898     $divstyles  = '';
 899
 900     if ($align) {
 901         $divclasses .= ' boxalign'.$align;    // Implement alignment using a class
 902     }
 903     if ($width) {    // Hopefully we can eliminate these in calls to this function (inline styles are bad)
 904         if (substr($width, -1, 1) == '%') {    // Width is a % value
 905             $width = (int) substr($width, 0, -1);    // Extract just the number
 906             if ($width < 40) {
 907                 $divclasses .= ' boxwidthnarrow';    // Approx 30% depending on theme
 908             } else if ($width > 60) {
 909                 $divclasses .= ' boxwidthwide';      // Approx 80% depending on theme
 910             } else {
 911                 $divclasses .= ' boxwidthnormal';    // Approx 50% depending on theme
 912             }
 913         } else {
 914             $divstyles  .= ' width:'.$width.';';     // Last resort
 915         }
 916     }
 917     if ($color) {    // Hopefully we can eliminate these in calls to this function (inline styles are bad)
 918         $divstyles  .= ' background:'.$color.';';
 919     }
 920     if ($divstyles) {
 921         $divstyles = ' style="'.$divstyles.'"';
 922     }
 923
 924     if ($id) {
 925         $id = ' id="'.$id.'"';
 926     }
 927
 928     $output .= '<div'.$id.$divstyles.' class="'.$divclasses.'">';
 929
 930     if ($return) {
 931         return $output;
 932     } else {
 933         echo $output;
 934     }
 935 }
 936
 937
 938 /**
 939  * Print the end portion of a standard themed box.
 940  * Preferably just use print_box_end() in weblib.php
 941  */
 942 function print_simple_box_end($return=false) {
 943     $output = '</div>';
 944     if ($return) {
 945         return $output;
 946     } else {
 947         echo $output;
 948     }
 949 }
 950
 951 /**
 952  * deprecated - use clean_param($string, PARAM_FILE); instead
 953  * Check for bad characters ?
 954  *
 955  * @param string $string ?
 956  * @param int $allowdots ?
 957  * @todo Finish documenting this function - more detail needed in description as well as details on arguments
 958  */
 959 function detect_munged_arguments($string, $allowdots=1) {
 960     if (substr_count($string, '..') > $allowdots) {   // Sometimes we allow dots in references
 961         return true;
 962     }
 963     if (ereg('[\|\`]', $string)) {  // check for other bad characters
 964         return true;
 965     }
 966     if (empty($string) or $string == '/') {
 967         return true;
 968     }
 969
 970     return false;
 971 }
 972
 973 /** Deprecated function - returns the code of the current charset - originally depended on the selected language pack.
 974  *
 975  * @param $ignorecache not used anymore
 976  * @return string always returns 'UTF-8'
 977  */
 978 function current_charset($ignorecache = false) {
 979     return 'UTF-8';
 980 }
 981
 982
 983 /////////////////////////////////////////////////////////////
 984 /// Old functions not used anymore - candidates for removal
 985 /////////////////////////////////////////////////////////////
 986
 987 /**
 988  * Load a template from file - this function dates back to Moodle 1 :-) not used anymore
 989  *
 990  * Returns a (big) string containing the contents of a template file with all
 991  * the variables interpolated.  all the variables must be in the $var[] array or
 992  * object (whatever you decide to use).
 993  *
 994  * <b>WARNING: do not use this on big files!!</b>
 995  *
 996  * @param string $filename Location on the server's filesystem where template can be found.
 997  * @param mixed $var Passed in by reference. An array or object which will be loaded with data from the template file.
 998  *
 999  */
1000 function read_template($filename, &$var) {
1001
1002     $temp = str_replace("\\", "\\\\", implode(file($filename), ''));
1003     $temp = str_replace('"', '\"', $temp);
1004     eval("\$template = \"$temp\";");
1005     return $template;
1006 }
1007
1008
1009 /**
1010  * deprecated - relies on register globals; use new formslib instead
1011  *
1012  * Set a variable's value depending on whether or not it already has a value.
1013  *
1014  * If variable is set, set it to the set_value otherwise set it to the
1015  * unset_value.  used to handle checkboxes when you are expecting them from
1016  * a form
1017  *
1018  * @param mixed $var Passed in by reference. The variable to check.
1019  * @param mixed $set_value The value to set $var to if $var already has a value.
1020  * @param mixed $unset_value The value to set $var to if $var does not already have a value.
1021  */
1022 function checked(&$var, $set_value = 1, $unset_value = 0) {
1023
1024     if (empty($var)) {
1025         $var = $unset_value;
1026     } else {
1027         $var = $set_value;
1028     }
1029 }
1030
1031 /**
1032  * deprecated - use new formslib instead
1033  *
1034  * Prints the word "checked" if a variable is true, otherwise prints nothing,
1035  * used for printing the word "checked" in a checkbox form element.
1036  *
1037  * @param boolean $var Variable to be checked for true value
1038  * @param string $true_value Value to be printed if $var is true
1039  * @param string $false_value Value to be printed if $var is false
1040  */
1041 function frmchecked(&$var, $true_value = 'checked', $false_value = '') {
1042
1043     if ($var) {
1044         echo $true_value;
1045     } else {
1046         echo $false_value;
1047     }
1048 }
1049
1050 /**
1051  * Legacy function, provided for backward compatability.
1052  * This method now simply calls {@link use_html_editor()}
1053  *
1054  * @deprecated Use {@link use_html_editor()} instead.
1055  * @param string $name Form element to replace with HTMl editor by name
1056  * @todo Finish documenting this function
1057  */
1058 function print_richedit_javascript($form, $name, $source='no') {
1059     use_html_editor($name);
1060 }
1061
1062
1063
1064 ?>