docs: document required category field for abilities#224
Conversation
`wp_register_ability()` requires a `category` and returns `null` silently when it is missing or unregistered (issue #135). Every doc example omitted the field, so copy-pasting them reproduced the failure. Add the field to all registration examples, add a dedicated "Ability categories (required)" section covering core categories and the `wp_abilities_api_categories_init` hook, and add a troubleshooting entry for the silent `null` return.
|
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 Unlinked AccountsThe following contributors have not linked their GitHub and WordPress.org accounts: @flodufour, @stefanolissa, @gelakhubutia. Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases. If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
There was a problem hiding this comment.
Pull request overview
This PR updates the documentation to reflect that wp_register_ability() requires a registered category, and explains the observed failure mode when category is missing/unregistered (returning null with only a _doing_it_wrong() notice in debug).
Changes:
- Adds an “Ability categories (required)” section explaining core
site/usercategories and how to register custom categories onwp_abilities_api_categories_init. - Updates ability-registration examples across docs to include a
categoryfield (siteoruseras appropriate). - Adds a callout and troubleshooting guidance for the
nullreturn behavior whencategoryis missing/unregistered.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/troubleshooting/common-issues.md | Adds a troubleshooting entry for wp_register_ability() returning null due to missing/unregistered category. |
| docs/guides/default-server.md | Updates the default server example ability registration to include category. |
| docs/guides/creating-abilities.md | Adds a new “Ability categories (required)” section and updates examples to include category. |
| docs/getting-started/README.md | Updates the getting-started example to include category. |
| docs/getting-started/installation.md | Updates the installation tutorial’s registration snippet to include category. |
| docs/getting-started/basic-examples.md | Adds a top-level callout about required categories and updates examples to include category. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## trunk #224 +/- ##
=========================================
Coverage 87.86% 87.86%
Complexity 1245 1245
=========================================
Files 53 53
Lines 4037 4037
=========================================
Hits 3547 3547
Misses 490 490
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Clarify that WP_DEBUG_LOG (not just WP_DEBUG) is needed to capture the _doing_it_wrong() notice in debug.log. Mark the partial edit-post snippet in transport-permissions.md as incomplete and name the required fields, so it isn't copy-pasted into the same null failure.
gziolo
left a comment
gziolo
left a comment
There was a problem hiding this comment.
This is an accurate, well-scoped docs fix.
What?
Closes #135
Documents the required
categoryfield for WordPress abilities across the docs, and clarifies what actually happens when it's missing.Why?
In #135,
wp_register_ability()returnedNULLfor a user and they couldn't tell why. They suspected a load-order conflict with WooCommerce's bundled Abilities API. It wasn't that.The real cause: core requires a
category, and every registration example in our docs omitted it. So copy-pasting our docs reproduced the failure. @justlevine flagged this as a recurring DX/docs stumbling block, which is what this PR addresses.I verified the behavior against WordPress 6.9 core source (
wp-includes/abilities.php,default-filters.php) rather than trusting the issue thread:categoryis required.siteanduser(viawp_register_core_ability_categories(), hooked onwp_abilities_api_categories_init). No plugin code needed to use them.wp_register_ability()returnsnullwith noWP_Error, but does call_doing_it_wrong(). That notice only surfaces withWP_DEBUGon, so on production it looks completely silent. That's why it's so easy to misdiagnose.How?
'category'to every ability-registration example across the docs (site, oruserfor the user-data resource example).creating-abilities.mdcovering the core defaults, registering a custom category withwp_register_ability_category(), and thewp_abilities_api_categories_initvswp_abilities_api_inithook ordering.basic-examples.md.common-issues.mdfor thenullreturn, including the tip to enableWP_DEBUGand check the log forAbility category "..." is not registered.null, noWP_Error,_doing_it_wrong()notice only withWP_DEBUGon (not truly "silent").Use of AI Tools
AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 4.8
Used for: Drafting the doc edits and verifying the core-behavior claims (default categories, null-on-failure path) against WordPress core source. All claims were checked against
wordpress-develop6.9/trunk and reviewed and edited by me.Testing Instructions
Docs-only change, no code paths touched.
basic-examples.mdandcommon-issues.mdresolve to it.Changelog Entry