Proyectos de Subversion Moodle

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Contains the user_favourite_service class, part of the service layer for the favourites subsystem.
 *
 * @package   core_favourites
 * @copyright 2018 Jake Dallimore <jrhdallimore@gmail.com>
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
namespace core_favourites\local\service;
use \core_favourites\local\entity\favourite;
use \core_favourites\local\repository\favourite_repository_interface;

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 favourite_repository_interface object.
 *
 * @copyright 2018 Jake Dallimore <jrhdallimore@gmail.com>
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class user_favourite_service {

    /** @var favourite_repository_interface $repo the favourite repository object. */
    protected $repo;

    /** @var int $userid the id of the user to which this favourites service is scoped. */
    protected $userid;

    /**
     * The user_favourite_service constructor.
     *
     * @param \context_user $usercontext The context of the user to which this service operations are scoped.
     * @param \core_favourites\local\repository\favourite_repository_interface $repository a favourites repository.
     */
    public function __construct(\context_user $usercontext, favourite_repository_interface $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 favourite 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): favourite {
        // 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, \core_component::get_component_names())) {
            throw new \moodle_exception("Invalid component name '$component'");
        }

        $favourite = new favourite($component, $itemtype, $itemid, $context->id, $this->userid);
        $favourite->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.
     * @param int $limitfrom optional pagination control for returning a subset of records, starting at this point.
     * @param int $limitnum optional pagination control for returning a subset comprising this many records.
     * @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, int $limitfrom = 0, int $limitnum = 0): array {
        if (!in_array($component, \core_component::get_component_names())) {
            throw new \moodle_exception("Invalid component name '$component'");
        }
        return $this->repo->find_by(
            [
                'userid' => $this->userid,
                'component' => $component,
                'itemtype' => $itemtype
            ],
            $limitfrom,
            $limitnum
        );
    }

    /**
     * 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');
     *
     * @param string $component the frankenstyle component name.
     * @param array $itemtypes optional the type of the favourited item.
     * @param int $limitfrom optional pagination control for returning a subset of records, starting at this point.
     * @param int $limitnum optional pagination control for returning a subset comprising this many records.
     * @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_all_favourites(string $component, array $itemtypes = [], int $limitfrom = 0, int $limitnum = 0): array {
        if (!in_array($component, \core_component::get_component_names())) {
            throw new \moodle_exception("Invalid component name '$component'");
        }
        $params = [
            'userid' => $this->userid,
            'component' => $component,
        ];
        if ($itemtypes) {
            $params['itemtype'] = $itemtypes;
        }

        return $this->repo->find_by(
            $params,
            $limitfrom,
            $limitnum
        );
    }

    /**
     * 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']
     *
     * @param string $component the frankenstyle component name.
     * @param string $itemtype the type of the favourited item.
     * @param string $tablealias the desired alias for the favourites table.
     * @param string $joinitemid the table and column identifier which the itemid is joined to. E.g. conversation.id.
     * @return array the list of sql and params, in the format [$sql, $params].
     */
    public function get_join_sql_by_type(string $component, string $itemtype, string $tablealias, string $joinitemid): array {
        $sql = " LEFT JOIN {favourite} {$tablealias}
                        ON {$tablealias}.component = :favouritecomponent
                       AND {$tablealias}.itemtype = :favouriteitemtype
                       AND {$tablealias}.userid = {$this->userid}
                       AND {$tablealias}.itemid = {$joinitemid} ";

        $params = [
            'favouritecomponent' => $component,
            'favouriteitemtype' => $itemtype,
        ];

        return [$sql, $params];
    }

    /**
     * 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, \core_component::get_component_names())) {
            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);
    }

    /**
     * Check whether an item has been marked as a favourite in the respective area.
     *
     * @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.
     * @return bool true if the item is favourited, false otherwise.
     */
    public function favourite_exists(string $component, string $itemtype, int $itemid, \context $context): bool {
        return $this->repo->exists_by(
            [
                'userid' => $this->userid,
                'component' => $component,
                'itemtype' => $itemtype,
                'itemid' => $itemid,
                'contextid' => $context->id
            ]
        );
    }

    /**
     * Get the favourite.
     *
     * @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.
     * @return favourite|null
     */
    public function get_favourite(string $component, string $itemtype, int $itemid, \context $context) {
        try {
            return $this->repo->find_favourite(
                $this->userid,
                $component,
                $itemtype,
                $itemid,
                $context->id
            );
        } catch (\dml_missing_record_exception $e) {
            return null;
        }
    }

    /**
     * Count the favourite by item type.
     *
     * @param string $component the frankenstyle component name.
     * @param string $itemtype the type of the favourited item.
     * @param \context|null $context the context of the item which was favourited.
     * @return int
     */
    public function count_favourites_by_type(string $component, string $itemtype, \context $context = null) {
        $criteria = [
            'userid' => $this->userid,
            'component' => $component,
            'itemtype' => $itemtype
        ];

        if ($context) {
            $criteria['contextid'] = $context->id;
        }

        return $this->repo->count_by($criteria);
    }
}