diff --git a/favourites/classes/local/user_favourites_service.php b/favourites/classes/local/user_favourites_service.php new file mode 100644 index 00000000000..41eb97e57b8 --- /dev/null +++ b/favourites/classes/local/user_favourites_service.php @@ -0,0 +1,143 @@ +. + +/** + * Contains the user_favourites_service class, part of the service layer for the favourites subsystem. + * + * @package core_favourites + * @copyright 2018 Jake Dallimore + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ +namespace core_favourites\local; + +defined('MOODLE_INTERNAL') || die(); + +/** + * 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 ifavourites_repository. + * + * @copyright 2018 Jake Dallimore + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ +class user_favourites_service { + + /** @var user_favourites_repository $repo the user favourites repository object. */ + protected $repo; + + /** @var int $userid the id of the user to which this favourites service is scoped. */ + protected $userid; + + /** + * Helper, returning a flat list of component names. + * + * @return array the array of component names. + */ + protected function get_component_list() { + return array_keys(array_reduce(\core_component::get_component_list(), function($carry, $item) { + return array_merge($carry, $item); + }, [])); + } + + /** + * The user_favourites_service constructor. + * + * @param \context_user $usercontext The context of the user to which this service operations are scoped. + * @param ifavourites_repository $repository a user favourites repository. + */ + public function __construct(\context_user $usercontext, ifavourites_repository $repository) { + $this->repo = $repository; + $this->userid = $usercontext->instanceid; + } + + /** + * Favourite an item defined by itemid/context, in the area defined by component/itemtype. + * + * @param string $component the frankenstyle component name. + * @param string $itemtype the type of the item being favourited. + * @param int $itemid the id of the item which is to be favourited. + * @param \context $context the context in which the item is to be favourited. + * @param int|null $ordering optional ordering integer used for sorting the favourites in an area. + * @return \stdClass the favourite, once created. + * @throws \moodle_exception if the component name is invalid, or if the repository encounters any errors. + */ + public function create_favourite(string $component, string $itemtype, int $itemid, \context $context, + int $ordering = null) : \stdClass { + // Access: Any component can ask to favourite something, we can't verify access to that 'something' here though. + + // Validate the component name. + if (!in_array($component, $this->get_component_list())) { + throw new \moodle_exception("Invalid component name '$component'"); + } + + $favourite = (object) [ + 'userid' => $this->userid, + 'component' => $component, + 'itemtype' => $itemtype, + 'itemid' => $itemid, + 'contextid' => $context->id, + 'ordering' => $ordering > 0 ? $ordering : null + ]; + return $this->repo->add($favourite); + } + + /** + * 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'); + * + * @param string $component the frankenstyle component name. + * @param string $itemtype the type of the favourited item. + * @return array the list of favourites found. + * @throws \moodle_exception if the component name is invalid, or if the repository encounters any errors. + */ + public function find_favourites_by_type(string $component, string $itemtype) : array { + if (!in_array($component, $this->get_component_list())) { + throw new \moodle_exception("Invalid component name '$component'"); + } + return $this->repo->find_by(['userid' => $this->userid, 'component' => $component, 'itemtype' => $itemtype]); + } + + /** + * 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. + * + * @param string $component the frankenstyle component name. + * @param string $itemtype the type of the favourited item. + * @param int $itemid the id of the item which was favourited (not the favourite's id). + * @param \context $context the context of the item which was favourited. + * @throws \moodle_exception if the user does not control the favourite, or it doesn't exist. + */ + public function delete_favourite(string $component, string $itemtype, int $itemid, \context $context) { + if (!in_array($component, $this->get_component_list())) { + throw new \moodle_exception("Invalid component name '$component'"); + } + + // Business logic: check the user owns the favourite. + try { + $favourite = $this->repo->find_favourite($this->userid, $component, $itemtype, $itemid, $context->id); + } catch (\moodle_exception $e) { + throw new \moodle_exception("Favourite does not exist for the user. Cannot delete."); + } + + $this->repo->delete($favourite->id); + } +} diff --git a/favourites/classes/services.php b/favourites/classes/services.php new file mode 100644 index 00000000000..65eecaccd21 --- /dev/null +++ b/favourites/classes/services.php @@ -0,0 +1,49 @@ +. +/** + * Contains the service locators for the favourites subsystem. + * + * Services encapsulate the business logic, and any data manipulation code, and are what clients should interact with. + * + * @package core_favourites + * @copyright 2018 Jake Dallimore + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ +namespace core_favourites; + +defined('MOODLE_INTERNAL') || die(); + +/** + * Class services, providing functions for location of service objects for the favourites subsystem. + * + * This class is responsible for providing service objects to clients only. + * + * @copyright 2018 Jake Dallimore + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ +class services { + + /** + * Returns a basic service object providing operations for user favourites. + * + * @param \context_user $context the context of the user to which the service should be scoped. + * @return user_favourites_service the service object. + */ + public static function get_service_for_user_context(\context_user $context) : local\user_favourites_service { + return new local\user_favourites_service($context, new local\favourites_repository()); + } +} + diff --git a/favourites/tests/service_test.php b/favourites/tests/service_test.php new file mode 100644 index 00000000000..5c47e6b8ed3 --- /dev/null +++ b/favourites/tests/service_test.php @@ -0,0 +1,272 @@ +. + +/** + * Testing the service layer within core_favourites. + * + * @package core_favourites + * @category test + * @copyright 2018 Jake Dallimore + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +defined('MOODLE_INTERNAL') || die(); + +/** + * Test class covering the user_favourites_service within the service layer of favourites. + * + * @copyright 2018 Jake Dallimore + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ +class user_favourites_service_testcase extends advanced_testcase { + + public function setUp() { + $this->resetAfterTest(); + } + + // Basic setup stuff to be reused in most tests. + protected function setup_users_and_courses() { + $user1 = self::getDataGenerator()->create_user(); + $user1context = \context_user::instance($user1->id); + $user2 = self::getDataGenerator()->create_user(); + $user2context = \context_user::instance($user2->id); + $course1 = self::getDataGenerator()->create_course(); + $course2 = self::getDataGenerator()->create_course(); + $course1context = context_course::instance($course1->id); + $course2context = context_course::instance($course2->id); + return [$user1context, $user2context, $course1context, $course2context]; + } + + /** + * Generates an in-memory repository for testing, using an array store for CRUD stuff. + * + * @param array $mockstore + * @return \PHPUnit\Framework\MockObject\MockObject + */ + protected function get_mock_repository(array $mockstore) { + // This mock will just store data in an array. + $mockrepo = $this->getMockBuilder(\core_favourites\local\ifavourites_repository::class) + ->setMethods([]) + ->getMock(); + $mockrepo->expects($this->any()) + ->method('add') + ->will($this->returnCallback(function(\stdclass $favourite) use (&$mockstore) { + // Mock implementation of repository->add(), where an array is used instead of the DB. + // Duplicates are confirmed via the unique key, and exceptions thrown just like a real repo. + $key = $favourite->userid . $favourite->component . $favourite->itemtype . $favourite->itemid + . $favourite->contextid; + + // Check the objects for the unique key. + foreach ($mockstore as $item) { + if ($item->uniquekey == $key) { + throw new \moodle_exception('Favourite already exists'); + } + } + $index = count($mockstore); // Integer index. + $favourite->uniquekey = $key; // Simulate the unique key constraint. + $favourite->id = $index; + $mockstore[$index] = $favourite; + return $mockstore[$index]; + }) + ); + $mockrepo->expects($this->any()) + ->method('find_by') + ->will($this->returnCallback(function(array $criteria) use (&$mockstore) { + // Check the mockstore for all objects with properties matching the key => val pairs in $criteria. + foreach ($mockstore as $index => $mockrow) { + $mockrowarr = (array)$mockrow; + if (array_diff($criteria, $mockrowarr) == []) { + $returns[$index] = $mockrow; + } + } + return $returns; + }) + ); + $mockrepo->expects($this->any()) + ->method('find_favourite') + ->will($this->returnCallback(function(int $userid, string $comp, string $type, int $id, int $ctxid) use (&$mockstore) { + // Check the mockstore for all objects with properties matching the key => val pairs in $criteria. + $crit = ['userid' => $userid, 'component' => $comp, 'itemtype' => $type, 'itemid' => $id, 'contextid' => $ctxid]; + foreach ($mockstore as $fakerow) { + $fakerowarr = (array)$fakerow; + if (array_diff($crit, $fakerowarr) == []) { + return $fakerow; + } + } + throw new \moodle_exception("Item not found"); + }) + ); + $mockrepo->expects($this->any()) + ->method('find') + ->will($this->returnCallback(function(int $id) use (&$mockstore) { + return $mockstore[$id]; + }) + ); + $mockrepo->expects($this->any()) + ->method('exists') + ->will($this->returnCallback(function(int $id) use (&$mockstore) { + return array_key_exists($id, $mockstore); + }) + ); + $mockrepo->expects($this->any()) + ->method('delete') + ->will($this->returnCallback(function(int $id) use (&$mockstore) { + foreach ($mockstore as $mockrow) { + if ($mockrow->id == $id) { + unset($mockstore[$id]); + } + } + }) + ); + return $mockrepo; + } + + /** + * Test getting a user_favourites_service from the static locator. + */ + public function test_get_service_for_user_context() { + list($user1context, $user2context, $course1context, $course2context) = $this->setup_users_and_courses(); + $userservice = \core_favourites\services::get_service_for_user_context($user1context); + $this->assertInstanceOf(\core_favourites\local\user_favourites_service::class, $userservice); + } + + /** + * Test confirming an item can be favourited only once. + */ + public function test_create_favourite_basic() { + list($user1context, $user2context, $course1context, $course2context) = $this->setup_users_and_courses(); + + // Get a user_favourites_service for a user. + $repo = $this->get_mock_repository([]); // Mock repository, using the array as a mock DB. + $user1service = new \core_favourites\local\user_favourites_service($user1context, $repo); + + // Favourite a course. + $favourite1 = $user1service->create_favourite('core_course', 'course', $course1context->instanceid, $course1context); + $this->assertObjectHasAttribute('id', $favourite1); + + // Try to favourite the same course again. + $this->expectException('moodle_exception'); + $user1service->create_favourite('core_course', 'course', $course1context->instanceid, $course1context); + } + + /** + * Test confirming that an exception is thrown if trying to favourite an item for a non-existent component. + */ + public function test_create_favourite_nonexistent_component() { + list($user1context, $user2context, $course1context, $course2context) = $this->setup_users_and_courses(); + + // Get a user_favourites_service for the user. + $repo = $this->get_mock_repository([]); // Mock repository, using the array as a mock DB. + $user1service = new \core_favourites\local\user_favourites_service($user1context, $repo); + + // Try to favourite something in a non-existent component. + $this->expectException('moodle_exception'); + $user1service->create_favourite('core_cccourse', 'my_area', $course1context->instanceid, $course1context); + } + + /** + * Test fetching favourites for single user, by area. + */ + public function test_find_favourites_by_type_single_user() { + list($user1context, $user2context, $course1context, $course2context) = $this->setup_users_and_courses(); + + // Get a user_favourites_service for the user. + $repo = $this->get_mock_repository([]); // Mock repository, using the array as a mock DB. + $service = new \core_favourites\local\user_favourites_service($user1context, $repo); + + // Favourite 2 courses, in separate areas. + $fav1 = $service->create_favourite('core_course', 'course', $course1context->instanceid, $course1context); + $fav2 = $service->create_favourite('core_course', 'anothertype', $course2context->instanceid, $course2context); + + // Verify we can get favourites by area. + $favourites = $service->find_favourites_by_type('core_course', 'course'); + $this->assertInternalType('array', $favourites); + $this->assertCount(1, $favourites); // We only get favourites for the 'core_course/course' area. + $this->assertAttributeEquals($fav1->id, 'id', $favourites[$fav1->id]); + + $favourites = $service->find_favourites_by_type('core_course', 'anothertype'); + $this->assertInternalType('array', $favourites); + $this->assertCount(1, $favourites); // We only get favourites for the 'core_course/course' area. + $this->assertAttributeEquals($fav2->id, 'id', $favourites[$fav2->id]); + } + + /** + * Make sure the find_favourites_by_type() method only returns favourites for the scoped user. + */ + public function test_find_favourites_by_type_multiple_users() { + list($user1context, $user2context, $course1context, $course2context) = $this->setup_users_and_courses(); + + // Get a user_favourites_service for 2 users. + $repo = $this->get_mock_repository([]); + $user1service = new \core_favourites\local\user_favourites_service($user1context, $repo); + $user2service = new \core_favourites\local\user_favourites_service($user2context, $repo); + + // Now, as each user, favourite the same course. + $fav1 = $user1service->create_favourite('core_course', 'course', $course1context->instanceid, $course1context); + $fav2 = $user2service->create_favourite('core_course', 'course', $course1context->instanceid, $course1context); + + // Verify find_favourites_by_type only returns results for the user to which the service is scoped. + $user1favourites = $user1service->find_favourites_by_type('core_course', 'course'); + $this->assertInternalType('array', $user1favourites); + $this->assertCount(1, $user1favourites); // We only get favourites for the 'core_course/course' area for $user1. + $this->assertAttributeEquals($fav1->id, 'id', $user1favourites[$fav1->id]); + + $user2favourites = $user2service->find_favourites_by_type('core_course', 'course'); + $this->assertInternalType('array', $user2favourites); + $this->assertCount(1, $user2favourites); // We only get favourites for the 'core_course/course' area for $user2. + $this->assertAttributeEquals($fav2->id, 'id', $user2favourites[$fav2->id]); + } + + /** + * Test confirming that an exception is thrown if trying to get favourites for a non-existent component. + */ + public function test_find_favourites_by_type_nonexistent_component() { + list($user1context, $user2context, $course1context, $course2context) = $this->setup_users_and_courses(); + + // Get a user_favourites_service for the user. + $repo = $this->get_mock_repository([]); + $service = new \core_favourites\local\user_favourites_service($user1context, $repo); + + // Verify we get an exception if we try to search for favourites in an invalid component. + $this->expectException('moodle_exception'); + $service->find_favourites_by_type('cccore_notreal', 'something'); + } + + /** + * Test confirming the basic deletion behaviour. + */ + public function test_delete_favourite_basic() { + list($user1context, $user2context, $course1context, $course2context) = $this->setup_users_and_courses(); + + // Get a user_favourites_service for the user. + $repo = $this->get_mock_repository([]); + $service = new \core_favourites\local\user_favourites_service($user1context, $repo); + + // Favourite a course. + $fav1 = $service->create_favourite('core_course', 'course', $course1context->instanceid, $course1context); + $this->assertTrue($repo->exists($fav1->id)); + + // Delete the favourite. + $service->delete_favourite('core_course', 'course', $course1context->instanceid, $course1context); + + // Verify the favourite doesn't exist. + $this->assertFalse($repo->exists($fav1->id)); + + // Try to delete a favourite which we know doesn't exist. + $this->expectException(\moodle_exception::class); + $service->delete_favourite('core_course', 'course', $course1context->instanceid, $course1context); + } +}