[ticket/11103] Interface docblocks

PHPBB3-11103

phpBB/includes/notification/method/email.php

@@ -40,6 +40,9 @@ class phpbb_notification_method_email extends phpbb_notification_method_base
 		return true;
 	}
 
+	/**
+	* Parse the queue and notify the users
+	*/
 	public function notify()
 	{
 		if (!sizeof($this->queue))

phpBB/includes/notification/method/interface.php

@@ -21,7 +21,26 @@ if (!defined('IN_PHPBB'))
 */
 interface phpbb_notification_method_interface
 {
+	/**
+	* Is this method available for the user?
+	* This is checked on the notifications options
+	*/
 	public function is_available();
 
+	/**
+	* Add a notification to the queue
+	*
+	* @param phpbb_notification_type_interface $notification
+	*/
+	public function add_to_queue(phpbb_notification_type_interface $notification);
+
+	/**
+	* Empty the queue
+	*/
+	protected function empty_queue();
+
+	/**
+	* Parse the queue and notify the users
+	*/
 	public function notify();
 }

phpBB/includes/notification/type/base.php

@@ -149,60 +149,6 @@ abstract class phpbb_notification_type_base implements phpbb_notification_type_i
 		$this->data['data'][$name] = $value;
 	}
 
-	/**
-	* Prepare to output the notification to the template
-	*/
-	public function prepare_for_display()
-	{
-		if ($this->get_url())
-		{
-			$u_mark_read = append_sid($this->phpbb_root_path . 'index.' . $this->php_ext, 'mark_notification=' . $this->notification_id);
-		}
-		else
-		{
-			$redirect = (($this->user->page['page_dir']) ? $this->user->page['page_dir'] . '/' : '') . $this->user->page['page_name'] . (($this->user->page['query_string']) ? '?' . $this->user->page['query_string'] : '');
-
-			$u_mark_read = append_sid($this->phpbb_root_path . 'index.' . $this->php_ext, 'mark_notification=' . $this->notification_id . '&redirect=' . urlencode($redirect));
-		}
-
-		return array(
-			'NOTIFICATION_ID'	=> $this->notification_id,
-
-			'AVATAR'			=> $this->get_avatar(),
-
-			'FORMATTED_TITLE'	=> $this->get_title(),
-
-			'URL'				=> $this->get_url(),
-			'TIME'	   			=> $this->user->format_date($this->time),
-
-			'UNREAD'			=> $this->unread,
-
-			'U_MARK_READ'		=> ($this->unread) ? $u_mark_read : '',
-		);
-	}
-
-	/**
-	* Mark this item read
-	*
-	* @param bool $return True to return a string containing the SQL code to update this item, False to execute it (Default: False)
-	* @return string
-	*/
-	public function mark_read($return = false)
-	{
-		return $this->mark(false, $return);
-	}
-
-	/**
-	* Mark this item unread
-	*
-	* @param bool $return True to return a string containing the SQL code to update this item, False to execute it (Default: False)
-	* @return string
-	*/
-	public function mark_unread($return = false)
-	{
-		return $this->mark(true, $return);
-	}
-
 	/**
 	* Function for preparing the data for insertion in an SQL query
 	* (The service handles insertion)
@@ -256,12 +202,66 @@ abstract class phpbb_notification_type_base implements phpbb_notification_type_i
 		return $data;
 	}
 
+	/**
+	* Mark this item read
+	*
+	* @param bool $return True to return a string containing the SQL code to update this item, False to execute it (Default: False)
+	* @return string
+	*/
+	public function mark_read($return = false)
+	{
+		return $this->mark(false, $return);
+	}
+
+	/**
+	* Mark this item unread
+	*
+	* @param bool $return True to return a string containing the SQL code to update this item, False to execute it (Default: False)
+	* @return string
+	*/
+	public function mark_unread($return = false)
+	{
+		return $this->mark(true, $return);
+	}
+
+	/**
+	* Prepare to output the notification to the template
+	*/
+	public function prepare_for_display()
+	{
+		if ($this->get_url())
+		{
+			$u_mark_read = append_sid($this->phpbb_root_path . 'index.' . $this->php_ext, 'mark_notification=' . $this->notification_id);
+		}
+		else
+		{
+			$redirect = (($this->user->page['page_dir']) ? $this->user->page['page_dir'] . '/' : '') . $this->user->page['page_name'] . (($this->user->page['query_string']) ? '?' . $this->user->page['query_string'] : '');
+
+			$u_mark_read = append_sid($this->phpbb_root_path . 'index.' . $this->php_ext, 'mark_notification=' . $this->notification_id . '&redirect=' . urlencode($redirect));
+		}
+
+		return array(
+			'NOTIFICATION_ID'	=> $this->notification_id,
+
+			'AVATAR'			=> $this->get_avatar(),
+
+			'FORMATTED_TITLE'	=> $this->get_title(),
+
+			'URL'				=> $this->get_url(),
+			'TIME'	   			=> $this->user->format_date($this->time),
+
+			'UNREAD'			=> $this->unread,
+
+			'U_MARK_READ'		=> ($this->unread) ? $u_mark_read : '',
+		);
+	}
+
 	/**
 	* -------------- Fall back functions -------------------
 	*/
 
 	/**
-	* URL to unsubscribe to this notification (fall-back)
+	* URL to unsubscribe to this notification (fall back)
 	*
 	* @param string|bool $method Method name to unsubscribe from (email|jabber|etc), False to unsubscribe from all notifications for this item
 	*/
