register_post_status() WordPress Function
The register_post_status() function is used to register a new post status for a post type. This function takes two arguments: $post_status - The post status key. $args - An array of arguments. The $args array can contain the following: 'label' - The post status label. 'label_count' - The post status label when there is more than one post. 'public' - Whether the post status should be publicly queryable. 'show_in_admin_status_list' - Whether the post status should be shown in the list of post statuses in the admin area. 'show_in_admin_all_list' - Whether the post status should be shown in the list of all posts in the admin area. 'exclude_from_search' - Whether the post status should be excluded from search results. 'capability_type' - The post type capability type. The following example registers a post status with the key 'publish' and sets the label to 'Published': register_post_status( 'publish', array( 'label' => 'Published', 'public' => true, 'show_in_admin_status_list' => true, 'capability_type' => 'post' ) );
register_post_status( string $post_status, array|string $args = array() ) #
Register a post status. Do not use before init.
Description
A simple function for creating or modifying a post status based on the parameters given. The function will accept an array (second optional parameter), along with a string for the post status name.
Arguments prefixed with an _underscore shouldn’t be used by plugins and themes.
Parameters
- $post_status
(string)(Required)Name of the post status.
- $args
(array|string)(Optional)Array or string of post status arguments.
- 'label'
(bool|string) A descriptive name for the post status marked for translation. Defaults to value of $post_status. - 'label_count'
(bool|array) Descriptive text to use for nooped plurals. Default array of $label, twice. - 'exclude_from_search'
(bool) Whether to exclude posts with this post status from search results. Default is value of $internal. - '_builtin'
(bool) Whether the status is built-in. Core-use only. Default false. - 'public'
(bool) Whether posts of this status should be shown in the front end of the site. Default false. - 'internal'
(bool) Whether the status is for internal use only. Default false. - 'protected'
(bool) Whether posts with this status should be protected. Default false. - 'private'
(bool) Whether posts with this status should be private. Default false. - 'publicly_queryable'
(bool) Whether posts with this status should be publicly- queryable. Default is value of $public. - 'show_in_admin_all_list'
(bool) Whether to include posts in the edit listing for their post type. Default is the opposite value of $internal. - 'show_in_admin_status_list'
(bool) Show in the list of statuses with post counts at the top of the edit listings, e.g. All (12) | Published (9) | My Custom Status (2) Default is the opposite value of $internal. - 'date_floating'
(bool) Whether the post has a floating creation date. Default to false.
Default value: array()
- 'label'
Return
(object)
Source
File: wp-includes/post.php
function register_post_status( $post_status, $args = array() ) { global $wp_post_statuses; if ( ! is_array( $wp_post_statuses ) ) { $wp_post_statuses = array(); } // Args prefixed with an underscore are reserved for internal use. $defaults = array( 'label' => false, 'label_count' => false, 'exclude_from_search' => null, '_builtin' => false, 'public' => null, 'internal' => null, 'protected' => null, 'private' => null, 'publicly_queryable' => null, 'show_in_admin_status_list' => null, 'show_in_admin_all_list' => null, 'date_floating' => null, ); $args = wp_parse_args( $args, $defaults ); $args = (object) $args; $post_status = sanitize_key( $post_status ); $args->name = $post_status; // Set various defaults. if ( null === $args->public && null === $args->internal && null === $args->protected && null === $args->private ) { $args->internal = true; } if ( null === $args->public ) { $args->public = false; } if ( null === $args->private ) { $args->private = false; } if ( null === $args->protected ) { $args->protected = false; } if ( null === $args->internal ) { $args->internal = false; } if ( null === $args->publicly_queryable ) { $args->publicly_queryable = $args->public; } if ( null === $args->exclude_from_search ) { $args->exclude_from_search = $args->internal; } if ( null === $args->show_in_admin_all_list ) { $args->show_in_admin_all_list = ! $args->internal; } if ( null === $args->show_in_admin_status_list ) { $args->show_in_admin_status_list = ! $args->internal; } if ( null === $args->date_floating ) { $args->date_floating = false; } if ( false === $args->label ) { $args->label = $post_status; } if ( false === $args->label_count ) { // phpcs:ignore WordPress.WP.I18n.NonSingularStringLiteralSingle,WordPress.WP.I18n.NonSingularStringLiteralPlural $args->label_count = _n_noop( $args->label, $args->label ); } $wp_post_statuses[ $post_status ] = $args; return $args; }
Expand full source codeCollapse full source codeView on TracView on GitHub
Changelog
Version | Description |
---|---|
3.0.0 | Introduced. |