weekly release 3.1dev
[moodle.git] / lib / classes / user.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/>.
17 /**
18  * User class
19  *
20  * @package    core
21  * @copyright  2013 Rajesh Taneja <rajesh@moodle.com>
22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 defined('MOODLE_INTERNAL') || die();
27 /**
28  * User class to access user details.
29  *
30  * @todo       move api's from user/lib.php and depreciate old ones.
31  * @package    core
32  * @copyright  2013 Rajesh Taneja <rajesh@moodle.com>
33  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
34  */
35 class core_user {
36     /**
37      * No reply user id.
38      */
39     const NOREPLY_USER = -10;
41     /**
42      * Support user id.
43      */
44     const SUPPORT_USER = -20;
46     /** @var stdClass keep record of noreply user */
47     public static $noreplyuser = false;
49     /** @var stdClass keep record of support user */
50     public static $supportuser = false;
52     /**
53      * Return user object from db or create noreply or support user,
54      * if userid matches corse_user::NOREPLY_USER or corse_user::SUPPORT_USER
55      * respectively. If userid is not found, then return false.
56      *
57      * @param int $userid user id
58      * @param string $fields A comma separated list of user fields to be returned, support and noreply user
59      *                       will not be filtered by this.
60      * @param int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
61      *                        IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended);
62      *                        MUST_EXIST means throw an exception if no user record or multiple records found.
63      * @return stdClass|bool user record if found, else false.
64      * @throws dml_exception if user record not found and respective $strictness is set.
65      */
66     public static function get_user($userid, $fields = '*', $strictness = IGNORE_MISSING) {
67         global $DB;
69         // If noreply user then create fake record and return.
70         switch ($userid) {
71             case self::NOREPLY_USER:
72                 return self::get_noreply_user();
73                 break;
74             case self::SUPPORT_USER:
75                 return self::get_support_user();
76                 break;
77             default:
78                 return $DB->get_record('user', array('id' => $userid), $fields, $strictness);
79         }
80     }
83     /**
84      * Return user object from db based on their username.
85      *
86      * @param string $username The username of the user searched.
87      * @param string $fields A comma separated list of user fields to be returned, support and noreply user.
88      * @param int $mnethostid The id of the remote host.
89      * @param int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
90      *                        IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended);
91      *                        MUST_EXIST means throw an exception if no user record or multiple records found.
92      * @return stdClass|bool user record if found, else false.
93      * @throws dml_exception if user record not found and respective $strictness is set.
94      */
95     public static function get_user_by_username($username, $fields = '*', $mnethostid = null, $strictness = IGNORE_MISSING) {
96         global $DB, $CFG;
98         // Because we use the username as the search criteria, we must also restrict our search based on mnet host.
99         if (empty($mnethostid)) {
100             // If empty, we restrict to local users.
101             $mnethostid = $CFG->mnet_localhost_id;
102         }
104         return $DB->get_record('user', array('username' => $username, 'mnethostid' => $mnethostid), $fields, $strictness);
105     }
107     /**
108      * Helper function to return dummy noreply user record.
109      *
110      * @return stdClass
111      */
112     protected static function get_dummy_user_record() {
113         global $CFG;
115         $dummyuser = new stdClass();
116         $dummyuser->id = self::NOREPLY_USER;
117         $dummyuser->email = $CFG->noreplyaddress;
118         $dummyuser->firstname = get_string('noreplyname');
119         $dummyuser->username = 'noreply';
120         $dummyuser->lastname = '';
121         $dummyuser->confirmed = 1;
122         $dummyuser->suspended = 0;
123         $dummyuser->deleted = 0;
124         $dummyuser->picture = 0;
125         $dummyuser->auth = 'manual';
126         $dummyuser->firstnamephonetic = '';
127         $dummyuser->lastnamephonetic = '';
128         $dummyuser->middlename = '';
129         $dummyuser->alternatename = '';
130         $dummyuser->imagealt = '';
131         return $dummyuser;
132     }
134     /**
135      * Return noreply user record, this is currently used in messaging
136      * system only for sending messages from noreply email.
137      * It will return record of $CFG->noreplyuserid if set else return dummy
138      * user object with hard-coded $user->emailstop = 1 so noreply can be sent to user.
139      *
140      * @return stdClass user record.
141      */
142     public static function get_noreply_user() {
143         global $CFG;
145         if (!empty(self::$noreplyuser)) {
146             return self::$noreplyuser;
147         }
149         // If noreply user is set then use it, else create one.
150         if (!empty($CFG->noreplyuserid)) {
151             self::$noreplyuser = self::get_user($CFG->noreplyuserid);
152         }
154         if (empty(self::$noreplyuser)) {
155             self::$noreplyuser = self::get_dummy_user_record();
156             self::$noreplyuser->maildisplay = '1'; // Show to all.
157         }
158         self::$noreplyuser->emailstop = 1; // Force msg stop for this user.
159         return self::$noreplyuser;
160     }
162     /**
163      * Return support user record, this is currently used in messaging
164      * system only for sending messages to support email.
165      * $CFG->supportuserid is set then returns user record
166      * $CFG->supportemail is set then return dummy record with $CFG->supportemail
167      * else return admin user record with hard-coded $user->emailstop = 0, so user
168      * gets support message.
169      *
170      * @return stdClass user record.
171      */
172     public static function get_support_user() {
173         global $CFG;
175         if (!empty(self::$supportuser)) {
176             return self::$supportuser;
177         }
179         // If custom support user is set then use it, else if supportemail is set then use it, else use noreply.
180         if (!empty($CFG->supportuserid)) {
181             self::$supportuser = self::get_user($CFG->supportuserid, '*', MUST_EXIST);
182         }
184         // Try sending it to support email if support user is not set.
185         if (empty(self::$supportuser) && !empty($CFG->supportemail)) {
186             self::$supportuser = self::get_dummy_user_record();
187             self::$supportuser->id = self::SUPPORT_USER;
188             self::$supportuser->email = $CFG->supportemail;
189             if ($CFG->supportname) {
190                 self::$supportuser->firstname = $CFG->supportname;
191             }
192             self::$supportuser->username = 'support';
193             self::$supportuser->maildisplay = '1'; // Show to all.
194         }
196         // Send support msg to admin user if nothing is set above.
197         if (empty(self::$supportuser)) {
198             self::$supportuser = get_admin();
199         }
201         // Unset emailstop to make sure support message is sent.
202         self::$supportuser->emailstop = 0;
203         return self::$supportuser;
204     }
206     /**
207      * Reset self::$noreplyuser and self::$supportuser.
208      * This is only used by phpunit, and there is no other use case for this function.
209      * Please don't use it outside phpunit.
210      */
211     public static function reset_internal_users() {
212         if (PHPUNIT_TEST) {
213             self::$noreplyuser = false;
214             self::$supportuser = false;
215         } else {
216             debugging('reset_internal_users() should not be used outside phpunit.', DEBUG_DEVELOPER);
217         }
218     }
220     /**
221      * Return true is user id is greater than self::NOREPLY_USER and
222      * alternatively check db.
223      *
224      * @param int $userid user id.
225      * @param bool $checkdb if true userid will be checked in db. By default it's false, and
226      *                      userid is compared with NOREPLY_USER for performance.
227      * @return bool true is real user else false.
228      */
229     public static function is_real_user($userid, $checkdb = false) {
230         global $DB;
232         if ($userid < 0) {
233             return false;
234         }
235         if ($checkdb) {
236             return $DB->record_exists('user', array('id' => $userid));
237         } else {
238             return true;
239         }
240     }
242     /**
243      * Check if the given user is an active user in the site.
244      *
245      * @param  stdClass  $user         user object
246      * @param  boolean $checksuspended whether to check if the user has the account suspended
247      * @param  boolean $checknologin   whether to check if the user uses the nologin auth method
248      * @throws moodle_exception
249      * @since  Moodle 3.0
250      */
251     public static function require_active_user($user, $checksuspended = false, $checknologin = false) {
253         if (!self::is_real_user($user->id)) {
254             throw new moodle_exception('invaliduser', 'error');
255         }
257         if ($user->deleted) {
258             throw new moodle_exception('userdeleted');
259         }
261         if (empty($user->confirmed)) {
262             throw new moodle_exception('usernotconfirmed', 'moodle', '', $user->username);
263         }
265         if (isguestuser($user)) {
266             throw new moodle_exception('guestsarenotallowed', 'error');
267         }
269         if ($checksuspended and $user->suspended) {
270             throw new moodle_exception('suspended', 'auth');
271         }
273         if ($checknologin and $user->auth == 'nologin') {
274             throw new moodle_exception('suspended', 'auth');
275         }
276     }