From 67cf0a912c8ed24c7466163fa409e8154082e1df Mon Sep 17 00:00:00 2001 From: Joas Schilling Date: Sun, 13 Apr 2014 23:24:10 +0200 Subject: [ticket/10073] Add doc blocks to new classes PHPBB3-10073 --- phpBB/phpbb/message/admin_form.php | 21 ++++++++ phpBB/phpbb/message/form.php | 64 ++++++++++++++++++++--- phpBB/phpbb/message/message.php | 101 ++++++++++++++++++++++++++++++++++++- phpBB/phpbb/message/topic_form.php | 33 +++++++++++- phpBB/phpbb/message/user_form.php | 55 +++++++++++++++----- 5 files changed, 251 insertions(+), 23 deletions(-) (limited to 'phpBB/phpbb/message') diff --git a/phpBB/phpbb/message/admin_form.php b/phpBB/phpbb/message/admin_form.php index dc995062a0..5201994c73 100644 --- a/phpBB/phpbb/message/admin_form.php +++ b/phpBB/phpbb/message/admin_form.php @@ -9,12 +9,24 @@ namespace phpbb\message; +/** +* Class admin_form +* Displays a message to the user and allows him to send an email +* +* @package phpbb\message +*/ class admin_form extends form { + /** @var string */ protected $subject; + /** @var string */ protected $sender_name; + /** @var string */ protected $sender_address; + /** + * {inheritDoc} + */ public function check_allow() { $error = parent::check_allow(); @@ -31,6 +43,9 @@ class admin_form extends form return false; } + /** + * {inheritDoc} + */ public function bind(\phpbb\request\request_interface $request) { parent::bind($request); @@ -40,6 +55,9 @@ class admin_form extends form $this->sender_name = $request->variable('name', '', true); } + /** + * {inheritDoc} + */ public function submit(\messenger $messenger) { if (!$this->subject) @@ -93,6 +111,9 @@ class admin_form extends form parent::submit($messenger); } + /** + * {inheritDoc} + */ public function render(\phpbb\template\template $template) { $template->assign_vars(array( diff --git a/phpBB/phpbb/message/form.php b/phpBB/phpbb/message/form.php index 91da2d69b5..205999e5f2 100644 --- a/phpBB/phpbb/message/form.php +++ b/phpBB/phpbb/message/form.php @@ -9,6 +9,11 @@ namespace phpbb\message; +/** +* Abstract class form +* +* @package phpbb\message +*/ abstract class form { /** @var \phpbb\auth\auth */ @@ -17,6 +22,8 @@ abstract class form protected $config; /** @var \phpbb\db\driver\driver_interface */ protected $db; + /** @var \phpbb\message\message */ + protected $message; /** @var \phpbb\user */ protected $user; @@ -25,11 +32,23 @@ abstract class form /** @var string */ protected $phpEx; - protected $errors; - protected $message; + /** @var array */ + protected $errors = array(); + /** @var bool */ protected $cc_sender; + /** @var string */ protected $body; + /** + * Construct + * + * @param \phpbb\auth\auth $auth + * @param \phpbb\config\config $config + * @param \phpbb\db\driver\driver_interface $db + * @param \phpbb\user $user + * @param string $phpbb_root_path + * @param string $phpEx + */ public function __construct(\phpbb\auth\auth $auth, \phpbb\config\config $config, \phpbb\db\driver\driver_interface $db, \phpbb\user $user, $phpbb_root_path, $phpEx) { $this->phpbb_root_path = $phpbb_root_path; @@ -39,25 +58,35 @@ abstract class form $this->config = $config; $this->db = $db; - $this->errors = array(); - - $this->message = new \phpbb\message\message($config['server_name']); + $this->message = new message($config['server_name']); $this->message->set_sender_from_user($this->user); } /** * Returns the title for the email form page + * + * @return string */ public function get_page_title() { - $this->user->lang['SEND_EMAIL']; + return $this->user->lang['SEND_EMAIL']; } + /** + * Returns the file name of the form template + * + * @return string + */ public function get_template_file() { return 'memberlist_email.html'; } + /** + * Checks whether the user is allowed to use the form + * + * @return false|string Error string if not allowed, false otherwise + */ public function check_allow() { if (!$this->config['email_enable']) @@ -73,17 +102,34 @@ abstract class form return false; } + /** + * Get the return link after the message has been sent + * + * @return string + */ public function get_return_message() { return sprintf($this->user->lang['RETURN_INDEX'], '', ''); } + /** + * Bind the values of the request to the form + * + * @param \phpbb\request\request_interface $request + * @return null + */ public function bind(\phpbb\request\request_interface $request) { $this->cc_sender = $request->is_set_post('cc_sender'); $this->body = $request->variable('message', '', true); } + /** + * Submit form, generate the email and send it + * + * @param \messenger $messenger + * @return null + */ public function submit(\messenger $messenger) { if (!check_form_key('memberlist_email')) @@ -110,6 +156,12 @@ abstract class form } } + /** + * Render the template of the form + * + * @param \phpbb\template\template $template + * @return null + */ public function render(\phpbb\template\template $template) { add_form_key('memberlist_email'); diff --git a/phpBB/phpbb/message/message.php b/phpBB/phpbb/message/message.php index 899d553a6d..332604cc8e 100644 --- a/phpBB/phpbb/message/message.php +++ b/phpBB/phpbb/message/message.php @@ -9,63 +9,129 @@ namespace phpbb\message; +/** +* Class message +* Holds all information for an email and sends it in the end +* +* @package phpbb\message +*/ class message { + /** @var string */ protected $server_name; + /** @var string */ protected $subject = ''; + /** @var string */ protected $body = ''; + /** @var string */ protected $template = ''; + /** @var array */ protected $template_vars = array(); + /** @var string */ protected $sender_ip = ''; + /** @var string */ protected $sender_name = ''; + /** @var string */ protected $sender_address = ''; + /** @var string */ protected $sender_lang = ''; + /** @var string */ protected $sender_id = ''; + /** @var string */ protected $sender_username = ''; + /** @var string */ protected $sender_jabber = ''; + /** @var int */ protected $sender_notify_type = NOTIFY_EMAIL; + /** @var array */ protected $recipients; + /** + * Construct + * + * @param string $server_name Used for AntiAbuse header + */ public function __construct($server_name) { $this->server_name = $server_name; } + /** + * Set the subject of the email + * + * @param string $subject + * @return null + */ public function set_subject($subject) { $this->subject = $subject; } + /** + * Set the body of the email text + * + * @param string $body + * @return null + */ public function set_body($body) { $this->body = $body; } + /** + * Set the name of the email template to use + * + * @param string $template + * @return null + */ public function set_template($template) { $this->template = $template; } + /** + * Set the array with the "template" data for the email + * + * @param array $template_vars + * @return null + */ public function set_template_vars($template_vars) { $this->template_vars = $template_vars; } + /** + * Add a recipient from \phpbb\user + * + * @param \phpbb\user $user + * @return null + */ public function add_recipient_from_user_row(array $user) { $this->add_recipient( $user['username'], $user['user_email'], $user['user_lang'], + $user['user_notify_type'], $user['username'], - $user['user_jabber'], - $user['user_notify_type'] + $user['user_jabber'] ); } + /** + * Add a recipient + * + * @param string $recipient_name Displayed sender name + * @param string $recipient_address Email address + * @param string $recipient_lang + * @param int $recipient_notify_type Used notification methods (Jabber, Email, ...) + * @param string $recipient_username User Name (used for AntiAbuse header) + * @param string $recipient_jabber + * @return null + */ public function add_recipient($recipient_name, $recipient_address, $recipient_lang, $recipient_notify_type = NOTIFY_EMAIL, $recipient_username = '', $recipient_jabber = '') { $this->recipients[] = array( @@ -79,6 +145,12 @@ class message ); } + /** + * Set the senders data from \phpbb\user object + * + * @param \phpbb\user $user + * @return null + */ public function set_sender_from_user($user) { $this->set_sender( @@ -94,6 +166,18 @@ class message $this->set_sender_notify_type($user->data['user_notify_type']); } + /** + * Set the senders data + * + * @param string $sender_ip + * @param string $sender_name Displayed sender name + * @param string $sender_address Email address + * @param string $sender_lang + * @param int $sender_id User ID + * @param string $sender_username User Name (used for AntiAbuse header) + * @param string $sender_jabber + * @return null + */ public function set_sender($sender_ip, $sender_name, $sender_address, $sender_lang = '', $sender_id = 0, $sender_username = '', $sender_jabber = '') { $this->sender_ip = $sender_ip; @@ -105,6 +189,12 @@ class message $this->sender_jabber = $sender_jabber; } + /** + * Which notification type should be used? Jabber, Email, ...? + * + * @param int $sender_notify_type + * @return null + */ public function set_sender_notify_type($sender_notify_type) { $this->sender_notify_type = $sender_notify_type; @@ -137,6 +227,13 @@ class message ); } + /** + * Send the email + * + * @param \messenger $messenger + * @param string $phpEx + * @return null + */ public function send(\messenger $messenger, $phpEx) { if (!sizeof($this->recipients)) diff --git a/phpBB/phpbb/message/topic_form.php b/phpBB/phpbb/message/topic_form.php index 5a5d090017..988028c301 100644 --- a/phpBB/phpbb/message/topic_form.php +++ b/phpBB/phpbb/message/topic_form.php @@ -9,15 +9,31 @@ namespace phpbb\message; +/** +* Class topic_form +* Form used to send topics as notification emails +* +* @package phpbb\message +*/ class topic_form extends form { + /** @var int */ protected $topic_id; - + /** @var array */ protected $topic_row; + /** @var string */ protected $recipient_address; + /** @var string */ protected $recipient_name; + /** @var string */ protected $recipient_lang; + /** + * Get the data of the topic + * + * @param int $topic_id + * @return false|array false if the topic does not exist, array otherwise + */ protected function get_topic_row($topic_id) { $sql = 'SELECT forum_id, topic_title @@ -30,6 +46,9 @@ class topic_form extends form return $row; } + /** + * {inheritDoc} + */ public function check_allow() { $error = parent::check_allow(); @@ -61,6 +80,9 @@ class topic_form extends form return false; } + /** + * {inheritDoc} + */ public function bind(\phpbb\request\request_interface $request) { parent::bind($request); @@ -73,6 +95,9 @@ class topic_form extends form $this->topic_row = $this->get_topic_row($this->topic_id); } + /** + * {inheritDoc} + */ public function submit(\messenger $messenger) { if (!$this->recipient_address || !preg_match('/^' . get_preg_expression('email') . '$/i', $this->recipient_address)) @@ -102,11 +127,17 @@ class topic_form extends form parent::submit($messenger); } + /** + * {inheritDoc} + */ public function get_return_message() { return sprintf($this->user->lang['RETURN_TOPIC'], '', ''); } + /** + * {inheritDoc} + */ public function render(\phpbb\template\template $template) { parent::render($template); diff --git a/phpBB/phpbb/message/user_form.php b/phpBB/phpbb/message/user_form.php index a76d553b7c..5e98590c58 100644 --- a/phpBB/phpbb/message/user_form.php +++ b/phpBB/phpbb/message/user_form.php @@ -9,12 +9,43 @@ namespace phpbb\message; +/** +* Class user_form +* Allows users to send emails to other users +* +* @package phpbb\message +*/ class user_form extends form { + /** @var int */ protected $recipient_id; - protected $subject; + /** @var array */ protected $recipient_row; + /** @var string */ + protected $subject; + /** + * Get the data of the recipient + * + * @param int $user_id + * @return false|array false if the user does not exist, array otherwise + */ + protected function get_user_row($user_id) + { + $sql = 'SELECT username, user_email, user_allow_viewemail, user_lang, user_jabber, user_notify_type + FROM ' . USERS_TABLE . ' + WHERE user_id = ' . (int) $user_id . ' + AND user_type IN (' . USER_NORMAL . ', ' . USER_FOUNDER . ')'; + $result = $this->db->sql_query($sql); + $row = $this->db->sql_fetchrow($result); + $this->db->sql_freeresult($result); + + return $row; + } + + /** + * {inheritDoc} + */ public function check_allow() { $error = parent::check_allow(); @@ -47,19 +78,9 @@ class user_form extends form return false; } - protected function get_user_row($user_id) - { - $sql = 'SELECT username, user_email, user_allow_viewemail, user_lang, user_jabber, user_notify_type - FROM ' . USERS_TABLE . ' - WHERE user_id = ' . ((int) $user_id) . ' - AND user_type IN (' . USER_NORMAL . ', ' . USER_FOUNDER . ')'; - $result = $this->db->sql_query($sql); - $row = $this->db->sql_fetchrow($result); - $this->db->sql_freeresult($result); - - return $row; - } - + /** + * {inheritDoc} + */ public function bind(\phpbb\request\request_interface $request) { parent::bind($request); @@ -70,6 +91,9 @@ class user_form extends form $this->recipient_row = $this->get_user_row($this->recipient_id); } + /** + * {inheritDoc} + */ public function submit(\messenger $messenger) { if (!$this->subject) @@ -90,6 +114,9 @@ class user_form extends form parent::submit($messenger); } + /** + * {inheritDoc} + */ public function render(\phpbb\template\template $template) { parent::render($template); -- cgit v1.2.1