register_post_status

Register a post status.

Description

(object) register_post_status( (string) $post_status, (array) $args = array() ); 

Do not use before init.

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.

Returns (object)

Parameters (2)

0. $post_status (string)
Name of the post status.
1. $args — Optional. (array) => array()
Array or string of post status arguments.

Options

  • label (bool|string) => to value of $post_status

    A descriptive name for the post status marked for translation.

  • label_count (bool|array) => array of $label, twice

    Descriptive text to use for nooped plurals.

  • exclude_from_search (bool) => is value of $internal

    Whether to exclude posts with this post status from search results.

  • _builtin (bool) => false

    Whether the status is built-in. Core-use only.

  • public (bool) => false

    Whether posts of this status should be shown in the front end of the site.

  • internal (bool) => false

    Whether the status is for internal use only.

  • protected (bool) => false

    Whether posts with this status should be protected.

  • private (bool) => false

    Whether posts with this status should be private.

  • publicly_queryable (bool) => is value of $public

    Whether posts with this status should be publicly- queryable.

  • show_in_admin_all_list (bool) => is value of $internal

    Whether to include posts in the edit listing for their post type.

array(

    /**
     * A descriptive name for the post status marked for translation.
     *
     * @type bool|string
     * @default to value of $post_status
     */
    'label' => to value of $post_status,

    /**
     * Descriptive text to use for nooped plurals.
     *
     * @type bool|array
     * @default array of $label, twice
     */
    'label_count' => array of $label, twice,

    /**
     * Whether to exclude posts with this post status from search results.
     *
     * @type bool
     * @default is value of $internal
     */
    'exclude_from_search' => is value of $internal,

    /**
     * Whether the status is built-in. Core-use only.
     *
     * @type bool
     * @default false
     */
    '_builtin' => false,

    /**
     * Whether posts of this status should be shown in the front end of the site.
     *
     * @type bool
     * @default false
     */
    'public' => false,

    /**
     * Whether the status is for internal use only.
     *
     * @type bool
     * @default false
     */
    'internal' => false,

    /**
     * Whether posts with this status should be protected.
     *
     * @type bool
     * @default false
     */
    'protected' => false,

    /**
     * Whether posts with this status should be private.
     *
     * @type bool
     * @default false
     */
    'private' => false,

    /**
     * Whether posts with this status should be publicly- queryable.
     *
     * @type bool
     * @default is value of $public
     */
    'publicly_queryable' => is value of $public,

    /**
     * Whether to include posts in the edit listing for their post type.
     *
     * @type bool
     * @default is value of $internal
     */
    'show_in_admin_all_list' => is value of $internal
);        


Usage

  1. if ( !function_exists( 'register_post_status' ) ) { 
  2. require_once ABSPATH . WPINC . '/post.php'; 
  3.  
  4. // Name of the post status. 
  5. $post_status = ''; 
  6.  
  7. // Optional. Array or string of post status arguments. 
  8. $args = array( 
  9. 'label' => to value of $post_status, 
  10. 'label_count' => array of $label, twice, 
  11. 'exclude_from_search' => is value of $internal, 
  12. '_builtin' => false, 
  13. 'public' => false, 
  14. 'internal' => false, 
  15. 'protected' => false, 
  16. 'private' => false, 
  17. 'publicly_queryable' => is value of $public, 
  18. 'show_in_admin_all_list' => is value of $internal 
  19. ); 
  20.  
  21. // NOTICE! Understand what this does before running. 
  22. $result = register_post_status($post_status, $args); 
  23.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/post.php  
  1. function register_post_status( $post_status, $args = array() ) { 
  2. global $wp_post_statuses; 
  3.  
  4. if (!is_array($wp_post_statuses)) 
  5. $wp_post_statuses = array(); 
  6.  
  7. // Args prefixed with an underscore are reserved for internal use. 
  8. $defaults = array( 
  9. 'label' => false,  
  10. 'label_count' => false,  
  11. 'exclude_from_search' => null,  
  12. '_builtin' => false,  
  13. 'public' => null,  
  14. 'internal' => null,  
  15. 'protected' => null,  
  16. 'private' => null,  
  17. 'publicly_queryable' => null,  
  18. 'show_in_admin_status_list' => null,  
  19. 'show_in_admin_all_list' => null,  
  20. ); 
  21. $args = wp_parse_args($args, $defaults); 
  22. $args = (object) $args; 
  23.  
  24. $post_status = sanitize_key($post_status); 
  25. $args->name = $post_status; 
  26.  
  27. // Set various defaults. 
  28. if ( null === $args->public && null === $args->internal && null === $args->protected && null === $args->private ) 
  29. $args->internal = true; 
  30.  
  31. if ( null === $args->public ) 
  32. $args->public = false; 
  33.  
  34. if ( null === $args->private ) 
  35. $args->private = false; 
  36.  
  37. if ( null === $args->protected ) 
  38. $args->protected = false; 
  39.  
  40. if ( null === $args->internal ) 
  41. $args->internal = false; 
  42.  
  43. if ( null === $args->publicly_queryable ) 
  44. $args->publicly_queryable = $args->public; 
  45.  
  46. if ( null === $args->exclude_from_search ) 
  47. $args->exclude_from_search = $args->internal; 
  48.  
  49. if ( null === $args->show_in_admin_all_list ) 
  50. $args->show_in_admin_all_list = !$args->internal; 
  51.  
  52. if ( null === $args->show_in_admin_status_list ) 
  53. $args->show_in_admin_status_list = !$args->internal; 
  54.  
  55. if ( false === $args->label ) 
  56. $args->label = $post_status; 
  57.  
  58. if ( false === $args->label_count ) 
  59. $args->label_count = array( $args->label, $args->label ); 
  60.  
  61. $wp_post_statuses[$post_status] = $args; 
  62.  
  63. return $args;