Favourites API

Overview

The favourites API allows you to mark items as favourites for a given user. Marking an item as a favourite is akin to adding a web page to your browser favourites (or bookmarks), or marking someone in your contacts as a favourite. The API provides a means to create, read, update and delete favourite items, allowing any component to favourite arbitrary items as they see fit.

What can be marked as a favourite?

Almost any 'item' can be marked as a favourite, provided it is something which can be identified by a unique integer id.

Identifying items

In order to store a favourite, and be able to uniquely identify it for later retrieval, 4 fields are required. These are: component, itemtype, itemid and contextid. You will see these in a range of API calls.

The itemid is a unique integer identifier of the item itself. This might be a course id, or conversation id, or the id of any entity in Moodle. In fact, it does not have to be the id of a record from the database either; it can be any arbitrary id, so long as the component storing the item knows what it represents.

The two fields component and itemtype make up a pairing representing the type of each favourite. Within this pair, the component must be a valid frankenstyle component name and is the name of the component wishing to set/unset the item as a favourite. The itemtype can be any identifying string, provided it is unique within the respective component. The type pairing allows us to distinguish between favourites of different types (from different areas of Moodle), which may have identical itemid values.

The contextid is the id of the context in which the item is being marked as a favourite. For example, a user's course might be marked as a favourite at the course context, whereas a user's conversation with another user might be marked as a favourite at the user context. It's also possible that items of a certain type (remember, this is the {component, itemtype} pairing) will be marked as favourites in different contexts, based on the context of the item itself. For example, consider the case in messaging, in which we have a group conversation (one which is linked to a course group), and an individual conversation between two users. Setting the group conversation as a favourite would require the course context to be used, whereas doing the same for the individual conversation would require a user context. Which contextid to use is a decision that must be made by the component creating the favourite.

Using the API

Getting a service

Favourites relies on a service layer to provide functionality to consumers. Getting a service object is as simple as using the service factory methods.

To get a service scoped to a single user: $ufservice = \core_favourites\service_factory::get_service_for_user_context($usercontext);

where $usercontext is the \context_user object. The returned $ufservice is an object of type \core_favourites\local\service\user_favourite_service.

Creating a favourite

Let's say we want to set a course as a favourite. Note: In core, this is done by using the favourite type {'core_course', 'courses'}.

The service provides the method: public function create_favourite(string $component, string $itemtype, int $itemid, \context $context, int $ordering = null) : favourite; So, assuming we have the courseid and course context, we can create our favourite with: $favourite = $ufservice->create_favourite('core_course', 'courses', $course->id, $coursecontext); The returned $favourite is an object of type \core_favourites\local\entity\favourite.

Reading favourites

There are several read actions supported by the service object. public function count_favourites_by_type(string $component, string $itemtype, \context $context = null) : int; public function find_favourites_by_type(string $component, string $itemtype, int $limitfrom = 0, int $limitnum = 0) : array; public function favourite_exists(string $component, string $itemtype, int $itemid, \context $context) : bool; public function get_favourite(string $component, string $itemtype, int $itemid, \context $context) : favourite;