Comments: Allow comment types to register a display callback

[adamsilverstein]

Description

Adds a render_callback argument to register_comment_type() so a custom comment type can control how its comments are displayed in comment lists, addressing dshanske's request on the tracking ticket (#35214 comment:18) for "a way to register a callback to handle display that can still be overridden by the usual methods."

What it adds

• A render_callback registration argument, stored on WP_Comment_Type (default null).
• Walker_Comment::start_el() dispatches to a comment type's render_callback when one is set, passing the same arguments as the wp_list_comments() callback: the comment, the arguments array, and the depth.

register_comment_type( 'review', array(
    'render_callback' => function ( $comment, $args, $depth ) {
        // Custom markup for a "review" comment.
    },
) );

Precedence / non-breaking

• An explicit callback passed to wp_list_comments() still takes precedence (handled before the type callback).
• Built-in types (comment, pingback, trackback) set no callback, so their output is unchanged.

Scope / boundary

Stacked on WordPress#12311 (the register_comment_type() API) and targets that branch; it will be retargeted to trunk once WordPress#12311 lands. This is item 3 of the remaining below-the-hood work on #35214.

Item 4 (generalizing the remaining hard-coded pingback/trackback checks in Walker_Comment and separate_comments()) is intentionally not included: those checks encode a ping-vs-comment distinction the registry does not yet model, so generalizing them safely needs a dedicated "ping grouping" concept on the registration object and carries output-regression risk. It is better handled as its own focused PR.

Testing

$ phpunit --group comment
OK (699 tests, 1696 assertions)

New coverage in tests/phpunit/tests/comment/walker.php and wpCommentType.php. PHPCS reports no new warnings on the changed files and PHPStan is clean.

Review updates

• The docblocks now state the full precedence chain: an explicit wp_list_comments() 'callback' wins, then the type's render_callback, then the default markup.
• They also document the open-tag contract - a callback outputs only the opening of the element, and Walker_Comment::end_el() closes it after any children are rendered, the same contract as wp_list_comments() callbacks - and the classic-theme-only scope: block themes render comments through the core/comment-template block and never invoke Walker_Comment.
• Test fix: the original test callbacks echoed closed <li> elements, which produced stray closing tags the substring assertions missed. The tests now emit unclosed <li> elements and assert the full element shape including end_el()'s close, plus a threaded-child test pinning the contract end to end.

Following a second review pass over the stack, three more parts of the contract that were left to inference:

• The callback has to branch on $args['style']. end_el() emits </div> under style => 'div' and </li> otherwise. "An unclosed <li> by default" was accurate but read as the whole story, and a callback that always opens an <li> produces mismatched markup. Documented, and pinned with a test under the div style - the suite previously only covered the default.
• The callback must echo. The name deliberately echoes register_block_type(), whose render_callback returns a string. This one is captured with an output buffer, so a returned string is silently discarded. Now says so, with the contrast called out.
• Built-ins can acquire a callback through the args filter, and that is intended. set_props() applies register_comment_type_args to _builtin registrations too, so a plugin can set a callback on comment, pingback, or trackback even though re-registration is blocked. Worth keeping - it grants no more than the wp_list_comments() callback argument always has - so it is now documented as the sanctioned override path and covered by a test, rather than left as an accident of where the filter sits. One consequence is called out in the docs: a callback on the comment type also replaces the walker's link stripping for pending comments.

See #35214.

AI Use

Code and description both written with 🤖 Claude Code. I will review and test.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 97398cf7-8409-48dc-86c8-2a9f1c62cf67

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/comment-type-render-callback

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props adamsilverstein.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.