Add comments to functions in mailstream plugin

This commit is contained in:
Matthew Exon 2021-05-08 19:59:46 +02:00
parent e646aa3695
commit 3d2bdeb5a4

View file

@ -16,6 +16,9 @@ use Friendica\Model\Item;
use Friendica\Model\Post; use Friendica\Model\Post;
use Friendica\Protocol\Activity; use Friendica\Protocol\Activity;
/**
* Sets up the addon hooks and the database table
*/
function mailstream_install() { function mailstream_install() {
Hook::register('addon_settings', 'addon/mailstream/mailstream.php', 'mailstream_addon_settings'); Hook::register('addon_settings', 'addon/mailstream/mailstream.php', 'mailstream_addon_settings');
Hook::register('addon_settings_post', 'addon/mailstream/mailstream.php', 'mailstream_addon_settings_post'); 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_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'); $frommail = DI::config()->get('mailstream', 'frommail');
$template = Renderer::getMarkupTemplate('admin.tpl', 'addon/mailstream/'); $template = Renderer::getMarkupTemplate('admin.tpl', 'addon/mailstream/');
$config = ['frommail', $config = ['frommail',
@ -71,14 +83,27 @@ function mailstream_addon_admin(&$a,&$o) {
'$submit' => DI::l10n()->t('Save Settings')]); '$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) { function mailstream_addon_admin_post ($a) {
if (!empty($_POST['frommail'])) { if (!empty($_POST['frommail'])) {
DI::config()->set('mailstream', 'frommail', $_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) { function mailstream_generate_id($a, $uri) {
// http://www.jwz.org/doc/mid.html
$host = DI::baseUrl()->getHostname(); $host = DI::baseUrl()->getHostname();
$resource = hash('md5', $uri); $resource = hash('md5', $uri);
$message_id = "<" . $resource . "@" . $host . ">"; $message_id = "<" . $resource . "@" . $host . ">";
@ -86,6 +111,14 @@ function mailstream_generate_id($a, $uri) {
return $message_id; 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) { function mailstream_post_hook(&$a, &$item) {
if (!DI::pConfig()->get($item['uid'], 'mailstream', 'enabled')) { if (!DI::pConfig()->get($item['uid'], 'mailstream', 'enabled')) {
Logger::debug('mailstream: not enabled for item ' . $item['id']); 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); 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) { function mailstream_get_user($uid) {
$r = q('SELECT * FROM `user` WHERE `uid` = %d', intval($uid)); $r = q('SELECT * FROM `user` WHERE `uid` = %d', intval($uid));
if (count($r) != 1) { if (count($r) != 1) {
@ -142,6 +182,18 @@ function mailstream_get_user($uid) {
return $r[0]; 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) { function mailstream_do_images($a, &$item, &$attachments) {
if (!DI::pConfig()->get($item['uid'], 'mailstream', 'attachimg')) { if (!DI::pConfig()->get($item['uid'], 'mailstream', 'attachimg')) {
return; return;
@ -172,6 +224,13 @@ function mailstream_do_images($a, &$item, &$attachments) {
return $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) { function mailstream_sender($item) {
$r = q('SELECT * FROM `contact` WHERE `id` = %d', $item['contact-id']); $r = q('SELECT * FROM `contact` WHERE `id` = %d', $item['contact-id']);
if (DBA::isResult($r)) { if (DBA::isResult($r)) {
@ -183,6 +242,13 @@ function mailstream_sender($item) {
return $item['author-name']; 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) { function mailstream_decode_subject($subject) {
$html = BBCode::convert($subject); $html = BBCode::convert($subject);
if (!$html) { if (!$html) {
@ -207,6 +273,13 @@ function mailstream_decode_subject($subject) {
return $trimmed; 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) { function mailstream_subject($item) {
if ($item['title']) { if ($item['title']) {
return mailstream_decode_subject($item['title']); return mailstream_decode_subject($item['title']);
@ -255,6 +328,14 @@ function mailstream_subject($item) {
return DI::l10n()->t("Friendica 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) { function mailstream_send(\Friendica\App $a, $message_id, $item, $user) {
if (!$item['visible']) { if (!$item['visible']) {
return; 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 * Email tends to break if you send excessively long lines. To make
* bbcode's output suitable for transmission, we try to break things * bbcode's output suitable for transmission, we try to break things
* up so that lines are about 200 characters. * up so that lines are about 200 characters.
*
* @param string $text text to word wrap - modified in-place
*/ */
function mailstream_html_wrap(&$text) function mailstream_html_wrap(&$text)
{ {
@ -330,6 +413,12 @@ function mailstream_html_wrap(&$text)
$text = implode($lines); $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) { function mailstream_cron($a, $b) {
// Only process items older than an hour in cron. This is because // Only process items older than an hour in cron. This is because
// we want to give mailstream_post_remote_hook a fair chance to // we want to give mailstream_post_remote_hook a fair chance to
@ -380,6 +469,12 @@ EOT;
mailstream_tidy(); 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) { function mailstream_addon_settings(&$a, &$s) {
$enabled = DI::pConfig()->get(local_user(), 'mailstream', 'enabled'); $enabled = DI::pConfig()->get(local_user(), 'mailstream', 'enabled');
$address = DI::pConfig()->get(local_user(), 'mailstream', 'address'); $address = DI::pConfig()->get(local_user(), 'mailstream', 'address');
@ -410,7 +505,13 @@ function mailstream_addon_settings(&$a, &$s) {
'$submit' => DI::l10n()->t('Save Settings')]); '$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'] != "") { if ($_POST['mailstream_address'] != "") {
DI::pConfig()->set(local_user(), 'mailstream', 'address', $_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() { function mailstream_tidy() {
$r = q("SELECT id FROM mailstream_item WHERE completed IS NOT NULL AND completed < DATE_SUB(NOW(), INTERVAL 1 YEAR)"); $r = q("SELECT id FROM mailstream_item WHERE completed IS NOT NULL AND completed < DATE_SUB(NOW(), INTERVAL 1 YEAR)");
foreach ($r as $rr) { foreach ($r as $rr) {