Changeset 50109

Timestamp:

01/31/2021 12:48:24 PM (4 years ago)

Author:

johnbillion

Message:

Comments: Introduce a method for commenters to opt-in to receiving an email notification when their moderated comment gets approved.

The opt-in form is shown after the comment is submitted and held for moderation.

Sorry this took five years.

Props jeffr0, swissspidy, mrahmadawais, wonderboymusic, jdgrimes, obenland, Monika, imath, garrett-eclipse, johnbillion

Fixes #33717

Location:

trunk

Files:

• src/wp-comments-post.php (modified) (1 diff)
• src/wp-includes/class-walker-comment.php (modified) (7 diffs)
• src/wp-includes/comment.php (modified) (1 diff)
• src/wp-includes/default-filters.php (modified) (1 diff)
• tests/phpunit/tests/comment.php (modified) (1 diff)

trunk/src/wp-comments-post.php

@@ -23 +23 @@
 nocache_headers();
 
-$comment = wp_handle_comment_submission( wp_unslash( $_POST ) );
-if ( is_wp_error( $comment ) ) {
-    $data = (int) $comment->get_error_data();
-    if ( ! empty( $data ) ) {
+if ( isset( $_POST['wp-comment-approved-notification-optin'], $_POST['comment_ID'], $_POST['moderation-hash'] ) ) {
+    $comment = get_comment( $_POST['comment_ID'] );
+
+    if ( $comment && hash_equals( $_POST['moderation-hash'], wp_hash( $comment->comment_date_gmt ) ) ) {
+        update_comment_meta( $comment->comment_ID, '_wp_comment_author_notification_optin', true );
+    } else {
         wp_die(
-            '<p>' . $comment->get_error_message() . '</p>',
-            __( 'Comment Submission Failure' ),
+            '<p>' . __( 'Invalid comment ID.' ) . '</p>',
+            __( 'Comment Notification Opt-in Failure' ),
             array(
-                'response'  => $data,
+                'response'  => 404,
                 'back_link' => true,
             )
         );
-    } else {
-        exit;
     }
+} else {
+    $comment = wp_handle_comment_submission( wp_unslash( $_POST ) );
+    if ( is_wp_error( $comment ) ) {
+        $data = (int) $comment->get_error_data();
+        if ( ! empty( $data ) ) {
+            wp_die(
+                '<p>' . $comment->get_error_message() . '</p>',
+                __( 'Comment Submission Failure' ),
+                array(
+                    'response'  => $data,
+                    'back_link' => true,
+                )
+            );
+        } else {
+            exit;
+        }
+    }
+
+    $user            = wp_get_current_user();
+    $cookies_consent = ( isset( $_POST['wp-comment-cookies-consent'] ) );
+
+    /**
+     * Perform other actions when comment cookies are set.
+     *
+     * @since 3.4.0
+     * @since 4.9.6 The `$cookies_consent` parameter was added.
+     *
+     * @param WP_Comment $comment         Comment object.
+     * @param WP_User    $user            Comment author's user object. The user may not exist.
+     * @param bool       $cookies_consent Comment author's consent to store cookies.
+     */
+    do_action( 'set_comment_cookies', $comment, $user, $cookies_consent );
 }
-
-$user            = wp_get_current_user();
-$cookies_consent = ( isset( $_POST['wp-comment-cookies-consent'] ) );
-
-/**
- * Perform other actions when comment cookies are set.
- *
- * @since 3.4.0
- * @since 4.9.6 The `$cookies_consent` parameter was added.
- *
- * @param WP_Comment $comment         Comment object.
- * @param WP_User    $user            Comment author's user object. The user may not exist.
- * @param bool       $cookies_consent Comment author's consent to store cookies.
- */
-do_action( 'set_comment_cookies', $comment, $user, $cookies_consent );
 
 $location = empty( $_POST['redirect_to'] ) ? get_comment_link( $comment ) : $_POST['redirect_to'] . '#comment-' . $comment->comment_ID;

trunk/src/wp-includes/class-walker-comment.php

@@ -40 +40 @@
         'id'     => 'comment_ID',
     );
+
+    /**
+     * Whether the comment approval notification opt-in form or message needs to be
+     * output automatically.
+     *
+     * @since 5.7.0
+     *
+     * @var bool
+     */
+    protected $needs_comment_approval_notification_output = true;
 
     /**
@@ -256 +266 @@
      * Filters the comment text.
      *
-     * Removes links from the pending comment's text if the commenter did not consent
-     * to the comment cookies.
+     *   - Removes links from the pending comment's text if the commenter did not consent
+     *     to the comment cookies
+     *   - Prepends the approval notification opt-in form or message to pending comments
      *
      * @since 5.4.2
+     * @since 5.7.0 Comment approval notification opt-in form is now automatically
+     *              appended if necessary.
      *
      * @param string          $comment_text Text of the current comment.
@@ -273 +286 @@
         }
 
+        /*
+         * Checks if we need to output the comment approval notification opt-in form.
+         */
+        if ( $this->needs_comment_approval_notification_output ) {
+            $comment_text = $this->comment_approval_notification_form( $comment ) . "\n" . $comment_text;
+        }
+
+        $this->needs_comment_approval_notification_output = true;
+
         return $comment_text;
+    }
+
+    /**
+     * Outputs the awaiting moderation text.
+     *
+     * @since 5.7.0
+     *
+     * @param WP_Comment $comment Comment to display.
+     */
+    protected function awaiting_moderation_text( $comment ) {
+        if ( '0' !== $comment->comment_approved ) {
+            return;
+        }
+
+        $commenter = wp_get_current_commenter();
+
+        if ( $commenter['comment_author_email'] ) {
+            $moderation_note = __( 'Your comment is awaiting moderation.' );
+        } else {
+            $moderation_note = __( 'Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.' );
+        }
+
+        printf(
+            '<em class="comment-awaiting-moderation">%s</em>',
+            esc_html( $moderation_note )
+        );
+    }
+
+    /**
+     * Gets the comment approval notification opt-in form or message for a pending comment.
+     *
+     * @since 5.7.0
+     *
+     * @param WP_Comment $comment Comment to display.
+     * @return string HTML output.
+     */
+    protected function comment_approval_notification_form( $comment ) {
+        $comment_approval_output = '';
+
+        if ( '0' === $comment->comment_approved && has_action( 'comment_unapproved_to_approved', 'wp_new_comment_notify_comment_author' ) ) {
+            if ( get_comment_meta( $comment->comment_ID, '_wp_comment_author_notification_optin', true ) ) {
+                $comment_approval_output = sprintf(
+                    '<p><em class="wp-comment-approved-notification-optedin">%s</em></p>',
+                    esc_html__( 'You will receive an email when your comment is approved.' )
+                );
+            } else {
+                $comment_approval_output = sprintf(
+                    '<form action="%1$s" method="post">
+                        <p>
+                            <input type="checkbox" id="wp-comment-approved-notification-optin" name="wp-comment-approved-notification-optin">
+                            <label for="wp-comment-approved-notification-optin">
+                                %2$s
+                            </label>
+                        </p>
+                        <input type="hidden" name="comment_ID" value="%3$s">
+                        <input type="hidden" name="moderation-hash" value="%4$s">
+                        <input type="submit" class="button" value="%5$s">
+                    </form>',
+                    esc_url( site_url( '/wp-comments-post.php' ) ),
+                    esc_html__( 'I want to be notified by email when my comment is approved.' ),
+                    absint( $comment->comment_ID ),
+                    wp_hash( $comment->comment_date_gmt ),
+                    esc_html_x( 'Save', 'comment approval notification form' )
+                );
+            }
+        }
+
+        // Disable the backcompat output.
+        $this->needs_comment_approval_notification_output = false;
+
+        // Return the approval notification opt-in form.
+        return $comment_approval_output;
     }
 
