Merge branch 'MDL-52597-29' of git://github.com/andrewnicols/moodle into MOODLE_29_STABLE
[moodle.git] / user / filters / lib.php
blob2d6c04a0cfff94b6e1e9a147e71808206f6b92e2
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.
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 * This file contains the User Filter API.
20 * @package core_user
21 * @category user
22 * @copyright 1999 Martin Dougiamas http://dougiamas.com
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26 require_once($CFG->dirroot.'/user/filters/text.php');
27 require_once($CFG->dirroot.'/user/filters/date.php');
28 require_once($CFG->dirroot.'/user/filters/select.php');
29 require_once($CFG->dirroot.'/user/filters/simpleselect.php');
30 require_once($CFG->dirroot.'/user/filters/courserole.php');
31 require_once($CFG->dirroot.'/user/filters/globalrole.php');
32 require_once($CFG->dirroot.'/user/filters/profilefield.php');
33 require_once($CFG->dirroot.'/user/filters/yesno.php');
34 require_once($CFG->dirroot.'/user/filters/cohort.php');
35 require_once($CFG->dirroot.'/user/filters/user_filter_forms.php');
36 require_once($CFG->dirroot.'/user/filters/checkbox.php');
38 /**
39 * User filtering wrapper class.
41 * @copyright 1999 Martin Dougiamas http://dougiamas.com
42 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
44 class user_filtering {
45 /** @var array */
46 public $_fields;
47 /** @var \user_add_filter_form */
48 public $_addform;
49 /** @var \user_active_filter_form */
50 public $_activeform;
52 /**
53 * Contructor
54 * @param array $fieldnames array of visible user fields
55 * @param string $baseurl base url used for submission/return, null if the same of current page
56 * @param array $extraparams extra page parameters
58 public function user_filtering($fieldnames = null, $baseurl = null, $extraparams = null) {
59 global $SESSION;
61 if (!isset($SESSION->user_filtering)) {
62 $SESSION->user_filtering = array();
65 if (empty($fieldnames)) {
66 $fieldnames = array('realname' => 0, 'lastname' => 1, 'firstname' => 1, 'username' => 1, 'email' => 1, 'city' => 1, 'country' => 1,
67 'confirmed' => 1, 'suspended' => 1, 'profile' => 1, 'courserole' => 1, 'systemrole' => 1,
68 'cohort' => 1, 'firstaccess' => 1, 'lastaccess' => 1, 'neveraccessed' => 1, 'timemodified' => 1,
69 'nevermodified' => 1, 'auth' => 1, 'mnethostid' => 1, 'idnumber' => 1);
72 $this->_fields = array();
74 foreach ($fieldnames as $fieldname => $advanced) {
75 if ($field = $this->get_field($fieldname, $advanced)) {
76 $this->_fields[$fieldname] = $field;
80 // Fist the new filter form.
81 $this->_addform = new user_add_filter_form($baseurl, array('fields' => $this->_fields, 'extraparams' => $extraparams));
82 if ($adddata = $this->_addform->get_data()) {
83 foreach ($this->_fields as $fname => $field) {
84 $data = $field->check_data($adddata);
85 if ($data === false) {
86 continue; // Nothing new.
88 if (!array_key_exists($fname, $SESSION->user_filtering)) {
89 $SESSION->user_filtering[$fname] = array();
91 $SESSION->user_filtering[$fname][] = $data;
93 // Clear the form.
94 $_POST = array();
95 $this->_addform = new user_add_filter_form($baseurl, array('fields' => $this->_fields, 'extraparams' => $extraparams));
98 // Now the active filters.
99 $this->_activeform = new user_active_filter_form($baseurl, array('fields' => $this->_fields, 'extraparams' => $extraparams));
100 if ($adddata = $this->_activeform->get_data()) {
101 if (!empty($adddata->removeall)) {
102 $SESSION->user_filtering = array();
104 } else if (!empty($adddata->removeselected) and !empty($adddata->filter)) {
105 foreach ($adddata->filter as $fname => $instances) {
106 foreach ($instances as $i => $val) {
107 if (empty($val)) {
108 continue;
110 unset($SESSION->user_filtering[$fname][$i]);
112 if (empty($SESSION->user_filtering[$fname])) {
113 unset($SESSION->user_filtering[$fname]);
117 // Clear+reload the form.
118 $_POST = array();
119 $this->_activeform = new user_active_filter_form($baseurl, array('fields' => $this->_fields, 'extraparams' => $extraparams));
121 // Now the active filters.
125 * Creates known user filter if present
126 * @param string $fieldname
127 * @param boolean $advanced
128 * @return object filter
130 public function get_field($fieldname, $advanced) {
131 global $USER, $CFG, $DB, $SITE;
133 switch ($fieldname) {
134 case 'username': return new user_filter_text('username', get_string('username'), $advanced, 'username');
135 case 'realname': return new user_filter_text('realname', get_string('fullnameuser'), $advanced, $DB->sql_fullname());
136 case 'lastname': return new user_filter_text('lastname', get_string('lastname'), $advanced, 'lastname');
137 case 'firstname': return new user_filter_text('firstname', get_string('firstname'), $advanced, 'firstname');
138 case 'email': return new user_filter_text('email', get_string('email'), $advanced, 'email');
139 case 'city': return new user_filter_text('city', get_string('city'), $advanced, 'city');
140 case 'country': return new user_filter_select('country', get_string('country'), $advanced, 'country', get_string_manager()->get_list_of_countries(), $USER->country);
141 case 'confirmed': return new user_filter_yesno('confirmed', get_string('confirmed', 'admin'), $advanced, 'confirmed');
142 case 'suspended': return new user_filter_yesno('suspended', get_string('suspended', 'auth'), $advanced, 'suspended');
143 case 'profile': return new user_filter_profilefield('profile', get_string('profilefields', 'admin'), $advanced);
144 case 'courserole': return new user_filter_courserole('courserole', get_string('courserole', 'filters'), $advanced);
145 case 'systemrole': return new user_filter_globalrole('systemrole', get_string('globalrole', 'role'), $advanced);
146 case 'firstaccess': return new user_filter_date('firstaccess', get_string('firstaccess', 'filters'), $advanced, 'firstaccess');
147 case 'lastaccess': return new user_filter_date('lastaccess', get_string('lastaccess'), $advanced, 'lastaccess');
148 case 'neveraccessed': return new user_filter_checkbox('neveraccessed', get_string('neveraccessed', 'filters'), $advanced, 'firstaccess', array('lastaccess_sck', 'lastaccess_eck', 'firstaccess_eck', 'firstaccess_sck'));
149 case 'timemodified': return new user_filter_date('timemodified', get_string('lastmodified'), $advanced, 'timemodified');
150 case 'nevermodified': return new user_filter_checkbox('nevermodified', get_string('nevermodified', 'filters'), $advanced, array('timemodified', 'timecreated'), array('timemodified_sck', 'timemodified_eck'));
151 case 'cohort': return new user_filter_cohort($advanced);
152 case 'idnumber': return new user_filter_text('idnumber', get_string('idnumber'), $advanced, 'idnumber');
153 case 'auth':
154 $plugins = core_component::get_plugin_list('auth');
155 $choices = array();
156 foreach ($plugins as $auth => $unused) {
157 $choices[$auth] = get_string('pluginname', "auth_{$auth}");
159 return new user_filter_simpleselect('auth', get_string('authentication'), $advanced, 'auth', $choices);
161 case 'mnethostid':
162 // Include all hosts even those deleted or otherwise problematic.
163 if (!$hosts = $DB->get_records('mnet_host', null, 'id', 'id, wwwroot, name')) {
164 $hosts = array();
166 $choices = array();
167 foreach ($hosts as $host) {
168 if ($host->id == $CFG->mnet_localhost_id) {
169 $choices[$host->id] = format_string($SITE->fullname).' ('.get_string('local').')';
170 } else if (empty($host->wwwroot)) {
171 // All hosts.
172 continue;
173 } else {
174 $choices[$host->id] = $host->name.' ('.$host->wwwroot.')';
177 if ($usedhosts = $DB->get_fieldset_sql("SELECT DISTINCT mnethostid FROM {user} WHERE deleted=0")) {
178 foreach ($usedhosts as $hostid) {
179 if (empty($hosts[$hostid])) {
180 $choices[$hostid] = 'id: '.$hostid.' ('.get_string('error').')';
184 if (count($choices) < 2) {
185 return null; // Filter not needed.
187 return new user_filter_simpleselect('mnethostid', get_string('mnetidprovider', 'mnet'), $advanced, 'mnethostid', $choices);
189 default:
190 return null;
195 * Returns sql where statement based on active user filters
196 * @param string $extra sql
197 * @param array $params named params (recommended prefix ex)
198 * @return array sql string and $params
200 public function get_sql_filter($extra='', array $params=null) {
201 global $SESSION;
203 $sqls = array();
204 if ($extra != '') {
205 $sqls[] = $extra;
207 $params = (array)$params;
209 if (!empty($SESSION->user_filtering)) {
210 foreach ($SESSION->user_filtering as $fname => $datas) {
211 if (!array_key_exists($fname, $this->_fields)) {
212 continue; // Filter not used.
214 $field = $this->_fields[$fname];
215 foreach ($datas as $i => $data) {
216 list($s, $p) = $field->get_sql_filter($data);
217 $sqls[] = $s;
218 $params = $params + $p;
223 if (empty($sqls)) {
224 return array('', array());
225 } else {
226 $sqls = implode(' AND ', $sqls);
227 return array($sqls, $params);
232 * Print the add filter form.
234 public function display_add() {
235 $this->_addform->display();
239 * Print the active filter form.
241 public function display_active() {
242 $this->_activeform->display();
248 * The base user filter class. All abstract classes must be implemented.
250 * @copyright 1999 Martin Dougiamas http://dougiamas.com
251 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
253 class user_filter_type {
255 * The name of this filter instance.
256 * @var string
258 public $_name;
261 * The label of this filter instance.
262 * @var string
264 public $_label;
267 * Advanced form element flag
268 * @var bool
270 public $_advanced;
273 * Constructor
274 * @param string $name the name of the filter instance
275 * @param string $label the label of the filter instance
276 * @param boolean $advanced advanced form element flag
278 public function user_filter_type($name, $label, $advanced) {
279 $this->_name = $name;
280 $this->_label = $label;
281 $this->_advanced = $advanced;
285 * Returns the condition to be used with SQL where
286 * @param array $data filter settings
287 * @return string the filtering condition or null if the filter is disabled
289 public function get_sql_filter($data) {
290 print_error('mustbeoveride', 'debug', '', 'get_sql_filter');
294 * Retrieves data from the form data
295 * @param stdClass $formdata data submited with the form
296 * @return mixed array filter data or false when filter not set
298 public function check_data($formdata) {
299 print_error('mustbeoveride', 'debug', '', 'check_data');
303 * Adds controls specific to this filter in the form.
304 * @param moodleform $mform a MoodleForm object to setup
306 public function setupForm(&$mform) {
307 print_error('mustbeoveride', 'debug', '', 'setupForm');
311 * Returns a human friendly description of the filter used as label.
312 * @param array $data filter settings
313 * @return string active filter label
315 public function get_label($data) {
316 print_error('mustbeoveride', 'debug', '', 'get_label');