core_favourites\local\service\user_favourite_service Class Reference

Class service, providing an single API for interacting with the favourites subsystem for a SINGLE USER. More...

Public Member Functions
	__construct (\context_user $usercontext, favourite_repository_interface $repository)
	The user_favourite_service constructor.
	count_favourites_by_type (string $component, string $itemtype, context $context=null)
	Count the favourite by item type.
	create_favourite (string $component, string $itemtype, int $itemid, context $context, int $ordering=null)
	Favourite an item defined by itemid/context, in the area defined by component/itemtype.
	delete_favourite (string $component, string $itemtype, int $itemid, context $context)
	Delete a favourite item from an area and from within a context.
	favourite_exists (string $component, string $itemtype, int $itemid, context $context)
	Check whether an item has been marked as a favourite in the respective area.
	find_all_favourites (string $component, array $itemtypes=[], int $limitfrom=0, int $limitnum=0)
	Find a list of favourites, by multiple types within a component.
	find_favourites_by_type (string $component, string $itemtype, int $limitfrom=0, int $limitnum=0)
	Find a list of favourites, by type, where type is the component/itemtype pair.
	get_favourite (string $component, string $itemtype, int $itemid, context $context)
	Get the favourite.
	get_join_sql_by_type (string $component, string $itemtype, string $tablealias, string $joinitemid)
	Returns the SQL required to include favourite information for a given component/itemtype combination.

Protected Attributes
favourite_repository_interface	$repo
	$repo the favourite repository object.
int	$userid
	$userid the id of the user to which this favourites service is scoped.

Detailed Description

Class service, providing an single API for interacting with the favourites subsystem for a SINGLE USER.

This class is responsible for exposing key operations (add, remove, find) and enforces any business logic necessary to validate authorization/data integrity for these operations.

All object persistence is delegated to the favourite_repository_interface object.

Copyright

2018 Jake Dallimore jrhda.nosp@m.llim.nosp@m.ore@g.nosp@m.mail.nosp@m..com

License

http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Constructor & Destructor Documentation

__construct()

core_favourites\local\service\user_favourite_service::__construct	(	\context_user	$usercontext,
		favourite_repository_interface	$repository )

The user_favourite_service constructor.

Parameters

context_user	$usercontext	The context of the user to which this service operations are scoped.
core_favourites\local\repository\favourite_repository_interface	$repository	a favourites repository.

Member Function Documentation

count_favourites_by_type()

core_favourites\local\service\user_favourite_service::count_favourites_by_type	(	string	$component,
		string	$itemtype,
		context	$context = null )

Count the favourite by item type.

Parameters

string	$component	the frankenstyle component name.
string	$itemtype	the type of the favourited item.
context | null	$context	the context of the item which was favourited.

Return values

int

create_favourite()

core_favourites\local\service\user_favourite_service::create_favourite	(	string	$component,
		string	$itemtype,
		int	$itemid,
		context	$context,
		int	$ordering = null )

Favourite an item defined by itemid/context, in the area defined by component/itemtype.

Parameters

string	$component	the frankenstyle component name.
string	$itemtype	the type of the item being favourited.
int	$itemid	the id of the item which is to be favourited.
context	$context	the context in which the item is to be favourited.
int | null	$ordering	optional ordering integer used for sorting the favourites in an area.

Return values

favourite

the favourite, once created.

Exceptions

moodle_exception

if the component name is invalid, or if the repository encounters any errors.

delete_favourite()

core_favourites\local\service\user_favourite_service::delete_favourite	(	string	$component,
		string	$itemtype,
		int	$itemid,
		context	$context )

Delete a favourite item from an area and from within a context.

E.g. delete a favourite course from the area 'core_course', 'course' with itemid 3 and from within the CONTEXT_USER context.

Parameters

