[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3  *
   4  * This file is part of the phpBB Forum Software package.
   5  *
   6  * @copyright (c) phpBB Limited <https://www.phpbb.com>
   7  * @license GNU General Public License, version 2 (GPL-2.0)
   8  *
   9  * For full copyright and license information, please see
  10  * the docs/CREDITS.txt file.
  11  *
  12  */
  13  
  14  namespace phpbb\notification\method;
  15  
  16  /**
  17  * Base notifications method interface
  18  */
  19  interface method_interface
  20  {
  21      /**
  22      * Get notification method name
  23      *
  24      * @return string
  25      */
  26  	public function get_type();
  27  
  28      /**
  29      * Is the method enable by default?
  30      *
  31      * @return bool
  32      */
  33  	public function is_enabled_by_default();
  34  
  35      /**
  36      * Is this method available for the user?
  37      * This is checked on the notifications options
  38      */
  39  	public function is_available();
  40  
  41      /**
  42      * Return the list of the users already notified
  43      *
  44      * @param int $notification_type_id ID of the notification type
  45      * @param array $options
  46      * @return array User
  47      */
  48  	public function get_notified_users($notification_type_id, array $options);
  49  
  50      /**
  51      * Load the user's notifications
  52      *
  53      * @param array $options Optional options to control what notifications are loaded
  54      *                notification_id        Notification id to load (or array of notification ids)
  55      *                user_id                User id to load notifications for (Default: $user->data['user_id'])
  56      *                order_by            Order by (Default: notification_time)
  57      *                order_dir            Order direction (Default: DESC)
  58      *                 limit                Number of notifications to load (Default: 5)
  59      *                 start                Notifications offset (Default: 0)
  60      *                 all_unread            Load all unread notifications? If set to true, count_unread is set to true (Default: false)
  61      *                 count_unread        Count all unread notifications? (Default: false)
  62      *                 count_total            Count all notifications? (Default: false)
  63      * @return array Array of information based on the request with keys:
  64      *    'notifications'        array of notification type objects
  65      *    'unread_count'        number of unread notifications the user has if count_unread is true in the options
  66      *    'total_count'        number of notifications the user has if count_total is true in the options
  67      */
  68  	public function load_notifications(array $options = array());
  69  
  70      /**
  71      * Add a notification to the queue
  72      *
  73      * @param \phpbb\notification\type\type_interface $notification
  74      */
  75  	public function add_to_queue(\phpbb\notification\type\type_interface $notification);
  76  
  77      /**
  78      * Parse the queue and notify the users
  79      */
  80  	public function notify();
  81  
  82      /**
  83      * Update a notification
  84      *
  85      * @param \phpbb\notification\type\type_interface $notification Notification to update
  86      * @param array $data Data specific for this type that will be updated
  87      * @param array $options
  88      */
  89  	public function update_notification($notification, array $data, array $options);
  90  
  91      /**
  92      * Mark notifications read or unread
  93      *
  94      * @param bool|string $notification_type_id Type identifier of item types. False to mark read for all item types
  95      * @param bool|int|array $item_id Item id or array of item ids. False to mark read for all item ids
  96      * @param bool|int|array $user_id User id or array of user ids. False to mark read for all user ids
  97      * @param bool|int $time Time at which to mark all notifications prior to as read. False to mark all as read. (Default: False)
  98      * @param bool $mark_read Define if the notification as to be set to True or False. (Default: True)
  99      */
 100  	public function mark_notifications($notification_type_id, $item_id, $user_id, $time = false, $mark_read = true);
 101  
 102      /**
 103      * Mark notifications read or unread from a parent identifier
 104      *
 105      * @param string $notification_type_id Type identifier of item types
 106      * @param bool|int|array $item_parent_id Item parent id or array of item parent ids. False to mark read for all item parent ids
 107      * @param bool|int|array $user_id User id or array of user ids. False to mark read for all user ids
 108      * @param bool|int $time Time at which to mark all notifications prior to as read. False to mark all as read. (Default: False)
 109      * @param bool $mark_read Define if the notification as to be set to True or False. (Default: True)
 110      */
 111  	public function mark_notifications_by_parent($notification_type_id, $item_parent_id, $user_id, $time = false, $mark_read = true);
 112  
 113      /**
 114      * Mark notifications read or unread
 115      *
 116      * @param int $notification_id Notification id of notification ids.
 117      * @param bool|int $time Time at which to mark all notifications prior to as read. False to mark all as read. (Default: False)
 118      * @param bool $mark_read Define if the notification as to be set to True or False. (Default: True)
 119      */
 120  	public function mark_notifications_by_id($notification_id, $time = false, $mark_read = true);
 121  
 122      /**
 123      * Delete a notification
 124      *
 125      * @param string $notification_type_id Type identifier of item types
 126      * @param int|array $item_id Identifier within the type (or array of ids)
 127      * @param mixed $parent_id Parent identifier within the type (or array of ids), used in combination with item_id if specified (Default: false; not checked)
 128      * @param mixed $user_id User id (Default: false; not checked)
 129      */
 130  	public function delete_notifications($notification_type_id, $item_id, $parent_id = false, $user_id = false);
 131  
 132      /**
 133      * Delete all notifications older than a certain time
 134      *
 135      * @param int $timestamp Unix timestamp to delete all notifications that were created before
 136      * @param bool $only_read True (default) to only prune read notifications
 137      */
 138  	public function prune_notifications($timestamp, $only_read = true);
 139  
 140      /**
 141      * Purge all notifications of a certain type
 142      *
 143      * This should be called when an extension which has notification types
 144      * is purged so that all those notifications are removed
 145      *
 146      * @param string $notification_type_id Type identifier of the subscription
 147      */
 148  	public function purge_notifications($notification_type_id);
 149  }