Do we need named parameters

Warning: This page is no longer in use. The information contained on the page should NOT be seen as relevant or reliable.

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 string $sort A SQL snippet for the sorting criteria to use
 * @param string $recordsperpage how many records do pages have
 * @param string $page which page to return (starts from 0)
 * @param string $fields A comma separated list of fields to be returned from the chosen table.
 * @param object $selectioncriteria:
 *      ->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
 *      ->firstinitial   string     ?
 *      ->lastinitial    string     ?
 * @return array|false Array of {@link $USER} objects. False is returned if an error is encountered.
 */
function namedparams_get_users($sort='firstname ASC', $recordsperpage=999999, $page=0, $fields='*', $selectioncriteria=NULL) {
    global $DB;

    if (empty($selectioncriteria->recordsperpage)){
        $selectioncriteria->recordsperpage='';
    }

    $LIKE      = $DB->sql_ilike();
    $fullname  = $DB->sql_fullname();

    $select = " username <> :guest AND deleted = 0";
    $params = array('guest'=>'guest');

    if (!empty($selectioncriteria->search)){
        $selectioncriteria->search = trim($selectioncriteria->search);
        $select .= " AND ($fullname $LIKE :search1 OR email $LIKE :search2 OR username = :search3)";
        $params['search1'] = "%".$selectioncriteria->search."%";
        $params['search2'] = "%".$selectioncriteria->search."%";
        $params['search3'] = $selectioncriteria->search;
    }

    if (!empty($selectioncriteria->confirmed)) {
        $select .= " AND confirmed = 1";
    }

    if (!empty($selectioncriteria->exceptions)) {
        list($selectioncriteria->exceptions, $eparams) = $DB->get_in_or_equal($selectioncriteria->exceptions, SQL_PARAMS_NAMED, 'ex0000', false);
        $params = $params + $eparams;
        $except = " AND id ".$selectioncriteria->exceptions;
    }

    if (!empty($selectioncriteria->firstinitial)) {
        $select .= " AND firstname $LIKE :fni";
        $params['fni'] = $selectioncriteria->firstinitial."%";
    }
    if (!empty($selectioncriteria->lastinitial)) {
        $select .= " AND lastname $LIKE :lni";
        $params['lni'] = $selectioncriteria->lastinitial."%";
    }

    if (!empty($selectioncriteria->extraselect)) {
        $select .= " AND ".$selectioncriteria->extraselect;
        if (empty($selectioncriteria->extraparams)){
            $params = $params + (array)$selectioncriteria->extraparams;
        }
    }

    return $DB->get_records_select('user', $select, $params, $sort, $fields, $page, $selectioncriteria->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);
    }
}