Development:Do we need named parameters: Difference between revisions
No edit summary |
No edit summary |
||
Line 148: | Line 148: | ||
} | } | ||
} | } | ||
</code> | |||
== Web Services / Moodle API== | |||
This is just a note about web services, not really related to this page. It will need to be moved somewhere else. | |||
<code php> | |||
final class user_api extends moodle_api { | |||
/** | |||
* Constructor - We set the description of this API in order to be access by Web service | |||
*/ | |||
function __construct () { | |||
$this->descriptions = array(); | |||
$this->descriptions['get_users'] = array( 'wsparams' => array('search'=> PARAM_ALPHA), | |||
'return' => array('users' => PARAM_RAW), | |||
'paramorder' => array('get', 'search', 'confirmed', 'exceptions', 'sort', | |||
'firstinitial', 'lastinitial', 'page', 'recordsperpage', 'fields', 'extraselect', 'extraparams'), | |||
'paramdefaultvalues' => array(true, '', false, null, 'firstname ASC', | |||
'', '', '', '', 'id, username', '', null)); | |||
} | |||
/** | |||
* Returns a subset of users | |||
* ... | |||
*/ | |||
function get_users($get=true, $search='', $confirmed=false, array $exceptions=null, $sort='firstname ASC', | |||
... | |||
} | |||
} | |||
</code> | |||
<code php> | |||
<?php | |||
/* | |||
* Moodle API base class | |||
*/ | |||
abstract class moodle_api { | |||
protected $descriptions; | |||
/** | |||
* Constructor - We set the description of this API in order to be access by Web service | |||
*/ | |||
function __construct () { | |||
$this->descriptions = array(); | |||
} | |||
/** | |||
* Get description of a web service function | |||
* @param <type> $functionname | |||
*/ | |||
function get_function_webservice_description($functionname) { | |||
if (key_exists($functionname, $this->descriptions)) { | |||
return $this->descriptions[$functionname]; | |||
} | |||
else { | |||
return false; | |||
} | |||
} | |||
} | |||
?> | |||
</code> | </code> |
Revision as of 08:59, 28 November 2008
Many Moodle functions end up to have 4 or (a lot) more parameters. It could be good to study if we could group most of these parameters into an object. Following a refactor of datalib.php/get_users()
//named parameters function call
$parameters = new object();
$parameters->search = 'arthur';
namedparams_get_users($parameters, 'firstname ASC', , $fields='id, username');
//current function call
get_users(true, 'arthur', false, null, 'firstname ASC', , , , , 'id, username');
/**
* Returns a subset of users (DO NOT COUNT)
* @global object $DB
* @param object $parameters:
* ->get bool If false then only a count of the records is returned
* ->search string A simple string to search for
* ->confirmed bool A switch to allow/disallow unconfirmed users
* ->exceptions array(int) A list of IDs to ignore, eg 2,4,5,8,9,10
* ->sort string A SQL snippet for the sorting criteria to use
* ->firstinitial string ?
* ->lastinitial string ?
* ->recordsperpage string ?
* @param string $sort A SQL snippet for the sorting criteria to use
* @param string $page ?
* @param string $fields A comma separated list of fields to be returned from the chosen table.
* @return object|false|int {@link $USER} records. False is returned if an error is encountered.
*/
function namedparams_get_users($parameters, $sort='firstname ASC', $page=, $fields='*') {
global $DB;
if (empty($parameters->recordsperpage)){
$parameters->recordsperpage=;
}
$LIKE = $DB->sql_ilike();
$fullname = $DB->sql_fullname();
$select = " username <> :guest AND deleted = 0";
$params = array('guest'=>'guest');
if (!empty($parameters->search)){
$parameters->search = trim($parameters->search);
$select .= " AND ($fullname $LIKE :search1 OR email $LIKE :search2 OR username = :search3)";
$params['search1'] = "%".$parameters->search."%";
$params['search2'] = "%".$parameters->search."%";
$params['search3'] = $parameters->search;
}
if (!empty($parameters->confirmed)) {
$select .= " AND confirmed = 1";
}
if (!empty($parameters->exceptions)) {
list($parameters->exceptions, $eparams) = $DB->get_in_or_equal($parameters->exceptions, SQL_PARAMS_NAMED, 'ex0000', false);
$params = $params + $eparams;
$except = " AND id ".$parameters->exceptions;
}
if (!empty($parameters->firstinitial)) {
$select .= " AND firstname $LIKE :fni";
$params['fni'] = $parameters->firstinitial."%";
}
if (!empty($parameters->lastinitial)) {
$select .= " AND lastname $LIKE :lni";
$params['lni'] = $parameters->lastinitial."%";
}
if (!empty($parameters->extraselect)) {
$select .= " AND ".$parameters->extraselect;
if (empty($parameters->extraparams)){
$params = $params + (array)$parameters->extraparams;
}
}
return $DB->get_records_select('user', $select, $params, $sort, $fields, $page, $parameters->recordsperpage);
}
/**
* Returns a subset of users
*
* @uses $CFG
* @param bool $get If false then only a count of the records is returned
* @param string $search A simple string to search for
* @param bool $confirmed A switch to allow/disallow unconfirmed users
* @param array(int) $exceptions A list of IDs to ignore, eg 2,4,5,8,9,10
* @param string $sort A SQL snippet for the sorting criteria to use
* @param string $firstinitial ?
* @param string $lastinitial ?
* @param string $page ?
* @param string $recordsperpage ?
* @param string $fields A comma separated list of fields to be returned from the chosen table.
* @return object|false|int {@link $USER} records unless get is false in which case the integer count of the records found is returned. False is returned if an error is encountered.
*/
function get_users($get=true, $search=, $confirmed=false, array $exceptions=null, $sort='firstname ASC',
$firstinitial=, $lastinitial=, $page=, $recordsperpage=, $fields='*', $extraselect=, array $extraparams=null) {
global $DB;
if ($get && !$recordsperpage) {
debugging('Call to get_users with $get = true no $recordsperpage limit. ' .
'On large installations, this will probably cause an out of memory error. ' .
'Please think again and change your code so that it does not try to ' .
'load so much data into memory.', DEBUG_DEVELOPER);
}
$LIKE = $DB->sql_ilike();
$fullname = $DB->sql_fullname();
$select = " username <> :guest AND deleted = 0";
$params = array('guest'=>'guest');
if (!empty($search)){
$search = trim($search);
$select .= " AND ($fullname $LIKE :search1 OR email $LIKE :search2 OR username = :search3)";
$params['search1'] = "%$search%";
$params['search2'] = "%$search%";
$params['search3'] = "$search";
}
if ($confirmed) {
$select .= " AND confirmed = 1";
}
if ($exceptions) {
list($exceptions, $eparams) = $DB->get_in_or_equal($exceptions, SQL_PARAMS_NAMED, 'ex0000', false);
$params = $params + $eparams;
$except = " AND id $exceptions";
}
if ($firstinitial) {
$select .= " AND firstname $LIKE :fni";
$params['fni'] = "$firstinitial%";
}
if ($lastinitial) {
$select .= " AND lastname $LIKE :lni";
$params['lni'] = "$lastinitial%";
}
if ($extraselect) {
$select .= " AND $extraselect";
$params = $params + (array)$extraparams;
}
if ($get) {
return $DB->get_records_select('user', $select, $params, $sort, $fields, $page, $recordsperpage);
} else {
return $DB->count_records_select('user', $select, $params);
}
}
Web Services / Moodle API
This is just a note about web services, not really related to this page. It will need to be moved somewhere else.
final class user_api extends moodle_api {
/**
* Constructor - We set the description of this API in order to be access by Web service
*/
function __construct () {
$this->descriptions = array();
$this->descriptions['get_users'] = array( 'wsparams' => array('search'=> PARAM_ALPHA),
'return' => array('users' => PARAM_RAW),
'paramorder' => array('get', 'search', 'confirmed', 'exceptions', 'sort',
'firstinitial', 'lastinitial', 'page', 'recordsperpage', 'fields', 'extraselect', 'extraparams'),
'paramdefaultvalues' => array(true, , false, null, 'firstname ASC',
, , , , 'id, username', , null));
}
/**
* Returns a subset of users
* ...
*/
function get_users($get=true, $search=, $confirmed=false, array $exceptions=null, $sort='firstname ASC',
...
}
}
<?php
/*
* Moodle API base class
*/
abstract class moodle_api {
protected $descriptions;
/**
* Constructor - We set the description of this API in order to be access by Web service
*/
function __construct () {
$this->descriptions = array();
}
/**
* Get description of a web service function
* @param <type> $functionname
*/
function get_function_webservice_description($functionname) {
if (key_exists($functionname, $this->descriptions)) {
return $this->descriptions[$functionname];
}
else {
return false;
}
}
}
?>