Implement new Comment Date Functions

[dshanske]

WordPress 5.3 introduces get_post_datetime() and get_post_timestamp(). Suggesting that these be mirrored with the equivalent functions get_comment_datetime and get_comment_timestamp.

[Rarst]

Makes sense, just didn't get to it yet. :)

[dshanske]

The attachment introduces the get_comment_timestamp and get_comment_datetime functions that are basically copies of the post versions of same. It does change the signature of get_comment_time to allow passing through a comment, which mirrors get_post_time. The fact that get_comment_time only allowed for the current comment, yet get_comment_date allowed for the passing of any comment seemed an odd inconsistency.

[Rarst]

From quick look seems fine, given that it is mostly a copy of post version of functions and I really hope we ironed all of quirks out there. :)

Need thorough unit tests, since old stuff is really really quirky about timestamps and stuff. I can work on that, once I survive 5.3 release.

PS not sure about adding to API here, feels tad out of scope of the ticket. I need to go over existing functions tree for comments, I hadn't done that as thoroughly as for posts yet.

[dshanske]

@Rarst I tried to make it as close a copy as possible, figuring that once we ironed out if this is the approach, we could duplicate the same unit tests you did for the post versions of these functions.

As for adding to the API, I can understand the process issue of having it as a separate ticket, however, without it, you would have more duplicative code. And as mentioned, it brings get_comment_time in line with get_post_time in terms of behavior. It seems unnecessary to introduce a new function for this.

Introduced comprehensive PHPUnit tests for the functions get_comment_datetime and get_comment_timestamp to ensure they handle various edge cases correctly, such as handling invalid or zero dates, respecting timezones, and managing future or very old dates. Also updated the implementation to integrate these functions within the existing comment time retrieval mechanism, enhancing accuracy and consistency of datetime operations in comments.

Trac ticket:

[pbearne]

refreshed and added tests

I added a commit to this PR to fix some WPCS and docblocks formatting issues.

[audrasjb]

As per today's bug scrub and as stated by @jeffpaul, let's convert this ticket to an enhancement and therefore move it to 6.9.

[mukesh27]

@pbearne The PR needs to refresh against the latest trunk and fix the failed unit tests.

[pbearne]

refreshed

[wildworks]

This ticket was featured on today's 6.9 Bug SCrub. It looks like the patch has been updated and needs to be retested.

[welcher]

6.9 Beta 1 is tomorrow and this doesn't look to be ready so I'm going to move it to the 7.0 milestone.

[ozgursar]

Test Report

Description

This report validates whether the indicated patch works as expected.

Patch tested: ​https://github.com/WordPress/wordpress-develop/pull/7943

Environment

• WordPress: 7.0-alpha-61215-src
• PHP: 8.2.29
• Server: nginx/1.29.4
• Database: mysqli (Server: 8.4.7 / Client: mysqlnd 8.2.29)
• Browser: Chrome 144.0.0.0
• OS: macOS
• Theme: Twenty Twenty-One 2.7
• MU Plugins: None activated
• Plugins:
  • Code Snippets 3.9.4
  • Test Reports 1.2.1

Steps to Reproduce

1. Add the following snippet via Code Snippets plugin or directly into your theme's functions.php to see the the output of the functions get_post_datetime() and get_post_timestamp() provided with the patch.

/**
 * Plugin Name: Test Comment DateTime Functions
 * Description: Tests the new get_comment_datetime and get_comment_timestamp functions
 * Version: 1.0
 */

add_action('admin_notices', 'display_comment_datetime_tests');

