Comments: Add opt-in callback order for Walker_Comment

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

@@ -180,7 +180,12 @@ public function start_el( &$output, $data_object, $depth = 0, $args = array(), $
 
 		if ( ! empty( $args['callback'] ) ) {
 			ob_start();
-			call_user_func( $args['callback'], $comment, $args, $depth );
+			if ( isset( $args['callback_order'] ) && 'comment_depth_args' === $args['callback_order'] ) {
+				$callback_args = array( $comment, $depth, $args );
+			} else {
+				$callback_args = array( $comment, $args, $depth );
+			}
+			call_user_func_array( $args['callback'], $callback_args );
 			$output .= ob_get_clean();
 			return;
 		}

src/wp-includes/comment-template.php

@@ -2195,6 +2195,7 @@ function _get_comment_reply_id( $post = null ) {
  * Used in the comments.php template to list comments for a particular post.
  *
  * @since 2.7.0
+ * @since 7.1.0 Added the `callback_order` argument.
  *
  * @see WP_Query::$comments
  *
@@ -2213,6 +2214,10 @@ function _get_comment_reply_id( $post = null ) {
  *     @type string   $style             The style of list ordering. Accepts 'ul', 'ol', or 'div'.
  *                                       'div' will result in no additional list markup. Default 'ul'.
  *     @type callable $callback          Callback function to use. Default null.
+ *     @type string   $callback_order    Order to pass arguments to the callback. Accepts
+ *                                       'comment_args_depth' for `($comment, $args, $depth)` or
+ *                                       'comment_depth_args' for `($comment, $depth, $args)`.
+ *                                       Default 'comment_args_depth'.
  *     @type callable $end-callback      Callback function to use at the end. Default null.
  *     @type string   $type              Type of comments to list. Accepts 'all', 'comment',
  *                                       'pingback', 'trackback', 'pings'. Default 'all'.
@@ -2250,6 +2255,7 @@ function wp_list_comments( $args = array(), $comments = null ) {
 		'page'              => '',
 		'per_page'          => '',
 		'avatar_size'       => 32,
+		'callback_order'    => 'comment_args_depth',
 		'reverse_top_level' => null,
 		'reverse_children'  => '',
 		'format'            => current_theme_supports( 'html5', 'comment-list' ) ? 'html5' : 'xhtml',

tests/phpunit/tests/comment/walker.php

@@ -54,6 +54,65 @@ public function test_has_children() {
 			array( $comment_child, $comment_parent )
 		);
 	}
+
+	/**
+	 * @ticket 45498
+	 */
+	public function test_callback_receives_comment_args_and_depth_in_default_order_for_back_compat() {
+		$comment_id = self::factory()->comment->create( array( 'comment_post_ID' => $this->post_id ) );
+		$comment    = get_comment( $comment_id );
+		$actual     = array();
+
+		wp_list_comments(
+			array(
+				'callback'  => function ( $comment, $args, $depth ) use ( &$actual ) {
+					$actual = array(
+						'comment' => $comment,
+						'args'    => $args,
+						'depth'   => $depth,
+					);
+				},
+				'echo'      => false,
+				'max_depth' => 3,
+			),
+			array( $comment )
+		);
+
+		$this->assertSame( $comment, $actual['comment'] );
+		$this->assertSame( 1, $actual['depth'] );
+		$this->assertIsArray( $actual['args'] );
+		$this->assertSame( 3, $actual['args']['max_depth'] );
+	}
+
+	/**
+	 * @ticket 45498
+	 */
+	public function test_callback_can_receive_comment_depth_and_args_in_walker_order() {
+		$comment_id = self::factory()->comment->create( array( 'comment_post_ID' => $this->post_id ) );
+		$comment    = get_comment( $comment_id );
+		$actual     = array();
+
+		wp_list_comments(
+			array(
+				'callback'       => function ( $comment, $depth, $args ) use ( &$actual ) {
+					$actual = array(
+						'comment' => $comment,
+						'depth'   => $depth,
+						'args'    => $args,
+					);
+				},
+				'callback_order' => 'comment_depth_args',
+				'echo'           => false,
+				'max_depth'      => 3,
+			),
+			array( $comment )
+		);
+
+		$this->assertSame( $comment, $actual['comment'] );
+		$this->assertSame( 1, $actual['depth'] );
+		$this->assertIsArray( $actual['args'] );
+		$this->assertSame( 3, $actual['args']['max_depth'] );
+	}
 }
 
 class Comment_Callback_Test_Helper {