MDL-63658 core_favourites: rename user_favourites_service and services
[moodle.git] / favourites / classes / local / service / user_favourite_service.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 /**
18  * Contains the user_favourite_service class, part of the service layer for the favourites subsystem.
19  *
20  * @package   core_favourites
21  * @copyright 2018 Jake Dallimore <jrhdallimore@gmail.com>
22  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
24 namespace core_favourites\local\service;
25 use \core_favourites\local\entity\favourite;
27 defined('MOODLE_INTERNAL') || die();
29 /**
30  * Class service, providing an single API for interacting with the favourites subsystem for a SINGLE USER.
31  *
32  * This class is responsible for exposing key operations (add, remove, find) and enforces any business logic necessary to validate
33  * authorization/data integrity for these operations.
34  *
35  * All object persistence is delegated to the ifavourite_repository.
36  *
37  * @copyright 2018 Jake Dallimore <jrhdallimore@gmail.com>
38  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
39  */
40 class user_favourite_service {
42     /** @var ifavourite_repository $repo the user favourites repository object. */
43     protected $repo;
45     /** @var int $userid the id of the user to which this favourites service is scoped. */
46     protected $userid;
48     /**
49      * The user_favourite_service constructor.
50      *
51      * @param \context_user $usercontext The context of the user to which this service operations are scoped.
52      * @param \core_favourites\local\repository\ifavourite_repository $repository a user favourites repository.
53      */
54     public function __construct(\context_user $usercontext, \core_favourites\local\repository\ifavourite_repository $repository) {
55         $this->repo = $repository;
56         $this->userid = $usercontext->instanceid;
57     }
59     /**
60      * Helper, returning a flat list of component names.
61      *
62      * @return array the array of component names.
63      */
64     protected function get_component_list() {
65         return array_keys(array_reduce(\core_component::get_component_list(), function($carry, $item) {
66             return array_merge($carry, $item);
67         }, []));
68     }
70     /**
71      * Favourite an item defined by itemid/context, in the area defined by component/itemtype.
72      *
73      * @param string $component the frankenstyle component name.
74      * @param string $itemtype the type of the item being favourited.
75      * @param int $itemid the id of the item which is to be favourited.
76      * @param \context $context the context in which the item is to be favourited.
77      * @param int|null $ordering optional ordering integer used for sorting the favourites in an area.
78      * @return favourite the favourite, once created.
79      * @throws \moodle_exception if the component name is invalid, or if the repository encounters any errors.
80      */
81     public function create_favourite(string $component, string $itemtype, int $itemid, \context $context,
82             int $ordering = null) : favourite {
83         // Access: Any component can ask to favourite something, we can't verify access to that 'something' here though.
85         // Validate the component name.
86         if (!in_array($component, $this->get_component_list())) {
87             throw new \moodle_exception("Invalid component name '$component'");
88         }
90         $favourite = new favourite($component, $itemtype, $itemid, $context->id, $this->userid);
91         $favourite->ordering = $ordering > 0 ? $ordering : null;
92         return $this->repo->add($favourite);
93     }
95     /**
96      * Find a list of favourites, by type, where type is the component/itemtype pair.
97      *
98      * E.g. "Find all favourite courses" might result in:
99      * $favcourses = find_favourites_by_type('core_course', 'course');
100      *
101      * @param string $component the frankenstyle component name.
102      * @param string $itemtype the type of the favourited item.
103      * @param int $limitfrom optional pagination control for returning a subset of records, starting at this point.
104      * @param int $limitnum optional pagination control for returning a subset comprising this many records.
105      * @return array the list of favourites found.
106      * @throws \moodle_exception if the component name is invalid, or if the repository encounters any errors.
107      */
108     public function find_favourites_by_type(string $component, string $itemtype, int $limitfrom = 0, int $limitnum = 0) : array {
109         if (!in_array($component, $this->get_component_list())) {
110             throw new \moodle_exception("Invalid component name '$component'");
111         }
112         return $this->repo->find_by(
113             [
114                 'userid' => $this->userid,
115                 'component' => $component,
116                 'itemtype' => $itemtype
117             ],
118             $limitfrom,
119             $limitnum
120         );
121     }
123     /**
124      * Delete a favourite item from an area and from within a context.
125      *
126      * E.g. delete a favourite course from the area 'core_course', 'course' with itemid 3 and from within the CONTEXT_USER context.
127      *
128      * @param string $component the frankenstyle component name.
129      * @param string $itemtype the type of the favourited item.
130      * @param int $itemid the id of the item which was favourited (not the favourite's id).
131      * @param \context $context the context of the item which was favourited.
132      * @throws \moodle_exception if the user does not control the favourite, or it doesn't exist.
133      */
134     public function delete_favourite(string $component, string $itemtype, int $itemid, \context $context) {
135         if (!in_array($component, $this->get_component_list())) {
136             throw new \moodle_exception("Invalid component name '$component'");
137         }
139         // Business logic: check the user owns the favourite.
140         try {
141             $favourite = $this->repo->find_favourite($this->userid, $component, $itemtype, $itemid, $context->id);
142         } catch (\moodle_exception $e) {
143             throw new \moodle_exception("Favourite does not exist for the user. Cannot delete.");
144         }
146         $this->repo->delete($favourite->id);
147     }