string	$component	the frankenstyle component name.
string	$itemtype	the type of the favourited item.
int	$itemid	the id of the item which was favourited (not the favourite's id).
context	$context	the context of the item which was favourited.

Exceptions

moodle_exception

if the user does not control the favourite, or it doesn't exist.

favourite_exists()

core_favourites\local\service\user_favourite_service::favourite_exists	(	string	$component,
		string	$itemtype,
		int	$itemid,
		context	$context )

Check whether an item has been marked as a favourite in the respective area.

Parameters

string	$component	the frankenstyle component name.
string	$itemtype	the type of the favourited item.
int	$itemid	the id of the item which was favourited (not the favourite's id).
context	$context	the context of the item which was favourited.

Return values

bool	true if the item is favourited, false otherwise.

find_all_favourites()

core_favourites\local\service\user_favourite_service::find_all_favourites	(	string	$component,
		array	$itemtypes = [],
		int	$limitfrom = 0,
		int	$limitnum = 0 )

Find a list of favourites, by multiple types within a component.

E.g. "Find all favourites in the activity chooser" might result in: $favcourses = find_all_favourites('core_course', ['contentitem_mod_assign');

Parameters

string	$component	the frankenstyle component name.
array	$itemtypes	optional the type of the favourited item.
int	$limitfrom	optional pagination control for returning a subset of records, starting at this point.
int	$limitnum	optional pagination control for returning a subset comprising this many records.

Return values

array

the list of favourites found.

Exceptions

moodle_exception

if the component name is invalid, or if the repository encounters any errors.

find_favourites_by_type()

core_favourites\local\service\user_favourite_service::find_favourites_by_type	(	string	$component,
		string	$itemtype,
		int	$limitfrom = 0,
		int	$limitnum = 0 )

Find a list of favourites, by type, where type is the component/itemtype pair.

E.g. "Find all favourite courses" might result in: $favcourses = find_favourites_by_type('core_course', 'course');

Parameters

string	$component	the frankenstyle component name.
string	$itemtype	the type of the favourited item.
int	$limitfrom	optional pagination control for returning a subset of records, starting at this point.
int	$limitnum	optional pagination control for returning a subset comprising this many records.

Return values

array

the list of favourites found.

Exceptions

moodle_exception

if the component name is invalid, or if the repository encounters any errors.

get_favourite()

core_favourites\local\service\user_favourite_service::get_favourite	(	string	$component,
		string	$itemtype,
		int	$itemid,
		context	$context )

Get the favourite.

Parameters

string	$component	the frankenstyle component name.
string	$itemtype	the type of the favourited item.
int	$itemid	the id of the item which was favourited (not the favourite's id).
context	$context	the context of the item which was favourited.

Return values

favourite|null

get_join_sql_by_type()

core_favourites\local\service\user_favourite_service::get_join_sql_by_type	(	string	$component,
		string	$itemtype,
		string	$tablealias,
		string	$joinitemid )

Returns the SQL required to include favourite information for a given component/itemtype combination.

Generally, find_favourites_by_type() is the recommended way to fetch favourites.

This method is used to include favourite information in external queries, for items identified by their component and itemtype, matching itemid to the $joinitemid, and for the user to which this service is scoped.

It uses a LEFT JOIN to preserve the original records. If you wish to restrict your records, please consider using a "WHERE {$tablealias}.id IS NOT NULL" in your query.

Example usage:

list($sql, $params) = $service->get_join_sql_by_type('core_message', 'message_conversations', 'myfavouritetablealias', 'conv.id'); Results in $sql: "LEFT JOIN {favourite} fav ON fav.component = :favouritecomponent AND fav.itemtype = :favouriteitemtype AND fav.userid = 1234 AND fav.itemid = conv.id" and $params: ['favouritecomponent' => 'core_message', 'favouriteitemtype' => 'message_conversations']

Parameters

string	$component	the frankenstyle component name.
string	$itemtype	the type of the favourited item.
string	$tablealias	the desired alias for the favourites table.
string	$joinitemid	the table and column identifier which the itemid is joined to. E.g. conversation.id.

Return values

array

the list of sql and params, in the format [$sql, $params].

---

The documentation for this class was generated from the following file:

• favourites/classes/local/service/user_favourite_service.php