@@ -271,7 +271,7 @@ abstract class phpbb_notification_type_base implements phpbb_notification_type_i
 	}
 
 	/**
-	* Get the user's avatar (fall-back)
+	* Get the user's avatar (fall back)
 	*/
 	public function get_avatar()
 	{
@@ -279,7 +279,7 @@ abstract class phpbb_notification_type_base implements phpbb_notification_type_i
 	}
 
 	/**
-	* Get the special items to load (fall-back)
+	* Get the special items to load (fall back)
 	*/
 	public function get_load_special()
 	{
@@ -287,7 +287,7 @@ abstract class phpbb_notification_type_base implements phpbb_notification_type_i
 	}
 
 	/**
-	* Load the special items (fall-back)
+	* Load the special items (fall back)
 	*/
 	public function load_special($data, $notifications)
 	{
@@ -295,7 +295,7 @@ abstract class phpbb_notification_type_base implements phpbb_notification_type_i
 	}
 
 	/**
-	* Is available (fall-back)
+	* Is available (fall back)
 	*/
 	public function is_available()
 	{
@@ -303,15 +303,7 @@ abstract class phpbb_notification_type_base implements phpbb_notification_type_i
 	}
 
 	/**
-	* Pre create insert array function
+	* Pre create insert array function (fall back)
-	* This allows you to perform certain actions, like run a query
-	* and load data, before create_insert_array() is run. The data
-	* returned from this function will be sent to create_insert_array().
-	*
-	* @param array $type_data Data unique to this notification type
-	* @param array $notify_users Notify users list
-	* 		Formated from find_users_for_notification()
-	* @return array Whatever you want to send to create_insert_array().
 	*/
 	public function pre_create_insert_array($type_data, $notify_users)
 	{

phpBB/includes/notification/type/interface.php

@@ -21,33 +21,161 @@ if (!defined('IN_PHPBB'))
 */
 interface phpbb_notification_type_interface
 {
+	/**
+	* Set initial data from the database
+	*
+	* @param array $data Row directly from the database
+	*/
+	public function set_initial_data($data);
+
+	/**
+	* Get the type of notification this is
+	* phpbb_notification_type_
+	*/
 	public static function get_item_type();
 
+	/**
+	* Get the id of the item
+	*
+	* @param array $type_data The type specific data
+	*/
 	public static function get_item_id($type_data);
 
+	/**
+	* Get the id of the parent
+	*
+	* @param array $type_data The type specific data
+	*/
+	public static function get_item_parent_id($type_data);
+
+	/**
+	* Is this type available to the current user (defines whether or not it will be shown in the UCP Edit notification options)
+	*
+	* @return bool True/False whether or not this is available to the user
+	*/
 	public function is_available();
 
+	/**
+	* Find the users who want to receive notifications
+	*
+	* @param array $type_data The type specific data
+	* @param array $options Options for finding users for notification
+	* 		ignore_users => array of users and user types that should not receive notifications from this type because they've already been notified
+	* 						e.g.: array(2 => array(''), 3 => array('', 'email'), ...)
+	*
+	* @return array
+	*/
 	public function find_users_for_notification($type_data, $options);
 
-	public function get_title();
+	/**
-
+	* Users needed to query before this notification can be displayed
-	public function get_email_template_variables();
+	*
-
+	* @return array Array of user_ids
-	public function get_url();
+	*/
-
-	public function get_unsubscribe_url($method);
-
-	public function mark_read($return);
-
-	public function mark_unread($return);
-
-	public function pre_create_insert_array($type_data, $notify_users);
-
-	public function create_insert_array($type_data, $pre_create_data);
-
 	public function users_to_query();
 
+	/**
+	* Get the special items to load
+	*
+	* @return array Data will be combined sent to load_special() so you can run a single query and get data required for this notification type
+	*/
 	public function get_load_special();
 
+	/**
+	* Load the special items
+	*
+	* @param array $data Data from get_load_special()
+	* @param array $notifications Array of notifications (key is notification_id, value is the notification objects)
+	*/
 	public function load_special($data, $notifications);
+
+	/**
+	* Get the HTML formatted title of this notification
+	*
+	* @return string
+	*/
+	public function get_title();
+
+	/**
+	* Get the url to this item
+	*
+	* @return string URL
+	*/
+	public function get_url();
+
+	/**
+	* URL to unsubscribe to this notification
+	*
+	* @param string|bool $method Method name to unsubscribe from (email|jabber|etc), False to unsubscribe from all notifications for this item
+	*/
+	public function get_unsubscribe_url($method);
+
+	/**
+	* Get the user's avatar (the user who caused the notification typically)
+	*
+	* @return string
+	*/
+	public function get_avatar();
+
+	/**
+	* Prepare to output the notification to the template
+	*/
+	public function prepare_for_display();
+
+	/**
+	* Get email template variables
+	*
+	* @return array
+	*/
+	public function get_email_template_variables();
+
+	/**
+	* Pre create insert array function
+	* This allows you to perform certain actions, like run a query
+	* and load data, before create_insert_array() is run. The data
+	* returned from this function will be sent to create_insert_array().
+	*
+	* @param array $type_data The type specific data
+	* @param array $notify_users Notify users list
+	* 		Formated from find_users_for_notification()
+	* @return array Whatever you want to send to create_insert_array().
+	*/
+	public function pre_create_insert_array($type_data, $notify_users);
+
+	/**
+	* Function for preparing the data for insertion in an SQL query
+	* (The service handles insertion)
+	*
+	* @param array $type_data The type specific data
+	* @param array $pre_create_data Data from pre_create_insert_array()
+	*
+	* @return array Array of data ready to be inserted into the database
+	*/
+	public function create_insert_array($type_data, $pre_create_data);
+
+	/**
+	* Function for preparing the data for update in an SQL query
+	* (The service handles insertion)
+	*
+	* @param array $type_data Data unique to this notification type
+	*
+	* @return array Array of data ready to be updated in the database
+	*/
+	public function create_update_array($type_data);
+
+	/**
+	* Mark this item read
+	*
+	* @param bool $return True to return a string containing the SQL code to update this item, False to execute it (Default: False)
+	* @return string
+	*/
+	public function mark_read($return);
+
+	/**
+	* Mark this item unread
+	*
+	* @param bool $return True to return a string containing the SQL code to update this item, False to execute it (Default: False)
+	* @return string
+	*/
+	public function mark_unread($return);
 }

phpBB/includes/notification/type/post.php

@@ -89,10 +89,6 @@ class phpbb_notification_type_post extends phpbb_notification_type_base
 			'ignore_users'		=> array(),
 		), $options);
 
-		// Let's continue to use the phpBB subscriptions system, at least for now.
-		// It may not be the nicest thing, but it is already working and it would be significant work to replace it
-		//$users = parent::_find_users_for_notification($phpbb_container, $post['topic_id']);
-
 		$users = array();
 
 		$sql = 'SELECT user_id

phpBB/includes/notification/type/report_pm.php

@@ -76,7 +76,9 @@ class phpbb_notification_type_report_pm extends phpbb_notification_type_pm
 	}
 
 	/**
-	* Is available
+	* Is this type available to the current user (defines whether or not it will be shown in the UCP Edit notification options)
+	*
+	* @return bool True/False whether or not this is available to the user
 	*/
 	public function is_available()
 	{