User-related APIs

Jump to: navigation, search

Overview

This is a collection of miscellaneous APIs that can help with doing things with lists of users. Note that, in many cases, the more specific Access API, Groups API, Enrolment API, etc. may be what you need.

User fields definition

Moodle 3.1

To guarantee the sanity of the data inserted into Moodle and avoid security bugs, new user fields definition methods have been created for use in Moodle 3.1 onwards. The purpose of these new methods is to create a central point of user fields data validation and guarantee all data inserted into Moodle will be cleaned against the correct parameter type. Another goal of this new API is to create consistency across Moodle core and avoid different parameter validations for the same user fields. For now on, user data must validate against the user field, not using clean_param() directly.

$propertiescache

Cached information of each user field and its attributes filled by the fill_properties_cache.

fill_properties_cache()

The main method of the user definition is to keep the definition of each user field and its properties. It verifies if the core_user::$propertiescache is already filled and caches all user fields attributes into this same attribute. Each field matches the exact field name on the user table. That said, every new field added to the user table should be added to fill_properties_cache $fields array, otherwise it won't be validated or cleaned. Each field has four possible properties, being choices and default optional:

  • null - Whether the field is NULL or NOT_NULL, it SHOULD NOT be used as form validation, as many fields in the user table have NOT_NULL property but have the default value as (``).
  • type - The expected parameter type (PARAM_*) to be used as validation and sanitizing.
  • choices - A list of accepted values of that field. For example the list of the available countries, timezones, calendar type etc.
  • default - The default value in case the user field didn't pass the validation or cleaned and we must set the default value. For example if the user country is invalid and it is not in the list of choices, set $CFG->country.

validate()

A static method to validate user fields, accepts an array or the user object as parameter, validate each parameter individually and can return true if all user data is correct or an array of validation errors. The purpose of this method is to just validate the user data, it won’t do any cleaning of the data.

clean_data()

A static method that has the purpose of clean the user data and return the same user array/object. It receives an array with user data or a user object as parameter and it checks if the data is in the list of choices and if the property has a default value and clean the data if the user object doesn’t have a choices property. It will display a debugging message if one the operations above has problems.

clean_field()

A static method to clean a single user field. It has two parameters, the data to be cleaned and its user field. The behaviour of the method is similar to the clean_data. It will do the validations and cleaning and can display a debug message if an error has been found. It returns the cleaned data.

get_property_type()

A helper method to get the type of the property. It receives the user field name as parameter and if it doesn't exist will throw an exception. If the property has been found, it will return its type.

get_property_null()

A helper method to get the null property of the user field. It receives the user field name as parameter and if it doesn't exist it throws an exception. If the property has been found, it will return the null value.

get_property_choices()

A helper method to get the list of choices of a user field. It receives the user field name as parameter and if it doesn't exist will throw an exception. If the property has been found, it will return the list of accepted values.

get_property_default()

A helper method to get the default value of a property. It receives the user field name as parameter and if it doesn't exist or if it doesn't have a default attribute will throw an exception. If the property has been found, it will return its default value.

User selector

The base class user_selector_base defined in user/selector/lib.php, which you can subclass to make a widget that lets you select users in an AJAX-y way. It is used, for example, on the Add group members page. The best way to learn how to use it is to search the code for other users, and see how they work. The base class also has good PHPdoc comments.

Sorting lists of users

When you fetch a list of users from the database, they should always be sorted consistently, by using the users_order_by_sql function to generate the order-by clause. Again, the best way to see how that works is to search the code for existing uses.

Others

Please add more..

See also