Skip to content

Docs: Describe the shape of post type, taxonomy and capability data #13220

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
swissspidy wants to merge 5 commits into from
Closed

Docs: Describe the shape of post type, taxonomy and capability data #13220

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d643ede
Docs: Describe the shape of post type, taxonomy and capability data.
claude Aug 21, 2026
7a0a968
Merge branch 'trunk' into claude/phpstan-wordpress-typing-f9zirv
swissspidy Aug 27, 2026
be7d990
Merge branch 'trunk' into claude/phpstan-wordpress-typing-f9zirv
swissspidy Aug 27, 2026
5349fb2
Apply suggestion from @westonruter
swissspidy Aug 31, 2026
95114ea
Merge branch 'trunk' into claude/phpstan-wordpress-typing-f9zirv
swissspidy Aug 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions src/wp-includes/class-wp-post-type.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -337,6 +337,8 @@ final class WP_Post_Type {
/**
* Post type capabilities.
*
* @see get_post_type_capabilities()
*
* @since 4.6.0
* @var stdClass $cap
*/
Expand Down
4 changes: 2 additions & 2 deletions src/wp-includes/class-wp-role.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@ class WP_Role {
* List of capabilities the role contains.
*
* @since 2.0.0
* @var bool[] Array of key/value pairs where keys represent a capability name and boolean values
* represent whether the role has that capability.
* @var array<string, bool> Array of key/value pairs where keys represent a capability name and
* boolean values represent whether the role has that capability.
*/
public $capabilities;

Expand Down
11 changes: 10 additions & 1 deletion src/wp-includes/class-wp-taxonomy.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,8 +160,17 @@ final class WP_Taxonomy {
/**
* Capabilities for this taxonomy.
*
* @see register_taxonomy()
*
* @since 4.7.0
* @var stdClass
* @var stdClass {
* Object with all the capabilities as member variables.
*
* @type string $manage_terms Capability to manage terms. Default 'manage_categories'.
* @type string $edit_terms Capability to edit terms. Default 'manage_categories'.
* @type string $delete_terms Capability to delete terms. Default 'manage_categories'.
* @type string $assign_terms Capability to assign terms. Default 'edit_posts'.
* }

@westonruter westonruter Aug 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should add the PHPStan type as well, as otherwise this cannot help with static analysis.

*/
public $cap;

Expand Down
8 changes: 4 additions & 4 deletions src/wp-includes/class-wp-user.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,8 +65,8 @@ class WP_User {
* Capabilities that the individual user has been granted outside of those inherited from their role.
*
* @since 2.0.0
* @var bool[] Array of key/value pairs where keys represent a capability name
* and boolean values represent whether the user has that capability.
* @var array<string, bool> Array of key/value pairs where keys represent a capability name
* and boolean values represent whether the user has that capability.
*/
public $caps = array();

Expand All @@ -90,8 +90,8 @@ class WP_User {
* All capabilities the user has, including individual and role based.
*
* @since 2.0.0
* @var bool[] Array of key/value pairs where keys represent a capability name
* and boolean values represent whether the user has that capability.
* @var array<string, bool> Array of key/value pairs where keys represent a capability name
* and boolean values represent whether the user has that capability.
*/
public $allcaps = array();

Expand Down
41 changes: 23 additions & 18 deletions src/wp-includes/option.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2982,15 +2982,17 @@ function register_initial_settings() {
* @param array $args {
* Data used to describe the setting when registered.
*
* @type string $type The type of data associated with this setting.
* Valid values are 'string', 'boolean', 'integer', 'number', 'array', and 'object'.
* @type string $label A label of the data attached to this setting.
* @type string $description A description of the data attached to this setting.
* @type callable $sanitize_callback A callback function that sanitizes the option's value.
* @type bool|array $show_in_rest Whether data associated with this setting should be included in the REST API.
* When registering complex settings, this argument may optionally be an
* array with a 'schema' key.
* @type mixed $default Default value when calling `get_option()`.
* @type string $type The type of data associated with this setting.
* Valid values are 'string', 'boolean', 'integer', 'number', 'array',
* and 'object'.
* @type string $label A label of the data attached to this setting.
* @type string $description A description of the data attached to this setting.
* @type callable|null $sanitize_callback A callback function that sanitizes the option's value.
* Default null.
* @type bool|array $show_in_rest Whether data associated with this setting should be included in the
* REST API. When registering complex settings, this argument may
* optionally be an array with a 'schema' key.
Comment on lines +2992 to +2994

@westonruter westonruter Aug 28, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TODO: In a future PR add the @phpstan-param to be able to document what this array is.

* @type mixed $default Default value when calling `get_option()`.
* }
*/
function register_setting( $option_group, $option_name, $args = array() ) {
Expand Down Expand Up @@ -3201,15 +3203,18 @@ function unregister_setting( $option_group, $option_name, $deprecated = '' ) {
* @type array ...$0 {
* Data used to describe the setting when registered.
*
* @type string $type The type of data associated with this setting.
* Valid values are 'string', 'boolean', 'integer', 'number', 'array', and 'object'.
* @type string $label A label of the data attached to this setting.
* @type string $description A description of the data attached to this setting.
* @type callable $sanitize_callback A callback function that sanitizes the option's value.
* @type bool|array $show_in_rest Whether data associated with this setting should be included in the REST API.
* When registering complex settings, this argument may optionally be an
* array with a 'schema' key.
* @type mixed $default Default value when calling `get_option()`.
* @type string $type The type of data associated with this setting.
* Valid values are 'string', 'boolean', 'integer', 'number', 'array',
* and 'object'.
* @type string $group The settings group name the setting was registered in.
* @type string $label A label of the data attached to this setting.
* @type string $description A description of the data attached to this setting.
* @type callable|null $sanitize_callback A callback function that sanitizes the option's value.
* @type bool|array $show_in_rest Whether data associated with this setting should be included in the
* REST API. When registering complex settings, this argument may
* optionally be an array with a 'schema' key.
Comment on lines +3213 to +3215

@westonruter westonruter Aug 28, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TODO: In the future, document what array is here in a @phpstan-return tag.

* @type mixed $default Default value when calling `get_option()`. Only present when the
* setting was registered with a default.
* }
* }
*/
Expand Down
129 changes: 78 additions & 51 deletions src/wp-includes/post.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2103,56 +2103,6 @@ function _post_type_meta_capabilities( $capabilities = null ) {
/**
* Builds an object with all post type labels out of a post type object.
*
* Accepted keys of the label array in the post type object:
*
* - `name` - General name for the post type, usually plural. The same and overridden
* by `$post_type_object->label`. Default is 'Posts' / 'Pages'.
* - `singular_name` - Name for one object of this post type. Default is 'Post' / 'Page'.
* - `add_new` - Label for adding a new item. Default is 'Add Post' / 'Add Page'.
* - `add_new_item` - Label for adding a new singular item. Default is 'Add Post' / 'Add Page'.
* - `edit_item` - Label for editing a singular item. Default is 'Edit Post' / 'Edit Page'.
* - `new_item` - Label for the new item page title. Default is 'New Post' / 'New Page'.
* - `view_item` - Label for viewing a singular item. Default is 'View Post' / 'View Page'.
* - `view_items` - Label for viewing post type archives. Default is 'View Posts' / 'View Pages'.
* - `search_items` - Label for searching plural items. Default is 'Search Posts' / 'Search Pages'.
* - `not_found` - Label used when no items are found. Default is 'No posts found' / 'No pages found'.
* - `not_found_in_trash` - Label used when no items are in the Trash. Default is 'No posts found in Trash' /
* 'No pages found in Trash'.
* - `parent_item_colon` - Label used to prefix parents of hierarchical items. Not used on non-hierarchical
* post types. Default is 'Parent Page:'.
* - `all_items` - Label to signify all items in a submenu link. Default is 'All Posts' / 'All Pages'.
* - `archives` - Label for archives in nav menus. Default is 'Post Archives' / 'Page Archives'.
* - `attributes` - Label for the attributes meta box. Default is 'Post Attributes' / 'Page Attributes'.
* - `insert_into_item` - Label for the media frame button. Default is 'Insert into post' / 'Insert into page'.
* - `uploaded_to_this_item` - Label for the media frame filter. Default is 'Uploaded to this post' /
* 'Uploaded to this page'.
* - `featured_image` - Label for the featured image meta box title. Default is 'Featured image'.
* - `set_featured_image` - Label for setting the featured image. Default is 'Set featured image'.
* - `remove_featured_image` - Label for removing the featured image. Default is 'Remove featured image'.
* - `use_featured_image` - Label in the media frame for using a featured image. Default is 'Use as featured image'.
* - `menu_name` - Label for the menu name. Default is the same as `name`.
* - `filter_items_list` - Label for the table views hidden heading. Default is 'Filter posts list' /
* 'Filter pages list'.
* - `filter_by_date` - Label for the date filter in list tables. Default is 'Filter by date'.
* - `items_list_navigation` - Label for the table pagination hidden heading. Default is 'Posts list navigation' /
* 'Pages list navigation'.
* - `items_list` - Label for the table hidden heading. Default is 'Posts list' / 'Pages list'.
* - `item_published` - Label used when an item is published. Default is 'Post published.' / 'Page published.'
* - `item_published_privately` - Label used when an item is published with private visibility.
* Default is 'Post published privately.' / 'Page published privately.'
* - `item_reverted_to_draft` - Label used when an item is switched to a draft.
* Default is 'Post reverted to draft.' / 'Page reverted to draft.'
* - `item_trashed` - Label used when an item is moved to Trash. Default is 'Post trashed.' / 'Page trashed.'
* - `item_scheduled` - Label used when an item is scheduled for publishing. Default is 'Post scheduled.' /
* 'Page scheduled.'
* - `item_updated` - Label used when an item is updated. Default is 'Post updated.' / 'Page updated.'
* - `item_link` - Title for a navigation link block variation. Default is 'Post Link' / 'Page Link'.
* - `item_link_description` - Description for a navigation link block variation. Default is 'A link to a post.' /
* 'A link to a page.'
*
* Above, the first default value is for non-hierarchical post types (like posts)
* and the second one is for hierarchical post types (like pages).
*
* Note: To set labels used in post type admin notices, see the {@see 'post_updated_messages'} filter.
*
* @since 3.0.0
Expand All @@ -2176,7 +2126,84 @@ function _post_type_meta_capabilities( $capabilities = null ) {
* @access private
*
* @param object|WP_Post_Type $post_type_object Post type object.
* @return object Object with all the labels as member variables.
* @return stdClass {
* Post type labels object. The first default value is for non-hierarchical post types
* (like posts) and the second one is for hierarchical post types (like pages).
*
* @type string $name General name for the post type, usually plural. The same and
* overridden by `$post_type_object->label`.
* Default is 'Posts' / 'Pages'.
* @type string $singular_name Name for one object of this post type. Default is 'Post' / 'Page'.
* @type string $add_new Label for adding a new item. Default is 'Add Post' / 'Add Page'.
* @type string $add_new_item Label for adding a new singular item.
* Default is 'Add Post' / 'Add Page'.
* @type string $edit_item Label for editing a singular item.
* Default is 'Edit Post' / 'Edit Page'.
* @type string $new_item Label for the new item page title.
* Default is 'New Post' / 'New Page'.
* @type string $view_item Label for viewing a singular item.
* Default is 'View Post' / 'View Page'.
* @type string $view_items Label for viewing post type archives.
* Default is 'View Posts' / 'View Pages'.
* @type string $search_items Label for searching plural items.
* Default is 'Search Posts' / 'Search Pages'.
* @type string $not_found Label used when no items are found.
* Default is 'No posts found' / 'No pages found'.
* @type string $not_found_in_trash Label used when no items are in the Trash.
* Default is 'No posts found in Trash' / 'No pages found in Trash'.
* @type string|null $parent_item_colon Label used to prefix parents of hierarchical items. Not used on
* non-hierarchical post types.
* Default is 'Parent Page:'.
* @type string $all_items Label to signify all items in a submenu link.
* Default is 'All Posts' / 'All Pages'.
* @type string $archives Label for archives in nav menus.
* Default is 'Post Archives' / 'Page Archives'.
* @type string $attributes Label for the attributes meta box.
* Default is 'Post Attributes' / 'Page Attributes'.
* @type string $insert_into_item Label for the media frame button.
* Default is 'Insert into post' / 'Insert into page'.
* @type string $uploaded_to_this_item Label for the media frame filter.
* Default is 'Uploaded to this post' / 'Uploaded to this page'.
* @type string $featured_image Label for the featured image meta box title.
* Default is 'Featured image'.
* @type string $set_featured_image Label for setting the featured image.
* Default is 'Set featured image'.
* @type string $remove_featured_image Label for removing the featured image.
* Default is 'Remove featured image'.
* @type string $use_featured_image Label in the media frame for using a featured image.
* Default is 'Use as featured image'.
* @type string $menu_name Label for the menu name. Default is the same as `name`.
* @type string $name_admin_bar Label for the object name in the admin bar.
* Default is the value of `singular_name` in the given labels, or the
* post type key.
* @type string $filter_items_list Label for the table views hidden heading.
* Default is 'Filter posts list' / 'Filter pages list'.
* @type string $filter_by_date Label for the date filter in list tables.
* Default is 'Filter by date'.
* @type string $items_list_navigation Label for the table pagination hidden heading.
* Default is 'Posts list navigation' / 'Pages list navigation'.
* @type string $items_list Label for the table hidden heading.
* Default is 'Posts list' / 'Pages list'.
* @type string $item_published Label used when an item is published.
* Default is 'Post published.' / 'Page published.'
* @type string $item_published_privately Label used when an item is published with private visibility.
* Default is 'Post published privately.' / 'Page published privately.'
* @type string $item_reverted_to_draft Label used when an item is switched to a draft.
* Default is 'Post reverted to draft.' / 'Page reverted to draft.'
* @type string $item_trashed Label used when an item is moved to Trash.
* Default is 'Post trashed.' / 'Page trashed.'
* @type string $item_scheduled Label used when an item is scheduled for publishing.
* Default is 'Post scheduled.' / 'Page scheduled.'
* @type string $item_updated Label used when an item is updated.
* Default is 'Post updated.' / 'Page updated.'
* @type string $item_link Title for a navigation link block variation.
* Default is 'Post Link' / 'Page Link'.
* @type string $item_link_description Description for a navigation link block variation.
* Default is 'A link to a post.' / 'A link to a page.'
* @type string $template_name Label for the single item template. Only set when the post type is
* given a `singular_name` label.
* Default is 'Single item: ' followed by the singular name.
* }
*/
function get_post_type_labels( $post_type_object ) {
$nohier_vs_hier_defaults = WP_Post_Type::get_default_labels();
Expand Down
Loading
Loading