From 3d2bdeb5a42dc698f9c0c92cc72606ee9f96a401 Mon Sep 17 00:00:00 2001 From: Matthew Exon Date: Sat, 8 May 2021 19:59:46 +0200 Subject: [PATCH 1/2] Add comments to functions in mailstream plugin --- mailstream/mailstream.php | 110 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 107 insertions(+), 3 deletions(-) diff --git a/mailstream/mailstream.php b/mailstream/mailstream.php index 6d5e15d2..38d159d9 100644 --- a/mailstream/mailstream.php +++ b/mailstream/mailstream.php @@ -16,6 +16,9 @@ use Friendica\Model\Item; use Friendica\Model\Post; use Friendica\Protocol\Activity; +/** + * Sets up the addon hooks and the database table + */ function mailstream_install() { Hook::register('addon_settings', 'addon/mailstream/mailstream.php', 'mailstream_addon_settings'); Hook::register('addon_settings_post', 'addon/mailstream/mailstream.php', 'mailstream_addon_settings_post'); @@ -57,9 +60,18 @@ function mailstream_install() { } } +/** + * This funciton indicates a module that can be wrapped in the LegacyModule class + */ function mailstream_module() {} -function mailstream_addon_admin(&$a,&$o) { +/** + * Adds an item in "addon features" in the admin menu of the site + * + * @param Friendica\App $a App object (unused) + * @param string $o HTML form data + */ +function mailstream_addon_admin(&$a, &$o) { $frommail = DI::config()->get('mailstream', 'frommail'); $template = Renderer::getMarkupTemplate('admin.tpl', 'addon/mailstream/'); $config = ['frommail', @@ -71,14 +83,27 @@ function mailstream_addon_admin(&$a,&$o) { '$submit' => DI::l10n()->t('Save Settings')]); } +/** + * Process input from the "addon features" part of the admin menu + * + * @param Friendica\App $a App object (unused) + */ function mailstream_addon_admin_post ($a) { if (!empty($_POST['frommail'])) { DI::config()->set('mailstream', 'frommail', $_POST['frommail']); } } +/** + * Creates a message ID for a post URI in accordance with RFC 1036 + * See also http://www.jwz.org/doc/mid.html + * + * @param Friendica\App $a App object (unused) + * @param string $uri the URI to be converted to a message ID + * + * @return string the created message ID + */ function mailstream_generate_id($a, $uri) { - // http://www.jwz.org/doc/mid.html $host = DI::baseUrl()->getHostname(); $resource = hash('md5', $uri); $message_id = "<" . $resource . "@" . $host . ">"; @@ -86,6 +111,14 @@ function mailstream_generate_id($a, $uri) { return $message_id; } +/** + * Called when either a local or remote post is created. Creates a + * record in the mailstream_item table to track this email, and then + * immediately attempts to send it + * + * @param Friendica\App $a App object (unused) + * @param array $item results from the item table + */ function mailstream_post_hook(&$a, &$item) { if (!DI::pConfig()->get($item['uid'], 'mailstream', 'enabled')) { Logger::debug('mailstream: not enabled for item ' . $item['id']); @@ -133,6 +166,13 @@ function mailstream_post_hook(&$a, &$item) { mailstream_send($a, $ms_item['message-id'], $item, $user); } +/** + * Converts a user ID into a full user record from the corresponding database table + * + * @param int $uid ID of the user to query + * + * @return array results from the user table + */ function mailstream_get_user($uid) { $r = q('SELECT * FROM `user` WHERE `uid` = %d', intval($uid)); if (count($r) != 1) { @@ -142,6 +182,18 @@ function mailstream_get_user($uid) { return $r[0]; } +/** + * If the user has configured attaching images to emails as + * attachments, this function searches the post for such images, + * retrieves the image, and inserts the data and metadata into the + * supplied array + * + * @param Friendica\App $a App object (unused) + * @param array $item results from the item table + * @param array $attachments contains an array element for each attachment to add to the email + * + * @return array new value of the attachments table (results are also stored in the reference parameter) + */ function mailstream_do_images($a, &$item, &$attachments) { if (!DI::pConfig()->get($item['uid'], 'mailstream', 'attachimg')) { return; @@ -172,6 +224,13 @@ function mailstream_do_images($a, &$item, &$attachments) { return $attachments; } +/** + * Creates a sender to use in the email, either from the contact or the author of the item, or both + * + * @param array $item results from the item table + * + * @return string sender suitable for use in the email + */ function mailstream_sender($item) { $r = q('SELECT * FROM `contact` WHERE `id` = %d', $item['contact-id']); if (DBA::isResult($r)) { @@ -183,6 +242,13 @@ function mailstream_sender($item) { return $item['author-name']; } +/** + * Converts a bbcode-encoded subject line into a plaintext version suitable for the subject line of an email + * + * @param string $subject bbcode-encoded subject line + * + * @return string plaintext subject line + */ function mailstream_decode_subject($subject) { $html = BBCode::convert($subject); if (!$html) { @@ -207,6 +273,13 @@ function mailstream_decode_subject($subject) { return $trimmed; } +/** + * Creates a subject line to use in the email + * + * @param array $item results from the item table + * + * @return string subject line suitable for use in the email + */ function mailstream_subject($item) { if ($item['title']) { return mailstream_decode_subject($item['title']); @@ -255,6 +328,14 @@ function mailstream_subject($item) { return DI::l10n()->t("Friendica Item"); } +/** + * Sends a message using PHPMailer + * + * @param Friendica\App $a App object (unused) + * @param string $message_id ID of the message (RFC 1036) + * @param array $item results from the item table + * @param array $user results from the user table + */ function mailstream_send(\Friendica\App $a, $message_id, $item, $user) { if (!$item['visible']) { return; @@ -320,6 +401,8 @@ function mailstream_send(\Friendica\App $a, $message_id, $item, $user) { * Email tends to break if you send excessively long lines. To make * bbcode's output suitable for transmission, we try to break things * up so that lines are about 200 characters. + * + * @param string $text text to word wrap - modified in-place */ function mailstream_html_wrap(&$text) { @@ -330,6 +413,12 @@ function mailstream_html_wrap(&$text) $text = implode($lines); } +/** + * Cron job for the mailstream plugin. Sends delayed messages and cleans up old successful entries from the table. + * + * @param Friendica\App $a App object + * @param null $b legacy argument (unused) + */ function mailstream_cron($a, $b) { // Only process items older than an hour in cron. This is because // we want to give mailstream_post_remote_hook a fair chance to @@ -380,6 +469,12 @@ EOT; mailstream_tidy(); } +/** + * Form for configuring mailstream features for a user + * + * @param Friendica\App $a App object + * @param string $o HTML form data + */ function mailstream_addon_settings(&$a, &$s) { $enabled = DI::pConfig()->get(local_user(), 'mailstream', 'enabled'); $address = DI::pConfig()->get(local_user(), 'mailstream', 'address'); @@ -410,7 +505,13 @@ function mailstream_addon_settings(&$a, &$s) { '$submit' => DI::l10n()->t('Save Settings')]); } -function mailstream_addon_settings_post($a,$post) { +/** + * Process data submitted to user's mailstream features form + * + * @param Friendica\App $a App object + * @param array $post posted results (unused) + */ +function mailstream_addon_settings_post($a, $post) { if ($_POST['mailstream_address'] != "") { DI::pConfig()->set(local_user(), 'mailstream', 'address', $_POST['mailstream_address']); } @@ -437,6 +538,9 @@ function mailstream_addon_settings_post($a,$post) { } } +/** + * Deletes records from the mailstream_item table older than one year + */ function mailstream_tidy() { $r = q("SELECT id FROM mailstream_item WHERE completed IS NOT NULL AND completed < DATE_SUB(NOW(), INTERVAL 1 YEAR)"); foreach ($r as $rr) { From 99462552a01800586209845e5a16002e03cfcb6b Mon Sep 17 00:00:00 2001 From: Matthew Exon Date: Sat, 8 May 2021 21:01:51 +0200 Subject: [PATCH 2/2] correction to the content of the item array --- mailstream/mailstream.php | 49 +++++++++++++++------------------------ 1 file changed, 19 insertions(+), 30 deletions(-) diff --git a/mailstream/mailstream.php b/mailstream/mailstream.php index 38d159d9..845118a0 100644 --- a/mailstream/mailstream.php +++ b/mailstream/mailstream.php @@ -85,10 +85,8 @@ function mailstream_addon_admin(&$a, &$o) { /** * Process input from the "addon features" part of the admin menu - * - * @param Friendica\App $a App object (unused) */ -function mailstream_addon_admin_post ($a) { +function mailstream_addon_admin_post() { if (!empty($_POST['frommail'])) { DI::config()->set('mailstream', 'frommail', $_POST['frommail']); } @@ -98,12 +96,11 @@ function mailstream_addon_admin_post ($a) { * Creates a message ID for a post URI in accordance with RFC 1036 * See also http://www.jwz.org/doc/mid.html * - * @param Friendica\App $a App object (unused) - * @param string $uri the URI to be converted to a message ID + * @param string $uri the URI to be converted to a message ID * * @return string the created message ID */ -function mailstream_generate_id($a, $uri) { +function mailstream_generate_id($uri) { $host = DI::baseUrl()->getHostname(); $resource = hash('md5', $uri); $message_id = "<" . $resource . "@" . $host . ">"; @@ -117,7 +114,7 @@ function mailstream_generate_id($a, $uri) { * immediately attempts to send it * * @param Friendica\App $a App object (unused) - * @param array $item results from the item table + * @param array $item content of the item (may or may not already be stored in the item table) */ function mailstream_post_hook(&$a, &$item) { if (!DI::pConfig()->get($item['uid'], 'mailstream', 'enabled')) { @@ -147,7 +144,7 @@ function mailstream_post_hook(&$a, &$item) { } } - $message_id = mailstream_generate_id($a, $item['uri']); + $message_id = mailstream_generate_id($item['uri']); q("INSERT INTO `mailstream_item` (`uid`, `contact-id`, `uri`, `message-id`) " . "VALUES (%d, '%s', '%s', '%s')", intval($item['uid']), intval($item['contact-id']), DBA::escape($item['uri']), DBA::escape($message_id)); @@ -163,7 +160,7 @@ function mailstream_post_hook(&$a, &$item) { Logger::info('mailstream_post_remote_hook: no user ' . $item['uid']); return; } - mailstream_send($a, $ms_item['message-id'], $item, $user); + mailstream_send($ms_item['message-id'], $item, $user); } /** @@ -188,13 +185,12 @@ function mailstream_get_user($uid) { * retrieves the image, and inserts the data and metadata into the * supplied array * - * @param Friendica\App $a App object (unused) - * @param array $item results from the item table + * @param array $item content of the item * @param array $attachments contains an array element for each attachment to add to the email * * @return array new value of the attachments table (results are also stored in the reference parameter) */ -function mailstream_do_images($a, &$item, &$attachments) { +function mailstream_do_images(&$item, &$attachments) { if (!DI::pConfig()->get($item['uid'], 'mailstream', 'attachimg')) { return; } @@ -227,7 +223,7 @@ function mailstream_do_images($a, &$item, &$attachments) { /** * Creates a sender to use in the email, either from the contact or the author of the item, or both * - * @param array $item results from the item table + * @param array $item content of the item * * @return string sender suitable for use in the email */ @@ -276,7 +272,7 @@ function mailstream_decode_subject($subject) { /** * Creates a subject line to use in the email * - * @param array $item results from the item table + * @param array $item content of the item * * @return string subject line suitable for use in the email */ @@ -331,12 +327,11 @@ function mailstream_subject($item) { /** * Sends a message using PHPMailer * - * @param Friendica\App $a App object (unused) - * @param string $message_id ID of the message (RFC 1036) - * @param array $item results from the item table - * @param array $user results from the user table + * @param string $message_id ID of the message (RFC 1036) + * @param array $item content of the item + * @param array $user results from the user table */ -function mailstream_send(\Friendica\App $a, $message_id, $item, $user) { +function mailstream_send($message_id, $item, $user) { if (!$item['visible']) { return; } @@ -346,7 +341,7 @@ function mailstream_send(\Friendica\App $a, $message_id, $item, $user) { require_once(dirname(__file__).'/phpmailer/class.phpmailer.php'); $attachments = []; - mailstream_do_images($a, $item, $attachments); + mailstream_do_images($item, $attachments); $frommail = DI::config()->get('mailstream', 'frommail'); if ($frommail == "") { $frommail = 'friendica@localhost.local'; @@ -363,7 +358,7 @@ function mailstream_send(\Friendica\App $a, $message_id, $item, $user) { $mail->MessageID = $message_id; $mail->Subject = mailstream_subject($item); if ($item['thr-parent'] != $item['uri']) { - $mail->addCustomHeader('In-Reply-To: ' . mailstream_generate_id($a, $item['thr-parent'])); + $mail->addCustomHeader('In-Reply-To: ' . mailstream_generate_id($item['thr-parent'])); } $mail->addCustomHeader('X-Friendica-Mailstream-URI: ' . $item['uri']); $mail->addCustomHeader('X-Friendica-Mailstream-Plink: ' . $item['plink']); @@ -415,11 +410,8 @@ function mailstream_html_wrap(&$text) /** * Cron job for the mailstream plugin. Sends delayed messages and cleans up old successful entries from the table. - * - * @param Friendica\App $a App object - * @param null $b legacy argument (unused) */ -function mailstream_cron($a, $b) { +function mailstream_cron() { // Only process items older than an hour in cron. This is because // we want to give mailstream_post_remote_hook a fair chance to // send the email itself before cron jumps in. Only if @@ -458,7 +450,7 @@ EOT; $users = q("SELECT * FROM `user` WHERE `uid` = %d", intval($item['uid'])); $user = $users[0]; if ($user && $item) { - mailstream_send($a, $ms_item_id['message-id'], $item, $user); + mailstream_send($ms_item_id['message-id'], $item, $user); } else { Logger::info('mailstream_cron: Unable to find item ' . $ms_item_id['id']); @@ -507,11 +499,8 @@ function mailstream_addon_settings(&$a, &$s) { /** * Process data submitted to user's mailstream features form - * - * @param Friendica\App $a App object - * @param array $post posted results (unused) */ -function mailstream_addon_settings_post($a, $post) { +function mailstream_addon_settings_post() { if ($_POST['mailstream_address'] != "") { DI::pConfig()->set(local_user(), 'mailstream', 'address', $_POST['mailstream_address']); }