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	}