Comments: Introduce a register_comment_type() API#12311
Comments: Introduce a register_comment_type() API#12311adamsilverstein wants to merge 9 commits into
Conversation
Add a comment type registration API modeled on the post type and taxonomy APIs, a first step toward custom comment types. Introduce the WP_Comment_Type class and register_comment_type(), unregister_comment_type(), get_comment_type_object(), get_comment_types(), and comment_type_exists(). Register the built-in comment, pingback, trackback, and note types via create_initial_comment_types(), hooked on init at priority 0 and on change_locale so labels re-translate. The note type is marked internal. Make the comment_type() template tag fall back to a registered type's singular label for non-built-in types when no custom text is supplied. Built-in output and explicit overrides are unchanged. Registration provides labels and metadata only; it does not constrain the values stored in the comment_type column or alter WP_Comment_Query behavior. See #35214.
Cover register_comment_type(), unregister_comment_type(), get_comment_type_object(), get_comment_types(), comment_type_exists(), the WP_Comment_Type class, and the registered/unregistered actions and label filters. Verify the built-in types are registered and cannot be unregistered, and that the comment_type() template tag renders registered type labels while preserving built-in output. See #35214.
|
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 Core Committers: Use this line as a base for the props when committing in SVN: To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
|
Hi there! 👋 Thank you for your contribution to WordPress! 💖 It looks like this is your first pull request to No one monitors this repository for new pull requests. Pull requests must be attached to a Trac ticket to be considered for inclusion in WordPress Core. To attach a pull request to a Trac ticket, please include the ticket's full URL in your pull request description. Pull requests are never merged on GitHub. The WordPress codebase continues to be managed through the SVN repository that this GitHub repository mirrors. Please feel free to open pull requests to work on any contribution you are making. More information about how GitHub pull requests can be used to contribute to WordPress can be found in the Core Handbook. Please include automated tests. Including tests in your pull request is one way to help your patch be considered faster. To learn about WordPress' test suites, visit the Automated Testing page in the handbook. If you have not had a chance, please review the Contribute with Code page in the WordPress Core Handbook. The Developer Hub also documents the various coding standards that are followed:
Thank you, |
Test using WordPress PlaygroundThe changes in this pull request can previewed and tested using a WordPress Playground instance. WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser. Some things to be aware of
For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation. |
…abel. Omit 'label' from the WP_Comment_Type::set_props() defaults so the property stays null when not provided. A false default was treated as a supplied value by _get_custom_object_labels(), which overwrote the default name with false, leaving labels->name and label as false for any type registered without an explicit label. This mirrors WP_Post_Type and WP_Taxonomy, which omit 'label' from their defaults for the same reason. Add a regression test covering default labels for a label-less comment type. See #35214.
The default branch of comment_type() echoed a registered type's
singular_name label without escaping. Labels are developer-supplied
(via register_comment_type() or the comment_type_labels_{$type}
filter) and reach the public comment list unescaped, so wrap the
output in esc_html() to match the post type and taxonomy label
contract. Document that labels are stored unescaped and add a
regression test asserting an HTML payload in the label is escaped.
Expose registered comment types through a read-only `/wp/v2/comment-types` controller, mirroring the post types controller (`/wp/v2/types`). This lets REST clients discover the registered types and their labels, which the block editor's inline-commenting work needs in order to add and query comments by type. Add a `show_in_rest` argument to `WP_Comment_Type` (defaulting to the value of `public`, as `show_ui` does) to gate which types the endpoint exposes. The built-in `comment`, `pingback`, and `trackback` types are public and therefore visible; the internal `note` type is not. Builds on the registration API in WordPress#12311. See #35214.
Add reset_comment_types() to WP_UnitTestCase_Base, mirroring reset_post_types()/reset_taxonomies(), plus an _unregister_comment_type() helper. This removes the need for hand-rolled tear_down() cleanup loops in individual test classes, which never ran when an assertion failed first, and heals any test that mutates the built-in types.
…stration. Nothing in the comment type API consumes 'show_ui' yet; the admin list table work that would read it is still design-gated. Removing an argument after release is impossible while adding one later is trivial, so defer it to the PR that introduces the admin UI.
register_comment_type() previously overwrote an existing registration silently, matching register_post_type(). For built-in comment types that would let a plugin strip flags core relies on (for example rendering and query behavior), so reject those with _doing_it_wrong() and a WP_Error instead. Core's own repeated registrations on 'init' and 'change_locale' pass '_builtin' and remain allowed, and unregister_comment_type() already guards built-ins the same way. Custom (non-built-in) types keep silent-overwrite semantics, now pinned by a test alongside register -> unregister -> register.
- Replace the inaccurate 'upgrade routine' rationale on
register_comment_type() with the real reason registrations should not
be hooked before 'init' (translations must be loaded).
- Rewrite the 'public' and 'internal' docs to describe what core
actually does with them today instead of promising behavior that is
not implemented; note why 'public' defaults to true.
- Move the misplaced escaping paragraph in the
comment_type_labels_{$comment_type} filter docblock above the tags so
the code reference parser keeps it.
- Add the missing @SInCE 7.1.0 changelog entry to comment_type() for
the new singular-label fallback.
- Type get_comment_types() $args as array: a string would fatal in
wp_filter_object_list() on PHP 8.
- Note the deliberate i18n string reuse in create_initial_comment_types()
and include comment types in the _get_custom_object_labels() summary.
- Fix label docblock nits and @param alignment.
_get_custom_object_labels() unconditionally derives 'name_admin_bar' and spawns 'all_items'/'archives' when a 'menu_name' is provided, all of which are meaningless for comment types. Strip them from the labels object unless explicitly provided at registration. Also expand test coverage for the registration API: name sanitization and the 20-character boundary, get_comment_types() operators and output keying, the label fallback chain, filter backfill of required labels, action arguments, non-scalar lookups, idempotent built-in registration, template output for legacy empty and built-in 'note' types, and make the reset_default_labels() test able to fail by poisoning the static cache. Add per-method @Covers tags.
1 participant
Description
Trac #35214 is the long-running tracking ticket for custom comment types. Its repeated consensus (dshanske, jeremyfelt) has been "backend first, smaller steps." The data-storage groundwork already shipped in 5.5 via #49236 (comments now store
comment_type = 'comment'instead of''). This PR adds the next logical slice: a comment type registration API modeled on the post type and taxonomy APIs.What this adds
WP_Comment_Typeclass (src/wp-includes/class-wp-comment-type.php), a trimmed mirror ofWP_Taxonomy.register_comment_type(),unregister_comment_type(),get_comment_type_object(),get_comment_types(), andcomment_type_exists().create_initial_comment_types()registering the built-incomment,pingback,trackback, andnotetypes, hooked oninit(priority 0) andchange_locale. Thenotetype (added in 6.9 for editor Notes) is markedinternal.get_comment_type_labels(), reusing the shared_get_custom_object_labels()helper. Post-type-only labels the helper derives (name_admin_bar,all_items,archives) are stripped unless explicitly provided.comment_type()template tag now falls back to a registered, non-built-in type's singular label when the caller supplies no custom text. Built-in output and explicit overrides are byte-for-byte unchanged.register_comment_type( 'pingback', ... )from a plugin returns aWP_Errorwith_doing_it_wrong(), stricter thanregister_post_type(). A new API has no legacy re-registration usage to preserve, and silently overwriting a built-in could strip flags core relies on (this matters more once per-type rendering/query flags land in follow-ups). Core's own repeated registrations oninit/change_localepass_builtinand remain allowed; custom types keep silent-overwrite semantics (pinned by a test).Filters mirror the post type/taxonomy conventions:
register_comment_type_args,register_{$type}_comment_type_args,comment_type_labels_{$type}, and theregistered_comment_type/registered_comment_type_{$type}/unregistered_comment_typeactions.Scope / non-goals
This is deliberately a small, non-breaking step. Registration provides labels and metadata only; it does not constrain values stored in the
comment_typecolumn and makes no change toWP_Comment_Query.The
internalflag is advisory metadata in this PR. Generalizing the hard-codednoteexclusion inWP_Comment_Queryis handled separately by #12310 (default_excluded_comment_typesfilter); these two PRs are complementary and do not overlap. Admin list-table/dropdown integration and capabilities are left to follow-ups (the admin UI is design-feedback gated per discussion on #35214). Ashow_uiargument was originally included here and has been removed: nothing consumes it yet, and it can be reintroduced trivially with the admin UI follow-up, while removing an argument after release would be impossible.Testing
Test framework:
WP_UnitTestCase_Basenow resets comment types between tests (reset_comment_types(), alongside the existing post type/taxonomy resets), with an_unregister_comment_type()helper intests/phpunit/includes/utils.php.New tests under
tests/phpunit/tests/comment/:types.php— registration (including name sanitization, length boundaries, and the built-in re-registration guard), unregistration (including blocking built-ins), re-registration semantics,get_comment_types()filtering/operators, actions and their arguments, label fallbacks, and label filters.wpCommentType.php—WP_Comment_Typedefaults, arg filters, and default-label caching (the reset test poisons the static cache via reflection so it can actually fail).commentType.php—comment_type()output for built-in types (unchanged), the legacy''type,note(label fallback must not apply to built-ins), explicit overrides, escaping, and registered custom type labels.All 601
--group commenttests pass;post/types.phpstill passes (shared label helper unaffected); PHPCS is clean on changed files.See #35214