@@ -298 +392 @@
         $commenter          = wp_get_current_commenter();
         $show_pending_links = isset( $commenter['comment_author'] ) && $commenter['comment_author'];
-
-        if ( $commenter['comment_author_email'] ) {
-            $moderation_note = __( 'Your comment is awaiting moderation.' );
-        } else {
-            $moderation_note = __( 'Your comment is awaiting moderation. This is a preview; your comment will be visible after it has been approved.' );
-        }
         ?>
         <<?php echo $tag; ?> <?php comment_class( $this->has_children ? 'parent' : '', $comment ); ?> id="comment-<?php comment_ID(); ?>">
@@ -329 +417 @@
             ?>
         </div>
-        <?php if ( '0' == $comment->comment_approved ) : ?>
-        <em class="comment-awaiting-moderation"><?php echo $moderation_note; ?></em>
-        <br />
-        <?php endif; ?>
+
+        <?php
+        // Output the comment moderation feedback if needed.
+        $this->awaiting_moderation_text( $comment );
+
+        // Output the comment approval notification opt-in form if needed.
+        echo $this->comment_approval_notification_form( $comment );
+        ?>
 
         <div class="comment-meta commentmetadata">
@@ -402 +494 @@
         $commenter          = wp_get_current_commenter();
         $show_pending_links = ! empty( $commenter['comment_author'] );
