register_post_status()

You are here:
In this article

register_post_status( string $post_status, array|string $args = array() )

Register a post status. Do not use before init.

Description 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.

Top ↑

Parameters 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()

Top ↑

Return Return

(object)

Top ↑

Source Source

File: wp-includes/post.php

1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
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 code View on Trac

Top ↑

Uses Uses

Uses
Uses Description
wp-includes/l10n.php: _n_noop()

Registers plural strings in POT file, but does not translate them.
wp-includes/formatting.php: sanitize_key()

Sanitizes a string key.
wp-includes/functions.php: wp_parse_args()

Merge user defined arguments into defaults array.

Top ↑

Used By Used By

Used By
Used By Description
wp-includes/post.php: create_initial_post_types()

Creates the initial post types when ‘init’ action is fired.

Top ↑

Changelog Changelog

Changelog
Version Description
3.0.0 Introduced.
Was this article helpful?
Dislike 0
Views: 6