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

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$post_statusstring

Name of the post status.

$argsarray|stringoptional

Array or string of post status arguments.Default: array()

• $labelbool|string

  A descriptive name for the post status marked for translation. Defaults to value of $post_status.

• $label_countarray|false

  Nooped plural text from _n_noop() to provide the singular and plural forms of the label for counts. Default false which means the $label argument will be used for both the singular and plural forms of this label.

• $exclude_from_searchbooldefault: is value of $internal

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

• $_builtinbooldefault: false

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

• $publicbooldefault: false

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

• $internalbooldefault: false

  Whether the status is for internal use only.

• $protectedbooldefault: false

  Whether posts with this status should be protected.

• $privatebooldefault: false

  Whether posts with this status should be private.

• $publicly_queryablebooldefault: is value of $public

  Whether posts with this status should be publicly- queryable.

• $show_in_admin_all_listbooldefault: is the opposite value of $internal

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

• $show_in_admin_status_listbooldefault: is the opposite value of $internal

  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)

• $date_floatingbooldefault: to false

  Whether the post has a floating creation date.

Return value

object

Performance profile

How much work a call to register_post_status() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Trivial

Touches nothing outside its own arguments.

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

58–95

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 106.

Plugin surface

None

Nothing here hands control to plugin code.

Called by

1

1 place in core call this, so the cost is paid more often than your own code shows.

What it touches

• hookthird-party callbacksapply_filters()one call below register_post_status()

What one call costs · 2 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost register_post_status() can have, taken from its control-flow graph on PHP 8.5.

This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.

Uses · 3

• wp_parse_args()Merges user defined arguments into defaults array.
• sanitize_key()Sanitizes a string key.
• _n_noop()Registers plural strings in POT file, but does not translate them.

Used by · 1

• create_initial_post_types()Creates the initial post types when 'init' action is fired.

Source code

View on Trac ↗View on GitHub ↗

1457function register_post_status( $post_status, $args = array() ) {1458	global $wp_post_statuses;1459 1460	if ( ! is_array( $wp_post_statuses ) ) {1461		$wp_post_statuses = array();1462	}1463 1464	// Args prefixed with an underscore are reserved for internal use.1465	$defaults = array(1466		'label'                     => false,1467		'label_count'               => false,1468		'exclude_from_search'       => null,1469		'_builtin'                  => false,1470		'public'                    => null,1471		'internal'                  => null,1472		'protected'                 => null,1473		'private'                   => null,1474		'publicly_queryable'        => null,1475		'show_in_admin_status_list' => null,1476		'show_in_admin_all_list'    => null,1477		'date_floating'             => null,1478	);1479	$args     = wp_parse_args( $args, $defaults );1480	$args     = (object) $args;1481 1482	$post_status = sanitize_key( $post_status );1483	$args->name  = $post_status;1484 1485	// Set various defaults.1486	if ( null === $args->public && null === $args->internal && null === $args->protected && null === $args->private ) {1487		$args->internal = true;1488	}1489 1490	if ( null === $args->public ) {1491		$args->public = false;1492	}1493 1494	if ( null === $args->private ) {1495		$args->private = false;1496	}1497 1498	if ( null === $args->protected ) {1499		$args->protected = false;1500	}1501 1502	if ( null === $args->internal ) {1503		$args->internal = false;1504	}1505 1506	if ( null === $args->publicly_queryable ) {1507		$args->publicly_queryable = $args->public;1508	}1509 1510	if ( null === $args->exclude_from_search ) {1511		$args->exclude_from_search = $args->internal;1512	}1513 1514	if ( null === $args->show_in_admin_all_list ) {1515		$args->show_in_admin_all_list = ! $args->internal;1516	}1517 1518	if ( null === $args->show_in_admin_status_list ) {1519		$args->show_in_admin_status_list = ! $args->internal;1520	}1521 1522	if ( null === $args->date_floating ) {1523		$args->date_floating = false;1524	}1525 1526	if ( false === $args->label ) {1527		$args->label = $post_status;1528	}1529 1530	if ( false === $args->label_count ) {1531		// phpcs:ignore WordPress.WP.I18n.NonSingularStringLiteralSingular,WordPress.WP.I18n.NonSingularStringLiteralPlural1532		$args->label_count = _n_noop( $args->label, $args->label );1533	}1534 1535	$wp_post_statuses[ $post_status ] = $args;1536

Changelog

Introduced in 3.0.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/post.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.