-
-        if ( $commenter['comment_author_email'] ) {
-            $moderation_note = __( 'Your comment is awaiting moderation.' );
-        } else {
-            $moderation_note = __( 'Your comment is awaiting moderation. This is a preview; your comment will be visible after it has been approved.' );
-        }
         ?>
         <<?php echo $tag; ?> id="comment-<?php comment_ID(); ?>" <?php comment_class( $this->has_children ? 'parent' : '', $comment ); ?>>
@@ -451 +537 @@
                     </div><!-- .comment-metadata -->
 
-                    <?php if ( '0' == $comment->comment_approved ) : ?>
-                    <em class="comment-awaiting-moderation"><?php echo $moderation_note; ?></em>
-                    <?php endif; ?>
+                    <?php
+                    // Output the comment moderation feedback if needed.
+                    $this->awaiting_moderation_text( $comment );
+
+                    // Output the comment approval notification opt-in form if needed.
+                    echo $this->comment_approval_notification_form( $comment );
+                    ?>
                 </footer><!-- .comment-meta -->
 

trunk/src/wp-includes/comment.php

@@ -2350 +2350 @@
 
 /**
+ * Notifies the comment author when their comment gets approved.
+ *
+ * This notification is only sent once when the comment status
+ * changes from unapproved to approved.
+ *
+ * @since 5.7.0
+ *
+ * @param int|WP_Comment $comment_id Comment ID or WP_Comment object.
+ * @return bool Whether the email was sent.
+ */
+function wp_new_comment_notify_comment_author( $comment_id ) {
+    $comment = get_comment( $comment_id );
+
+    if ( ! $comment ) {
+        return false;
+    }
+
+    $post = get_post( $comment->comment_post_ID );
+
+    if ( ! $post ) {
+        return false;
+    }
+
+    // Make sure the comment author can be notified by email.
+    if ( empty( $comment->comment_author_email ) ) {
+        return false;
+    }
+
+    if ( ! get_comment_meta( $comment->comment_ID, '_wp_comment_author_notification_optin', true ) ) {
+        return false;
+    }
+
+    /**
+     * The blogname option is escaped with esc_html when
+     * saved into the database, we need to reverse this for
+     * the plain text area of the email.
+     */
+    $blogname = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES );
+
+    $subject = sprintf(
+        /* translators: 1: blog name, 2: post title */
+        __( '[%1$s] Your comment on "%2$s" has been approved' ),
+        $blogname,
+        $post->post_title
+    );
+
+    if ( ! empty( $comment->comment_author ) ) {
+        $notify_message = sprintf(
+            /* translators: 1: comment author's name */
+            __( 'Howdy %s,' ),
+            $comment->comment_author
+        ) . "\r\n\r\n";
+    } else {
+        $notify_message = __( 'Howdy,' ) . "\r\n\r\n";
+    }
+
+    $notify_message .= sprintf(
+        /* translators: 1: post title */
+        __( 'Your comment on "%s" has been approved.' ),
+        $post->post_title
+    ) . "\r\n\r\n";
+
+    $notify_message .= sprintf(
+        /* translators: 1: comment permalink */
+        __( 'View comment: %s' ),
+        get_comment_link( $comment )
+    ) . "\r\n";
+
+    $email = array(
+        'to'      => $comment->comment_author_email,
+        'subject' => $subject,
+        'message' => $notify_message,
+        'headers' => '',
+    );
+
+    /**
+     * Filters the contents of the email sent to notify a comment author that their comment was approved.
+     *
+     * Content should be formatted for transmission via wp_mail().
+     *
+     * @since 5.7.0
+     *
+     * @param array      $email   {
+     *     Used to build wp_mail().
+     *
+     *     @type string $to      The email address of the comment author.
+     *     @type string $subject The subject of the email.
+     *     @type string $message The content of the email.
+     *     @type string $headers Headers.
+     * }
+     * @param WP_Comment $comment Comment object.
+     */
+    $email = apply_filters( 'comment_approval_notification', $email, $comment );
+
+    $sent = wp_mail(
+        $email['to'],
+        wp_specialchars_decode( $email['subject'] ),
+        $email['message'],
+        $email['headers']
+    );
+
+    // Delete the opt-in now the notification has been sent.
+    delete_comment_meta( $comment->comment_ID, '_wp_comment_author_notification_optin' );
+
+    return $sent;
+}
+
+/**
  * Sets the status of a comment.
  *

trunk/src/wp-includes/default-filters.php

@@ -469 +469 @@
 add_action( 'register_new_user', 'wp_send_new_user_notifications' );
 add_action( 'edit_user_created_user', 'wp_send_new_user_notifications', 10, 2 );
+add_action( 'comment_unapproved_to_approved', 'wp_new_comment_notify_comment_author' );
 
 // REST API actions.

trunk/tests/phpunit/tests/comment.php

@@ -553 +553 @@
         self::$notify_message = $notify_message;
         return $notify_message;
+    }
+
+    /**
+     * @ticket 33717
+     */
+    public function test_wp_new_comment_notify_comment_author_once_only() {
+        $c = self::factory()->comment->create(
+            array(
+                'comment_post_ID'      => self::$post_id,
+                'comment_approved'     => '0',
+                'comment_author_email' => 'foo@bar.mail',
+            )
+        );
+
+        // The comment author subscribed to receive an email once comment is approved.
+        update_comment_meta( $c, '_wp_comment_author_notification_optin', true );
+
+        // For the purpose of the test we are removing this hook to directly use the function to notify the comment author.
+        remove_action( 'comment_unapproved_to_approved', 'wp_new_comment_notify_comment_author' );
+
+        // Approve the comment.
+        wp_set_comment_status( $c, 'approve' );
+
+        $sent = wp_new_comment_notify_comment_author( $c );
+        $resent = wp_new_comment_notify_comment_author( $c );
+
+        $this->assertTrue( $sent );
+        $this->assertFalse( $resent );
+    }
+
+    /**
+     * @ticket 33717
+     */
+    public function test_wp_new_comment_notify_comment_author_has_not_opted_in() {
+        $c = self::factory()->comment->create(
+            array(
+                'comment_post_ID'      => self::$post_id,
+                'comment_approved'     => '0',
+                'comment_author_email' => 'bat@man.mail',
+            )
+        );
+
+        // For the purpose of the test we are removing this hook to directly use the function to notify the comment author.
+        remove_action( 'comment_unapproved_to_approved', 'wp_new_comment_notify_comment_author' );
+
+        // Approve the comment.
+        wp_set_comment_status( $c, 'approve' );
+
+        $sent = wp_new_comment_notify_comment_author( $c );
+
+        // The comment author hasn't subscribed to receive an email, no email should be sent.
+        $this->assertFalse( $sent );
     }