[Summary view]

   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/>.
  16  /**
  17   * Contains the favourite_repository interface.
  18   *
  19   * @package   core_favourites
  20   * @copyright 2018 Jake Dallimore <jrhdallimore@gmail.com>
  21   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  22   */
  23  namespace core_favourites\local\repository;
  24  use \core_favourites\local\entity\favourite;
  25  
  26  defined('MOODLE_INTERNAL') || die();
  27  
  28  /**
  29   * The favourite_repository interface, defining the basic CRUD operations for favourite type items within core_favourites.
  30   */
  31  interface favourite_repository_interface {
  32      /**
  33       * Add one item to this repository.
  34       *
  35       * @param favourite $item the item to add.
  36       * @return favourite the item which was added.
  37       */
  38      public function add(favourite $item) : favourite;
  39  
  40      /**
  41       * Add all the items in the list to this repository.
  42       *
  43       * @param array $items the list of items to add.
  44       * @return array the list of items added to this repository.
  45       */
  46      public function add_all(array $items) : array;
  47  
  48      /**
  49       * Find an item in this repository based on its id.
  50       *
  51       * @param int $id the id of the item.
  52       * @return favourite the item.
  53       */
  54      public function find(int $id) : favourite;
  55  
  56      /**
  57       * Find all items in this repository.
  58       *
  59       * @param int $limitfrom optional pagination control for returning a subset of records, starting at this point.
  60       * @param int $limitnum optional pagination control for returning a subset comprising this many records.
  61       * @return array list of all items in this repository.
  62       */
  63      public function find_all(int $limitfrom = 0, int $limitnum = 0) : array;
  64  
  65      /**
  66       * Find all items with attributes matching certain values.
  67       *
  68       * @param array $criteria the array of attribute/value pairs.
  69       * @param int $limitfrom optional pagination control for returning a subset of records, starting at this point.
  70       * @param int $limitnum optional pagination control for returning a subset comprising this many records.
  71       * @return array the list of items matching the criteria.
  72       */
  73      public function find_by(array $criteria, int $limitfrom = 0, int $limitnum = 0) : array;
  74  
  75      /**
  76       * Check whether an item exists in this repository, based on its id.
  77       *
  78       * @param int $id the id to search for.
  79       * @return bool true if the item could be found, false otherwise.
  80       */
  81      public function exists(int $id) : bool;
  82  
  83      /**
  84       * Check whether an item exists in this repository, based on the specified criteria.
  85       *
  86       * @param array $criteria the list of key/value criteria pairs.
  87       * @return bool true if the favourite exists, false otherwise.
  88       */
  89      public function exists_by(array $criteria) : bool;
  90  
  91      /**
  92       * Return the total number of items in this repository.
  93       *
  94       * @return int the total number of items.
  95       */
  96      public function count() : int;
  97  
  98      /**
  99       * Return the number of favourites matching the specified criteria.
 100       *
 101       * @param array $criteria the list of key/value criteria pairs.
 102       * @return int the number of favourites matching the criteria.
 103       */
 104      public function count_by(array $criteria) : int;
 105  
 106      /**
 107       * Update an item within this repository.
 108       *
 109       * @param favourite $item the item to update.
 110       * @return favourite the updated item.
 111       */
 112      public function update(favourite $item) : favourite;
 113  
 114      /**
 115       * Delete an item by id.
 116       *
 117       * @param int $id the id of the item to delete.
 118       * @return void
 119       */
 120      public function delete(int $id);
 121  
 122      /**
 123       * Delete all favourites matching the specified criteria.
 124       *
 125       * @param array $criteria the list of key/value criteria pairs.
 126       * @return void.
 127       */
 128      public function delete_by(array $criteria);
 129  
 130      /**
 131       * Find a single favourite, based on it's unique identifiers.
 132       *
 133       * @param int $userid the id of the user to which the favourite belongs.
 134       * @param string $component the frankenstyle component name.
 135       * @param string $itemtype the type of the favourited item.
 136       * @param int $itemid the id of the item which was favourited (not the favourite's id).
 137       * @param int $contextid the contextid of the item which was favourited.
 138       * @return favourite the favourite.
 139       */
 140      public function find_favourite(int $userid, string $component, string $itemtype, int $itemid, int $contextid) : favourite;
 141  }