abel. Default null.
* @type string $link_before Text or HTML to precede the page link label. Default null.
* @type string $post_type Post type to query for. Default 'page'.
* @type string|array $post_status Comma-separated list or array of post statuses to include. Default 'publish'.
* @type string $show_date Whether to display the page publish or modified date for each page. Accepts
* 'modified' or any other value. An empty value hides the date. Default empty.
* @type string $sort_column Comma-separated list of column names to sort the pages by. Accepts 'post_author',
* 'post_date', 'post_title', 'post_name', 'post_modified', 'post_modified_gmt',
* 'menu_order', 'post_parent', 'ID', 'rand', or 'comment_count'. Default 'post_title'.
* @type string $title_li List heading. Passing a null or empty value will result in no heading, and the list
* will not be wrapped with unordered list `
` tags. Default 'Pages'.
* @type string $item_spacing Whether to preserve whitespace within the menu's HTML. Accepts 'preserve' or 'discard'.
* Default 'preserve'.
* @type Walker $walker Walker instance to use for listing pages. Default empty which results in a
* Walker_Page instance being used.
* }
* @return void|string Void if 'echo' argument is true, HTML list of pages if 'echo' is false.
*/
function wp_list_pages( $args = '' ) {
$defaults = array(
'depth' => 0,
'show_date' => '',
'date_format' => get_option( 'date_format' ),
'child_of' => 0,
'exclude' => '',
'title_li' => __( 'Pages' ),
'echo' => 1,
'authors' => '',
'sort_column' => 'menu_order, post_title',
'link_before' => '',
'link_after' => '',
'item_spacing' => 'preserve',
'walker' => '',
);
$parsed_args = wp_parse_args( $args, $defaults );
if ( ! in_array( $parsed_args['item_spacing'], array( 'preserve', 'discard' ), true ) ) {
// Invalid value, fall back to default.
$parsed_args['item_spacing'] = $defaults['item_spacing'];
}
$output = '';
$current_page = 0;
// Sanitize, mostly to keep spaces out.
$parsed_args['exclude'] = preg_replace( '/[^0-9,]/', '', $parsed_args['exclude'] );
// Allow plugins to filter an array of excluded pages (but don't put a nullstring into the array).
$exclude_array = ( $parsed_args['exclude'] ) ? explode( ',', $parsed_args['exclude'] ) : array();
/**
* Filters the array of pages to exclude from the pages list.
*
* @since 2.1.0
*
* @param string[] $exclude_array An array of page IDs to exclude.
*/
$parsed_args['exclude'] = implode( ',', apply_filters( 'wp_list_pages_excludes', $exclude_array ) );
$parsed_args['hierarchical'] = 0;
// Query pages.
$pages = get_pages( $parsed_args );
if ( ! empty( $pages ) ) {
if ( $parsed_args['title_li'] ) {
$output .= '- ' . $parsed_args['title_li'] . '
';
}
global $wp_query;
if ( is_page() || is_attachment() || $wp_query->is_posts_page ) {
$current_page = get_queried_object_id();
} elseif ( is_singular() ) {
$queried_object = get_queried_object();
if ( is_post_type_hierarchical( $queried_object->post_type ) ) {
$current_page = $queried_object->ID;
}
}
$output .= walk_page_tree( $pages, $parsed_args['depth'], $current_page, $parsed_args );
if ( $parsed_args['title_li'] ) {
$output .= '
';
}
}
/**
* Filters the HTML output of the pages to list.
*
* @since 1.5.1
* @since 4.4.0 `$pages` added as arguments.
*
* @see wp_list_pages()
*
* @param string $output HTML output of the pages list.
* @param array $parsed_args An array of page-listing arguments. See wp_list_pages()
* for information on accepted arguments.
* @param WP_Post[] $pages Array of the page objects.
*/
$html = apply_filters( 'wp_list_pages', $output, $parsed_args, $pages );
if ( $parsed_args['echo'] ) {
echo $html;
} else {
return $html;
}
}
/**
* Displays or retrieves a list of pages with an optional home link.
*
* The arguments are listed below and part of the arguments are for wp_list_pages() function.
* Check that function for more info on those arguments.
*
* @since 2.7.0
* @since 4.4.0 Added `menu_id`, `container`, `before`, `after`, and `walker` arguments.
* @since 4.7.0 Added the `item_spacing` argument.
*
* @param array|string $args {
* Optional. Array or string of arguments to generate a page menu. See wp_list_pages() for additional arguments.
*
* @type string $sort_column How to sort the list of pages. Accepts post column names.
* Default 'menu_order, post_title'.
* @type string $menu_id ID for the div containing the page list. Default is empty string.
* @type string $menu_class Class to use for the element containing the page list. Default 'menu'.
* @type string $container Element to use for the element containing the page list. Default 'div'.
* @type bool $echo Whether to echo the list or return it. Accepts true (echo) or false (return).
* Default true.
* @type int|bool|string $show_home Whether to display the link to the home page. Can just enter the text
* you'd like shown for the home link. 1|true defaults to 'Home'.
* @type string $link_before The HTML or text to prepend to $show_home text. Default empty.
* @type string $link_after The HTML or text to append to $show_home text. Default empty.
* @type string $before The HTML or text to prepend to the menu. Default is ''.
* @type string $after The HTML or text to append to the menu. Default is '
'.
* @type string $item_spacing Whether to preserve whitespace within the menu's HTML. Accepts 'preserve'
* or 'discard'. Default 'discard'.
* @type Walker $walker Walker instance to use for listing pages. Default empty which results in a
* Walker_Page instance being used.
* }
* @return void|string Void if 'echo' argument is true, HTML menu if 'echo' is false.
*/
function wp_page_menu( $args = array() ) {
$defaults = array(
'sort_column' => 'menu_order, post_title',
'menu_id' => '',
'menu_class' => 'menu',
'container' => 'div',
'echo' => true,
'link_before' => '',
'link_after' => '',
'before' => '',
'item_spacing' => 'discard',
'walker' => '',
);
$args = wp_parse_args( $args, $defaults );
if ( ! in_array( $args['item_spacing'], array( 'preserve', 'discard' ), true ) ) {
// Invalid value, fall back to default.
$args['item_spacing'] = $defaults['item_spacing'];
}
if ( 'preserve' === $args['item_spacing'] ) {
$t = "\t";
$n = "\n";
} else {
$t = '';
$n = '';
}
/**
* Filters the arguments used to generate a page-based menu.
*
* @since 2.7.0
*
* @see wp_page_menu()
*
* @param array $args An array of page menu arguments. See wp_page_menu()
* for information on accepted arguments.
*/
$args = apply_filters( 'wp_page_menu_args', $args );
$menu = '';
$list_args = $args;
// Show Home in the menu.
if ( ! empty( $args['show_home'] ) ) {
if ( true === $args['show_home'] || '1' === $args['show_home'] || 1 === $args['show_home'] ) {
$text = __( 'Home' );
} else {
$text = $args['show_home'];
}
$class = '';
if ( is_front_page() && ! is_paged() ) {
$class = 'class="current_page_item"';
}
$menu .= '- ' . $args['link_before'] . $text . $args['link_after'] . '
';
// If the front page is a page, add it to the exclude list.
if ( 'page' === get_option( 'show_on_front' ) ) {
if ( ! empty( $list_args['exclude'] ) ) {
$list_args['exclude'] .= ',';
} else {
$list_args['exclude'] = '';
}
$list_args['exclude'] .= get_option( 'page_on_front' );
}
}
$list_args['echo'] = false;
$list_args['title_li'] = '';
$menu .= wp_list_pages( $list_args );
$container = sanitize_text_field( $args['container'] );
// Fallback in case `wp_nav_menu()` was called without a container.
if ( empty( $container ) ) {
$container = 'div';
}
if ( $menu ) {
// wp_nav_menu() doesn't set before and after.
if ( isset( $args['fallback_cb'] ) &&
'wp_page_menu' === $args['fallback_cb'] &&
'ul' !== $container ) {
$args['before'] = "{$n}";
$args['after'] = '
';
}
$menu = $args['before'] . $menu . $args['after'];
}
$attrs = '';
if ( ! empty( $args['menu_id'] ) ) {
$attrs .= ' id="' . esc_attr( $args['menu_id'] ) . '"';
}
if ( ! empty( $args['menu_class'] ) ) {
$attrs .= ' class="' . esc_attr( $args['menu_class'] ) . '"';
}
$menu = "<{$container}{$attrs}>" . $menu . "{$container}>{$n}";
/**
* Filters the HTML output of a page-based menu.
*
* @since 2.7.0
*
* @see wp_page_menu()
*
* @param string $menu The HTML output.
* @param array $args An array of arguments. See wp_page_menu()
* for information on accepted arguments.
*/
$menu = apply_filters( 'wp_page_menu', $menu, $args );
if ( $args['echo'] ) {
echo $menu;
} else {
return $menu;
}
}
//
// Page helpers.
//
/**
* Retrieves HTML list content for page list.
*
* @uses Walker_Page to create HTML list content.
* @since 2.1.0
*
* @param array $pages
* @param int $depth
* @param int $current_page
* @param array $args
* @return string
*/
function walk_page_tree( $pages, $depth, $current_page, $args ) {
if ( empty( $args['walker'] ) ) {
$walker = new Walker_Page();
} else {
/**
* @var Walker $walker
*/
$walker = $args['walker'];
}
foreach ( (array) $pages as $page ) {
if ( $page->post_parent ) {
$args['pages_with_children'][ $page->post_parent ] = true;
}
}
return $walker->walk( $pages, $depth, $args, $current_page );
}
/**
* Retrieves HTML dropdown (select) content for page list.
*
* @since 2.1.0
* @since 5.3.0 Formalized the existing `...$args` parameter by adding it
* to the function signature.
*
* @uses Walker_PageDropdown to create HTML dropdown content.
* @see Walker_PageDropdown::walk() for parameters and return description.
*
* @param mixed ...$args Elements array, maximum hierarchical depth and optional additional arguments.
* @return string
*/
function walk_page_dropdown_tree( ...$args ) {
if ( empty( $args[2]['walker'] ) ) { // The user's options are the third parameter.
$walker = new Walker_PageDropdown();
} else {
/**
* @var Walker $walker
*/
$walker = $args[2]['walker'];
}
return $walker->walk( ...$args );
}
//
// Attachments.
//
/**
* Displays an attachment page link using an image or icon.
*
* @since 2.0.0
*
* @param int|WP_Post $post Optional. Post ID or post object.
* @param bool $fullsize Optional. Whether to use full size. Default false.
* @param bool $deprecated Deprecated. Not used.
* @param bool $permalink Optional. Whether to include permalink. Default false.
*/
function the_attachment_link( $post = 0, $fullsize = false, $deprecated = false, $permalink = false ) {
if ( ! empty( $deprecated ) ) {
_deprecated_argument( __FUNCTION__, '2.5.0' );
}
if ( $fullsize ) {
echo wp_get_attachment_link( $post, 'full', $permalink );
} else {
echo wp_get_attachment_link( $post, 'thumbnail', $permalink );
}
}
/**
* Retrieves an attachment page link using an image or icon, if possible.
*
* @since 2.5.0
* @since 4.4.0 The `$post` parameter can now accept either a post ID or `WP_Post` object.
*
* @param int|WP_Post $post Optional. Post ID or post object.
* @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
* of width and height values in pixels (in that order). Default 'thumbnail'.
* @param bool $permalink Optional. Whether to add permalink to image. Default false.
* @param bool $icon Optional. Whether the attachment is an icon. Default false.
* @param string|false $text Optional. Link text to use. Activated by passing a string, false otherwise.
* Default false.
* @param array|string $attr Optional. Array or string of attributes. Default empty.
* @return string HTML content.
*/
function wp_get_attachment_link( $post = 0, $size = 'thumbnail', $permalink = false, $icon = false, $text = false, $attr = '' ) {
$_post = get_post( $post );
if ( empty( $_post ) || ( 'attachment' !== $_post->post_type ) || ! wp_get_attachment_url( $_post->ID ) ) {
return __( 'Missing Attachment' );
}
$url = wp_get_attachment_url( $_post->ID );
if ( $permalink ) {
$url = get_attachment_link( $_post->ID );
}
if ( $text ) {
$link_text = $text;
} elseif ( $size && 'none' !== $size ) {
$link_text = wp_get_attachment_image( $_post->ID, $size, $icon, $attr );
} else {
$link_text = '';
}
if ( '' === trim( $link_text ) ) {
$link_text = $_post->post_title;
}
if ( '' === trim( $link_text ) ) {
$link_text = esc_html( pathinfo( get_attached_file( $_post->ID ), PATHINFO_FILENAME ) );
}
/**
* Filters the list of attachment link attributes.
*
* @since 6.2.0
*
* @param array $attributes An array of attributes for the link markup,
* keyed on the attribute name.
* @param int $id Post ID.
*/
$attributes = apply_filters( 'wp_get_attachment_link_attributes', array( 'href' => $url ), $_post->ID );
$link_attributes = '';
foreach ( $attributes as $name => $value ) {
$value = 'href' === $name ? esc_url( $value ) : esc_attr( $value );
$link_attributes .= ' ' . esc_attr( $name ) . "='" . $value . "'";
}
$link_html = "$link_text";
/**
* Filters a retrieved attachment page link.
*
* @since 2.7.0
* @since 5.1.0 Added the `$attr` parameter.
*
* @param string $link_html The page link HTML output.
* @param int|WP_Post $post Post ID or object. Can be 0 for the current global post.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
* @param bool $permalink Whether to add permalink to image. Default false.
* @param bool $icon Whether to include an icon.
* @param string|false $text If string, will be link text.
* @param array|string $attr Array or string of attributes.
*/
return apply_filters( 'wp_get_attachment_link', $link_html, $post, $size, $permalink, $icon, $text, $attr );
}
/**
* Wraps attachment in paragraph tag before content.
*
* @since 2.0.0
*
* @param string $content
* @return string
*/
function prepend_attachment( $content ) {
$post = get_post();
if ( empty( $post->post_type ) || 'attachment' !== $post->post_type ) {
return $content;
}
if ( wp_attachment_is( 'video', $post ) ) {
$meta = wp_get_attachment_metadata( get_the_ID() );
$atts = array( 'src' => wp_get_attachment_url() );
if ( ! empty( $meta['width'] ) && ! empty( $meta['height'] ) ) {
$atts['width'] = (int) $meta['width'];
$atts['height'] = (int) $meta['height'];
}
if ( has_post_thumbnail() ) {
$atts['poster'] = wp_get_attachment_url( get_post_thumbnail_id() );
}
$p = wp_video_shortcode( $atts );
} elseif ( wp_attachment_is( 'audio', $post ) ) {
$p = wp_audio_shortcode( array( 'src' => wp_get_attachment_url() ) );
} else {
$p = '';
// Show the medium sized image representation of the attachment if available, and link to the raw file.
$p .= wp_get_attachment_link( 0, 'medium', false );
$p .= '
';
}
/**
* Filters the attachment markup to be prepended to the post content.
*
* @since 2.0.0
*
* @see prepend_attachment()
*
* @param string $p The attachment HTML output.
*/
$p = apply_filters( 'prepend_attachment', $p );
return "$p\n$content";
}
//
// Misc.
//
/**
* Retrieves protected post password form content.
*
* @since 1.0.0
*
* @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global $post.
* @return string HTML content for password form for password protected post.
*/
function get_the_password_form( $post = 0 ) {
$post = get_post( $post );
$label = 'pwbox-' . ( empty( $post->ID ) ? rand() : $post->ID );
$output = '
';
/**
* Filters the HTML output for the protected post password form.
*
* If modifying the password field, please note that the core database schema
* limits the password field to 20 characters regardless of the value of the
* size attribute in the form input.
*
* @since 2.7.0
* @since 5.8.0 Added the `$post` parameter.
*
* @param string $output The password form HTML output.
* @param WP_Post $post Post object.
*/
return apply_filters( 'the_password_form', $output, $post );
}
/**
* Determines whether the current post uses a page template.
*
* This template tag allows you to determine if you are in a page template.
* You can optionally provide a template filename or array of template filenames
* and then the check will be specific to that template.
*
* For more information on this and similar theme functions, check out
* the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
* Conditional Tags} article in the Theme Developer Handbook.
*
* @since 2.5.0
* @since 4.2.0 The `$template` parameter was changed to also accept an array of page templates.
* @since 4.7.0 Now works with any post type, not just pages.
*
* @param string|string[] $template The specific template filename or array of templates to match.
* @return bool True on success, false on failure.
*/
function is_page_template( $template = '' ) {
if ( ! is_singular() ) {
return false;
}
$page_template = get_page_template_slug( get_queried_object_id() );
if ( empty( $template ) ) {
return (bool) $page_template;
}
if ( $template == $page_template ) {
return true;
}
if ( is_array( $template ) ) {
if ( ( in_array( 'default', $template, true ) && ! $page_template )
|| in_array( $page_template, $template, true )
) {
return true;
}
}
return ( 'default' === $template && ! $page_template );
}
/**
* Gets the specific template filename for a given post.
*
* @since 3.4.0
* @since 4.7.0 Now works with any post type, not just pages.
*
* @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global $post.
* @return string|false Page template filename. Returns an empty string when the default page template
* is in use. Returns false if the post does not exist.
*/
function get_page_template_slug( $post = null ) {
$post = get_post( $post );
if ( ! $post ) {
return false;
}
$template = get_post_meta( $post->ID, '_wp_page_template', true );
if ( ! $template || 'default' === $template ) {
return '';
}
return $template;
}
/**
* Retrieves formatted date timestamp of a revision (linked to that revisions's page).
*
* @since 2.6.0
*
* @param int|object $revision Revision ID or revision object.
* @param bool $link Optional. Whether to link to revision's page. Default true.
* @return string|false i18n formatted datetimestamp or localized 'Current Revision'.
*/
function wp_post_revision_title( $revision, $link = true ) {
$revision = get_post( $revision );
if ( ! $revision ) {
return $revision;
}
if ( ! in_array( $revision->post_type, array( 'post', 'page', 'revision' ), true ) ) {
return false;
}
/* translators: Revision date format, see https://www.php.net/manual/datetime.format.php */
$datef = _x( 'F j, Y @ H:i:s', 'revision date format' );
/* translators: %s: Revision date. */
$autosavef = __( '%s [Autosave]' );
/* translators: %s: Revision date. */
$currentf = __( '%s [Current Revision]' );
$date = date_i18n( $datef, strtotime( $revision->post_modified ) );
$edit_link = get_edit_post_link( $revision->ID );
if ( $link && current_user_can( 'edit_post', $revision->ID ) && $edit_link ) {
$date = "$date";
}
if ( ! wp_is_post_revision( $revision ) ) {
$date = sprintf( $currentf, $date );
} elseif ( wp_is_post_autosave( $revision ) ) {
$date = sprintf( $autosavef, $date );
}
return $date;
}
/**
* Retrieves formatted date timestamp of a revision (linked to that revisions's page).
*
* @since 3.6.0
*
* @param int|object $revision Revision ID or revision object.
* @param bool $link Optional. Whether to link to revision's page. Default true.
* @return string|false gravatar, user, i18n formatted datetimestamp or localized 'Current Revision'.
*/
function wp_post_revision_title_expanded( $revision, $link = true ) {
$revision = get_post( $revision );
if ( ! $revision ) {
return $revision;
}
if ( ! in_array( $revision->post_type, array( 'post', 'page', 'revision' ), true ) ) {
return false;
}
$author = get_the_author_meta( 'display_name', $revision->post_author );
/* translators: Revision date format, see https://www.php.net/manual/datetime.format.php */
$datef = _x( 'F j, Y @ H:i:s', 'revision date format' );
$gravatar = get_avatar( $revision->post_author, 24 );
$date = date_i18n( $datef, strtotime( $revision->post_modified ) );
$edit_link = get_edit_post_link( $revision->ID );
if ( $link && current_user_can( 'edit_post', $revision->ID ) && $edit_link ) {
$date = "$date";
}
$revision_date_author = sprintf(
/* translators: Post revision title. 1: Author avatar, 2: Author name, 3: Time ago, 4: Date. */
__( '%1$s %2$s, %3$s ago (%4$s)' ),
$gravatar,
$author,
human_time_diff( strtotime( $revision->post_modified_gmt ) ),
$date
);
/* translators: %s: Revision date with author avatar. */
$autosavef = __( '%s [Autosave]' );
/* translators: %s: Revision date with author avatar. */
$currentf = __( '%s [Current Revision]' );
if ( ! wp_is_post_revision( $revision ) ) {
$revision_date_author = sprintf( $currentf, $revision_date_author );
} elseif ( wp_is_post_autosave( $revision ) ) {
$revision_date_author = sprintf( $autosavef, $revision_date_author );
}
/**
* Filters the formatted author and date for a revision.
*
* @since 4.4.0
*
* @param string $revision_date_author The formatted string.
* @param WP_Post $revision The revision object.
* @param bool $link Whether to link to the revisions page, as passed into
* wp_post_revision_title_expanded().
*/
return apply_filters( 'wp_post_revision_title_expanded', $revision_date_author, $revision, $link );
}
/**
* Displays a list of a post's revisions.
*
* Can output either a UL with edit links or a TABLE with diff interface, and
* restore action links.
*
* @since 2.6.0
*
* @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global $post.
* @param string $type 'all' (default), 'revision' or 'autosave'
*/
function wp_list_post_revisions( $post = 0, $type = 'all' ) {
$post = get_post( $post );
if ( ! $post ) {
return;
}
// $args array with (parent, format, right, left, type) deprecated since 3.6.
if ( is_array( $type ) ) {
$type = ! empty( $type['type'] ) ? $type['type'] : $type;
_deprecated_argument( __FUNCTION__, '3.6.0' );
}
$revisions = wp_get_post_revisions( $post->ID );
if ( ! $revisions ) {
return;
}
$rows = '';
foreach ( $revisions as $revision ) {
if ( ! current_user_can( 'read_post', $revision->ID ) ) {
continue;
}
$is_autosave = wp_is_post_autosave( $revision );
if ( ( 'revision' === $type && $is_autosave ) || ( 'autosave' === $type && ! $is_autosave ) ) {
continue;
}
$rows .= "\t" . wp_post_revision_title_expanded( $revision ) . "\n";
}
echo "" . __( 'JavaScript must be enabled to use this feature.' ) . "
\n";
echo "';
}
/**
* Retrieves the parent post object for the given post.
*
* @since 5.7.0
*
* @param int|WP_Post|null $post Optional. Post ID or WP_Post object. Default is global $post.
* @return WP_Post|null Parent post object, or null if there isn't one.
*/
function get_post_parent( $post = null ) {
$wp_post = get_post( $post );
return ! empty( $wp_post->post_parent ) ? get_post( $wp_post->post_parent ) : null;
}
/**
* Returns whether the given post has a parent post.
*
* @since 5.7.0
*
* @param int|WP_Post|null $post Optional. Post ID or WP_Post object. Default is global $post.
* @return bool Whether the post has a parent post.
*/
function has_post_parent( $post = null ) {
return (bool) get_post_parent( $post );
}
se().
),
'properties' => array(
'raw' => array(
'description' => __( 'Content for the post, as it exists in the database.' ),
'type' => 'string',
'context' => array( 'edit' ),
),
'rendered' => array(
'description' => __( 'HTML content for the post, transformed for display.' ),
'type' => 'string',
'context' => array( 'view', 'edit' ),
'readonly' => true,
),
'block_version' => array(
'description' => __( 'Version of the content block format used by the post.' ),
'type' => 'integer',
'context' => array( 'edit' ),
'readonly' => true,
),
'protected' => array(
'description' => __( 'Whether the content is protected with a password.' ),
'type' => 'boolean',
'context' => array( 'view', 'edit', 'embed' ),
'readonly' => true,
),
),
);
break;
case 'author':
$schema['properties']['author'] = array(
'description' => __( 'The ID for the author of the post.' ),
'type' => 'integer',
'context' => array( 'view', 'edit', 'embed' ),
);
break;
case 'excerpt':
$schema['properties']['excerpt'] = array(
'description' => __( 'The excerpt for the post.' ),
'type' => 'object',
'context' => array( 'view', 'edit', 'embed' ),
'arg_options' => array(
'sanitize_callback' => null, // Note: sanitization implemented in self::prepare_item_for_database().
'validate_callback' => null, // Note: validation implemented in self::prepare_item_for_database().
),
'properties' => array(
'raw' => array(
'description' => __( 'Excerpt for the post, as it exists in the database.' ),
'type' => 'string',
'context' => array( 'edit' ),
),
'rendered' => array(
'description' => __( 'HTML excerpt for the post, transformed for display.' ),
'type' => 'string',
'context' => array( 'view', 'edit', 'embed' ),
'readonly' => true,
),
'protected' => array(
'description' => __( 'Whether the excerpt is protected with a password.' ),
'type' => 'boolean',
'context' => array( 'view', 'edit', 'embed' ),
'readonly' => true,
),
),
);
break;
case 'thumbnail':
$schema['properties']['featured_media'] = array(
'description' => __( 'The ID of the featured media for the post.' ),
'type' => 'integer',
'context' => array( 'view', 'edit', 'embed' ),
);
break;
case 'comments':
$schema['properties']['comment_status'] = array(
'description' => __( 'Whether or not comments are open on the post.' ),
'type' => 'string',
'enum' => array( 'open', 'closed' ),
'context' => array( 'view', 'edit' ),
);
$schema['properties']['ping_status'] = array(
'description' => __( 'Whether or not the post can be pinged.' ),
'type' => 'string',
'enum' => array( 'open', 'closed' ),
'context' => array( 'view', 'edit' ),
);
break;
case 'page-attributes':
$schema['properties']['menu_order'] = array(
'description' => __( 'The order of the post in relation to other posts.' ),
'type' => 'integer',
'context' => array( 'view', 'edit' ),
);
break;
case 'post-formats':
// Get the native post formats and remove the array keys.
$formats = array_values( get_post_format_slugs() );
$schema['properties']['format'] = array(
'description' => __( 'The format for the post.' ),
'type' => 'string',
'enum' => $formats,
'context' => array( 'view', 'edit' ),
);
break;
case 'custom-fields':
$schema['properties']['meta'] = $this->meta->get_field_schema();
break;
}
}
if ( 'post' === $this->post_type ) {
$schema['properties']['sticky'] = array(
'description' => __( 'Whether or not the post should be treated as sticky.' ),
'type' => 'boolean',
'context' => array( 'view', 'edit' ),
);
}
$schema['properties']['template'] = array(
'description' => __( 'The theme file to use to display the post.' ),
'type' => 'string',
'context' => array( 'view', 'edit' ),
'arg_options' => array(
'validate_callback' => array( $this, 'check_template' ),
),
);
$taxonomies = wp_list_filter( get_object_taxonomies( $this->post_type, 'objects' ), array( 'show_in_rest' => true ) );
foreach ( $taxonomies as $taxonomy ) {
$base = ! empty( $taxonomy->rest_base ) ? $taxonomy->rest_base : $taxonomy->name;
if ( array_key_exists( $base, $schema['properties'] ) ) {
$taxonomy_field_name_with_conflict = ! empty( $taxonomy->rest_base ) ? 'rest_base' : 'name';
_doing_it_wrong(
'register_taxonomy',
sprintf(
/* translators: 1: The taxonomy name, 2: The property name, either 'rest_base' or 'name', 3: The conflicting value. */
__( 'The "%1$s" taxonomy "%2$s" property (%3$s) conflicts with an existing property on the REST API Posts Controller. Specify a custom "rest_base" when registering the taxonomy to avoid this error.' ),
$taxonomy->name,
$taxonomy_field_name_with_conflict,
$base
),
'5.4.0'
);
}
$schema['properties'][ $base ] = array(
/* translators: %s: Taxonomy name. */
'description' => sprintf( __( 'The terms assigned to the post in the %s taxonomy.' ), $taxonomy->name ),
'type' => 'array',
'items' => array(
'type' => 'integer',
),
'context' => array( 'view', 'edit' ),
);
}
$schema_links = $this->get_schema_links();
if ( $schema_links ) {
$schema['links'] = $schema_links;
}
// Take a snapshot of which fields are in the schema pre-filtering.
$schema_fields = array_keys( $schema['properties'] );
/**
* Filters the post's schema.
*
* The dynamic portion of the filter, `$this->post_type`, refers to the
* post type slug for the controller.
*
* Possible hook names include:
*
* - `rest_post_item_schema`
* - `rest_page_item_schema`
* - `rest_attachment_item_schema`
*
* @since 5.4.0
*
* @param array $schema Item schema data.
*/
$schema = apply_filters( "rest_{$this->post_type}_item_schema", $schema );
// Emit a _doing_it_wrong warning if user tries to add new properties using this filter.
$new_fields = array_diff( array_keys( $schema['properties'] ), $schema_fields );
if ( count( $new_fields ) > 0 ) {
_doing_it_wrong(
__METHOD__,
sprintf(
/* translators: %s: register_rest_field */
__( 'Please use %s to add new schema properties.' ),
'register_rest_field'
),
'5.4.0'
);
}
$this->schema = $schema;
return $this->add_additional_fields_schema( $this->schema );
}
/**
* Retrieves Link Description Objects that should be added to the Schema for the posts collection.
*
* @since 4.9.8
*
* @return array
*/
protected function get_schema_links() {
$href = rest_url( "{$this->namespace}/{$this->rest_base}/{id}" );
$links = array();
if ( 'attachment' !== $this->post_type ) {
$links[] = array(
'rel' => 'https://api.w.org/action-publish',
'title' => __( 'The current user can publish this post.' ),
'href' => $href,
'targetSchema' => array(
'type' => 'object',
'properties' => array(
'status' => array(
'type' => 'string',
'enum' => array( 'publish', 'future' ),
),
),
),
);
}
$links[] = array(
'rel' => 'https://api.w.org/action-unfiltered-html',
'title' => __( 'The current user can post unfiltered HTML markup and JavaScript.' ),
'href' => $href,
'targetSchema' => array(
'type' => 'object',
'properties' => array(
'content' => array(
'raw' => array(
'type' => 'string',
),
),
),
),
);
if ( 'post' === $this->post_type ) {
$links[] = array(
'rel' => 'https://api.w.org/action-sticky',
'title' => __( 'The current user can sticky this post.' ),
'href' => $href,
'targetSchema' => array(
'type' => 'object',
'properties' => array(
'sticky' => array(
'type' => 'boolean',
),
),
),
);
}
if ( post_type_supports( $this->post_type, 'author' ) ) {
$links[] = array(
'rel' => 'https://api.w.org/action-assign-author',
'title' => __( 'The current user can change the author on this post.' ),
'href' => $href,
'targetSchema' => array(
'type' => 'object',
'properties' => array(
'author' => array(
'type' => 'integer',
),
),
),
);
}
$taxonomies = wp_list_filter( get_object_taxonomies( $this->post_type, 'objects' ), array( 'show_in_rest' => true ) );
foreach ( $taxonomies as $tax ) {
$tax_base = ! empty( $tax->rest_base ) ? $tax->rest_base : $tax->name;
/* translators: %s: Taxonomy name. */
$assign_title = sprintf( __( 'The current user can assign terms in the %s taxonomy.' ), $tax->name );
/* translators: %s: Taxonomy name. */
$create_title = sprintf( __( 'The current user can create terms in the %s taxonomy.' ), $tax->name );
$links[] = array(
'rel' => 'https://api.w.org/action-assign-' . $tax_base,
'title' => $assign_title,
'href' => $href,
'targetSchema' => array(
'type' => 'object',
'properties' => array(
$tax_base => array(
'type' => 'array',
'items' => array(
'type' => 'integer',
),
),
),
),
);
$links[] = array(
'rel' => 'https://api.w.org/action-create-' . $tax_base,
'title' => $create_title,
'href' => $href,
'targetSchema' => array(
'type' => 'object',
'properties' => array(
$tax_base => array(
'type' => 'array',
'items' => array(
'type' => 'integer',
),
),
),
),
);
}
return $links;
}
/**
* Retrieves the query params for the posts collection.
*
* @since 4.7.0
* @since 5.4.0 The `tax_relation` query parameter was added.
* @since 5.7.0 The `modified_after` and `modified_before` query parameters were added.
*
* @return array Collection parameters.
*/
public function get_collection_params() {
$query_params = parent::get_collection_params();
$query_params['context']['default'] = 'view';
$query_params['after'] = array(
'description' => __( 'Limit response to posts published after a given ISO8601 compliant date.' ),
'type' => 'string',
'format' => 'date-time',
);
$query_params['modified_after'] = array(
'description' => __( 'Limit response to posts modified after a given ISO8601 compliant date.' ),
'type' => 'string',
'format' => 'date-time',
);
if ( post_type_supports( $this->post_type, 'author' ) ) {
$query_params['author'] = array(
'description' => __( 'Limit result set to posts assigned to specific authors.' ),
'type' => 'array',
'items' => array(
'type' => 'integer',
),
'default' => array(),
);
$query_params['author_exclude'] = array(
'description' => __( 'Ensure result set excludes posts assigned to specific authors.' ),
'type' => 'array',
'items' => array(
'type' => 'integer',
),
'default' => array(),
);
}
$query_params['before'] = array(
'description' => __( 'Limit response to posts published before a given ISO8601 compliant date.' ),
'type' => 'string',
'format' => 'date-time',
);
$query_params['modified_before'] = array(
'description' => __( 'Limit response to posts modified before a given ISO8601 compliant date.' ),
'type' => 'string',
'format' => 'date-time',
);
$query_params['exclude'] = array(
'description' => __( 'Ensure result set excludes specific IDs.' ),
'type' => 'array',
'items' => array(
'type' => 'integer',
),
'default' => array(),
);
$query_params['include'] = array(
'description' => __( 'Limit result set to specific IDs.' ),
'type' => 'array',
'items' => array(
'type' => 'integer',
),
'default' => array(),
);
if ( 'page' === $this->post_type || post_type_supports( $this->post_type, 'page-attributes' ) ) {
$query_params['menu_order'] = array(
'description' => __( 'Limit result set to posts with a specific menu_order value.' ),
'type' => 'integer',
);
}
$query_params['offset'] = array(
'description' => __( 'Offset the result set by a specific number of items.' ),
'type' => 'integer',
);
$query_params['order'] = array(
'description' => __( 'Order sort attribute ascending or descending.' ),
'type' => 'string',
'default' => 'desc',
'enum' => array( 'asc', 'desc' ),
);
$query_params['orderby'] = array(
'description' => __( 'Sort collection by post attribute.' ),
'type' => 'string',
'default' => 'date',
'enum' => array(
'author',
'date',
'id',
'include',
'modified',
'parent',
'relevance',
'slug',
'include_slugs',
'title',
),
);
if ( 'page' === $this->post_type || post_type_supports( $this->post_type, 'page-attributes' ) ) {
$query_params['orderby']['enum'][] = 'menu_order';
}
$post_type = get_post_type_object( $this->post_type );
if ( $post_type->hierarchical || 'attachment' === $this->post_type ) {
$query_params['parent'] = array(
'description' => __( 'Limit result set to items with particular parent IDs.' ),
'type' => 'array',
'items' => array(
'type' => 'integer',
),
'default' => array(),
);
$query_params['parent_exclude'] = array(
'description' => __( 'Limit result set to all items except those of a particular parent ID.' ),
'type' => 'array',
'items' => array(
'type' => 'integer',
),
'default' => array(),
);
}
$query_params['search_columns'] = array(
'default' => array(),
'description' => __( 'Array of column names to be searched.' ),
'type' => 'array',
'items' => array(
'enum' => array( 'post_title', 'post_content', 'post_excerpt' ),
'type' => 'string',
),
);
$query_params['slug'] = array(
'description' => __( 'Limit result set to posts with one or more specific slugs.' ),
'type' => 'array',
'items' => array(
'type' => 'string',
),
);
$query_params['status'] = array(
'default' => 'publish',
'description' => __( 'Limit result set to posts assigned one or more statuses.' ),
'type' => 'array',
'items' => array(
'enum' => array_merge( array_keys( get_post_stati() ), array( 'any' ) ),
'type' => 'string',
),
'sanitize_callback' => array( $this, 'sanitize_post_statuses' ),
);
$query_params = $this->prepare_taxonomy_limit_schema( $query_params );
if ( 'post' === $this->post_type ) {
$query_params['sticky'] = array(
'description' => __( 'Limit result set to items that are sticky.' ),
'type' => 'boolean',
);
}
/**
* Filters collection parameters for the posts controller.
*
* The dynamic part of the filter `$this->post_type` refers to the post
* type slug for the controller.
*
* This filter registers the collection parameter, but does not map the
* collection parameter to an internal WP_Query parameter. Use the
* `rest_{$this->post_type}_query` filter to set WP_Query parameters.
*
* @since 4.7.0
*
* @param array $query_params JSON Schema-formatted collection parameters.
* @param WP_Post_Type $post_type Post type object.
*/
return apply_filters( "rest_{$this->post_type}_collection_params", $query_params, $post_type );
}
/**
* Sanitizes and validates the list of post statuses, including whether the
* user can query private statuses.
*
* @since 4.7.0
*
* @param string|array $statuses One or more post statuses.
* @param WP_REST_Request $request Full details about the request.
* @param string $parameter Additional parameter to pass to validation.
* @return array|WP_Error A list of valid statuses, otherwise WP_Error object.
*/
public function sanitize_post_statuses( $statuses, $request, $parameter ) {
$statuses = wp_parse_slug_list( $statuses );
// The default status is different in WP_REST_Attachments_Controller.
$attributes = $request->get_attributes();
$default_status = $attributes['args']['status']['default'];
foreach ( $statuses as $status ) {
if ( $status === $default_status ) {
continue;
}
$post_type_obj = get_post_type_object( $this->post_type );
if ( current_user_can( $post_type_obj->cap->edit_posts ) || 'private' === $status && current_user_can( $post_type_obj->cap->read_private_posts ) ) {
$result = rest_validate_request_arg( $status, $request, $parameter );
if ( is_wp_error( $result ) ) {
return $result;
}
} else {
return new WP_Error(
'rest_forbidden_status',
__( 'Status is forbidden.' ),
array( 'status' => rest_authorization_required_code() )
);
}
}
return $statuses;
}
/**
* Prepares the 'tax_query' for a collection of posts.
*
* @since 5.7.0
*
* @param array $args WP_Query arguments.
* @param WP_REST_Request $request Full details about the request.
* @return array Updated query arguments.
*/
private function prepare_tax_query( array $args, WP_REST_Request $request ) {
$relation = $request['tax_relation'];
if ( $relation ) {
$args['tax_query'] = array( 'relation' => $relation );
}
$taxonomies = wp_list_filter(
get_object_taxonomies( $this->post_type, 'objects' ),
array( 'show_in_rest' => true )
);
foreach ( $taxonomies as $taxonomy ) {
$base = ! empty( $taxonomy->rest_base ) ? $taxonomy->rest_base : $taxonomy->name;
$tax_include = $request[ $base ];
$tax_exclude = $request[ $base . '_exclude' ];
if ( $tax_include ) {
$terms = array();
$include_children = false;
$operator = 'IN';
if ( rest_is_array( $tax_include ) ) {
$terms = $tax_include;
} elseif ( rest_is_object( $tax_include ) ) {
$terms = empty( $tax_include['terms'] ) ? array() : $tax_include['terms'];
$include_children = ! empty( $tax_include['include_children'] );
if ( isset( $tax_include['operator'] ) && 'AND' === $tax_include['operator'] ) {
$operator = 'AND';
}
}
if ( $terms ) {
$args['tax_query'][] = array(
'taxonomy' => $taxonomy->name,
'field' => 'term_id',
'terms' => $terms,
'include_children' => $include_children,
'operator' => $operator,
);
}
}
if ( $tax_exclude ) {
$terms = array();
$include_children = false;
if ( rest_is_array( $tax_exclude ) ) {
$terms = $tax_exclude;
} elseif ( rest_is_object( $tax_exclude ) ) {
$terms = empty( $tax_exclude['terms'] ) ? array() : $tax_exclude['terms'];
$include_children = ! empty( $tax_exclude['include_children'] );
}
if ( $terms ) {
$args['tax_query'][] = array(
'taxonomy' => $taxonomy->name,
'field' => 'term_id',
'terms' => $terms,
'include_children' => $include_children,
'operator' => 'NOT IN',
);
}
}
}
return $args;
}
/**
* Prepares the collection schema for including and excluding items by terms.
*
* @since 5.7.0
*
* @param array $query_params Collection schema.
* @return array Updated schema.
*/
private function prepare_taxonomy_limit_schema( array $query_params ) {
$taxonomies = wp_list_filter( get_object_taxonomies( $this->post_type, 'objects' ), array( 'show_in_rest' => true ) );
if ( ! $taxonomies ) {
return $query_params;
}
$query_params['tax_relation'] = array(
'description' => __( 'Limit result set based on relationship between multiple taxonomies.' ),
'type' => 'string',
'enum' => array( 'AND', 'OR' ),
);
$limit_schema = array(
'type' => array( 'object', 'array' ),
'oneOf' => array(
array(
'title' => __( 'Term ID List' ),
'description' => __( 'Match terms with the listed IDs.' ),
'type' => 'array',
'items' => array(
'type' => 'integer',
),
),
array(
'title' => __( 'Term ID Taxonomy Query' ),
'description' => __( 'Perform an advanced term query.' ),
'type' => 'object',
'properties' => array(
'terms' => array(
'description' => __( 'Term IDs.' ),
'type' => 'array',
'items' => array(
'type' => 'integer',
),
'default' => array(),
),
'include_children' => array(
'description' => __( 'Whether to include child terms in the terms limiting the result set.' ),
'type' => 'boolean',
'default' => false,
),
),
'additionalProperties' => false,
),
),
);
$include_schema = array_merge(
array(
/* translators: %s: Taxonomy name. */
'description' => __( 'Limit result set to items with specific terms assigned in the %s taxonomy.' ),
),
$limit_schema
);
// 'operator' is supported only for 'include' queries.
$include_schema['oneOf'][1]['properties']['operator'] = array(
'description' => __( 'Whether items must be assigned all or any of the specified terms.' ),
'type' => 'string',
'enum' => array( 'AND', 'OR' ),
'default' => 'OR',
);
$exclude_schema = array_merge(
array(
/* translators: %s: Taxonomy name. */
'description' => __( 'Limit result set to items except those with specific terms assigned in the %s taxonomy.' ),
),
$limit_schema
);
foreach ( $taxonomies as $taxonomy ) {
$base = ! empty( $taxonomy->rest_base ) ? $taxonomy->rest_base : $taxonomy->name;
$base_exclude = $base . '_exclude';
$query_params[ $base ] = $include_schema;
$query_params[ $base ]['description'] = sprintf( $query_params[ $base ]['description'], $base );
$query_params[ $base_exclude ] = $exclude_schema;
$query_params[ $base_exclude ]['description'] = sprintf( $query_params[ $base_exclude ]['description'], $base );
if ( ! $taxonomy->hierarchical ) {
unset( $query_params[ $base ]['oneOf'][1]['properties']['include_children'] );
unset( $query_params[ $base_exclude ]['oneOf'][1]['properties']['include_children'] );
}
}
return $query_params;
}
}