V2.1.8 (#195)

* Added new hooks
* Updated documentation
* Added additional test coverage

WpMailCatcher.php

@@ -6,7 +6,7 @@
 Domain Path: /languages
 Description: Logging your mail will stop you from ever losing your emails again! This fast, lightweight plugin (under 140kb in size!) is also useful for debugging or backing up your messages.
 Author: James Ward
-Version: 2.1.7
+Version: 2.1.8
 Author URI: https://jamesward.io
 Donate link: https://paypal.me/jamesmward
 */

build/grunt/package.json

@@ -1,6 +1,6 @@
 {
   "name": "WpMailCatcher",
-  "version": "2.1.7",
+  "version": "2.1.8",
   "lang_po_directory": "../../languages",
   "build_directory": "./..",
   "dist_directory": "../../assets",

entrypoint.sh

@@ -4,7 +4,7 @@ export DB_DATABASE=wordpress
 export DB_USERNAME=wp_mail_catcher
 export DB_PASSWORD=password
 export PHP_VERSION=8.0
-export WP_VERSION=6.4.1
+export WP_VERSION=6.5.3
 
 CMD=$1
 

languages/WpMailCatcher.pot

@@ -6,9 +6,9 @@
 #, fuzzy
 msgid ""
 msgstr ""
-"Project-Id-Version: WpMailCatcher 2.1.4\n"
+"Project-Id-Version: WpMailCatcher 2.1.8\n"
 "Report-Msgid-Bugs-To: [email protected]\n"
-"POT-Creation-Date: 2023-11-09 20:31+0000\n"
+"POT-Creation-Date: 2024-05-29 19:52+0000\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <[email protected]>\n"
@@ -131,7 +131,7 @@ msgid ""
 "                             to perform the upgrade.</strong>"
 msgstr ""
 
-#: ../../src/Views/Log.php:47
+#: ../../src/Views/Log.php:50
 #, php-format
 msgid ""
 "You have <strong>over %s</strong> messages stored and <a href=\"%s\">auto-"
@@ -141,27 +141,27 @@ msgid ""
 "                             auto-delete or delete some logs."
 msgstr ""
 
-#: ../../src/Views/Log.php:62
+#: ../../src/Views/Log.php:65
 msgid "New Message"
 msgstr ""
 
-#: ../../src/Views/Log.php:67 ../../src/Views/Log.php:77
+#: ../../src/Views/Log.php:70 ../../src/Views/Log.php:80
 msgid "Export all messages"
 msgstr ""
 
-#: ../../src/Views/Log.php:88
+#: ../../src/Views/Log.php:91
 msgid "All"
 msgstr ""
 
-#: ../../src/Views/Log.php:96
+#: ../../src/Views/Log.php:99
 msgid "Successful"
 msgstr ""
 
-#: ../../src/Views/Log.php:104
+#: ../../src/Views/Log.php:107
 msgid "Failed"
 msgstr ""
 
-#: ../../src/Views/Log.php:118
+#: ../../src/Views/Log.php:121
 msgid "Search Logs"
 msgstr ""
 
@@ -290,20 +290,20 @@ msgstr ""
 msgid "Yes - delete messages that are over %s old"
 msgstr ""
 
-#: ../../src/Views/Settings.php:141
+#: ../../src/Views/Settings.php:144
 #, php-format
 msgid "Will next run in: %s. <a href=\""
 msgstr ""
 
-#: ../../src/Views/Settings.php:155
+#: ../../src/Views/Settings.php:158
 msgid "Database version"
 msgstr ""
 
-#: ../../src/Views/Settings.php:164
+#: ../../src/Views/Settings.php:170
 #, php-format
 msgid "%s. <a href=\""
 msgstr ""
 
-#: ../../src/Views/Settings.php:178
+#: ../../src/Views/Settings.php:184
 msgid "Save Changes"
 msgstr ""

readme.md

@@ -70,6 +70,19 @@ Backup and save your contact form emails (including Contact Form 7) to your data
   * `email_from` the from value of the email
 * `wp_mail_catcher_mail_failed` is triggered when a message failed to send and logged successfully. It has a single argument that is an array containing the log (same as the arguments for `wp_mail_catcher_mail_success`)
 * `wp_mail_catcher_deletion_intervals` is a filter that should return an array where each key is an amount of time in seconds, and the value is the label. Used to determine when a message has expired and should be deleted
+* `wp_mail_catcher_before_success_log_save` is a filter that is called just before a successful log is saved. It has a single argument that is the transformed log that will be saved - use this to alter the log before it's saved. Returning `false` will stop the log from being saved.
+  * `time` a unix timestamp of when the email was sent
+  * `email_to` the email address(es) that the message was sent to
+  * `subject` the subject line of the message
+  * `message` the contents of the message
+  * `backtrace_segment` an array that shows which file and line the mail was initially triggered from
+* `wp_mail_catcher_before_error_log_save`
+  * `time` a unix timestamp of when the email was sent
+  * `email_to` the email address(es) that the message was sent to
+  * `subject` the subject line of the message
+  * `message` the contents of the message
+  * `backtrace_segment` an array that shows which file and line the mail was initially triggered from
+  * `error` the error that occurred
 
 ## Developing locally
 1. Download the repo

readme.txt

@@ -4,7 +4,7 @@ Tags: mail logging, email log, email logger, logging, email logging, mail, crm
 Requires at least: 4.7
 Tested up to: 6.4
 Requires PHP: 7.4
-Stable tag: 2.1.7
+Stable tag: 2.1.8
 License: GNU General Public License v3.0
 License URI: https://raw.githubusercontent.com/JWardee/wp-mail-catcher/master/LICENSE
 Donate link: https://paypal.me/jamesmward
@@ -52,6 +52,19 @@ Immediately find out if your contact form submission was successfully sent.
   * `email_from` the from value of the email
 * `wp_mail_catcher_mail_failed` is triggered when a message failed to send and logged successfully. It has a single argument that is an array containing the log (same as the arguments for `wp_mail_catcher_mail_success`)
 * `wp_mail_catcher_deletion_intervals` is a filter that should return an array where each key is an amount of time in seconds, and the value is the label. Used to determine when a message has expired and should be deleted
+* `wp_mail_catcher_before_success_log_save` is a filter that is called just before a successful log is saved. It has a single argument that is the transformed log that will be saved - use this to alter the log before it's saved. Returning `false` will stop the log from being saved.
+  * `time` a unix timestamp of when the email was sent
+  * `email_to` the email address(es) that the message was sent to
+  * `subject` the subject line of the message
+  * `message` the contents of the message
+  * `backtrace_segment` an array that shows which file and line the mail was initially triggered from
+* `wp_mail_catcher_before_error_log_save`
+  * `time` a unix timestamp of when the email was sent
+  * `email_to` the email address(es) that the message was sent to
+  * `subject` the subject line of the message
+  * `message` the contents of the message
+  * `backtrace_segment` an array that shows which file and line the mail was initially triggered from
+  * `error` the error that occurred
 
 == Frequently Asked Questions ==
 = Is this really free?  =
@@ -94,6 +107,11 @@ Great! Please leave a note in our (GitHub tracker)
 
 == Changelog ==
 
+= 2.1.8 =
+
+- New: Added new hook `wp_mail_catcher_before_success_log_save`
+- New: Added new hook `wp_mail_catcher_before_error_log_save`
+
 = 2.1.7 =
 
 - Security: Added additional nonce checks to setting actions

src/Loggers/LogHelper.php

@@ -15,16 +15,27 @@ trait LogHelper
      * Save the mail to the database, override this method if you wish
      * to save the data elsewhere or change how it is saved
      *
-     * @param  array  $args the details of the mail going to be sent
-     * @param $transformFunc($args) called before inserting the db entry to transform the mail into log format
+     * @param array $args the details of the mail going to be sent
+     * @param $transformFunc ($args) called before inserting the db entry to transform the mail into log format
      *
      * @return array must return an array in the same format
      */
     public function saveMail(array $args, $transformFunc): array
     {
         global $wpdb;
 
-        $wpdb->insert($wpdb->prefix . GeneralHelper::$tableName, $transformFunc($args));
+        $transformedArgs = $transformFunc($args);
+        $userFilteredArgs = apply_filters(
+            GeneralHelper::$actionNameSpace . '_before_success_log_save',
+            // Only allow certain values to be changed via filters/hooks
+            array_intersect_key($transformedArgs, array_fill_keys(Logs::$whitelistedColumns, null))
+        );
+
+        if ($userFilteredArgs === false) {
+            return [];
+        }
+
+        $wpdb->insert($wpdb->prefix . GeneralHelper::$tableName, array_merge($transformedArgs, $userFilteredArgs));
 
         Cache::flush();
 
@@ -53,18 +64,38 @@ public function saveError(string $error)
 
         global $wpdb;
 
+        $log = Logs::getFirst(['post__in' => $this->id]);
+        $log['status'] = 0;
+        $log['error'] = $error;
+        $log['time'] = $log['timestamp'];
+
+        $transformedArgs = apply_filters(
+            GeneralHelper::$actionNameSpace . '_before_error_log_save',
+            // Only allow certain values to be changed via filters/hooks
+            array_intersect_key($log, array_fill_keys(Logs::$whitelistedColumns, null))
+        );
+
+        if ($transformedArgs === false) {
+            // Because of the way wp_mail hook works the log needs to be saved
+            // before appending any error that happened to it. As a result we need
+            // to delete the inital entry from the db rather than just `return`
+            Logs::delete($this->id);
+            return;
+        }
+
+        if (!$transformedArgs) {
+            $transformedArgs = $log;
+        }
+
         $wpdb->update(
             $wpdb->prefix . GeneralHelper::$tableName,
-            [
-                'status' => 0,
-                'error' => $error,
-            ],
+            array_merge($transformedArgs, ['status' => 0]),
             ['id' => $this->id]
         );
 
         Cache::flush();
 
-        do_action(GeneralHelper::$actionNameSpace . '_mail_failed', Logs::getFirst(['post__in' => $this->id]));
+        do_action(GeneralHelper::$actionNameSpace . '_mail_failed', $log);
     }
 
     public function saveIsHtml($contentType)
@@ -94,7 +125,7 @@ public function saveIsHtml($contentType)
      * Convert attachment ids or urls into a format to be usable
      * by the logs
      *
-     * @param  array | string  $attachments either array of attachment ids or their urls
+     * @param array | string $attachments either array of attachment ids or their urls
      *
      * @return array [id, url] of attachments
      */

src/Models/Logs.php

@@ -6,6 +6,11 @@
 
 class Logs
 {
+    // The db columns that can be set when logs are updated via filters/hooks
+    public static $whitelistedColumns = [
+        'email_to', 'subject', 'message', 'error', 'time', 'backtrace_segment'
+    ];
+
     // Need to set null because we're using array_intersect_key
     public static $whitelistedParams = [
         'orderby' => null,

testing/tests/TestEmails.php

@@ -10,12 +10,22 @@ public function setUp(): void
         Logs::truncate();
     }
 
-    public function testMail()
+    private function isTimeBetwen($time, $compareToTime, $threshold)
     {
-        $to = '[email protected]';
+        $upperBound = $compareToTime + $threshold;
+        $lowerBound = $compareToTime - $threshold;
+        return $time < $upperBound && $time > $lowerBound;
+    }
+
+    // TODO: Tidy method up, make more generic rather than just setting current args
+    //  needed by other tests
+    private function sendAndAssertMail($to, $additionalHeaders = [], $isHtml = false)
+    {
+        // FIXME: Need a better way to mock `time()`
+        $time = time();
+        $acceptableTimeThreshold = 5;
         $subject = 'subject';
         $message = 'message';
-        $additionalHeaders = [GeneralHelper::$htmlEmailHeader, 'cc: [email protected]'];
 
         $imgAttachmentId = $this->factory()->attachment->create_upload_object(__DIR__ . '/../assets/img-attachment.png');
         $pdfAttachmentId = $this->factory()->attachment->create_upload_object(__DIR__ . '/../assets/pdf-attachment.pdf');
@@ -31,10 +41,12 @@ public function testMail()
         $this->assertEquals($to, $emailLogs[0]['email_to']);
         $this->assertEquals($subject, $emailLogs[0]['subject']);
         $this->assertEquals($message, $emailLogs[0]['message']);
-        $this->assertTrue($emailLogs[0]['is_html']);
+        $this->assertTrue($this->isTimeBetwen($emailLogs[0]['timestamp'], $time, $acceptableTimeThreshold));
+        $this->assertEquals($isHtml, $emailLogs[0]['is_html']);
 
-        $this->assertEquals($additionalHeaders[0], $emailLogs[0]['additional_headers'][0]);
-        $this->assertEquals($additionalHeaders[1], $emailLogs[0]['additional_headers'][1]);
+        foreach ($additionalHeaders as $index => $additionalHeader) {
+            $this->assertEquals($additionalHeader, $emailLogs[0]['additional_headers'][$index]);
+        }
 
         $this->assertEquals($imgAttachmentId, $emailLogs[0]['attachments'][0]['id']);
         $this->assertEquals(wp_get_attachment_url($imgAttachmentId), $emailLogs[0]['attachments'][0]['url']);
@@ -48,13 +60,13 @@ public function testMail()
 
     public function testCorrectTos()
     {
-        wp_mail('[email protected]', 'subject', 'message');
+        $this->sendAndAssertMail('[email protected]', [GeneralHelper::$htmlEmailHeader, 'cc: [email protected]'], true);
         $this->assertTrue(Logs::getFirst()['status']);
     }
 
     public function testIncorrectTos()
     {
-        wp_mail('testtest.com', 'subject', 'message');
+        $this->sendAndAssertMail('testtest.com');
         $this->assertFalse(Logs::getFirst()['status']);
     }