function display_comment_datetime_tests() {
    // Get a test comment
    $comments = get_comments(array('number' => 1, 'status' => 'approve'));
    
    if (empty($comments)) {
        echo '<div class="notice notice-warning"><p>No comments found. Please create a test comment first.</p></div>';
        return;
    }
    
    $comment = $comments[0];
    $comment_id = $comment->comment_ID;
    
    echo '<div class="notice notice-info" style="padding: 20px;">';
    echo '<h2>Comment DateTime Function Tests</h2>';
    echo '<p><strong>Testing Comment ID:</strong> ' . $comment_id . '</p>';
    echo '<p><strong>Comment Text:</strong> ' . esc_html(substr($comment->comment_content, 0, 100)) . '...</p>';
    
    echo '<hr>';
    
    // Test 1: Compare with existing functions
    echo '<h3>1. Comparison with Existing Functions</h3>';
    echo '<table class="widefat" style="width: auto; min-width: 600px;">';
    echo '<tr><th>Method</th><th>Result</th></tr>';
    
    echo '<tr><td><code>get_comment_date()</code></td><td>' . get_comment_date('', $comment) . '</td></tr>';
    echo '<tr><td><code>get_comment_time()</code></td><td>' . get_comment_time('', $comment) . '</td></tr>';
    
    // Test the new functions if they exist
    if (function_exists('get_comment_datetime')) {
        $datetime = get_comment_datetime($comment);
        echo '<tr><td><code>get_comment_datetime()</code></td><td>';
        if ($datetime) {
            echo $datetime->format('Y-m-d H:i:s') . ' (DateTime object)';
        } else {
            echo 'false';
        }
        echo '</td></tr>';
    } else {
        echo '<tr><td><code>get_comment_datetime()</code></td><td style="color: red;">Function not available</td></tr>';
    }
    
    if (function_exists('get_comment_timestamp')) {
        $timestamp = get_comment_timestamp($comment);
        echo '<tr><td><code>get_comment_timestamp()</code></td><td>' . $timestamp . ' (' . date('Y-m-d H:i:s', $timestamp) . ')</td></tr>';
    } else {
        echo '<tr><td><code>get_comment_timestamp()</code></td><td style="color: red;">Function not available</td></tr>';
    }
    
    echo '</table>';
    
    // Test 2: Timezone handling
    echo '<hr><h3>2. Timezone Handling</h3>';
    if (function_exists('get_comment_datetime')) {
        echo '<table class="widefat" style="width: auto; min-width: 600px;">';
        echo '<tr><th>Timezone</th><th>DateTime Result</th></tr>';
        
        $datetime_utc = get_comment_datetime($comment, 'gmt');
        echo '<tr><td>UTC (GMT)</td><td>' . ($datetime_utc ? $datetime_utc->format('Y-m-d H:i:s T') : 'false') . '</td></tr>';
        
        $datetime_local = get_comment_datetime($comment, 'local');
        echo '<tr><td>Local (Blog timezone)</td><td>' . ($datetime_local ? $datetime_local->format('Y-m-d H:i:s T') : 'false') . '</td></tr>';
        
        echo '</table>';
    }
    
    // Test 3: Edge cases
    echo '<hr><h3>3. Edge Cases</h3>';
    echo '<table class="widefat" style="width: auto; min-width: 600px;">';
    echo '<tr><th>Test Case</th><th>Result</th></tr>';
    
    if (function_exists('get_comment_datetime')) {
        // Test with null comment
        $null_result = get_comment_datetime(null);
        echo '<tr><td>Null comment</td><td>' . ($null_result === false ? 'false (correct)' : 'unexpected result') . '</td></tr>';
        
        // Test with invalid comment ID
        $invalid_result = get_comment_datetime(999999);
        echo '<tr><td>Invalid comment ID</td><td>' . ($invalid_result === false ? 'false (correct)' : 'unexpected result') . '</td></tr>';
    }
    
    if (function_exists('get_comment_timestamp')) {
        // Test with null comment
        $null_ts = get_comment_timestamp(null);
        echo '<tr><td>Null comment (timestamp)</td><td>' . ($null_ts === false ? 'false (correct)' : 'unexpected result') . '</td></tr>';
    }
    
    echo '</table>';
    
    // Test 4: Parallel with post functions
    echo '<hr><h3>4. Parallel with Post DateTime Functions</h3>';
    $post_id = $comment->comment_post_ID;
    echo '<p><strong>Comparing comment and post datetime functions for consistency</strong></p>';
    echo '<table class="widefat" style="width: auto; min-width: 600px;">';
    echo '<tr><th>Function Type</th><th>Comment Function</th><th>Post Function</th></tr>';
    
    if (function_exists('get_comment_datetime') && function_exists('get_post_datetime')) {
        $comment_dt = get_comment_datetime($comment);
        $post_dt = get_post_datetime($post_id);
        echo '<tr><td>DateTime object</td><td>' . get_class($comment_dt) . '</td><td>' . get_class($post_dt) . '</td></tr>';
    }
    
    if (function_exists('get_comment_timestamp') && function_exists('get_post_timestamp')) {
        $comment_ts = get_comment_timestamp($comment);
        $post_ts = get_post_timestamp($post_id);
        echo '<tr><td>Timestamp type</td><td>' . gettype($comment_ts) . '</td><td>' . gettype($post_ts) . '</td></tr>';
    }
    
    echo '</table>';
    
    echo '</div>';
}

2. View WordPress dashboard to see the output as seen in the screenshots

Actual Results

1. ✅ Issue resolved with patch.

Supplemental Artifacts

Before:

After: