mirror/php-phpbb
1
0
Fork 0
mirror of https://github.com/phpbb/phpbb.git synced 2025-05-11 10:05:19 +02:00
Code Issues Releases Wiki Activity

[ticket/11103] Interface docblocks

Browse Source 
PHPBB3-11103
This commit is contained in:
Nathan Guse 2012-10-18 19:13:47 -05:00
parent eb07b3ad9c
commit f96dac3352
6 changed files with 229 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
phpBB/includes/notification/method/email.php
View File

@ -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))

19
phpBB/includes/notification/method/interface.php
View File

@ -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();
}

128
phpBB/includes/notification/type/base.php
View File

@ -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
* 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().
* Pre create insert array function (fall back)
*/
public function pre_create_insert_array($type_data, $notify_users)
{

160
phpBB/includes/notification/type/interface.php
View File

@ -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();
public function get_email_template_variables();
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);
/**
* Users needed to query before this notification can be displayed
*
* @return array Array of user_ids
*/
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);
}

4
phpBB/includes/notification/type/post.php
View File

@ -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

4
phpBB/includes/notification/type/report_pm.php
View File

@ -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()
{