source: moodle/trunk/fuentes/lib/classes/user.php

Last change on this file was 1331, checked in by jrpelegrina, 3 years ago

Updated to moodle 3.0.3

File size: 14.8 KB
Line 
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 * 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 */
24
25defined('MOODLE_INTERNAL') || die();
26
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 */
35class core_user {
36    /**
37     * No reply user id.
38     */
39    const NOREPLY_USER = -10;
40
41    /**
42     * Support user id.
43     */
44    const SUPPORT_USER = -20;
45
46    /** @var stdClass keep record of noreply user */
47    public static $noreplyuser = false;
48
49    /** @var stdClass keep record of support user */
50    public static $supportuser = false;
51
52    /** @var array store user fields properties cache. */
53    protected static $propertiescache = null;
54
55    /**
56     * Return user object from db or create noreply or support user,
57     * if userid matches corse_user::NOREPLY_USER or corse_user::SUPPORT_USER
58     * respectively. If userid is not found, then return false.
59     *
60     * @param int $userid user id
61     * @param string $fields A comma separated list of user fields to be returned, support and noreply user
62     *                       will not be filtered by this.
63     * @param int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
64     *                        IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended);
65     *                        MUST_EXIST means throw an exception if no user record or multiple records found.
66     * @return stdClass|bool user record if found, else false.
67     * @throws dml_exception if user record not found and respective $strictness is set.
68     */
69    public static function get_user($userid, $fields = '*', $strictness = IGNORE_MISSING) {
70        global $DB;
71
72        // If noreply user then create fake record and return.
73        switch ($userid) {
74            case self::NOREPLY_USER:
75                return self::get_noreply_user();
76                break;
77            case self::SUPPORT_USER:
78                return self::get_support_user();
79                break;
80            default:
81                return $DB->get_record('user', array('id' => $userid), $fields, $strictness);
82        }
83    }
84
85
86    /**
87     * Return user object from db based on their username.
88     *
89     * @param string $username The username of the user searched.
90     * @param string $fields A comma separated list of user fields to be returned, support and noreply user.
91     * @param int $mnethostid The id of the remote host.
92     * @param int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
93     *                        IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended);
94     *                        MUST_EXIST means throw an exception if no user record or multiple records found.
95     * @return stdClass|bool user record if found, else false.
96     * @throws dml_exception if user record not found and respective $strictness is set.
97     */
98    public static function get_user_by_username($username, $fields = '*', $mnethostid = null, $strictness = IGNORE_MISSING) {
99        global $DB, $CFG;
100
101        // Because we use the username as the search criteria, we must also restrict our search based on mnet host.
102        if (empty($mnethostid)) {
103            // If empty, we restrict to local users.
104            $mnethostid = $CFG->mnet_localhost_id;
105        }
106
107        return $DB->get_record('user', array('username' => $username, 'mnethostid' => $mnethostid), $fields, $strictness);
108    }
109
110    /**
111     * Helper function to return dummy noreply user record.
112     *
113     * @return stdClass
114     */
115    protected static function get_dummy_user_record() {
116        global $CFG;
117
118        $dummyuser = new stdClass();
119        $dummyuser->id = self::NOREPLY_USER;
120        $dummyuser->email = $CFG->noreplyaddress;
121        $dummyuser->firstname = get_string('noreplyname');
122        $dummyuser->username = 'noreply';
123        $dummyuser->lastname = '';
124        $dummyuser->confirmed = 1;
125        $dummyuser->suspended = 0;
126        $dummyuser->deleted = 0;
127        $dummyuser->picture = 0;
128        $dummyuser->auth = 'manual';
129        $dummyuser->firstnamephonetic = '';
130        $dummyuser->lastnamephonetic = '';
131        $dummyuser->middlename = '';
132        $dummyuser->alternatename = '';
133        $dummyuser->imagealt = '';
134        return $dummyuser;
135    }
136
137    /**
138     * Return noreply user record, this is currently used in messaging
139     * system only for sending messages from noreply email.
140     * It will return record of $CFG->noreplyuserid if set else return dummy
141     * user object with hard-coded $user->emailstop = 1 so noreply can be sent to user.
142     *
143     * @return stdClass user record.
144     */
145    public static function get_noreply_user() {
146        global $CFG;
147
148        if (!empty(self::$noreplyuser)) {
149            return self::$noreplyuser;
150        }
151
152        // If noreply user is set then use it, else create one.
153        if (!empty($CFG->noreplyuserid)) {
154            self::$noreplyuser = self::get_user($CFG->noreplyuserid);
155        }
156
157        if (empty(self::$noreplyuser)) {
158            self::$noreplyuser = self::get_dummy_user_record();
159            self::$noreplyuser->maildisplay = '1'; // Show to all.
160        }
161        self::$noreplyuser->emailstop = 1; // Force msg stop for this user.
162        return self::$noreplyuser;
163    }
164
165    /**
166     * Return support user record, this is currently used in messaging
167     * system only for sending messages to support email.
168     * $CFG->supportuserid is set then returns user record
169     * $CFG->supportemail is set then return dummy record with $CFG->supportemail
170     * else return admin user record with hard-coded $user->emailstop = 0, so user
171     * gets support message.
172     *
173     * @return stdClass user record.
174     */
175    public static function get_support_user() {
176        global $CFG;
177
178        if (!empty(self::$supportuser)) {
179            return self::$supportuser;
180        }
181
182        // If custom support user is set then use it, else if supportemail is set then use it, else use noreply.
183        if (!empty($CFG->supportuserid)) {
184            self::$supportuser = self::get_user($CFG->supportuserid, '*', MUST_EXIST);
185        }
186
187        // Try sending it to support email if support user is not set.
188        if (empty(self::$supportuser) && !empty($CFG->supportemail)) {
189            self::$supportuser = self::get_dummy_user_record();
190            self::$supportuser->id = self::SUPPORT_USER;
191            self::$supportuser->email = $CFG->supportemail;
192            if ($CFG->supportname) {
193                self::$supportuser->firstname = $CFG->supportname;
194            }
195            self::$supportuser->username = 'support';
196            self::$supportuser->maildisplay = '1'; // Show to all.
197        }
198
199        // Send support msg to admin user if nothing is set above.
200        if (empty(self::$supportuser)) {
201            self::$supportuser = get_admin();
202        }
203
204        // Unset emailstop to make sure support message is sent.
205        self::$supportuser->emailstop = 0;
206        return self::$supportuser;
207    }
208
209    /**
210     * Reset self::$noreplyuser and self::$supportuser.
211     * This is only used by phpunit, and there is no other use case for this function.
212     * Please don't use it outside phpunit.
213     */
214    public static function reset_internal_users() {
215        if (PHPUNIT_TEST) {
216            self::$noreplyuser = false;
217            self::$supportuser = false;
218        } else {
219            debugging('reset_internal_users() should not be used outside phpunit.', DEBUG_DEVELOPER);
220        }
221    }
222
223    /**
224     * Return true is user id is greater than self::NOREPLY_USER and
225     * alternatively check db.
226     *
227     * @param int $userid user id.
228     * @param bool $checkdb if true userid will be checked in db. By default it's false, and
229     *                      userid is compared with NOREPLY_USER for performance.
230     * @return bool true is real user else false.
231     */
232    public static function is_real_user($userid, $checkdb = false) {
233        global $DB;
234
235        if ($userid < 0) {
236            return false;
237        }
238        if ($checkdb) {
239            return $DB->record_exists('user', array('id' => $userid));
240        } else {
241            return true;
242        }
243    }
244
245    /**
246     * Check if the given user is an active user in the site.
247     *
248     * @param  stdClass  $user         user object
249     * @param  boolean $checksuspended whether to check if the user has the account suspended
250     * @param  boolean $checknologin   whether to check if the user uses the nologin auth method
251     * @throws moodle_exception
252     * @since  Moodle 3.0
253     */
254    public static function require_active_user($user, $checksuspended = false, $checknologin = false) {
255
256        if (!self::is_real_user($user->id)) {
257            throw new moodle_exception('invaliduser', 'error');
258        }
259
260        if ($user->deleted) {
261            throw new moodle_exception('userdeleted');
262        }
263
264        if (empty($user->confirmed)) {
265            throw new moodle_exception('usernotconfirmed', 'moodle', '', $user->username);
266        }
267
268        if (isguestuser($user)) {
269            throw new moodle_exception('guestsarenotallowed', 'error');
270        }
271
272        if ($checksuspended and $user->suspended) {
273            throw new moodle_exception('suspended', 'auth');
274        }
275
276        if ($checknologin and $user->auth == 'nologin') {
277            throw new moodle_exception('suspended', 'auth');
278        }
279    }
280
281    /**
282     * Definition of user profile fields and the expected parameter type for data validation.
283     *
284     * @return void
285     */
286    protected static function fill_properties_cache() {
287
288        if (self::$propertiescache !== null) {
289            return;
290        }
291
292        // Array of user fields properties and expected parameters.
293        // Every new field on the user table should be added here otherwise it won't be validated.
294        $fields = array();
295        $fields['id'] = array('type' => PARAM_INT);
296        $fields['auth'] = array('type' => PARAM_NOTAGS);
297        $fields['confirmed'] = array('type' => PARAM_BOOL);
298        $fields['policyagreed'] = array('type' => PARAM_BOOL);
299        $fields['deleted'] = array('type' => PARAM_BOOL);
300        $fields['suspended'] = array('type' => PARAM_BOOL);
301        $fields['mnethostid'] = array('type' => PARAM_BOOL);
302        $fields['username'] = array('type' => PARAM_USERNAME);
303        $fields['password'] = array('type' => PARAM_NOTAGS);
304        $fields['idnumber'] = array('type' => PARAM_NOTAGS);
305        $fields['firstname'] = array('type' => PARAM_NOTAGS);
306        $fields['lastname'] = array('type' => PARAM_NOTAGS);
307        $fields['surname'] = array('type' => PARAM_NOTAGS);
308        $fields['email'] = array('type' => PARAM_RAW_TRIMMED);
309        $fields['emailstop'] = array('type' => PARAM_INT);
310        $fields['icq'] = array('type' => PARAM_NOTAGS);
311        $fields['skype'] = array('type' => PARAM_NOTAGS);
312        $fields['aim'] = array('type' => PARAM_NOTAGS);
313        $fields['yahoo'] = array('type' => PARAM_NOTAGS);
314        $fields['msn'] = array('type' => PARAM_NOTAGS);
315        $fields['phone1'] = array('type' => PARAM_NOTAGS);
316        $fields['phone2'] = array('type' => PARAM_NOTAGS);
317        $fields['institution'] = array('type' => PARAM_TEXT);
318        $fields['department'] = array('type' => PARAM_TEXT);
319        $fields['address'] = array('type' => PARAM_TEXT);
320        $fields['city'] = array('type' => PARAM_TEXT);
321        $fields['country'] = array('type' => PARAM_TEXT);
322        $fields['lang'] = array('type' => PARAM_TEXT);
323        $fields['calendartype'] = array('type' => PARAM_NOTAGS);
324        $fields['theme'] = array('type' => PARAM_NOTAGS);
325        $fields['timezones'] = array('type' => PARAM_TEXT);
326        $fields['firstaccess'] = array('type' => PARAM_INT);
327        $fields['lastaccess'] = array('type' => PARAM_INT);
328        $fields['lastlogin'] = array('type' => PARAM_INT);
329        $fields['currentlogin'] = array('type' => PARAM_INT);
330        $fields['lastip'] = array('type' => PARAM_NOTAGS);
331        $fields['secret'] = array('type' => PARAM_TEXT);
332        $fields['picture'] = array('type' => PARAM_INT);
333        $fields['url'] = array('type' => PARAM_URL);
334        $fields['description'] = array('type' => PARAM_CLEANHTML);
335        $fields['descriptionformat'] = array('type' => PARAM_INT);
336        $fields['mailformat'] = array('type' => PARAM_INT);
337        $fields['maildigest'] = array('type' => PARAM_INT);
338        $fields['maildisplay'] = array('type' => PARAM_INT);
339        $fields['autosubscribe'] = array('type' => PARAM_INT);
340        $fields['trackforums'] = array('type' => PARAM_INT);
341        $fields['timecreated'] = array('type' => PARAM_INT);
342        $fields['timemodified'] = array('type' => PARAM_INT);
343        $fields['trustbitmask'] = array('type' => PARAM_INT);
344        $fields['imagealt'] = array('type' => PARAM_TEXT);
345        $fields['lastnamephonetic'] = array('type' => PARAM_NOTAGS);
346        $fields['firstnamephonetic'] = array('type' => PARAM_NOTAGS);
347        $fields['middlename'] = array('type' => PARAM_NOTAGS);
348        $fields['alternatename'] = array('type' => PARAM_NOTAGS);
349
350        self::$propertiescache = $fields;
351    }
352
353    /**
354     * Get properties of a user field.
355     *
356     * @param string $property property name to be retrieved.
357     * @throws coding_exception if the requested property name is invalid.
358     * @return array the property definition.
359     */
360    public static function get_property_definition($property) {
361
362        self::fill_properties_cache();
363
364        if (!array_key_exists($property, self::$propertiescache)) {
365            throw new coding_exception('Invalid property requested.');
366        }
367
368        return self::$propertiescache[$property];
369    }
370
371    /**
372     * Clean the properties cache.
373     *
374     * During unit tests we need to be able to reset all caches so that each new test starts in a known state.
375     * Intended for use only for testing, phpunit calls this before every test.
376     */
377    public static function reset_caches() {
378        self::$propertiescache = null;
379    }
380}
Note: See TracBrowser for help on using the repository browser.