$separator,
'link' => $link,
'format' => $format,
);
return get_term_parents_list( $category_id, 'category', $args );
}
/**
* Retrieves post categories.
*
* This tag may be used outside The Loop by passing a post ID as the parameter.
*
* Note: This function only returns results from the default "category" taxonomy.
* For custom taxonomies use get_the_terms().
*
* @since 0.71
*
* @param int $post_id Optional. The post ID. Defaults to current post ID.
* @return WP_Term[] Array of WP_Term objects, one for each category assigned to the post.
*/
function get_the_category( $post_id = false ) {
$categories = get_the_terms( $post_id, 'category' );
if ( ! $categories || is_wp_error( $categories ) ) {
$categories = array();
}
$categories = array_values( $categories );
foreach ( array_keys( $categories ) as $key ) {
_make_cat_compat( $categories[ $key ] );
}
/**
* Filters the array of categories to return for a post.
*
* @since 3.1.0
* @since 4.4.0 Added the `$post_id` parameter.
*
* @param WP_Term[] $categories An array of categories to return for the post.
* @param int|false $post_id The post ID.
*/
return apply_filters( 'get_the_categories', $categories, $post_id );
}
/**
* Retrieves category name based on category ID.
*
* @since 0.71
*
* @param int $cat_id Category ID.
* @return string|WP_Error Category name on success, WP_Error on failure.
*/
function get_the_category_by_ID( $cat_id ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionNameInvalid
$cat_id = (int) $cat_id;
$category = get_term( $cat_id );
if ( is_wp_error( $category ) ) {
return $category;
}
return ( $category ) ? $category->name : '';
}
/**
* Retrieves category list for a post in either HTML list or custom format.
*
* Generally used for quick, delimited (e.g. comma-separated) lists of categories,
* as part of a post entry meta.
*
* For a more powerful, list-based function, see wp_list_categories().
*
* @since 1.5.1
*
* @see wp_list_categories()
*
* @global WP_Rewrite $wp_rewrite WordPress rewrite component.
*
* @param string $separator Optional. Separator between the categories. By default, the links are placed
* in an unordered list. An empty string will result in the default behavior.
* @param string $parents Optional. How to display the parents. Accepts 'multiple', 'single', or empty.
* Default empty string.
* @param int $post_id Optional. ID of the post to retrieve categories for. Defaults to the current post.
* @return string Category list for a post.
*/
function get_the_category_list( $separator = '', $parents = '', $post_id = false ) {
global $wp_rewrite;
if ( ! is_object_in_taxonomy( get_post_type( $post_id ), 'category' ) ) {
/** This filter is documented in wp-includes/category-template.php */
return apply_filters( 'the_category', '', $separator, $parents );
}
/**
* Filters the categories before building the category list.
*
* @since 4.4.0
*
* @param WP_Term[] $categories An array of the post's categories.
* @param int|false $post_id ID of the post to retrieve categories for.
* When `false`, defaults to the current post in the loop.
*/
$categories = apply_filters( 'the_category_list', get_the_category( $post_id ), $post_id );
if ( empty( $categories ) ) {
/** This filter is documented in wp-includes/category-template.php */
return apply_filters( 'the_category', __( 'Uncategorized' ), $separator, $parents );
}
$rel = ( is_object( $wp_rewrite ) && $wp_rewrite->using_permalinks() ) ? 'rel="category tag"' : 'rel="category"';
$thelist = '';
if ( '' === $separator ) {
$thelist .= '';
foreach ( $categories as $category ) {
$thelist .= "\n\t";
switch ( strtolower( $parents ) ) {
case 'multiple':
if ( $category->parent ) {
$thelist .= get_category_parents( $category->parent, true, $separator );
}
$thelist .= '' . $category->name . ' ';
break;
case 'single':
$thelist .= '';
if ( $category->parent ) {
$thelist .= get_category_parents( $category->parent, false, $separator );
}
$thelist .= $category->name . ' ';
break;
case '':
default:
$thelist .= '' . $category->name . ' ';
}
}
$thelist .= ' ';
} else {
$i = 0;
foreach ( $categories as $category ) {
if ( 0 < $i ) {
$thelist .= $separator;
}
switch ( strtolower( $parents ) ) {
case 'multiple':
if ( $category->parent ) {
$thelist .= get_category_parents( $category->parent, true, $separator );
}
$thelist .= '' . $category->name . ' ';
break;
case 'single':
$thelist .= '';
if ( $category->parent ) {
$thelist .= get_category_parents( $category->parent, false, $separator );
}
$thelist .= "$category->name ";
break;
case '':
default:
$thelist .= '' . $category->name . ' ';
}
++$i;
}
}
/**
* Filters the category or list of categories.
*
* @since 1.2.0
*
* @param string $thelist List of categories for the current post.
* @param string $separator Separator used between the categories.
* @param string $parents How to display the category parents. Accepts 'multiple',
* 'single', or empty.
*/
return apply_filters( 'the_category', $thelist, $separator, $parents );
}
/**
* Checks if the current post is within any of the given categories.
*
* The given categories are checked against the post's categories' term_ids, names and slugs.
* Categories given as integers will only be checked against the post's categories' term_ids.
*
* Prior to v2.5 of WordPress, category names were not supported.
* Prior to v2.7, category slugs were not supported.
* Prior to v2.7, only one category could be compared: in_category( $single_category ).
* Prior to v2.7, this function could only be used in the WordPress Loop.
* As of 2.7, the function can be used anywhere if it is provided a post ID or post object.
*
* 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 1.2.0
* @since 2.7.0 The `$post` parameter was added.
*
* @param int|string|int[]|string[] $category Category ID, name, slug, or array of such
* to check against.
* @param int|WP_Post $post Optional. Post to check. Defaults to the current post.
* @return bool True if the current post is in any of the given categories.
*/
function in_category( $category, $post = null ) {
if ( empty( $category ) ) {
return false;
}
return has_category( $category, $post );
}
/**
* Displays category list for a post in either HTML list or custom format.
*
* @since 0.71
*
* @param string $separator Optional. Separator between the categories. By default, the links are placed
* in an unordered list. An empty string will result in the default behavior.
* @param string $parents Optional. How to display the parents. Accepts 'multiple', 'single', or empty.
* Default empty string.
* @param int $post_id Optional. ID of the post to retrieve categories for. Defaults to the current post.
*/
function the_category( $separator = '', $parents = '', $post_id = false ) {
echo get_the_category_list( $separator, $parents, $post_id );
}
/**
* Retrieves category description.
*
* @since 1.0.0
*
* @param int $category Optional. Category ID. Defaults to the current category ID.
* @return string Category description, if available.
*/
function category_description( $category = 0 ) {
return term_description( $category );
}
/**
* Displays or retrieves the HTML dropdown list of categories.
*
* The 'hierarchical' argument, which is disabled by default, will override the
* depth argument, unless it is true. When the argument is false, it will
* display all of the categories. When it is enabled it will use the value in
* the 'depth' argument.
*
* @since 2.1.0
* @since 4.2.0 Introduced the `value_field` argument.
* @since 4.6.0 Introduced the `required` argument.
* @since 6.1.0 Introduced the `aria_describedby` argument.
*
* @param array|string $args {
* Optional. Array or string of arguments to generate a categories drop-down element. See WP_Term_Query::__construct()
* for information on additional accepted arguments.
*
* @type string $show_option_all Text to display for showing all categories. Default empty.
* @type string $show_option_none Text to display for showing no categories. Default empty.
* @type string $option_none_value Value to use when no category is selected. Default empty.
* @type string $orderby Which column to use for ordering categories. See get_terms() for a list
* of accepted values. Default 'id' (term_id).
* @type bool $pad_counts See get_terms() for an argument description. Default false.
* @type bool|int $show_count Whether to include post counts. Accepts 0, 1, or their bool equivalents.
* Default 0.
* @type bool|int $echo Whether to echo or return the generated markup. Accepts 0, 1, or their
* bool equivalents. Default 1.
* @type bool|int $hierarchical Whether to traverse the taxonomy hierarchy. Accepts 0, 1, or their bool
* equivalents. Default 0.
* @type int $depth Maximum depth. Default 0.
* @type int $tab_index Tab index for the select element. Default 0 (no tabindex).
* @type string $name Value for the 'name' attribute of the select element. Default 'cat'.
* @type string $id Value for the 'id' attribute of the select element. Defaults to the value
* of `$name`.
* @type string $class Value for the 'class' attribute of the select element. Default 'postform'.
* @type int|string $selected Value of the option that should be selected. Default 0.
* @type string $value_field Term field that should be used to populate the 'value' attribute
* of the option elements. Accepts any valid term field: 'term_id', 'name',
* 'slug', 'term_group', 'term_taxonomy_id', 'taxonomy', 'description',
* 'parent', 'count'. Default 'term_id'.
* @type string|array $taxonomy Name of the taxonomy or taxonomies to retrieve. Default 'category'.
* @type bool $hide_if_empty True to skip generating markup if no categories are found.
* Default false (create select element even if no categories are found).
* @type bool $required Whether the `` element should have the HTML5 'required' attribute.
* Default false.
* @type Walker $walker Walker object to use to build the output. Default empty which results in a
* Walker_CategoryDropdown instance being used.
* @type string $aria_describedby The 'id' of an element that contains descriptive text for the select.
* Default empty string.
* }
* @return string HTML dropdown list of categories.
*/
function wp_dropdown_categories( $args = '' ) {
$defaults = array(
'show_option_all' => '',
'show_option_none' => '',
'orderby' => 'id',
'order' => 'ASC',
'show_count' => 0,
'hide_empty' => 1,
'child_of' => 0,
'exclude' => '',
'echo' => 1,
'selected' => 0,
'hierarchical' => 0,
'name' => 'cat',
'id' => '',
'class' => 'postform',
'depth' => 0,
'tab_index' => 0,
'taxonomy' => 'category',
'hide_if_empty' => false,
'option_none_value' => -1,
'value_field' => 'term_id',
'required' => false,
'aria_describedby' => '',
);
$defaults['selected'] = ( is_category() ) ? get_query_var( 'cat' ) : 0;
// Back compat.
if ( isset( $args['type'] ) && 'link' === $args['type'] ) {
_deprecated_argument(
__FUNCTION__,
'3.0.0',
sprintf(
/* translators: 1: "type => link", 2: "taxonomy => link_category" */
__( '%1$s is deprecated. Use %2$s instead.' ),
'type => link',
'taxonomy => link_category'
)
);
$args['taxonomy'] = 'link_category';
}
// Parse incoming $args into an array and merge it with $defaults.
$parsed_args = wp_parse_args( $args, $defaults );
$option_none_value = $parsed_args['option_none_value'];
if ( ! isset( $parsed_args['pad_counts'] ) && $parsed_args['show_count'] && $parsed_args['hierarchical'] ) {
$parsed_args['pad_counts'] = true;
}
$tab_index = $parsed_args['tab_index'];
$tab_index_attribute = '';
if ( (int) $tab_index > 0 ) {
$tab_index_attribute = " tabindex=\"$tab_index\"";
}
// Avoid clashes with the 'name' param of get_terms().
$get_terms_args = $parsed_args;
unset( $get_terms_args['name'] );
$categories = get_terms( $get_terms_args );
$name = esc_attr( $parsed_args['name'] );
$class = esc_attr( $parsed_args['class'] );
$id = $parsed_args['id'] ? esc_attr( $parsed_args['id'] ) : $name;
$required = $parsed_args['required'] ? 'required' : '';
$aria_describedby_attribute = $parsed_args['aria_describedby'] ? ' aria-describedby="' . esc_attr( $parsed_args['aria_describedby'] ) . '"' : '';
if ( ! $parsed_args['hide_if_empty'] || ! empty( $categories ) ) {
$output = "\n";
} else {
$output = '';
}
if ( empty( $categories ) && ! $parsed_args['hide_if_empty'] && ! empty( $parsed_args['show_option_none'] ) ) {
/**
* Filters a taxonomy drop-down display element.
*
* A variety of taxonomy drop-down display elements can be modified
* just prior to display via this filter. Filterable arguments include
* 'show_option_none', 'show_option_all', and various forms of the
* term name.
*
* @since 1.2.0
*
* @see wp_dropdown_categories()
*
* @param string $element Category name.
* @param WP_Term|null $category The category object, or null if there's no corresponding category.
*/
$show_option_none = apply_filters( 'list_cats', $parsed_args['show_option_none'], null );
$output .= "\t$show_option_none \n";
}
if ( ! empty( $categories ) ) {
if ( $parsed_args['show_option_all'] ) {
/** This filter is documented in wp-includes/category-template.php */
$show_option_all = apply_filters( 'list_cats', $parsed_args['show_option_all'], null );
$selected = ( '0' === (string) $parsed_args['selected'] ) ? " selected='selected'" : '';
$output .= "\t$show_option_all \n";
}
if ( $parsed_args['show_option_none'] ) {
/** This filter is documented in wp-includes/category-template.php */
$show_option_none = apply_filters( 'list_cats', $parsed_args['show_option_none'], null );
$selected = selected( $option_none_value, $parsed_args['selected'], false );
$output .= "\t$show_option_none \n";
}
if ( $parsed_args['hierarchical'] ) {
$depth = $parsed_args['depth']; // Walk the full depth.
} else {
$depth = -1; // Flat.
}
$output .= walk_category_dropdown_tree( $categories, $depth, $parsed_args );
}
if ( ! $parsed_args['hide_if_empty'] || ! empty( $categories ) ) {
$output .= " \n";
}
/**
* Filters the taxonomy drop-down output.
*
* @since 2.1.0
*
* @param string $output HTML output.
* @param array $parsed_args Arguments used to build the drop-down.
*/
$output = apply_filters( 'wp_dropdown_cats', $output, $parsed_args );
if ( $parsed_args['echo'] ) {
echo $output;
}
return $output;
}
/**
* Displays or retrieves the HTML list of categories.
*
* @since 2.1.0
* @since 4.4.0 Introduced the `hide_title_if_empty` and `separator` arguments.
* @since 4.4.0 The `current_category` argument was modified to optionally accept an array of values.
* @since 6.1.0 Default value of the 'use_desc_for_title' argument was changed from 1 to 0.
*
* @param array|string $args {
* Array of optional arguments. See get_categories(), get_terms(), and WP_Term_Query::__construct()
* for information on additional accepted arguments.
*
* @type int|int[] $current_category ID of category, or array of IDs of categories, that should get the
* 'current-cat' class. Default 0.
* @type int $depth Category depth. Used for tab indentation. Default 0.
* @type bool|int $echo Whether to echo or return the generated markup. Accepts 0, 1, or their
* bool equivalents. Default 1.
* @type int[]|string $exclude Array or comma/space-separated string of term IDs to exclude.
* If `$hierarchical` is true, descendants of `$exclude` terms will also
* be excluded; see `$exclude_tree`. See get_terms().
* Default empty string.
* @type int[]|string $exclude_tree Array or comma/space-separated string of term IDs to exclude, along
* with their descendants. See get_terms(). Default empty string.
* @type string $feed Text to use for the feed link. Default 'Feed for all posts filed
* under [cat name]'.
* @type string $feed_image URL of an image to use for the feed link. Default empty string.
* @type string $feed_type Feed type. Used to build feed link. See get_term_feed_link().
* Default empty string (default feed).
* @type bool $hide_title_if_empty Whether to hide the `$title_li` element if there are no terms in
* the list. Default false (title will always be shown).
* @type string $separator Separator between links. Default '` element. Pass an empty string
* to disable. Default 'Categories'.
* @type bool|int $use_desc_for_title Whether to use the category description as the title attribute.
* Accepts 0, 1, or their bool equivalents. Default 0.
* @type Walker $walker Walker object to use to build the output. Default empty which results
* in a Walker_Category instance being used.
* }
* @return void|string|false Void if 'echo' argument is true, HTML list of categories if 'echo' is false.
* False if the taxonomy does not exist.
*/
function wp_list_categories( $args = '' ) {
$defaults = array(
'child_of' => 0,
'current_category' => 0,
'depth' => 0,
'echo' => 1,
'exclude' => '',
'exclude_tree' => '',
'feed' => '',
'feed_image' => '',
'feed_type' => '',
'hide_empty' => 1,
'hide_title_if_empty' => false,
'hierarchical' => true,
'order' => 'ASC',
'orderby' => 'name',
'separator' => ' ' . $parsed_args['title_li'] . '';
}
if ( empty( $categories ) ) {
if ( ! empty( $show_option_none ) ) {
if ( 'list' === $parsed_args['style'] ) {
$output .= '' . $show_option_none . ' ';
} else {
$output .= $show_option_none;
}
}
} else {
if ( ! empty( $show_option_all ) ) {
$posts_page = '';
// For taxonomies that belong only to custom post types, point to a valid archive.
$taxonomy_object = get_taxonomy( $parsed_args['taxonomy'] );
if ( ! in_array( 'post', $taxonomy_object->object_type, true ) && ! in_array( 'page', $taxonomy_object->object_type, true ) ) {
foreach ( $taxonomy_object->object_type as $object_type ) {
$_object_type = get_post_type_object( $object_type );
// Grab the first one.
if ( ! empty( $_object_type->has_archive ) ) {
$posts_page = get_post_type_archive_link( $object_type );
break;
}
}
}
// Fallback for the 'All' link is the posts page.
if ( ! $posts_page ) {
if ( 'page' === get_option( 'show_on_front' ) && get_option( 'page_for_posts' ) ) {
$posts_page = get_permalink( get_option( 'page_for_posts' ) );
} else {
$posts_page = home_url( '/' );
}
}
$posts_page = esc_url( $posts_page );
if ( 'list' === $parsed_args['style'] ) {
$output .= "$show_option_all $show_option_all ";
}
}
if ( empty( $parsed_args['current_category'] ) && ( is_category() || is_tax() || is_tag() ) ) {
$current_term_object = get_queried_object();
if ( $current_term_object && $parsed_args['taxonomy'] === $current_term_object->taxonomy ) {
$parsed_args['current_category'] = get_queried_object_id();
}
}
if ( $parsed_args['hierarchical'] ) {
$depth = $parsed_args['depth'];
} else {
$depth = -1; // Flat.
}
$output .= walk_category_tree( $categories, $depth, $parsed_args );
}
if ( $parsed_args['title_li'] && 'list' === $parsed_args['style']
&& ( ! empty( $categories ) || ! $parsed_args['hide_title_if_empty'] )
) {
$output .= ' ';
}
/**
* Filters the HTML output of a taxonomy list.
*
* @since 2.1.0
*
* @param string $output HTML output.
* @param array|string $args An array or query string of taxonomy-listing arguments. See
* wp_list_categories() for information on accepted arguments.
*/
$html = apply_filters( 'wp_list_categories', $output, $args );
if ( $parsed_args['echo'] ) {
echo $html;
} else {
return $html;
}
}
/**
* Displays a tag cloud.
*
* Outputs a list of tags in what is called a 'tag cloud', where the size of each tag
* is determined by how many times that particular tag has been assigned to posts.
*
* @since 2.3.0
* @since 2.8.0 Added the `taxonomy` argument.
* @since 4.8.0 Added the `show_count` argument.
*
* @param array|string $args {
* Optional. Array or string of arguments for displaying a tag cloud. See wp_generate_tag_cloud()
* and get_terms() for the full lists of arguments that can be passed in `$args`.
*
* @type int $number The number of tags to display. Accepts any positive integer
* or zero to return all. Default 45.
* @type string $link Whether to display term editing links or term permalinks.
* Accepts 'edit' and 'view'. Default 'view'.
* @type string $post_type The post type. Used to highlight the proper post type menu
* on the linked edit page. Defaults to the first post type
* associated with the taxonomy.
* @type bool $echo Whether or not to echo the return value. Default true.
* }
* @return void|string|string[] Void if 'echo' argument is true, or on failure. Otherwise, tag cloud
* as a string or an array, depending on 'format' argument.
*/
function wp_tag_cloud( $args = '' ) {
$defaults = array(
'smallest' => 8,
'largest' => 22,
'unit' => 'pt',
'number' => 45,
'format' => 'flat',
'separator' => "\n",
'orderby' => 'name',
'order' => 'ASC',
'exclude' => '',
'include' => '',
'link' => 'view',
'taxonomy' => 'post_tag',
'post_type' => '',
'echo' => true,
'show_count' => 0,
);
$args = wp_parse_args( $args, $defaults );
$tags = get_terms(
array_merge(
$args,
array(
'orderby' => 'count',
'order' => 'DESC',
)
)
); // Always query top tags.
if ( empty( $tags ) || is_wp_error( $tags ) ) {
return;
}
foreach ( $tags as $key => $tag ) {
if ( 'edit' === $args['link'] ) {
$link = get_edit_term_link( $tag, $tag->taxonomy, $args['post_type'] );
} else {
$link = get_term_link( $tag, $tag->taxonomy );
}
if ( is_wp_error( $link ) ) {
return;
}
$tags[ $key ]->link = $link;
$tags[ $key ]->id = $tag->term_id;
}
// Here's where those top tags get sorted according to $args.
$return = wp_generate_tag_cloud( $tags, $args );
/**
* Filters the tag cloud output.
*
* @since 2.3.0
*
* @param string|string[] $return Tag cloud as a string or an array, depending on 'format' argument.
* @param array $args An array of tag cloud arguments. See wp_tag_cloud()
* for information on accepted arguments.
*/
$return = apply_filters( 'wp_tag_cloud', $return, $args );
if ( 'array' === $args['format'] || empty( $args['echo'] ) ) {
return $return;
}
echo $return;
}
/**
* Default topic count scaling for tag links.
*
* @since 2.9.0
*
* @param int $count Number of posts with that tag.
* @return int Scaled count.
*/
function default_topic_count_scale( $count ) {
return round( log10( $count + 1 ) * 100 );
}
/**
* Generates a tag cloud (heatmap) from provided data.
*
* @todo Complete functionality.
* @since 2.3.0
* @since 4.8.0 Added the `show_count` argument.
*
* @param WP_Term[] $tags Array of WP_Term objects to generate the tag cloud for.
* @param string|array $args {
* Optional. Array or string of arguments for generating a tag cloud.
*
* @type int $smallest Smallest font size used to display tags. Paired
* with the value of `$unit`, to determine CSS text
* size unit. Default 8 (pt).
* @type int $largest Largest font size used to display tags. Paired
* with the value of `$unit`, to determine CSS text
* size unit. Default 22 (pt).
* @type string $unit CSS text size unit to use with the `$smallest`
* and `$largest` values. Accepts any valid CSS text
* size unit. Default 'pt'.
* @type int $number The number of tags to return. Accepts any
* positive integer or zero to return all.
* Default 0.
* @type string $format Format to display the tag cloud in. Accepts 'flat'
* (tags separated with spaces), 'list' (tags displayed
* in an unordered list), or 'array' (returns an array).
* Default 'flat'.
* @type string $separator HTML or text to separate the tags. Default "\n" (newline).
* @type string $orderby Value to order tags by. Accepts 'name' or 'count'.
* Default 'name'. The {@see 'tag_cloud_sort'} filter
* can also affect how tags are sorted.
* @type string $order How to order the tags. Accepts 'ASC' (ascending),
* 'DESC' (descending), or 'RAND' (random). Default 'ASC'.
* @type int|bool $filter Whether to enable filtering of the final output
* via {@see 'wp_generate_tag_cloud'}. Default 1.
* @type array $topic_count_text Nooped plural text from _n_noop() to supply to
* tag counts. Default null.
* @type callable $topic_count_text_callback Callback used to generate nooped plural text for
* tag counts based on the count. Default null.
* @type callable $topic_count_scale_callback Callback used to determine the tag count scaling
* value. Default default_topic_count_scale().
* @type bool|int $show_count Whether to display the tag counts. Default 0. Accepts
* 0, 1, or their bool equivalents.
* }
* @return string|string[] Tag cloud as a string or an array, depending on 'format' argument.
*/
function wp_generate_tag_cloud( $tags, $args = '' ) {
$defaults = array(
'smallest' => 8,
'largest' => 22,
'unit' => 'pt',
'number' => 0,
'format' => 'flat',
'separator' => "\n",
'orderby' => 'name',
'order' => 'ASC',
'topic_count_text' => null,
'topic_count_text_callback' => null,
'topic_count_scale_callback' => 'default_topic_count_scale',
'filter' => 1,
'show_count' => 0,
);
$args = wp_parse_args( $args, $defaults );
$return = ( 'array' === $args['format'] ) ? array() : '';
if ( empty( $tags ) ) {
return $return;
}
// Juggle topic counts.
if ( isset( $args['topic_count_text'] ) ) {
// First look for nooped plural support via topic_count_text.
$translate_nooped_plural = $args['topic_count_text'];
} elseif ( ! empty( $args['topic_count_text_callback'] ) ) {
// Look for the alternative callback style. Ignore the previous default.
if ( 'default_topic_count_text' === $args['topic_count_text_callback'] ) {
/* translators: %s: Number of items (tags). */
$translate_nooped_plural = _n_noop( '%s item', '%s items' );
} else {
$translate_nooped_plural = false;
}
} elseif ( isset( $args['single_text'] ) && isset( $args['multiple_text'] ) ) {
// If no callback exists, look for the old-style single_text and multiple_text arguments.
// phpcs:ignore WordPress.WP.I18n.NonSingularStringLiteralSingular,WordPress.WP.I18n.NonSingularStringLiteralPlural
$translate_nooped_plural = _n_noop( $args['single_text'], $args['multiple_text'] );
} else {
// This is the default for when no callback, plural, or argument is passed in.
/* translators: %s: Number of items (tags). */
$translate_nooped_plural = _n_noop( '%s item', '%s items' );
}
/**
* Filters how the items in a tag cloud are sorted.
*
* @since 2.8.0
*
* @param WP_Term[] $tags Ordered array of terms.
* @param array $args An array of tag cloud arguments.
*/
$tags_sorted = apply_filters( 'tag_cloud_sort', $tags, $args );
if ( empty( $tags_sorted ) ) {
return $return;
}
if ( $tags_sorted !== $tags ) {
$tags = $tags_sorted;
unset( $tags_sorted );
} else {
if ( 'RAND' === $args['order'] ) {
shuffle( $tags );
} else {
// SQL cannot save you; this is a second (potentially different) sort on a subset of data.
if ( 'name' === $args['orderby'] ) {
uasort( $tags, '_wp_object_name_sort_cb' );
} else {
uasort( $tags, '_wp_object_count_sort_cb' );
}
if ( 'DESC' === $args['order'] ) {
$tags = array_reverse( $tags, true );
}
}
}
if ( $args['number'] > 0 ) {
$tags = array_slice( $tags, 0, $args['number'] );
}
$counts = array();
$real_counts = array(); // For the alt tag.
foreach ( (array) $tags as $key => $tag ) {
$real_counts[ $key ] = $tag->count;
$counts[ $key ] = call_user_func( $args['topic_count_scale_callback'], $tag->count );
}
$min_count = min( $counts );
$spread = max( $counts ) - $min_count;
if ( $spread <= 0 ) {
$spread = 1;
}
$font_spread = $args['largest'] - $args['smallest'];
if ( $font_spread < 0 ) {
$font_spread = 1;
}
$font_step = $font_spread / $spread;
$aria_label = false;
/*
* Determine whether to output an 'aria-label' attribute with the tag name and count.
* When tags have a different font size, they visually convey an important information
* that should be available to assistive technologies too. On the other hand, sometimes
* themes set up the Tag Cloud to display all tags with the same font size (setting
* the 'smallest' and 'largest' arguments to the same value).
* In order to always serve the same content to all users, the 'aria-label' gets printed out:
* - when tags have a different size
* - when the tag count is displayed (for example when users check the checkbox in the
* Tag Cloud widget), regardless of the tags font size
*/
if ( $args['show_count'] || 0 !== $font_spread ) {
$aria_label = true;
}
// Assemble the data that will be used to generate the tag cloud markup.
$tags_data = array();
foreach ( $tags as $key => $tag ) {
$tag_id = isset( $tag->id ) ? $tag->id : $key;
$count = $counts[ $key ];
$real_count = $real_counts[ $key ];
if ( $translate_nooped_plural ) {
$formatted_count = sprintf( translate_nooped_plural( $translate_nooped_plural, $real_count ), number_format_i18n( $real_count ) );
} else {
$formatted_count = call_user_func( $args['topic_count_text_callback'], $real_count, $tag, $args );
}
$tags_data[] = array(
'id' => $tag_id,
'url' => ( '#' !== $tag->link ) ? $tag->link : '#',
'role' => ( '#' !== $tag->link ) ? '' : ' role="button"',
'name' => $tag->name,
'formatted_count' => $formatted_count,
'slug' => $tag->slug,
'real_count' => $real_count,
'class' => 'tag-cloud-link tag-link-' . $tag_id,
'font_size' => $args['smallest'] + ( $count - $min_count ) * $font_step,
'aria_label' => $aria_label ? sprintf( ' aria-label="%1$s (%2$s)"', esc_attr( $tag->name ), esc_attr( $formatted_count ) ) : '',
'show_count' => $args['show_count'] ? ' (' . $real_count . ') ' : '',
);
}
/**
* Filters the data used to generate the tag cloud.
*
* @since 4.3.0
*
* @param array[] $tags_data An array of term data arrays for terms used to generate the tag cloud.
*/
$tags_data = apply_filters( 'wp_generate_tag_cloud_data', $tags_data );
$a = array();
// Generate the output links array.
foreach ( $tags_data as $key => $tag_data ) {
$class = $tag_data['class'] . ' tag-link-position-' . ( $key + 1 );
$a[] = sprintf(
'%6$s%7$s ',
esc_url( $tag_data['url'] ),
$tag_data['role'],
esc_attr( $class ),
esc_attr( str_replace( ',', '.', $tag_data['font_size'] ) . $args['unit'] ),
$tag_data['aria_label'],
esc_html( $tag_data['name'] ),
$tag_data['show_count']
);
}
switch ( $args['format'] ) {
case 'array':
$return =& $a;
break;
case 'list':
/*
* Force role="list", as some browsers (sic: Safari 10) don't expose to assistive
* technologies the default role when the list is styled with `list-style: none`.
* Note: this is redundant but doesn't harm.
*/
$return = "\n\t";
$return .= implode( " \n\t", $a );
$return .= " \n \n";
break;
default:
$return = implode( $args['separator'], $a );
break;
}
if ( $args['filter'] ) {
/**
* Filters the generated output of a tag cloud.
*
* The filter is only evaluated if a true value is passed
* to the $filter argument in wp_generate_tag_cloud().
*
* @since 2.3.0
*
* @see wp_generate_tag_cloud()
*
* @param string[]|string $return String containing the generated HTML tag cloud output
* or an array of tag links if the 'format' argument
* equals 'array'.
* @param WP_Term[] $tags An array of terms used in the tag cloud.
* @param array $args An array of wp_generate_tag_cloud() arguments.
*/
return apply_filters( 'wp_generate_tag_cloud', $return, $tags, $args );
} else {
return $return;
}
}
/**
* Serves as a callback for comparing objects based on name.
*
* Used with `uasort()`.
*
* @since 3.1.0
* @access private
*
* @param object $a The first object to compare.
* @param object $b The second object to compare.
* @return int Negative number if `$a->name` is less than `$b->name`, zero if they are equal,
* or greater than zero if `$a->name` is greater than `$b->name`.
*/
function _wp_object_name_sort_cb( $a, $b ) {
return strnatcasecmp( $a->name, $b->name );
}
/**
* Serves as a callback for comparing objects based on count.
*
* Used with `uasort()`.
*
* @since 3.1.0
* @access private
*
* @param object $a The first object to compare.
* @param object $b The second object to compare.
* @return int Negative number if `$a->count` is less than `$b->count`, zero if they are equal,
* or greater than zero if `$a->count` is greater than `$b->count`.
*/
function _wp_object_count_sort_cb( $a, $b ) {
return ( $a->count - $b->count );
}
//
// Helper functions.
//
/**
* Retrieves HTML list content for category list.
*
* @since 2.1.0
* @since 5.3.0 Formalized the existing `...$args` parameter by adding it
* to the function signature.
*
* @uses Walker_Category to create HTML list content.
* @see Walker::walk() for parameters and return description.
*
* @param mixed ...$args Elements array, maximum hierarchical depth and optional additional arguments.
* @return string
*/
function walk_category_tree( ...$args ) {
// The user's options are the third parameter.
if ( empty( $args[2]['walker'] ) || ! ( $args[2]['walker'] instanceof Walker ) ) {
$walker = new Walker_Category();
} else {
/**
* @var Walker $walker
*/
$walker = $args[2]['walker'];
}
return $walker->walk( ...$args );
}
/**
* Retrieves HTML dropdown (select) content for category list.
*
* @since 2.1.0
* @since 5.3.0 Formalized the existing `...$args` parameter by adding it
* to the function signature.
*
* @uses Walker_CategoryDropdown to create HTML dropdown content.
* @see Walker::walk() for parameters and return description.
*
* @param mixed ...$args Elements array, maximum hierarchical depth and optional additional arguments.
* @return string
*/
function walk_category_dropdown_tree( ...$args ) {
// The user's options are the third parameter.
if ( empty( $args[2]['walker'] ) || ! ( $args[2]['walker'] instanceof Walker ) ) {
$walker = new Walker_CategoryDropdown();
} else {
/**
* @var Walker $walker
*/
$walker = $args[2]['walker'];
}
return $walker->walk( ...$args );
}
//
// Tags.
//
/**
* Retrieves the link to the tag.
*
* @since 2.3.0
*
* @see get_term_link()
*
* @param int|object $tag Tag ID or object.
* @return string Link on success, empty string if tag does not exist.
*/
function get_tag_link( $tag ) {
return get_category_link( $tag );
}
/**
* Retrieves the tags for a post.
*
* @since 2.3.0
*
* @param int|WP_Post $post Post ID or object.
* @return WP_Term[]|false|WP_Error Array of WP_Term objects on success, false if there are no terms
* or the post does not exist, WP_Error on failure.
*/
function get_the_tags( $post = 0 ) {
$terms = get_the_terms( $post, 'post_tag' );
/**
* Filters the array of tags for the given post.
*
* @since 2.3.0
*
* @see get_the_terms()
*
* @param WP_Term[]|false|WP_Error $terms Array of WP_Term objects on success, false if there are no terms
* or the post does not exist, WP_Error on failure.
*/
return apply_filters( 'get_the_tags', $terms );
}
/**
* Retrieves the tags for a post formatted as a string.
*
* @since 2.3.0
*
* @param string $before Optional. String to use before the tags. Default empty.
* @param string $sep Optional. String to use between the tags. Default empty.
* @param string $after Optional. String to use after the tags. Default empty.
* @param int $post_id Optional. Post ID. Defaults to the current post ID.
* @return string|false|WP_Error A list of tags on success, false if there are no terms,
* WP_Error on failure.
*/
function get_the_tag_list( $before = '', $sep = '', $after = '', $post_id = 0 ) {
$tag_list = get_the_term_list( $post_id, 'post_tag', $before, $sep, $after );
/**
* Filters the tags list for a given post.
*
* @since 2.3.0
*
* @param string $tag_list List of tags.
* @param string $before String to use before the tags.
* @param string $sep String to use between the tags.
* @param string $after String to use after the tags.
* @param int $post_id Post ID.
*/
return apply_filters( 'the_tags', $tag_list, $before, $sep, $after, $post_id );
}
/**
* Displays the tags for a post.
*
* @since 2.3.0
*
* @param string $before Optional. String to use before the tags. Defaults to 'Tags:'.
* @param string $sep Optional. String to use between the tags. Default ', '.
* @param string $after Optional. String to use after the tags. Default empty.
*/
function the_tags( $before = null, $sep = ', ', $after = '' ) {
if ( null === $before ) {
$before = __( 'Tags: ' );
}
$the_tags = get_the_tag_list( $before, $sep, $after );
if ( ! is_wp_error( $the_tags ) ) {
echo $the_tags;
}
}
/**
* Retrieves tag description.
*
* @since 2.8.0
*
* @param int $tag Optional. Tag ID. Defaults to the current tag ID.
* @return string Tag description, if available.
*/
function tag_description( $tag = 0 ) {
return term_description( $tag );
}
/**
* Retrieves term description.
*
* @since 2.8.0
* @since 4.9.2 The `$taxonomy` parameter was deprecated.
*
* @param int $term Optional. Term ID. Defaults to the current term ID.
* @param null $deprecated Deprecated. Not used.
* @return string Term description, if available.
*/
function term_description( $term = 0, $deprecated = null ) {
if ( ! $term && ( is_tax() || is_tag() || is_category() ) ) {
$term = get_queried_object();
if ( $term ) {
$term = $term->term_id;
}
}
$description = get_term_field( 'description', $term );
return is_wp_error( $description ) ? '' : $description;
}
/**
* Retrieves the terms of the taxonomy that are attached to the post.
*
* @since 2.5.0
*
* @param int|WP_Post $post Post ID or object.
* @param string $taxonomy Taxonomy name.
* @return WP_Term[]|false|WP_Error Array of WP_Term objects on success, false if there are no terms
* or the post does not exist, WP_Error on failure.
*/
function get_the_terms( $post, $taxonomy ) {
$post = get_post( $post );
if ( ! $post ) {
return false;
}
$terms = get_object_term_cache( $post->ID, $taxonomy );
if ( false === $terms ) {
$terms = wp_get_object_terms( $post->ID, $taxonomy );
if ( ! is_wp_error( $terms ) ) {
$term_ids = wp_list_pluck( $terms, 'term_id' );
wp_cache_add( $post->ID, $term_ids, $taxonomy . '_relationships' );
}
}
/**
* Filters the list of terms attached to the given post.
*
* @since 3.1.0
*
* @param WP_Term[]|WP_Error $terms Array of attached terms, or WP_Error on failure.
* @param int $post_id Post ID.
* @param string $taxonomy Name of the taxonomy.
*/
$terms = apply_filters( 'get_the_terms', $terms, $post->ID, $taxonomy );
if ( empty( $terms ) ) {
return false;
}
return $terms;
}
/**
* Retrieves a post's terms as a list with specified format.
*
* Terms are linked to their respective term listing pages.
*
* @since 2.5.0
*
* @param int $post_id Post ID.
* @param string $taxonomy Taxonomy name.
* @param string $before Optional. String to use before the terms. Default empty.
* @param string $sep Optional. String to use between the terms. Default empty.
* @param string $after Optional. String to use after the terms. Default empty.
* @return string|false|WP_Error A list of terms on success, false if there are no terms,
* WP_Error on failure.
*/
function get_the_term_list( $post_id, $taxonomy, $before = '', $sep = '', $after = '' ) {
$terms = get_the_terms( $post_id, $taxonomy );
if ( is_wp_error( $terms ) ) {
return $terms;
}
if ( empty( $terms ) ) {
return false;
}
$links = array();
foreach ( $terms as $term ) {
$link = get_term_link( $term, $taxonomy );
if ( is_wp_error( $link ) ) {
return $link;
}
$links[] = '' . $term->name . ' ';
}
/**
* Filters the term links for a given taxonomy.
*
* The dynamic portion of the hook name, `$taxonomy`, refers
* to the taxonomy slug.
*
* Possible hook names include:
*
* - `term_links-category`
* - `term_links-post_tag`
* - `term_links-post_format`
*
* @since 2.5.0
*
* @param string[] $links An array of term links.
*/
$term_links = apply_filters( "term_links-{$taxonomy}", $links ); // phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores
return $before . implode( $sep, $term_links ) . $after;
}
/**
* Retrieves term parents with separator.
*
* @since 4.8.0
*
* @param int $term_id Term ID.
* @param string $taxonomy Taxonomy name.
* @param string|array $args {
* Array of optional arguments.
*
* @type string $format Use term names or slugs for display. Accepts 'name' or 'slug'.
* Default 'name'.
* @type string $separator Separator for between the terms. Default '/'.
* @type bool $link Whether to format as a link. Default true.
* @type bool $inclusive Include the term to get the parents for. Default true.
* }
* @return string|WP_Error A list of term parents on success, WP_Error or empty string on failure.
*/
function get_term_parents_list( $term_id, $taxonomy, $args = array() ) {
$list = '';
$term = get_term( $term_id, $taxonomy );
if ( is_wp_error( $term ) ) {
return $term;
}
if ( ! $term ) {
return $list;
}
$term_id = $term->term_id;
$defaults = array(
'format' => 'name',
'separator' => '/',
'link' => true,
'inclusive' => true,
);
$args = wp_parse_args( $args, $defaults );
foreach ( array( 'link', 'inclusive' ) as $bool ) {
$args[ $bool ] = wp_validate_boolean( $args[ $bool ] );
}
$parents = get_ancestors( $term_id, $taxonomy, 'taxonomy' );
if ( $args['inclusive'] ) {
array_unshift( $parents, $term_id );
}
foreach ( array_reverse( $parents ) as $term_id ) {
$parent = get_term( $term_id, $taxonomy );
$name = ( 'slug' === $args['format'] ) ? $parent->slug : $parent->name;
if ( $args['link'] ) {
$list .= '' . $name . ' ' . $args['separator'];
} else {
$list .= $name . $args['separator'];
}
}
return $list;
}
/**
* Displays the terms for a post in a list.
*
* @since 2.5.0
*
* @param int $post_id Post ID.
* @param string $taxonomy Taxonomy name.
* @param string $before Optional. String to use before the terms. Default empty.
* @param string $sep Optional. String to use between the terms. Default ', '.
* @param string $after Optional. String to use after the terms. Default empty.
* @return void|false Void on success, false on failure.
*/
function the_terms( $post_id, $taxonomy, $before = '', $sep = ', ', $after = '' ) {
$term_list = get_the_term_list( $post_id, $taxonomy, $before, $sep, $after );
if ( is_wp_error( $term_list ) ) {
return false;
}
/**
* Filters the list of terms to display.
*
* @since 2.9.0
*
* @param string $term_list List of terms to display.
* @param string $taxonomy The taxonomy name.
* @param string $before String to use before the terms.
* @param string $sep String to use between the terms.
* @param string $after String to use after the terms.
*/
echo apply_filters( 'the_terms', $term_list, $taxonomy, $before, $sep, $after );
}
/**
* Checks if the current post has any of given category.
*
* The given categories are checked against the post's categories' term_ids, names and slugs.
* Categories given as integers will only be checked against the post's categories' term_ids.
*
* If no categories are given, determines if post has any categories.
*
* @since 3.1.0
*
* @param string|int|array $category Optional. The category name/term_id/slug,
* or an array of them to check for. Default empty.
* @param int|WP_Post $post Optional. Post to check. Defaults to the current post.
* @return bool True if the current post has any of the given categories
* (or any category, if no category specified). False otherwise.
*/
function has_category( $category = '', $post = null ) {
return has_term( $category, 'category', $post );
}
/**
* Checks if the current post has any of given tags.
*
* The given tags are checked against the post's tags' term_ids, names and slugs.
* Tags given as integers will only be checked against the post's tags' term_ids.
*
* If no tags are given, determines if post has any tags.
*
* 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.6.0
* @since 2.7.0 Tags given as integers are only checked against
* the post's tags' term_ids, not names or slugs.
* @since 2.7.0 Can be used outside of the WordPress Loop if `$post` is provided.
*
* @param string|int|array $tag Optional. The tag name/term_id/slug,
* or an array of them to check for. Default empty.
* @param int|WP_Post $post Optional. Post to check. Defaults to the current post.
* @return bool True if the current post has any of the given tags
* (or any tag, if no tag specified). False otherwise.
*/
function has_tag( $tag = '', $post = null ) {
return has_term( $tag, 'post_tag', $post );
}
/**
* Checks if the current post has any of given terms.
*
* The given terms are checked against the post's terms' term_ids, names and slugs.
* Terms given as integers will only be checked against the post's terms' term_ids.
*
* If no terms are given, determines if post has any terms.
*
* @since 3.1.0
*
* @param string|int|array $term Optional. The term name/term_id/slug,
* or an array of them to check for. Default empty.
* @param string $taxonomy Optional. Taxonomy name. Default empty.
* @param int|WP_Post 'menu_item_parent',
'id' => 'db_id',
);
/**
* Starts the list before the elements are added.
*
* @since 3.0.0
*
* @see Walker::start_lvl()
*
* @param string $output Used to append additional content (passed by reference).
* @param int $depth Depth of menu item. Used for padding.
* @param stdClass $args An object of wp_nav_menu() arguments.
*/
public function start_lvl( &$output, $depth = 0, $args = null ) {
if ( isset( $args->item_spacing ) && 'discard' === $args->item_spacing ) {
$t = '';
$n = '';
} else {
$t = "\t";
$n = "\n";
}
$indent = str_repeat( $t, $depth );
// Default class.
$classes = array( 'sub-menu' );
/**
* Filters the CSS class(es) applied to a menu list element.
*
* @since 4.8.0
*
* @param string[] $classes Array of the CSS classes that are applied to the menu `` element.
* @param stdClass $args An object of `wp_nav_menu()` arguments.
* @param int $depth Depth of menu item. Used for padding.
*/
$class_names = implode( ' ', apply_filters( 'nav_menu_submenu_css_class', $classes, $args, $depth ) );
$atts = array();
$atts['class'] = ! empty( $class_names ) ? $class_names : '';
/**
* Filters the HTML attributes applied to a menu list element.
*
* @since 6.3.0
*
* @param array $atts {
* The HTML attributes applied to the `` element, empty strings are ignored.
*
* @type string $class HTML CSS class attribute.
* }
* @param stdClass $args An object of `wp_nav_menu()` arguments.
* @param int $depth Depth of menu item. Used for padding.
*/
$atts = apply_filters( 'nav_menu_submenu_attributes', $atts, $args, $depth );
$attributes = $this->build_atts( $atts );
$output .= "{$n}{$indent}{$n}";
}
/**
* Ends the list of after the elements are added.
*
* @since 3.0.0
*
* @see Walker::end_lvl()
*
* @param string $output Used to append additional content (passed by reference).
* @param int $depth Depth of menu item. Used for padding.
* @param stdClass $args An object of wp_nav_menu() arguments.
*/
public function end_lvl( &$output, $depth = 0, $args = null ) {
if ( isset( $args->item_spacing ) && 'discard' === $args->item_spacing ) {
$t = '';
$n = '';
} else {
$t = "\t";
$n = "\n";
}
$indent = str_repeat( $t, $depth );
$output .= "$indent {$n}";
}
/**
* Starts the element output.
*
* @since 3.0.0
* @since 4.4.0 The {@see 'nav_menu_item_args'} filter was added.
* @since 5.9.0 Renamed `$item` to `$data_object` and `$id` to `$current_object_id`
* to match parent class for PHP 8 named parameter support.
*
* @see Walker::start_el()
*
* @param string $output Used to append additional content (passed by reference).
* @param WP_Post $data_object Menu item data object.
* @param int $depth Depth of menu item. Used for padding.
* @param stdClass $args An object of wp_nav_menu() arguments.
* @param int $current_object_id Optional. ID of the current menu item. Default 0.
*/
public function start_el( &$output, $data_object, $depth = 0, $args = null, $current_object_id = 0 ) {
// Restores the more descriptive, specific name for use within this method.
$menu_item = $data_object;
if ( isset( $args->item_spacing ) && 'discard' === $args->item_spacing ) {
$t = '';
$n = '';
} else {
$t = "\t";
$n = "\n";
}
$indent = ( $depth ) ? str_repeat( $t, $depth ) : '';
$classes = empty( $menu_item->classes ) ? array() : (array) $menu_item->classes;
$classes[] = 'menu-item-' . $menu_item->ID;
/**
* Filters the arguments for a single nav menu item.
*
* @since 4.4.0
*
* @param stdClass $args An object of wp_nav_menu() arguments.
* @param WP_Post $menu_item Menu item data object.
* @param int $depth Depth of menu item. Used for padding.
*/
$args = apply_filters( 'nav_menu_item_args', $args, $menu_item, $depth );
/**
* Filters the CSS classes applied to a menu item's list item element.
*
* @since 3.0.0
* @since 4.1.0 The `$depth` parameter was added.
*
* @param string[] $classes Array of the CSS classes that are applied to the menu item's `` element.
* @param WP_Post $menu_item The current menu item object.
* @param stdClass $args An object of wp_nav_menu() arguments.
* @param int $depth Depth of menu item. Used for padding.
*/
$class_names = implode( ' ', apply_filters( 'nav_menu_css_class', array_filter( $classes ), $menu_item, $args, $depth ) );
/**
* Filters the ID attribute applied to a menu item's list item element.
*
* @since 3.0.1
* @since 4.1.0 The `$depth` parameter was added.
*
* @param string $menu_item_id The ID attribute applied to the menu item's ` ` element.
* @param WP_Post $menu_item The current menu item.
* @param stdClass $args An object of wp_nav_menu() arguments.
* @param int $depth Depth of menu item. Used for padding.
*/
$id = apply_filters( 'nav_menu_item_id', 'menu-item-' . $menu_item->ID, $menu_item, $args, $depth );
$li_atts = array();
$li_atts['id'] = ! empty( $id ) ? $id : '';
$li_atts['class'] = ! empty( $class_names ) ? $class_names : '';
/**
* Filters the HTML attributes applied to a menu's list item element.
*
* @since 6.3.0
*
* @param array $li_atts {
* The HTML attributes applied to the menu item's ` ` element, empty strings are ignored.
*
* @type string $class HTML CSS class attribute.
* @type string $id HTML id attribute.
* }
* @param WP_Post $menu_item The current menu item object.
* @param stdClass $args An object of wp_nav_menu() arguments.
* @param int $depth Depth of menu item. Used for padding.
*/
$li_atts = apply_filters( 'nav_menu_item_attributes', $li_atts, $menu_item, $args, $depth );
$li_attributes = $this->build_atts( $li_atts );
$output .= $indent . '';
$atts = array();
$atts['title'] = ! empty( $menu_item->attr_title ) ? $menu_item->attr_title : '';
$atts['target'] = ! empty( $menu_item->target ) ? $menu_item->target : '';
if ( '_blank' === $menu_item->target && empty( $menu_item->xfn ) ) {
$atts['rel'] = 'noopener';
} else {
$atts['rel'] = $menu_item->xfn;
}
if ( ! empty( $menu_item->url ) ) {
if ( get_privacy_policy_url() === $menu_item->url ) {
$atts['rel'] = empty( $atts['rel'] ) ? 'privacy-policy' : $atts['rel'] . ' privacy-policy';
}
$atts['href'] = $menu_item->url;
} else {
$atts['href'] = '';
}
$atts['aria-current'] = $menu_item->current ? 'page' : '';
/**
* Filters the HTML attributes applied to a menu item's anchor element.
*
* @since 3.6.0
* @since 4.1.0 The `$depth` parameter was added.
*
* @param array $atts {
* The HTML attributes applied to the menu item's `` element, empty strings are ignored.
*
* @type string $title Title attribute.
* @type string $target Target attribute.
* @type string $rel The rel attribute.
* @type string $href The href attribute.
* @type string $aria-current The aria-current attribute.
* }
* @param WP_Post $menu_item The current menu item object.
* @param stdClass $args An object of wp_nav_menu() arguments.
* @param int $depth Depth of menu item. Used for padding.
*/
$atts = apply_filters( 'nav_menu_link_attributes', $atts, $menu_item, $args, $depth );
$attributes = $this->build_atts( $atts );
/** This filter is documented in wp-includes/post-template.php */
$title = apply_filters( 'the_title', $menu_item->title, $menu_item->ID );
/**
* Filters a menu item's title.
*
* @since 4.4.0
*
* @param string $title The menu item's title.
* @param WP_Post $menu_item The current menu item object.
* @param stdClass $args An object of wp_nav_menu() arguments.
* @param int $depth Depth of menu item. Used for padding.
*/
$title = apply_filters( 'nav_menu_item_title', $title, $menu_item, $args, $depth );
$item_output = $args->before;
$item_output .= '';
$item_output .= $args->link_before . $title . $args->link_after;
$item_output .= ' ';
$item_output .= $args->after;
/**
* Filters a menu item's starting output.
*
* The menu item's starting output only includes `$args->before`, the opening ``,
* the menu item's title, the closing ` `, and `$args->after`. Currently, there is
* no filter for modifying the opening and closing `` for a menu item.
*
* @since 3.0taxonomy ) &&
'nav_menu' === $menu_obj->taxonomy
) {
return true;
}
return false;
}
/**
* Registers navigation menu locations for a theme.
*
* @since 3.0.0
*
* @global array $_wp_registered_nav_menus
*
* @param string[] $locations Associative array of menu location identifiers (like a slug) and descriptive text.
*/
function register_nav_menus( $locations = array() ) {
global $_wp_registered_nav_menus;
add_theme_support( 'menus' );
foreach ( $locations as $key => $value ) {
if ( is_int( $key ) ) {
_doing_it_wrong( __FUNCTION__, __( 'Nav menu locations must be strings.' ), '5.3.0' );
break;
}
}
$_wp_registered_nav_menus = array_merge( (array) $_wp_registered_nav_menus, $locations );
}
/**
* Unregisters a navigation menu location for a theme.
*
* @since 3.1.0
*
* @global array $_wp_registered_nav_menus
*
* @param string $location The menu location identifier.
* @return bool True on success, false on failure.
*/
function unregister_nav_menu( $location ) {
global $_wp_registered_nav_menus;
if ( is_array( $_wp_registered_nav_menus ) && isset( $_wp_registered_nav_menus[ $location ] ) ) {
unset( $_wp_registered_nav_menus[ $location ] );
if ( empty( $_wp_registered_nav_menus ) ) {
_remove_theme_support( 'menus' );
}
return true;
}
return false;
}
/**
* Registers a navigation menu location for a theme.
*
* @since 3.0.0
*
* @param string $location Menu location identifier, like a slug.
* @param string $description Menu location descriptive text.
*/
function register_nav_menu( $location, $description ) {
register_nav_menus( array( $location => $description ) );
}
/**
* Retrieves all registered navigation menu locations in a theme.
*
* @since 3.0.0
*
* @global array $_wp_registered_nav_menus
*
* @return string[] Associative array of registered navigation menu descriptions keyed
* by their location. If none are registered, an empty array.
*/
function get_registered_nav_menus() {
global $_wp_registered_nav_menus;
if ( isset( $_wp_registered_nav_menus ) ) {
return $_wp_registered_nav_menus;
}
return array();
}
/**
* Retrieves all registered navigation menu locations and the menus assigned to them.
*
* @since 3.0.0
*
* @return int[] Associative array of registered navigation menu IDs keyed by their
* location name. If none are registered, an empty array.
*/
function get_nav_menu_locations() {
$locations = get_theme_mod( 'nav_menu_locations' );
return ( is_array( $locations ) ) ? $locations : array();
}
/**
* Determines whether a registered nav menu location has a menu assigned to it.
*
* @since 3.0.0
*
* @param string $location Menu location identifier.
* @return bool Whether location has a menu.
*/
function has_nav_menu( $location ) {
$has_nav_menu = false;
$registered_nav_menus = get_registered_nav_menus();
if ( isset( $registered_nav_menus[ $location ] ) ) {
$locations = get_nav_menu_locations();
$has_nav_menu = ! empty( $locations[ $location ] );
}
/**
* Filters whether a nav menu is assigned to the specified location.
*
* @since 4.3.0
*
* @param bool $has_nav_menu Whether there is a menu assigned to a location.
* @param string $location Menu location.
*/
return apply_filters( 'has_nav_menu', $has_nav_menu, $location );
}
/**
* Returns the name of a navigation menu.
*
* @since 4.9.0
*
* @param string $location Menu location identifier.
* @return string Menu name.
*/
function wp_get_nav_menu_name( $location ) {
$menu_name = '';
$locations = get_nav_menu_locations();
if ( isset( $locations[ $location ] ) ) {
$menu = wp_get_nav_menu_object( $locations[ $location ] );
if ( $menu && $menu->name ) {
$menu_name = $menu->name;
}
}
/**
* Filters the navigation menu name being returned.
*
* @since 4.9.0
*
* @param string $menu_name Menu name.
* @param string $location Menu location identifier.
*/
return apply_filters( 'wp_get_nav_menu_name', $menu_name, $location );
}
/**
* Determines whether the given ID is a nav menu item.
*
* @since 3.0.0
*
* @param int $menu_item_id The ID of the potential nav menu item.
* @return bool Whether the given ID is that of a nav menu item.
*/
function is_nav_menu_item( $menu_item_id = 0 ) {
return ( ! is_wp_error( $menu_item_id ) && ( 'nav_menu_item' === get_post_type( $menu_item_id ) ) );
}
/**
* Creates a navigation menu.
*
* Note that `$menu_name` is expected to be pre-slashed.
*
* @since 3.0.0
*
* @param string $menu_name Menu name.
* @return int|WP_Error Menu ID on success, WP_Error object on failure.
*/
function wp_create_nav_menu( $menu_name ) {
// expected_slashed ($menu_name)
return wp_update_nav_menu_object( 0, array( 'menu-name' => $menu_name ) );
}
/**
* Deletes a navigation menu.
*
* @since 3.0.0
*
* @param int|string|WP_Term $menu Menu ID, slug, name, or object.
* @return bool|WP_Error True on success, false or WP_Error object on failure.
*/
function wp_delete_nav_menu( $menu ) {
$menu = wp_get_nav_menu_object( $menu );
if ( ! $menu ) {
return false;
}
$menu_objects = get_objects_in_term( $menu->term_id, 'nav_menu' );
if ( ! empty( $menu_objects ) ) {
foreach ( $menu_objects as $item ) {
wp_delete_post( $item );
}
}
$result = wp_delete_term( $menu->term_id, 'nav_menu' );
// Remove this menu from any locations.
$locations = get_nav_menu_locations();
foreach ( $locations as $location => $menu_id ) {
if ( $menu_id === $menu->term_id ) {
$locations[ $location ] = 0;
}
}
set_theme_mod( 'nav_menu_locations', $locations );
if ( $result && ! is_wp_error( $result ) ) {
/**
* Fires after a navigation menu has been successfully deleted.
*
* @since 3.0.0
*
* @param int $term_id ID of the deleted menu.
*/
do_action( 'wp_delete_nav_menu', $menu->term_id );
}
return $result;
}
/**
* Saves the properties of a menu or create a new menu with those properties.
*
* Note that `$menu_data` is expected to be pre-slashed.
*
* @since 3.0.0
*
* @param int $menu_id The ID of the menu or "0" to create a new menu.
* @param array $menu_data The array of menu data.
* @return int|WP_Error Menu ID on success, WP_Error object on failure.
*/
function wp_update_nav_menu_object( $menu_id = 0, $menu_data = array() ) {
// expected_slashed ($menu_data)
$menu_id = (int) $menu_id;
$_menu = wp_get_nav_menu_object( $menu_id );
$args = array(
'description' => ( isset( $menu_data['description'] ) ? $menu_data['description'] : '' ),
'name' => ( isset( $menu_data['menu-name'] ) ? $menu_data['menu-name'] : '' ),
'parent' => ( isset( $menu_data['parent'] ) ? (int) $menu_data['parent'] : 0 ),
'slug' => null,
);
// Double-check that we're not going to have one menu take the name of another.
$_possible_existing = get_term_by( 'name', $menu_data['menu-name'], 'nav_menu' );
if (
$_possible_existing &&
! is_wp_error( $_possible_existing ) &&
isset( $_possible_existing->term_id ) &&
$_possible_existing->term_id !== $menu_id
) {
return new WP_Error(
'menu_exists',
sprintf(
/* translators: %s: Menu name. */
__( 'The menu name %s conflicts with another menu name. Please try another.' ),
'' . esc_html( $menu_data['menu-name'] ) . ' '
)
);
}
// Menu doesn't already exist, so create a new menu.
if ( ! $_menu || is_wp_error( $_menu ) ) {
$menu_exists = get_term_by( 'name', $menu_data['menu-name'], 'nav_menu' );
if ( $menu_exists ) {
return new WP_Error(
'menu_exists',
sprintf(
/* translators: %s: Menu name. */
__( 'The menu name %s conflicts with another menu name. Please try another.' ),
'' . esc_html( $menu_data['menu-name'] ) . ' '
)
);
}
$_menu = wp_insert_term( $menu_data['menu-name'], 'nav_menu', $args );
if ( is_wp_error( $_menu ) ) {
return $_menu;
}
/**
* Fires after a navigation menu is successfully created.
*
* @since 3.0.0
*
* @param int $term_id ID of the new menu.
* @param array $menu_data An array of menu data.
*/
do_action( 'wp_create_nav_menu', $_menu['term_id'], $menu_data );
return (int) $_menu['term_id'];
}
if ( ! $_menu || ! isset( $_menu->term_id ) ) {
return 0;
}
$menu_id = (int) $_menu->term_id;
$update_response = wp_update_term( $menu_id, 'nav_menu', $args );
if ( is_wp_error( $update_response ) ) {
return $update_response;
}
$menu_id = (int) $update_response['term_id'];
/**
* Fires after a navigation menu has been successfully updated.
*
* @since 3.0.0
*
* @param int $menu_id ID of the updated menu.
* @param array $menu_data An array of menu data.
*/
do_action( 'wp_update_nav_menu', $menu_id, $menu_data );
return $menu_id;
}
/**
* Saves the properties of a menu item or create a new one.
*
* The menu-item-title, menu-item-description and menu-item-attr-title are expected
* to be pre-slashed since they are passed directly to APIs that expect slashed data.
*
* @since 3.0.0
* @since 5.9.0 Added the `$fire_after_hooks` parameter.
*
* @param int $menu_id The ID of the menu. If 0, makes the menu item a draft orphan.
* @param int $menu_item_db_id The ID of the menu item. If 0, creates a new menu item.
* @param array $menu_item_data The menu item's data.
* @param bool $fire_after_hooks Whether to fire the after insert hooks. Default true.
* @return int|WP_Error The menu item's database ID or WP_Error object on failure.
*/
function wp_update_nav_menu_item( $menu_id = 0, $menu_item_db_id = 0, $menu_item_data = array(), $fire_after_hooks = true ) {
$menu_id = (int) $menu_id;
$menu_item_db_id = (int) $menu_item_db_id;
// Make sure that we don't convert non-nav_menu_item objects into nav_menu_item objects.
if ( ! empty( $menu_item_db_id ) && ! is_nav_menu_item( $menu_item_db_id ) ) {
return new WP_Error( 'update_nav_menu_item_failed', __( 'The given object ID is not that of a menu item.' ) );
}
$menu = wp_get_nav_menu_object( $menu_id );
if ( ! $menu && 0 !== $menu_id ) {
return new WP_Error( 'invalid_menu_id', __( 'Invalid menu ID.' ) );
}
if ( is_wp_error( $menu ) ) {
return $menu;
}
$defaults = array(
'menu-item-db-id' => $menu_item_db_id,
'menu-item-object-id' => 0,
'menu-item-object' => '',
'menu-item-parent-id' => 0,
'menu-item-position' => 0,
'menu-item-type' => 'custom',
'menu-item-title' => '',
'menu-item-url' => '',
'menu-item-description' => '',
'menu-item-attr-title' => '',
'menu-item-target' => '',
'menu-item-classes' => '',
'menu-item-xfn' => '',
'menu-item-status' => '',
'menu-item-post-date' => '',
'menu-item-post-date-gmt' => '',
);
$args = wp_parse_args( $menu_item_data, $defaults );
if ( 0 === $menu_id ) {
$args['menu-item-position'] = 1;
} elseif ( 0 === (int) $args['menu-item-position'] ) {
$menu_items = array();
if ( 0 !== $menu_id ) {
$menu_items = (array) wp_get_nav_menu_items( $menu_id, array( 'post_status' => 'publish,draft' ) );
}
$last_item = array_pop( $menu_items );
if ( $last_item && isset( $last_item->menu_order ) ) {
$args['menu-item-position'] = 1 + $last_item->menu_order;
} else {
$args['menu-item-position'] = count( $menu_items );
}
}
$original_parent = 0 < $menu_item_db_id ? get_post_field( 'post_parent', $menu_item_db_id ) : 0;
if ( 'custom' === $args['menu-item-type'] ) {
// If custom menu item, trim the URL.
$args['menu-item-url'] = trim( $args['menu-item-url'] );
} else {
/*
* If non-custom menu item, then:
* - use the original object's URL.
* - blank default title to sync with the original object's title.
*/
$args['menu-item-url'] = '';
$original_title = '';
if ( 'taxonomy' === $args['menu-item-type'] ) {
$original_parent = get_term_field( 'parent', $args['menu-item-object-id'], $args['menu-item-object'], 'raw' );
$original_title = get_term_field( 'name', $args['menu-item-object-id'], $args['menu-item-object'], 'raw' );
} elseif ( 'post_type' === $args['menu-item-type'] ) {
$original_object = get_post( $args['menu-item-object-id'] );
$original_parent = (int) $original_object->post_parent;
$original_title = $original_object->post_title;
} elseif ( 'post_type_archive' === $args['menu-item-type'] ) {
$original_object = get_post_type_object( $args['menu-item-object'] );
if ( $original_object ) {
$original_title = $original_object->labels->archives;
}
}
if ( wp_unslash( $args['menu-item-title'] ) === wp_specialchars_decode( $original_title ) ) {
$args['menu-item-title'] = '';
}
// Hack to get wp to create a post object when too many properties are empty.
if ( '' === $args['menu-item-title'] && '' === $args['menu-item-description'] ) {
$args['menu-item-description'] = ' ';
}
}
// Populate the menu item object.
$post = array(
'menu_order' => $args['menu-item-position'],
'ping_status' => 0,
'post_content' => $args['menu-item-description'],
'post_excerpt' => $args['menu-item-attr-title'],
'post_parent' => $original_parent,
'post_title' => $args['menu-item-title'],
'post_type' => 'nav_menu_item',
);
$post_date = wp_resolve_post_date( $args['menu-item-post-date'], $args['menu-item-post-date-gmt'] );
if ( $post_date ) {
$post['post_date'] = $post_date;
}
$update = 0 !== $menu_item_db_id;
// New menu item. Default is draft status.
if ( ! $update ) {
$post['ID'] = 0;
$post['post_status'] = 'publish' === $args['menu-item-status'] ? 'publish' : 'draft';
$menu_item_db_id = wp_insert_post( $post, true, $fire_after_hooks );
if ( ! $menu_item_db_id || is_wp_error( $menu_item_db_id ) ) {
return $menu_item_db_id;
}
/**
* Fires immediately after a new navigation menu item has been added.
*
* @since 4.4.0
*
* @see wp_update_nav_menu_item()
*
* @param int $menu_id ID of the updated menu.
* @param int $menu_item_db_id ID of the new menu item.
* @param array $args An array of arguments used to update/add the menu item.
*/
do_action( 'wp_add_nav_menu_item', $menu_id, $menu_item_db_id, $args );
}
/*
* Associate the menu item with the menu term.
* Only set the menu term if it isn't set to avoid unnecessary wp_get_object_terms().
*/
if ( $menu_id && ( ! $update || ! is_object_in_term( $menu_item_db_id, 'nav_menu', (int) $menu->term_id ) ) ) {
$update_terms = wp_set_object_terms( $menu_item_db_id, array( $menu->term_id ), 'nav_menu' );
if ( is_wp_error( $update_terms ) ) {
return $update_terms;
}
}
if ( 'custom' === $args['menu-item-type'] ) {
$args['menu-item-object-id'] = $menu_item_db_id;
$args['menu-item-object'] = 'custom';
}
$menu_item_db_id = (int) $menu_item_db_id;
// Reset invalid `menu_item_parent`.
if ( (int) $args['menu-item-parent-id'] === $menu_item_db_id ) {
$args['menu-item-parent-id'] = 0;
}
update_post_meta( $menu_item_db_id, '_menu_item_type', sanitize_key( $args['menu-item-type'] ) );
update_post_meta( $menu_item_db_id, '_menu_item_menu_item_parent', (string) ( (int) $args['menu-item-parent-id'] ) );
update_post_meta( $menu_item_db_id, '_menu_item_object_id', (string) ( (int) $args['menu-item-object-id'] ) );
update_post_meta( $menu_item_db_id, '_menu_item_object', sanitize_key( $args['menu-item-object'] ) );
update_post_meta( $menu_item_db_id, '_menu_item_target', sanitize_key( $args['menu-item-target'] ) );
$args['menu-item-classes'] = array_map( 'sanitize_html_class', explode( ' ', $args['menu-item-classes'] ) );
$args['menu-item-xfn'] = implode( ' ', array_map( 'sanitize_html_class', explode( ' ', $args['menu-item-xfn'] ) ) );
update_post_meta( $menu_item_db_id, '_menu_item_classes', $args['menu-item-classes'] );
update_post_meta( $menu_item_db_id, '_menu_item_xfn', $args['menu-item-xfn'] );
update_post_meta( $menu_item_db_id, '_menu_item_url', sanitize_url( $args['menu-item-url'] ) );
if ( 0 === $menu_id ) {
update_post_meta( $menu_item_db_id, '_menu_item_orphaned', (string) time() );
} elseif ( get_post_meta( $menu_item_db_id, '_menu_item_orphaned' ) ) {
delete_post_meta( $menu_item_db_id, '_menu_item_orphaned' );
}
// Update existing menu item. Default is publish status.
if ( $update ) {
$post['ID'] = $menu_item_db_id;
$post['post_status'] = ( 'draft' === $args['menu-item-status'] ) ? 'draft' : 'publish';
$update_post = wp_update_post( $post, true );
if ( is_wp_error( $update_post ) ) {
return $update_post;
}
}
/**
* Fires after a navigation menu item has been updated.
*
* @since 3.0.0
*
* @see wp_update_nav_menu_item()
*
* @param int $menu_id ID of the updated menu.
* @param int $menu_item_db_id ID of the updated menu item.
* @param array $args An array of arguments used to update a menu item.
*/
do_action( 'wp_update_nav_menu_item', $menu_id, $menu_item_db_id, $args );
return $menu_item_db_id;
}
/**
* Returns all navigation menu objects.
*
* @since 3.0.0
* @since 4.1.0 Default value of the 'orderby' argument was changed from 'none'
* to 'name'.
*
* @param array $args Optional. Array of arguments passed on to get_terms().
* Default empty array.
* @return WP_Term[] An array of menu objects.
*/
function wp_get_nav_menus( $args = array() ) {
$defaults = array(
'taxonomy' => 'nav_menu',
'hide_empty' => false,
'orderby' => 'name',
);
$args = wp_parse_args( $args, $defaults );
/**
* Filters the navigation menu objects being returned.
*
* @since 3.0.0
*
* @see get_terms()
*
* @param WP_Term[] $menus An array of menu objects.
* @param array $args An array of arguments used to retrieve menu objects.
*/
return apply_filters( 'wp_get_nav_menus', get_terms( $args ), $args );
}
/**
* Determines whether a menu item is valid.
*
* @link https://core.trac.wordpress.org/ticket/13958
*
* @since 3.2.0
* @access private
*
* @param object $item The menu item to check.
* @return bool False if invalid, otherwise true.
*/
function _is_valid_nav_menu_item( $item ) {
return empty( $item->_invalid );
}
/**
* Retrieves all menu items of a navigation menu.
*
* Note: Most arguments passed to the `$args` parameter – save for 'output_key' – are
* specifically for retrieving nav_menu_item posts from get_posts() and may only
* indirectly affect the ultimate ordering and content of the resulting nav menu
* items that get returned from this function.
*
* @since 3.0.0
*
* @param int|string|WP_Term $menu Menu ID, slug, name, or object.
* @param array $args {
* Optional. Arguments to pass to get_posts().
*
* @type string $order How to order nav menu items as queried with get_posts().
* Will be ignored if 'output' is ARRAY_A. Default 'ASC'.
* @type string $orderby Field to order menu items by as retrieved from get_posts().
* Supply an orderby field via 'output_key' to affect the
* output order of nav menu items. Default 'menu_order'.
* @type string $post_type Menu items post type. Default 'nav_menu_item'.
* @type string $post_status Menu items post status. Default 'publish'.
* @type string $output How to order outputted menu items. Default ARRAY_A.
* @type string $output_key Key to use for ordering the actual menu items that get
* returned. Note that that is not a get_posts() argument
* and will only affect output of menu items processed in
* this function. Default 'menu_order'.
* @type bool $nopaging Whether to retrieve all menu items (true) or paginate
* (false). Default true.
* @type bool $update_menu_item_cache Whether to update the menu item cache. Default true.
* }
* @return array|false Array of menu items, otherwise false.
*/
function wp_get_nav_menu_items( $menu, $args = array() ) {
$menu = wp_get_nav_menu_object( $menu );
if ( ! $menu ) {
return false;
}
if ( ! taxonomy_exists( 'nav_menu' ) ) {
return false;
}
$defaults = array(
'order' => 'ASC',
'orderby' => 'menu_order',
'post_type' => 'nav_menu_item',
'post_status' => 'publish',
'output' => ARRAY_A,
'output_key' => 'menu_order',
'nopaging' => true,
'update_menu_item_cache' => true,
'tax_query' => array(
array(
'taxonomy' => 'nav_menu',
'field' => 'term_taxonomy_id',
'terms' => $menu->term_taxonomy_id,
),
),
);
$args = wp_parse_args( $args, $defaults );
if ( $menu->count > 0 ) {
$items = get_posts( $args );
} else {
$items = array();
}
$items = array_map( 'wp_setup_nav_menu_item', $items );
if ( ! is_admin() ) { // Remove invalid items only on front end.
$items = array_filter( $items, '_is_valid_nav_menu_item' );
}
if ( ARRAY_A === $args['output'] ) {
$items = wp_list_sort(
$items,
array(
$args['output_key'] => 'ASC',
)
);
$i = 1;
foreach ( $items as $k => $item ) {
$items[ $k ]->{$args['output_key']} = $i++;
}
}
/**
* Filters the navigation menu items being returned.
*
* @since 3.0.0
*
* @param array $items An array of menu item post objects.
* @param object $menu The menu object.
* @param array $args An array of arguments used to retrieve menu item objects.
*/
return apply_filters( 'wp_get_nav_menu_items', $items, $menu, $args );
}
/**
* Updates post and term caches for all linked objects for a list of menu items.
*
* @since 6.1.0
*
* @param WP_Post[] $menu_items Array of menu item post objects.
*/
function update_menu_item_cache( $menu_items ) {
$post_ids = array();
$term_ids = array();
foreach ( $menu_items as $menu_item ) {
if ( 'nav_menu_item' !== $menu_item->post_type ) {
continue;
}
$object_id = get_post_meta( $menu_item->ID, '_menu_item_object_id', true );
$type = get_post_meta( $menu_item->ID, '_menu_item_type', true );
if ( 'post_type' === $type ) {
$post_ids[] = (int) $object_id;
} elseif ( 'taxonomy' === $type ) {
$term_ids[] = (int) $object_id;
}
}
if ( ! empty( $post_ids ) ) {
_prime_post_caches( $post_ids, false );
}
if ( ! empty( $term_ids ) ) {
_prime_term_caches( $term_ids );
}
}
/**
* Decorates a menu item object with the shared navigation menu item properties.
*
* Properties:
* - ID: The term_id if the menu item represents a taxonomy term.
* - attr_title: The title attribute of the link element for this menu item.
* - classes: The array of class attribute values for the link element of this menu item.
* - db_id: The DB ID of this item as a nav_menu_item object, if it exists (0 if it doesn't exist).
* - description: The description of this menu item.
* - menu_item_parent: The DB ID of the nav_menu_item that is this item's menu parent, if any. 0 otherwise.
* - object: The type of object originally represented, such as 'category', 'post', or 'attachment'.
* - object_id: The DB ID of the original object this menu item represents, e.g. ID for posts and term_id for categories.
* - post_parent: The DB ID of the original object's parent object, if any (0 otherwise).
* - post_title: A "no title" label if menu item represents a post that lacks a title.
* - target: The target attribute of the link element for this menu item.
* - title: The title of this menu item.
* - type: The family of objects originally represented, such as 'post_type' or 'taxonomy'.
* - type_label: The singular label used to describe this type of menu item.
* - url: The URL to which this menu item points.
* - xfn: The XFN relationship expressed in the link of this menu item.
* - _invalid: Whether the menu item represents an object that no longer exists.
*
* @since 3.0.0
*
* @param object $menu_item The menu item to modify.
* @return object The menu item with standard menu item properties.
*/
function wp_setup_nav_menu_item( $menu_item ) {
/**
* Filters whether to short-circuit the wp_setup_nav_menu_item() output.
*
* Returning a non-null value from the filter will short-circuit wp_setup_nav_menu_item(),
* returning that value instead.
*
* @since 6.3.0
*
* @param object|null $modified_menu_item Modified menu item. Default null.
* @param object $menu_item The menu item to modify.
*/
$pre_menu_item = apply_filters( 'pre_wp_setup_nav_menu_item', null, $menu_item );
if ( null !== $pre_menu_item ) {
return $pre_menu_item;
}
if ( isset( $menu_item->post_type ) ) {
if ( 'nav_menu_item' === $menu_item->post_type ) {
$menu_item->db_id = (int) $menu_item->ID;
$menu_item->menu_item_parent = ! isset( $menu_item->menu_item_parent ) ? get_post_meta( $menu_item->ID, '_menu_item_menu_item_parent', true ) : $menu_item->menu_item_parent;
$menu_item->object_id = ! isset( $menu_item->object_id ) ? get_post_meta( $menu_item->ID, '_menu_item_object_id', true ) : $menu_item->object_id;
$menu_item->object = ! isset( $menu_item->object ) ? get_post_meta( $menu_item->ID, '_menu_item_object', true ) : $menu_item->object;
$menu_item->type = ! isset( $menu_item->type ) ? get_post_meta( $menu_item->ID, '_menu_item_type', true ) : $menu_item->type;
if ( 'post_type' === $menu_item->type ) {
$object = get_post_type_object( $menu_item->object );
if ( $object ) {
$menu_item->type_label = $object->labels->singular_name;
// Denote post states for special pages (only in the admin).
if ( function_exists( 'get_post_states' ) ) {
$menu_post = get_post( $menu_item->object_id );
$post_states = get_post_states( $menu_post );
if ( $post_states ) {
$menu_item->type_label = wp_strip_all_tags( implode( ', ', $post_states ) );
}
}
} else {
$menu_item->type_label = $menu_item->object;
$menu_item->_invalid = true;
}
if ( 'trash' === get_post_status( $menu_item->object_id ) ) {
$menu_item->_invalid = true;
}
$original_object = get_post( $menu_item->object_id );
if ( $original_object ) {
$menu_item->url = get_permalink( $original_object->ID );
/** This filter is documented in wp-includes/post-template.php */
$original_title = apply_filters( 'the_title', $original_object->post_title, $original_object->ID );
} else {
$menu_item->url = '';
$original_title = '';
$menu_item->_invalid = true;
}
if ( '' === $original_title ) {
/* translators: %d: ID of a post. */
$original_title = sprintf( __( '#%d (no title)' ), $menu_item->object_id );
}
$menu_item->title = ( '' === $menu_item->post_title ) ? $original_title : $menu_item->post_title;
} elseif ( 'post_type_archive' === $menu_item->type ) {
$object = get_post_type_object( $menu_item->object );
if ( $object ) {
$menu_item->title = ( '' === $menu_item->post_title ) ? $object->labels->archives : $menu_item->post_title;
$post_type_description = $object->description;
} else {
$post_type_description = '';
$menu_item->_invalid = true;
}
$menu_item->type_label = __( 'Post Type Archive' );
$post_content = wp_trim_words( $menu_item->post_content, 200 );
$post_type_description = ( '' === $post_content ) ? $post_type_description : $post_content;
$menu_item->url = get_post_type_archive_link( $menu_item->object );
} elseif ( 'taxonomy' === $menu_item->type ) {
$object = get_taxonomy( $menu_item->object );
if ( $object ) {
$menu_item->type_label = $object->labels->singular_name;
} else {
$menu_item->type_label = $menu_item->object;
$menu_item->_invalid = true;
}
$original_object = get_term( (int) $menu_item->object_id, $menu_item->object );
if ( $original_object && ! is_wp_error( $original_object ) ) {
$menu_item->url = get_term_link( (int) $menu_item->object_id, $menu_item->object );
$original_title = $original_object->name;
} else {
$menu_item->url = '';
$original_title = '';
$menu_item->_invalid = true;
}
if ( '' === $original_title ) {
/* translators: %d: ID of a term. */
$original_title = sprintf( __( '#%d (no title)' ), $menu_item->object_id );
}
$menu_item->title = ( '' === $menu_item->post_title ) ? $original_title : $menu_item->post_title;
} else {
$menu_item->type_label = __( 'Custom Link' );
$menu_item->title = $menu_item->post_title;
$menu_item->url = ! isset( $menu_item->url ) ? get_post_meta( $menu_item->ID, '_menu_item_url', true ) : $menu_item->url;
}
$menu_item->target = ! isset( $menu_item->target ) ? get_post_meta( $menu_item->ID, '_menu_item_target', true ) : $menu_item->target;
/**
* Filters a navigation menu item's title attribute.
*
* @since 3.0.0
*
* @param string $item_title The menu item title attribute.
*/
$menu_item->attr_title = ! isset( $menu_item->attr_title ) ? apply_filters( 'nav_menu_attr_title', $menu_item->post_excerpt ) : $menu_item->attr_title;
if ( ! isset( $menu_item->description ) ) {
/**
* Filters a navigation menu item's description.
*
* @since 3.0.0
*
* @param string $description The menu item description.
*/
$menu_item->description = apply_filters( 'nav_menu_description', wp_trim_words( $menu_item->post_content, 200 ) );
}
$menu_item->classes = ! isset( $menu_item->classes ) ? (array) get_post_meta( $menu_item->ID, '_menu_item_classes', true ) : $menu_item->classes;
$menu_item->xfn = ! isset( $menu_item->xfn ) ? get_post_meta( $menu_item->ID, '_menu_item_xfn', true ) : $menu_item->xfn;
} else {
$menu_item->db_id = 0;
$menu_item->menu_item_parent = 0;
$menu_item->object_id = (int) $menu_item->ID;
$menu_item->type = 'post_type';
$object = get_post_type_object( $menu_item->post_type );
$menu_item->object = $object->name;
$menu_item->type_label = $object->labels->singular_name;
if ( '' === $menu_item->post_title ) {
/* translators: %d: ID of a post. */
$menu_item->post_title = sprintf( __( '#%d (no title)' ), $menu_item->ID );
}
$menu_item->title = $menu_item->post_title;
$menu_item->url = get_permalink( $menu_item->ID );
$menu_item->target = '';
/** This filter is documented in wp-includes/nav-menu.php */
$menu_item->attr_title = apply_filters( 'nav_menu_attr_title', '' );
/** This filter is documented in wp-includes/nav-menu.php */
$menu_item->description = apply_filters( 'nav_menu_description', '' );
$menu_item->classes = array();
$menu_item->xfn = '';
}
} elseif ( isset( $menu_item->taxonomy ) ) {
$menu_item->ID = $menu_item->term_id;
$menu_item->db_id = 0;
$menu_item->menu_item_parent = 0;
$menu_item->object_id = (int) $menu_item->term_id;
$menu_item->post_parent = (int) $menu_item->parent;
$menu_item->type = 'taxonomy';
$object = get_taxonomy( $menu_item->taxonomy );
$menu_item->object = $object->name;
$menu_item->type_label = $object->labels->singular_name;
$menu_item->title = $menu_item->name;
$menu_item->url = get_term_link( $menu_item, $menu_item->taxonomy );
$menu_item->target = '';
$menu_item->attr_title = '';
$menu_item->description = get_term_field( 'description', $menu_item->term_id, $menu_item->taxonomy );
$menu_item->classes = array();
$menu_item->xfn = '';
}
/**
* Filters a navigation menu item object.
*
* @since 3.0.0
*
* @param object $menu_item The menu item object.
*/
return apply_filters( 'wp_setup_nav_menu_item', $menu_item );
}
/**
* Returns the menu items associated with a particular object.
*
* @since 3.0.0
*
* @param int $object_id Optional. The ID of the original object. Default 0.
* @param string $object_type Optional. The type of object, such as 'post_type' or 'taxonomy'.
* Default 'post_type'.
* @param string $taxonomy Optional. If $object_type is 'taxonomy', $taxonomy is the name
* of the tax that $object_id belongs to. Default empty.
* @return int[] The array of menu item IDs; empty array if none.
*/
function wp_get_associated_nav_menu_items( $object_id = 0, $object_type = 'post_type', $taxonomy = '' ) {
$object_id = (int) $object_id;
$menu_item_ids = array();
$query = new WP_Query();
$menu_items = $query->query(
array(
'meta_key' => '_menu_item_object_id',
'meta_value' => $object_id,
'post_status' => 'any',
'post_type' => 'nav_menu_item',
'posts_per_page' => -1,
)
);
foreach ( (array) $menu_items as $menu_item ) {
if ( isset( $menu_item->ID ) && is_nav_menu_item( $menu_item->ID ) ) {
$menu_item_type = get_post_meta( $menu_item->ID, '_menu_item_type', true );
if (
'post_type' === $object_type &&
'post_type' === $menu_item_type
) {
$menu_item_ids[] = (int) $menu_item->ID;
} elseif (
'taxonomy' === $object_type &&
'taxonomy' === $menu_item_type &&
get_post_meta( $menu_item->ID, '_menu_item_object', true ) === $taxonomy
) {
$menu_item_ids[] = (int) $menu_item->ID;
}
}
}
return array_unique( $menu_item_ids );
}
/**
* Callback for handling a menu item when its original object is deleted.
*
* @since 3.0.0
* @access private
*
* @param int $object_id The ID of the original object being trashed.
*/
function _wp_delete_post_menu_item( $object_id ) {
$object_id = (int) $object_id;
$menu_item_ids = wp_get_associated_nav_menu_items( $object_id, 'post_type' );
foreach ( (array) $menu_item_ids as $menu_item_id ) {
wp_delete_post( $menu_item_id, true );
}
}
/**
* Serves as a callback for handling a menu item when its original object is deleted.
*
* @since 3.0.0
* @access private
*
* @param int $object_id The ID of the original object being trashed.
* @param int $tt_id Term taxonomy ID. Unused.
* @param string $taxonomy Taxonomy slug.
*/
function _wp_delete_tax_menu_item( $object_id, $tt_id, $taxonomy ) {
$object_id = (int) $object_id;
$menu_item_ids = wp_get_associated_nav_menu_items( $object_id, 'taxonomy', $taxonomy );
foreach ( (array) $menu_item_ids as $menu_item_id ) {
wp_delete_post( $menu_item_id, true );
}
}
/**
* Automatically add newly published page objects to menus with that as an option.
*
* @since 3.0.0
* @access private
*
* @param string $new_status The new status of the post object.
* @param string $old_status The old status of the post object.
* @param WP_Post $post The post object being transitioned from one status to another.
*/
function _wp_auto_add_pages_to_menu( $new_status, $old_status, $post ) {
if ( 'publish' !== $new_status || 'publish' === $old_status || 'page' !== $post->post_type ) {
return;
}
if ( ! empty( $post->post_parent ) ) {
return;
}
$auto_add = get_option( 'nav_menu_options' );
if ( empty( $auto_add ) || ! is_array( $auto_add ) || ! isset( $auto_add['auto_add'] ) ) {
return;
}
$auto_add = $auto_add['auto_add'];
if ( empty( $auto_add ) || ! is_array( $auto_add ) ) {
return;
}
$args = array(
'menu-item-object-id' => $post->ID,
'menu-item-object' => $post->post_type,
'menu-item-type' => 'post_type',
'menu-item-status' => 'publish',
);
foreach ( $auto_add as $menu_id ) {
$items = wp_get_nav_menu_items( $menu_id, array( 'post_status' => 'publish,draft' ) );
if ( ! is_array( $items ) ) {
continue;
}
foreach ( $items as $item ) {
if ( $post->ID === (int) $item->object_id ) {
continue 2;
}
}
wp_update_nav_menu_item( $menu_id, 0, $args );
}
}
/**
* Deletes auto-draft posts associated with the supplied changeset.
*
* @since 4.8.0
* @access private
*
* @param int $post_id Post ID for the customize_changeset.
*/
function _wp_delete_customize_changeset_dependent_auto_drafts( $post_id ) {
$post = get_post( $post_id );
if ( ! $post || 'customize_changeset' !== $post->post_type ) {
return;
}
$data = json_decode( $post->post_content, true );
if ( empty( $data['nav_menus_created_posts']['value'] ) ) {
return;
}
remove_action( 'delete_post', '_wp_delete_customize_changeset_dependent_auto_drafts' );
foreach ( $data['nav_menus_created_posts']['value'] as $stub_post_id ) {
if ( empty( $stub_post_id ) ) {
continue;
}
if ( 'auto-draft' === get_post_status( $stub_post_id ) ) {
wp_delete_post( $stub_post_id, true );
} elseif ( 'draft' === get_post_status( $stub_post_id ) ) {
wp_trash_post( $stub_post_id );
delete_post_meta( $stub_post_id, '_customize_changeset_uuid' );
}
}
add_action( 'delete_post', '_wp_delete_customize_changeset_dependent_auto_drafts' );
}
/**
* Handles menu config after theme change.
*
* @access private
* @since 4.9.0
*/
function _wp_menus_changed() {
$old_nav_menu_locations = get_option( 'theme_switch_menu_locations', array() );
$new_nav_menu_locations = get_nav_menu_locations();
$mapped_nav_menu_locations = wp_map_nav_menu_locations( $new_nav_menu_locations, $old_nav_menu_locations );
set_theme_mod( 'nav_menu_locations', $mapped_nav_menu_locations );
delete_option( 'theme_switch_menu_locations' );
}
/**
* Maps nav menu locations according to assignments in previously active theme.
*
* @since 4.9.0
*
* @param array $new_nav_menu_locations New nav menu locations assignments.
* @param array $old_nav_menu_locations Old nav menu locations assignments.
* @return array Nav menus mapped to new nav menu locations.
*/
function wp_map_nav_menu_locations( $new_nav_menu_locations, $old_nav_menu_locations ) {
$registered_nav_menus = get_registered_nav_menus();
$new_nav_menu_locations = array_intersect_key( $new_nav_menu_locations, $registered_nav_menus );
// Short-circuit if there are no old nav menu location assignments to map.
if ( empty( $old_nav_menu_locations ) ) {
return $new_nav_menu_locations;
}
// If old and new theme have just one location, map it and we're done.
if ( 1 === count( $old_nav_menu_locations ) && 1 === count( $registered_nav_menus ) ) {
$new_nav_menu_locations[ key( $registered_nav_menus ) ] = array_pop( $old_nav_menu_locations );
return $new_nav_menu_locations;
}
$old_locations = array_keys( $old_nav_menu_locations );
// Map locations with the same slug.
foreach ( $registered_nav_menus as $location => $name ) {
if ( in_array( $location, $old_locations, true ) ) {
$new_nav_menu_locations[ $location ] = $old_nav_menu_locations[ $location ];
unset( $old_nav_menu_locations[ $location ] );
}
}
// If there are no old nav menu locations left, then we're done.
if ( empty( $old_nav_menu_locations ) ) {
return $new_nav_menu_locations;
}
/*
* If old and new theme both have locations that contain phrases
* from within the same group, make an educated guess and map it.
*/
$common_slug_groups = array(
array( 'primary', 'menu-1', 'main', 'header', 'navigation', 'top' ),
array( 'secondary', 'menu-2', 'footer', 'subsidiary', 'bottom' ),
array( 'social' ),
);
// Go through each group...
foreach ( $common_slug_groups as $slug_group ) {
// ...and see if any of these slugs...
foreach ( $slug_group as $slug ) {
// ...and any of the new menu locations...
foreach ( $registered_nav_menus as $new_location => $name ) {
// ...actually match!
if ( is_string( $new_location ) && false === stripos( $new_location, $slug ) && false === stripos( $slug, $new_location ) ) {
continue;
} elseif ( is_numeric( $new_location ) && $new_location !== $slug ) {
continue;
}
// Then see if any of the old locations...
foreach ( $old_nav_menu_locations as $location => $menu_id ) {
// ...and any slug in the same group...
foreach ( $slug_group as $slug ) {
// ... have a match as well.
if ( is_string( $location ) && false === stripos( $location, $slug ) && false === stripos( $slug, $location ) ) {
continue;
} elseif ( is_numeric( $location ) && $location !== $slug ) {
continue;
}
// Make sure this location wasn't mapped and removed previously.
if ( ! empty( $old_nav_menu_locations[ $location ] ) ) {
// We have a match that can be mapped!
$new_nav_menu_locations[ $new_location ] = $old_nav_menu_locations[ $location ];
// Remove the mapped location so it can't be mapped again.
unset( $old_nav_menu_locations[ $location ] );
// Go back and check the next new menu location.
continue 3;
}
} // namespace,
'/' . $this->rest_base . '/(?P[\d]+)/post-process',
array(
'methods' => WP_REST_Server::CREATABLE,
'callback' => array( $this, 'post_process_item' ),
'permission_callback' => array( $this, 'post_process_item_permissions_check' ),
'args' => array(
'id' => array(
'description' => __( 'Unique identifier for the attachment.' ),
'type' => 'integer',
),
'action' => array(
'type' => 'string',
'enum' => array( 'create-image-subsizes' ),
'required' => true,
),
),
)
);
register_rest_route(
$this->namespace,
'/' . $this->rest_base . '/(?P[\d]+)/edit',
array(
'methods' => WP_REST_Server::CREATABLE,
'callback' => array( $this, 'edit_media_item' ),
'permission_callback' => array( $this, 'edit_media_item_permissions_check' ),
'args' => $this->get_edit_media_item_args(),
)
);
}
/**
* Determines the allowed query_vars for a get_items() response and
* prepares for WP_Query.
*
* @since 4.7.0
*
* @param array $prepared_args Optional. Array of prepared arguments. Default empty array.
* @param WP_REST_Request $request Optional. Request to prepare items for.
* @return array Array of query arguments.
*/
protected function prepare_items_query( $prepared_args = array(), $request = null ) {
$query_args = parent::prepare_items_query( $prepared_args, $request );
if ( empty( $query_args['post_status'] ) ) {
$query_args['post_status'] = 'inherit';
}
$media_types = $this->get_media_types();
if ( ! empty( $request['media_type'] ) && isset( $media_types[ $request['media_type'] ] ) ) {
$query_args['post_mime_type'] = $media_types[ $request['media_type'] ];
}
if ( ! empty( $request['mime_type'] ) ) {
$parts = explode( '/', $request['mime_type'] );
if ( isset( $media_types[ $parts[0] ] ) && in_array( $request['mime_type'], $media_types[ $parts[0] ], true ) ) {
$query_args['post_mime_type'] = $request['mime_type'];
}
}
// Filter query clauses to include filenames.
if ( isset( $query_args['s'] ) ) {
add_filter( 'wp_allow_query_attachment_by_filename', '__return_true' );
}
return $query_args;
}
/**
* Checks if a given request has access to create an attachment.
*
* @since 4.7.0
*
* @param WP_REST_Request $request Full details about the request.
* @return true|WP_Error Boolean true if the attachment may be created, or a WP_Error if not.
*/
public function create_item_permissions_check( $request ) {
$ret = parent::create_item_permissions_check( $request );
if ( ! $ret || is_wp_error( $ret ) ) {
return $ret;
}
if ( ! current_user_can( 'upload_files' ) ) {
return new WP_Error(
'rest_cannot_create',
__( 'Sorry, you are not allowed to upload media on this site.' ),
array( 'status' => 400 )
);
}
// Attaching media to a post requires ability to edit said post.
if ( ! empty( $request['post'] ) && ! current_user_can( 'edit_post', (int) $request['post'] ) ) {
return new WP_Error(
'rest_cannot_edit',
__( 'Sorry, you are not allowed to upload media to this post.' ),
array( 'status' => rest_authorization_required_code() )
);
}
return true;
}
/**
* Creates a single attachment.
*
* @since 4.7.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, WP_Error object on failure.
*/
public function create_item( $request ) {
if ( ! empty( $request['post'] ) && in_array( get_post_type( $request['post'] ), array( 'revision', 'attachment' ), true ) ) {
return new WP_Error(
'rest_invalid_param',
__( 'Invalid parent type.' ),
array( 'status' => 400 )
);
}
$insert = $this->insert_attachment( $request );
if ( is_wp_error( $insert ) ) {
return $insert;
}
$schema = $this->get_item_schema();
// Extract by name.
$attachment_id = $insert['attachment_id'];
$file = $insert['file'];
if ( isset( $request['alt_text'] ) ) {
update_post_meta( $attachment_id, '_wp_attachment_image_alt', sanitize_text_field( $request['alt_text'] ) );
}
if ( ! empty( $schema['properties']['featured_media'] ) && isset( $request['featured_media'] ) ) {
$thumbnail_update = $this->handle_featured_media( $request['featured_media'], $attachment_id );
if ( is_wp_error( $thumbnail_update ) ) {
return $thumbnail_update;
}
}
if ( ! empty( $schema['properties']['meta'] ) && isset( $request['meta'] ) ) {
$meta_update = $this->meta->update_value( $request['meta'], $attachment_id );
if ( is_wp_error( $meta_update ) ) {
return $meta_update;
}
}
$attachment = get_post( $attachment_id );
$fields_update = $this->update_additional_fields_for_object( $attachment, $request );
if ( is_wp_error( $fields_update ) ) {
return $fields_update;
}
$terms_update = $this->handle_terms( $attachment_id, $request );
if ( is_wp_error( $terms_update ) ) {
return $terms_update;
}
$request->set_param( 'context', 'edit' );
/**
* Fires after a single attachment is completely created or updated via the REST API.
*
* @since 5.0.0
*
* @param WP_Post $attachment Inserted or updated attachment object.
* @param WP_REST_Request $request Request object.
* @param bool $creating True when creating an attachment, false when updating.
*/
do_action( 'rest_after_insert_attachment', $attachment, $request, true );
wp_after_insert_post( $attachment, false, null );
if ( wp_is_serving_rest_request() ) {
/*
* Set a custom header with the attachment_id.
* Used by the browser/client to resume creating image sub-sizes after a PHP fatal error.
*/
header( 'X-WP-Upload-Attachment-ID: ' . $attachment_id );
}
// Include media and image functions to get access to wp_generate_attachment_metadata().
require_once ABSPATH . 'wp-admin/includes/media.php';
require_once ABSPATH . 'wp-admin/includes/image.php';
/*
* Post-process the upload (create image sub-sizes, make PDF thumbnails, etc.) and insert attachment meta.
* At this point the server may run out of resources and post-processing of uploaded images may fail.
*/
wp_update_attachment_metadata( $attachment_id, wp_generate_attachment_metadata( $attachment_id, $file ) );
$response = $this->prepare_item_for_response( $attachment, $request );
$response = rest_ensure_response( $response );
$response->set_status( 201 );
$response->header( 'Location', rest_url( sprintf( '%s/%s/%d', $this->namespace, $this->rest_base, $attachment_id ) ) );
return $response;
}
/**
* Inserts the attachment post in the database. Does not update the attachment meta.
*
* @since 5.3.0
*
* @param WP_REST_Request $request
* @return array|WP_Error
*/
protected function insert_attachment( $request ) {
// Get the file via $_FILES or raw data.
$files = $request->get_file_params();
$headers = $request->get_headers();
$time = null;
// Matches logic in media_handle_upload().
if ( ! empty( $request['post'] ) ) {
$post = get_post( $request['post'] );
// The post date doesn't usually matter for pages, so don't backdate this upload.
if ( $post && 'page' !== $post->post_type && substr( $post->post_date, 0, 4 ) > 0 ) {
$time = $post->post_date;
}
}
if ( ! empty( $files ) ) {
$file = $this->upload_from_file( $files, $headers, $time );
} else {
$file = $this->upload_from_data( $request->get_body(), $headers, $time );
}
if ( is_wp_error( $file ) ) {
return $file;
}
$name = wp_basename( $file['file'] );
$name_parts = pathinfo( $name );
$name = trim( substr( $name, 0, -( 1 + strlen( $name_parts['extension'] ) ) ) );
$url = $file['url'];
$type = $file['type'];
$file = $file['file'];
// Include image functions to get access to wp_read_image_metadata().
require_once ABSPATH . 'wp-admin/includes/image.php';
// Use image exif/iptc data for title and caption defaults if possible.
$image_meta = wp_read_image_metadata( $file );
if ( ! empty( $image_meta ) ) {
if ( empty( $request['title'] ) && trim( $image_meta['title'] ) && ! is_numeric( sanitize_title( $image_meta['title'] ) ) ) {
$request['title'] = $image_meta['title'];
}
if ( empty( $request['caption'] ) && trim( $image_meta['caption'] ) ) {
$request['caption'] = $image_meta['caption'];
}
}
$attachment = $this->prepare_item_for_database( $request );
$attachment->post_mime_type = $type;
$attachment->guid = $url;
// If the title was not set, use the original filename.
if ( empty( $attachment->post_title ) && ! empty( $files['file']['name'] ) ) {
// Remove the file extension (after the last `.`)
$tmp_title = substr( $files['file']['name'], 0, strrpos( $files['file']['name'], '.' ) );
if ( ! empty( $tmp_title ) ) {
$attachment->post_title = $tmp_title;
}
}
// Fall back to the original approach.
if ( empty( $attachment->post_title ) ) {
$attachment->post_title = preg_replace( '/\.[^.]+$/', '', wp_basename( $file ) );
}
// $post_parent is inherited from $attachment['post_parent'].
$id = wp_insert_attachment( wp_slash( (array) $attachment ), $file, 0, true, false );
if ( is_wp_error( $id ) ) {
if ( 'db_update_error' === $id->get_error_code() ) {
$id->add_data( array( 'status' => 500 ) );
} else {
$id->add_data( array( 'status' => 400 ) );
}
return $id;
}
$attachment = get_post( $id );
/**
* Fires after a single attachment is created or updated via the REST API.
*
* @since 4.7.0
*
* @param WP_Post $attachment Inserted or updated attachment
* object.
* @param WP_REST_Request $request The request sent to the API.
* @param bool $creating True when creating an attachment, false when updating.
*/
do_action( 'rest_insert_attachment', $attachment, $request, true );
return array(
'attachment_id' => $id,
'file' => $file,
);
}
/**
* Determines the featured media based on a request param.
*
* @since 6.5.0
*
* @param int $featured_media Featured Media ID.
* @param int $post_id Post ID.
* @return bool|WP_Error Whether the post thumbnail was successfully deleted, otherwise WP_Error.
*/
protected function handle_featured_media( $featured_media, $post_id ) {
$post_type = get_post_type( $post_id );
$thumbnail_support = current_theme_supports( 'post-thumbnails', $post_type ) && post_type_supports( $post_type, 'thumbnail' );
// Similar check as in wp_insert_post().
if ( ! $thumbnail_support && get_post_mime_type( $post_id ) ) {
if ( wp_attachment_is( 'audio', $post_id ) ) {
$thumbnail_support = post_type_supports( 'attachment:audio', 'thumbnail' ) || current_theme_supports( 'post-thumbnails', 'attachment:audio' );
} elseif ( wp_attachment_is( 'video', $post_id ) ) {
$thumbnail_support = post_type_supports( 'attachment:video', 'thumbnail' ) || current_theme_supports( 'post-thumbnails', 'attachment:video' );
}
}
if ( $thumbnail_support ) {
return parent::handle_featured_media( $featured_media, $post_id );
}
return new WP_Error(
'rest_no_featured_media',
sprintf(
/* translators: %s: attachment mime type */
__( 'This site does not support post thumbnails on attachments with MIME type %s.' ),
get_post_mime_type( $post_id )
),
array( 'status' => 400 )
);
}
/**
* Updates a single attachment.
*
* @since 4.7.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, WP_Error object on failure.
*/
public function update_item( $request ) {
if ( ! empty( $request['post'] ) && in_array( get_post_type( $request['post'] ), array( 'revision', 'attachment' ), true ) ) {
return new WP_Error(
'rest_invalid_param',
__( 'Invalid parent type.' ),
array( 'status' => 400 )
);
}
$attachment_before = get_post( $request['id'] );
$response = parent::update_item( $request );
if ( is_wp_error( $response ) ) {
return $response;
}
$response = rest_ensure_response( $response );
$data = $response->get_data();
if ( isset( $request['alt_text'] ) ) {
update_post_meta( $data['id'], '_wp_attachment_image_alt', $request['alt_text'] );
}
$attachment = get_post( $request['id'] );
if ( ! empty( $schema['properties']['featured_media'] ) && isset( $request['featured_media'] ) ) {
$thumbnail_update = $this->handle_featured_media( $request['featured_media'], $attachment->ID );
if ( is_wp_error( $thumbnail_update ) ) {
return $thumbnail_update;
}
}
$fields_update = $this->update_additional_fields_for_object( $attachment, $request );
if ( is_wp_error( $fields_update ) ) {
return $fields_update;
}
$request->set_param( 'context', 'edit' );
/** This action is documented in wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php */
do_action( 'rest_after_insert_attachment', $attachment, $request, false );
wp_after_insert_post( $attachment, true, $attachment_before );
$response = $this->prepare_item_for_response( $attachment, $request );
$response = rest_ensure_response( $response );
return $response;
}
/**
* Performs post processing on an attachment.
*
* @since 5.3.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, WP_Error object on failure.
*/
public function post_process_item( $request ) {
switch ( $request['action'] ) {
case 'create-image-subsizes':
require_once ABSPATH . 'wp-admin/includes/image.php';
wp_update_image_subsizes( $request['id'] );
break;
}
$request['context'] = 'edit';
return $this->prepare_item_for_response( get_post( $request['id'] ), $request );
}
/**
* Checks if a given request can perform post processing on an attachment.
*
* @since 5.3.0
*
* @param WP_REST_Request $request Full details about the request.
* @return true|WP_Error True if the request has access to update the item, WP_Error object otherwise.
*/
public function post_process_item_permissions_check( $request ) {
return $this->update_item_permissions_check( $request );
}
/**
* Checks if a given request has access to editing media.
*
* @since 5.5.0
*
* @param WP_REST_Request $request Full details about the request.
* @return true|WP_Error True if the request has read access, WP_Error object otherwise.
*/
public function edit_media_item_permissions_check( $request ) {
if ( ! current_user_can( 'upload_files' ) ) {
return new WP_Error(
'rest_cannot_edit_image',
__( 'Sorry, you are not allowed to upload media on this site.' ),
array( 'status' => rest_authorization_required_code() )
);
}
return $this->update_item_permissions_check( $request );
}
/**
* Applies edits to a media item and creates a new attachment record.
*
* @since 5.5.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, WP_Error object on failure.
*/
public function edit_media_item( $request ) {
require_once ABSPATH . 'wp-admin/includes/image.php';
$attachment_id = $request['id'];
// This also confirms the attachment is an image.
$image_file = wp_get_original_image_path( $attachment_id );
$image_meta = wp_get_attachment_metadata( $attachment_id );
if (
! $image_meta ||
! $image_file ||
! wp_image_file_matches_image_meta( $request['src'], $image_meta, $attachment_id )
) {
return new WP_Error(
'rest_unknown_attachment',
__( 'Unable to get meta information for file.' ),
array( 'status' => 404 )
);
}
$supported_types = array( 'image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/avif' );
$mime_type = get_post_mime_type( $attachment_id );
if ( ! in_array( $mime_type, $supported_types, true ) ) {
return new WP_Error(
'rest_cannot_edit_file_type',
__( 'This type of file cannot be edited.' ),
array( 'status' => 400 )
);
}
// The `modifiers` param takes precedence over the older format.
if ( isset( $request['modifiers'] ) ) {
$modifiers = $request['modifiers'];
} else {
$modifiers = array();
if ( ! empty( $request['rotation'] ) ) {
$modifiers[] = array(
'type' => 'rotate',
'args' => array(
'angle' => $request['rotation'],
),
);
}
if ( isset( $request['x'], $request['y'], $request['width'], $request['height'] ) ) {
$modifiers[] = array(
'type' => 'crop',
'args' => array(
'left' => $request['x'],
'top' => $request['y'],
'width' => $request['width'],
'height' => $request['height'],
),
);
}
if ( 0 === count( $modifiers ) ) {
return new WP_Error(
'rest_image_not_edited',
__( 'The image was not edited. Edit the image before applying the changes.' ),
array( 'status' => 400 )
);
}
}
/*
* If the file doesn't exist, attempt a URL fopen on the src link.
* This can occur with certain file replication plugins.
* Keep the original file path to get a modified name later.
*/
$image_file_to_edit = $image_file;
if ( ! file_exists( $image_file_to_edit ) ) {
$image_file_to_edit = _load_image_to_edit_path( $attachment_id );
}
$image_editor = wp_get_image_editor( $image_file_to_edit );
if ( is_wp_error( $image_editor ) ) {
return new WP_Error(
'rest_unknown_image_file_type',
__( 'Unable to edit this image.' ),
array( 'status' => 500 )
);
}
foreach ( $modifiers as $modifier ) {
$args = $modifier['args'];
switch ( $modifier['type'] ) {
case 'rotate':
// Rotation direction: clockwise vs. counter clockwise.
$rotate = 0 - $args['angle'];
if ( 0 !== $rotate ) {
$result = $image_editor->rotate( $rotate );
if ( is_wp_error( $result ) ) {
return new WP_Error(
'rest_image_rotation_failed',
__( 'Unable to rotate this image.' ),
array( 'status' => 500 )
);
}
}
break;
case 'crop':
$size = $image_editor->get_size();
$crop_x = (int) round( ( $size['width'] * $args['left'] ) / 100.0 );
$crop_y = (int) round( ( $size['height'] * $args['top'] ) / 100.0 );
$width = (int) round( ( $size['width'] * $args['width'] ) / 100.0 );
$height = (int) round( ( $size['height'] * $args['height'] ) / 100.0 );
if ( $size['width'] !== $width || $size['height'] !== $height ) {
$result = $image_editor->crop( $crop_x, $crop_y, $width, $height );
if ( is_wp_error( $result ) ) {
return new WP_Error(
'rest_image_crop_failed',
__( 'Unable to crop this image.' ),
array( 'status' => 500 )
);
}
}
break;
}
}
// Calculate the file name.
$image_ext = pathinfo( $image_file, PATHINFO_EXTENSION );
$image_name = wp_basename( $image_file, ".{$image_ext}" );
/*
* Do not append multiple `-edited` to the file name.
* The user may be editing a previously edited image.
*/
if ( preg_match( '/-edited(-\d+)?$/', $image_name ) ) {
// Remove any `-1`, `-2`, etc. `wp_unique_filename()` will add the proper number.
$image_name = preg_replace( '/-edited(-\d+)?$/', '-edited', $image_name );
} else {
// Append `-edited` before the extension.
$image_name .= '-edited';
}
$filename = "{$image_name}.{$image_ext}";
// Create the uploads sub-directory if needed.
$uploads = wp_upload_dir();
// Make the file name unique in the (new) upload directory.
$filename = wp_unique_filename( $uploads['path'], $filename );
// Save to disk.
$saved = $image_editor->save( $uploads['path'] . "/$filename" );
if ( is_wp_error( $saved ) ) {
return $saved;
}
// Create new attachment post.
$new_attachment_post = array(
'post_mime_type' => $saved['mime-type'],
'guid' => $uploads['url'] . "/$filename",
'post_title' => $image_name,
'post_content' => '',
);
// Copy post_content, post_excerpt, and post_title from the edited image's attachment post.
$attachment_post = get_post( $attachment_id );
if ( $attachment_post ) {
$new_attachment_post['post_content'] = $attachment_post->post_content;
$new_attachment_post['post_excerpt'] = $attachment_post->post_excerpt;
$new_attachment_post['post_title'] = $attachment_post->post_title;
}
$new_attachment_id = wp_insert_attachment( wp_slash( $new_attachment_post ), $saved['path'], 0, true );
if ( is_wp_error( $new_attachment_id ) ) {
if ( 'db_update_error' === $new_attachment_id->get_error_code() ) {
$new_attachment_id->add_data( array( 'status' => 500 ) );
} else {
$new_attachment_id->add_data( array( 'status' => 400 ) );
}
return $new_attachment_id;
}
// Copy the image alt text from the edited image.
$image_alt = get_post_meta( $attachment_id, '_wp_attachment_image_alt', true );
if ( ! empty( $image_alt ) ) {
// update_post_meta() expects slashed.
update_post_meta( $new_attachment_id, '_wp_attachment_image_alt', wp_slash( $image_alt ) );
}
if ( wp_is_serving_rest_request() ) {
/*
* Set a custom header with the attachment_id.
* Used by the browser/client to resume creating image sub-sizes after a PHP fatal error.
*/
header( 'X-WP-Upload-Attachment-ID: ' . $new_attachment_id );
}
// Generate image sub-sizes and meta.
$new_image_meta = wp_generate_attachment_metadata( $new_attachment_id, $saved['path'] );
// Copy the EXIF metadata from the original attachment if not generated for the edited image.
if ( isset( $image_meta['image_meta'] ) && isset( $new_image_meta['image_meta'] ) && is_array( $new_image_meta['image_meta'] ) ) {
// Merge but skip empty values.
foreach ( (array) $image_meta['image_meta'] as $key => $value ) {
if ( empty( $new_image_meta['image_meta'][ $key ] ) && ! empty( $value ) ) {
$new_image_meta['image_meta'][ $key ] = $value;
}
}
}
// Reset orientation. At this point the image is edited and orientation is correct.
if ( ! empty( $new_image_meta['image_meta']['orientation'] ) ) {
$new_image_meta['image_meta']['orientation'] = 1;
}
// The attachment_id may change if the site is exported and imported.
$new_image_meta['parent_image'] = array(
'attachment_id' => $attachment_id,
// Path to the originally uploaded image file relative to the uploads directory.
'file' => _wp_relative_upload_path( $image_file ),
);
/**
* Filters the meta data for the new image created by editing an existing image.
*
* @since 5.5.0
*
* @param array $new_image_meta Meta data for the new image.
* @param int $new_attachment_id Attachment post ID for the new image.
* @param int $attachment_id Attachment post ID for the edited (parent) image.
*/
$new_image_meta = apply_filters( 'wp_edited_image_metadata', $new_image_meta, $new_attachment_id, $attachment_id );
wp_update_attachment_metadata( $new_attachment_id, $new_image_meta );
$response = $this->prepare_item_for_response( get_post( $new_attachment_id ), $request );
$response->set_status( 201 );
$response->header( 'Location', rest_url( sprintf( '%s/%s/%s', $this->namespace, $this->rest_base, $new_attachment_id ) ) );
return $response;
}
/**
* Prepares a single attachment for create or update.
*
* @since 4.7.0
*
* @param WP_REST_Request $request Request object.
* @return stdClass|WP_Error Post object.
*/
protected function prepare_item_for_database( $request ) {
$prepared_attachment = parent::prepare_item_for_database( $request );
// Attachment caption (post_excerpt internally).
if ( isset( $request['caption'] ) ) {
if ( is_string( $request['caption'] ) ) {
$prepared_attachment->post_excerpt = $request['caption'];
} elseif ( isset( $request['caption']['raw'] ) ) {
$prepared_attachment->post_excerpt = $request['caption']['raw'];
}
}
// Attachment description (post_content internally).
if ( isset( $request['description'] ) ) {
if ( is_string( $request['description'] ) ) {
$prepared_attachment->post_content = $request['description'];
} elseif ( isset( $request['description']['raw'] ) ) {
$prepared_attachment->post_content = $request['description']['raw'];
}
}
if ( isset( $request['post'] ) ) {
$prepared_attachment->post_parent = (int) $request['post'];
}
return $prepared_attachment;
}
/**
* Prepares a single attachment output for response.
*
* @since 4.7.0
* @since 5.9.0 Renamed `$post` to `$item` to match parent class for PHP 8 named parameter support.
*
* @param WP_Post $item Attachment object.
* @param WP_REST_Request $request Request object.
* @return WP_REST_Response Response object.
*/
public function prepare_item_for_response( $item, $request ) {
// Restores the more descriptive, specific name for use within this method.
$post = $item;
$response = parent::prepare_item_for_response( $post, $request );
$fields = $this->get_fields_for_response( $request );
$data = $response->get_data();
if ( in_array( 'description', $fields, true ) ) {
$data['description'] = array(
'raw' => $post->post_content,
/** This filter is documented in wp-includes/post-template.php */
'rendered' => apply_filters( 'the_content', $post->post_content ),
);
}
if ( in_array( 'caption', $fields, true ) ) {
/** This filter is documented in wp-includes/post-template.php */
$caption = apply_filters( 'get_the_excerpt', $post->post_excerpt, $post );
/** This filter is documented in wp-includes/post-template.php */
$caption = apply_filters( 'the_excerpt', $caption );
$data['caption'] = array(
'raw' => $post->post_excerpt,
'rendered' => $caption,
);
}
if ( in_array( 'alt_text', $fields, true ) ) {
$data['alt_text'] = get_post_meta( $post->ID, '_wp_attachment_image_alt', true );
}
if ( in_array( 'media_type', $fields, true ) ) {
$data['media_type'] = wp_attachment_is_image( $post->ID ) ? 'image' : 'file';
}
if ( in_array( 'mime_type', $fields, true ) ) {
$data['mime_type'] = $post->post_mime_type;
}
if ( in_array( 'media_details', $fields, true ) ) {
$data['media_details'] = wp_get_attachment_metadata( $post->ID );
// Ensure empty details is an empty object.
if ( empty( $data['media_details'] ) ) {
$data['media_details'] = new stdClass();
} elseif ( ! empty( $data['media_details']['sizes'] ) ) {
foreach ( $data['media_details']['sizes'] as $size => &$size_data ) {
if ( isset( $size_data['mime-type'] ) ) {
$size_data['mime_type'] = $size_data['mime-type'];
unset( $size_data['mime-type'] );
}
// Use the same method image_downsize() does.
$image_src = wp_get_attachment_image_src( $post->ID, $size );
if ( ! $image_src ) {
continue;
}
$size_data['source_url'] = $image_src[0];
}
$full_src = wp_get_attachment_image_src( $post->ID, 'full' );
if ( ! empty( $full_src ) ) {
$data['media_details']['sizes']['full'] = array(
'file' => wp_basename( $full_src[0] ),
'width' => $full_src[1],
'height' => $full_src[2],
'mime_type' => $post->post_mime_type,
'source_url' => $full_src[0],
);
}
} else {
$data['media_details']['sizes'] = new stdClass();
}
}
if ( in_array( 'post', $fields, true ) ) {
$data['post'] = ! empty( $post->post_parent ) ? (int) $post->post_parent : null;
}
if ( in_array( 'source_url', $fields, true ) ) {
$data['source_url'] = wp_get_attachment_url( $post->ID );
}
if ( in_array( 'missing_image_sizes', $fields, true ) ) {
require_once ABSPATH . 'wp-admin/includes/image.php';
$data['missing_image_sizes'] = array_keys( wp_get_missing_image_subsizes( $post->ID ) );
}
$context = ! empty( $request['context'] ) ? $request['context'] : 'view';
$data = $this->filter_response_by_context( $data, $context );
$links = $response->get_links();
// Wrap the data in a response object.
$response = rest_ensure_response( $data );
foreach ( $links as $rel => $rel_links ) {
foreach ( $rel_links as $link ) {
$response->add_link( $rel, $link['href'], $link['attributes'] );
}
}
/**
* Filters an attachment returned from the REST API.
*
* Allows modification of the attachment right before it is returned.
*
* @since 4.7.0
*
* @param WP_REST_Response $response The response object.
* @param WP_Post $post The original attachment post.
* @param WP_REST_Request $request Request used to generate the response.
*/
return apply_filters( 'rest_prepare_attachment', $response, $post, $request );
}
/**
* Retrieves the attachment's schema, conforming to JSON Schema.
*
* @since 4.7.0
*
* @return array Item schema as an array.
*/
public function get_item_schema() {
if ( $this->schema ) {
return $this->add_additional_fields_schema( $this->schema );
}
$schema = parent::get_item_schema();
$schema['properties']['alt_text'] = array(
'description' => __( 'Alternative text to display when attachment is not displayed.' ),
'type' => 'string',
'context' => array( 'view', 'edit', 'embed' ),
'arg_options' => array(
'sanitize_callback' => 'sanitize_text_field',
),
);
$schema['properties']['caption'] = array(
'description' => __( 'The attachment caption.' ),
'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' => __( 'Caption for the attachment, as it exists in the database.' ),
'type' => 'string',
'context' => array( 'edit' ),
),
'rendered' => array(
'description' => __( 'HTML caption for the attachment, transformed for display.' ),
'type' => 'string',
'context' => array( 'view', 'edit', 'embed' ),
'readonly' => true,
),
),
);
$schema['properties']['description'] = array(
'description' => __( 'The attachment description.' ),
'type' => 'object',
'context' => array( 'view', 'edit' ),
'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' => __( 'Description for the attachment, as it exists in the database.' ),
'type' => 'string',
'context' => array( 'edit' ),
),
'rendered' => array(
'description' => __( 'HTML description for the attachment, transformed for display.' ),
'type' => 'string',
'context' => array( 'view', 'edit' ),
'readonly' => true,
),
),
);
$schema['properties']['media_type'] = array(
'description' => __( 'Attachment type.' ),
'type' => 'string',
'enum' => array( 'image', 'file' ),
'context' => array( 'view', 'edit', 'embed' ),
'readonly' => true,
);
$schema['properties']['mime_type'] = array(
'description' => __( 'The attachment MIME type.' ),
'type' => 'string',
'context' => array( 'view', 'edit', 'embed' ),
'readonly' => true,
);
$schema['properties']['media_details'] = array(
'description' => __( 'Details about the media file, specific to its type.' ),
'type' => 'object',
'context' => array( 'view', 'edit', 'embed' ),
'readonly' => true,
);
$schema['properties']['post'] = array(
'description' => __( 'The ID for the associated post of the attachment.' ),
'type' => 'integer',
'context' => array( 'view', 'edit' ),
);
$schema['properties']['source_url'] = array(
'description' => __( 'URL to the original attachment file.' ),
'type' => 'string',
'format' => 'uri',
'context' => array( 'view', 'edit', 'embed' ),
'readonly' => true,
);
$schema['properties']['missing_image_sizes'] = array(
'description' => __( 'List of the missing image sizes of the attachment.' ),
'type' => 'array',
'items' => array( 'type' => 'string' ),
'context' => array( 'edit' ),
'readonly' => true,
);
unset( $schema['properties']['password'] );
$this->schema = $schema;
return $this->add_additional_fields_schema( $this->schema );
}
/**
* Handles an upload via raw POST data.
*
* @since 4.7.0
* @since 6.6.0 Added the `$time` parameter.
*
* @param string $data Supplied file data.
* @param array $headers HTTP headers from the request.
* @param string|null $time Optional. Time formatted in 'yyyy/mm'. Default null.
* @return array|WP_Error Data from wp_handle_sideload().
*/
protected function upload_from_data( $data, $headers, $time = null ) {
if ( empty( $data ) ) {
return new WP_Error(
'rest_upload_no_data',
__( 'No data supplied.' ),
array( 'status' => 400 )
);
}
if ( empty( $headers['content_type'] ) ) {
return new WP_Error(
'rest_upload_no_content_type',
__( 'No Content-Type supplied.' ),
array( 'status' => 400 )
);
}
if ( empty( $headers['content_disposition'] ) ) {
return new WP_Error(
'rest_upload_no_content_disposition',
__( 'No Content-Disposition supplied.' ),
array( 'status' => 400 )
);
}
$filename = self::get_filename_from_disposition( $headers['content_disposition'] );
if ( empty( $filename ) ) {
return new WP_Error(
'rest_upload_invalid_disposition',
__( 'Invalid Content-Disposition supplied. Content-Disposition needs to be formatted as `attachment; filename="image.png"` or similar.' ),
array( 'status' => 400 )
);
}
if ( ! empty( $headers['content_md5'] ) ) {
$content_md5 = array_shift( $headers['content_md5'] );
$expected = trim( $content_md5 );
$actual = md5( $data );
if ( $expected !== $actual ) {
return new WP_Error(
'rest_upload_hash_mismatch',
__( 'Content hash did not match expected.' ),
array( 'status' => 412 )
);
}
}
// Get the content-type.
$type = array_shift( $headers['content_type'] );
// Include filesystem functions to get access to wp_tempnam() and wp_handle_sideload().
require_once ABSPATH . 'wp-admin/includes/file.php';
// Save the file.
$tmpfname = wp_tempnam( $filename );
$fp = fopen( $tmpfname, 'w+' );
if ( ! $fp ) {
return new WP_Error(
'rest_upload_file_error',
__( 'Could not open file handle.' ),
array( 'status' => 500 )
);
}
fwrite( $fp, $data );
fclose( $fp );
// Now, sideload it in.
$file_data = array(
'error' => null,
'tmp_name' => $tmpfname,
'name' => $filename,
'type' => $type,
);
$size_check = self::check_upload_size( $file_data );
if ( is_wp_error( $size_check ) ) {
return $size_check;
}
$overrides = array(
'test_form' => false,
);
$sideloaded = wp_handle_sideload( $file_data, $overrides, $time );
if ( isset( $sideloaded['error'] ) ) {
@unlink( $tmpfname );
return new WP_Error(
'rest_upload_sideload_error',
$sideloaded['error'],
array( 'status' => 500 )
);
}
return $sideloaded;
}
/**
* Parses filename from a Content-Disposition header value.
*
* As per RFC6266:
*
* content-disposition = "Content-Disposition" ":"
* disposition-type *( ";" disposition-parm )
*
* disposition-type = "inline" | "attachment" | disp-ext-type
* ; case-insensitive
* disp-ext-type = token
*
* disposition-parm = filename-parm | disp-ext-parm
*
* filename-parm = "filename" "=" value
* | "filename*" "=" ext-value
*
* disp-ext-parm = token "=" value
* | ext-token "=" ext-value
* ext-token =
*
* @since 4.7.0
*
* @link https://tools.ietf.org/html/rfc2388
* @link https://tools.ietf.org/html/rfc6266
*
* @param string[] $disposition_header List of Content-Disposition header values.
* @return string|null Filename if available, or null if not found.
*/
public static function get_filename_from_disposition( $disposition_header ) {
// Get the filename.
$filename = null;
foreach ( $disposition_header as $value ) {
$value = trim( $value );
if ( ! str_contains( $value, ';' ) ) {
continue;
}
list( $type, $attr_parts ) = explode( ';', $value, 2 );
$attr_parts = explode( ';', $attr_parts );
$attributes = array();
foreach ( $attr_parts as $part ) {
if ( ! str_contains( $part, '=' ) ) {
continue;
}
list( $key, $value ) = explode( '=', $part, 2 );
$attributes[ trim( $key ) ] = trim( $value );
}
if ( empty( $attributes['filename'] ) ) {
continue;
}
$filename = trim( $attributes['filename'] );
// Unquote quoted filename, but after trimming.
if ( str_starts_with( $filename, '"' ) && str_ends_with( $filename, '"' ) ) {
$filename = substr( $filename, 1, -1 );
}
}
return $filename;
}
/**
* Retrieves the query params for collections of attachments.
*
* @since 4.7.0
*
* @return array Query parameters for the attachment collection as an array.
*/
public function get_collection_params() {
$params = parent::get_collection_params();
$params['status']['default'] = 'inherit';
$params['status']['items']['enum'] = array( 'inherit', 'private', 'trash' );
$media_types = $this->get_media_types();
$params['media_type'] = array(
'default' => null,
'description' => __( 'Limit result set to attachments of a particular media type.' ),
'type' => 'string',
'enum' => array_keys( $media_types ),
);
$params['mime_type'] = array(
'default' => null,
'description' => __( 'Limit result set to attachments of a particular MIME type.' ),
'type' => 'string',
);
return $params;
}
/**
* Handles an upload via multipart/form-data ($_FILES).
*
* @since 4.7.0
* @since 6.6.0 Added the `$time` parameter.
*
* @param array $files Data from the `$_FILES` superglobal.
* @param array $headers HTTP headers from the request.
* @param string|null $time Optional. Time formatted in 'yyyy/mm'. Default null.
* @return array|WP_Error Data from wp_handle_upload().
*/
protected function upload_from_file( $files, $headers, $time = null ) {
if ( empty( $files ) ) {
return new WP_Error(
'rest_upload_no_data',
__( 'No data supplied.' ),
namespace = 'wp/v2';
$this->rest_base = 'users/(?P(?:[\d]+|me))/application-passwords';
}
/**
* Registers the REST API routes for the application passwords controller.
*
* @since 5.6.0
*/
public function register_routes() {
register_rest_route(
$this->namespace,
'/' . $this->rest_base,
array(
array(
'methods' => WP_REST_Server::READABLE,
'callback' => array( $this, 'get_items' ),
'permission_callback' => array( $this, 'get_items_permissions_check' ),
'args' => $this->get_collection_params(),
),
array(
'methods' => WP_REST_Server::CREATABLE,
'callback' => array( $this, 'create_item' ),
'permission_callback' => array( $this, 'create_item_permissions_check' ),
'args' => $this->get_endpoint_args_for_item_schema(),
),
array(
'methods' => WP_REST_Server::DELETABLE,
'callback' => array( $this, 'delete_items' ),
'permission_callback' => array( $this, 'delete_items_permissions_check' ),
),
'schema' => array( $this, 'get_public_item_schema' ),
)
);
register_rest_route(
$this->namespace,
'/' . $this->rest_base . '/introspect',
array(
array(
'methods' => WP_REST_Server::READABLE,
'callback' => array( $this, 'get_current_item' ),
'permission_callback' => array( $this, 'get_current_item_permissions_check' ),
'args' => array(
'context' => $this->get_context_param( array( 'default' => 'view' ) ),
),
),
'schema' => array( $this, 'get_public_item_schema' ),
)
);
register_rest_route(
$this->namespace,
'/' . $this->rest_base . '/(?P[\w\-]+)',
array(
array(
'methods' => WP_REST_Server::READABLE,
'callback' => array( $this, 'get_item' ),
'permission_callback' => array( $this, 'get_item_permissions_check' ),
'args' => array(
'context' => $this->get_context_param( array( 'default' => 'view' ) ),
),
),
array(
'methods' => WP_REST_Server::EDITABLE,
'callback' => array( $this, 'update_item' ),
'permission_callback' => array( $this, 'update_item_permissions_check' ),
'args' => $this->get_endpoint_args_for_item_schema( WP_REST_Server::EDITABLE ),
),
array(
'methods' => WP_REST_Server::DELETABLE,
'callback' => array( $this, 'delete_item' ),
'permission_callback' => array( $this, 'delete_item_permissions_check' ),
),
'schema' => array( $this, 'get_public_item_schema' ),
)
);
}
/**
* Checks if a given request has access to get application passwords.
*
* @since 5.6.0
*
* @param WP_REST_Request $request Full details about the request.
* @return true|WP_Error True if the request has read access, WP_Error object otherwise.
*/
public function get_items_permissions_check( $request ) {
$user = $this->get_user( $request );
if ( is_wp_error( $user ) ) {
return $user;
}
if ( ! current_user_can( 'list_app_passwords', $user->ID ) ) {
return new WP_Error(
'rest_cannot_list_application_passwords',
__( 'Sorry, you are not allowed to list application passwords for this user.' ),
array( 'status' => rest_authorization_required_code() )
);
}
return true;
}
/**
* Retrieves a collection of application passwords.
*
* @since 5.6.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function get_items( $request ) {
$user = $this->get_user( $request );
if ( is_wp_error( $user ) ) {
return $user;
}
$passwords = WP_Application_Passwords::get_user_application_passwords( $user->ID );
$response = array();
foreach ( $passwords as $password ) {
$response[] = $this->prepare_response_for_collection(
$this->prepare_item_for_response( $password, $request )
);
}
return new WP_REST_Response( $response );
}
/**
* Checks if a given request has access to get a specific application password.
*
* @since 5.6.0
*
* @param WP_REST_Request $request Full details about the request.
* @return true|WP_Error True if the request has read access for the item, WP_Error object otherwise.
*/
public function get_item_permissions_check( $request ) {
$user = $this->get_user( $request );
if ( is_wp_error( $user ) ) {
return $user;
}
if ( ! current_user_can( 'read_app_password', $user->ID, $request['uuid'] ) ) {
return new WP_Error(
'rest_cannot_read_application_password',
__( 'Sorry, you are not allowed to read this application password.' ),
array( 'status' => rest_authorization_required_code() )
);
}
return true;
}
/**
* Retrieves one application password from the collection.
*
* @since 5.6.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function get_item( $request ) {
$password = $this->get_application_password( $request );
if ( is_wp_error( $password ) ) {
return $password;
}
return $this->prepare_item_for_response( $password, $request );
}
/**
* Checks if a given request has access to create application passwords.
*
* @since 5.6.0
*
* @param WP_REST_Request $request Full details about the request.
* @return true|WP_Error True if the request has access to create items, WP_Error object otherwise.
*/
public function create_item_permissions_check( $request ) {
$user = $this->get_user( $request );
if ( is_wp_error( $user ) ) {
return $user;
}
if ( ! current_user_can( 'create_app_password', $user->ID ) ) {
return new WP_Error(
'rest_cannot_create_application_passwords',
__( 'Sorry, you are not allowed to create application passwords for this user.' ),
array( 'status' => rest_authorization_required_code() )
);
}
return true;
}
/**
* Creates an application password.
*
* @since 5.6.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function create_item( $request ) {
$user = $this->get_user( $request );
if ( is_wp_error( $user ) ) {
return $user;
}
$prepared = $this->prepare_item_for_database( $request );
if ( is_wp_error( $prepared ) ) {
return $prepared;
}
$created = WP_Application_Passwords::create_new_application_password( $user->ID, wp_slash( (array) $prepared ) );
if ( is_wp_error( $created ) ) {
return $created;
}
$password = $created[0];
$item = WP_Application_Passwords::get_user_application_password( $user->ID, $created[1]['uuid'] );
$item['new_password'] = WP_Application_Passwords::chunk_password( $password );
$fields_update = $this->update_additional_fields_for_object( $item, $request );
if ( is_wp_error( $fields_update ) ) {
return $fields_update;
}
/**
* Fires after a single application password is completely created or updated via the REST API.
*
* @since 5.6.0
*
* @param array $item Inserted or updated password item.
* @param WP_REST_Request $request Request object.
* @param bool $creating True when creating an application password, false when updating.
*/
do_action( 'rest_after_insert_application_password', $item, $request, true );
$request->set_param( 'context', 'edit' );
$response = $this->prepare_item_for_response( $item, $request );
$response->set_status( 201 );
$response->header( 'Location', $response->get_links()['self'][0]['href'] );
return $response;
}
/**
* Checks if a given request has access to update application passwords.
*
* @since 5.6.0
*
* @param WP_REST_Request $request Full details about the request.
* @return true|WP_Error True if the request has access to create items, WP_Error object otherwise.
*/
public function update_item_permissions_check( $request ) {
$user = $this->get_user( $request );
if ( is_wp_error( $user ) ) {
return $user;
}
if ( ! current_user_can( 'edit_app_password', $user->ID, $request['uuid'] ) ) {
return new WP_Error(
'rest_cannot_edit_application_password',
__( 'Sorry, you are not allowed to edit this application password.' ),
array( 'status' => rest_authorization_required_code() )
);
}
return true;
}
/**
* Updates an application password.
*
* @since 5.6.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function update_item( $request ) {
$user = $this->get_user( $request );
if ( is_wp_error( $user ) ) {
return $user;
}
$item = $this->get_application_password( $request );
if ( is_wp_error( $item ) ) {
return $item;
}
$prepared = $this->prepare_item_for_database( $request );
if ( is_wp_error( $prepared ) ) {
return $prepared;
}
$saved = WP_Application_Passwords::update_application_password( $user->ID, $item['uuid'], wp_slash( (array) $prepared ) );
if ( is_wp_error( $saved ) ) {
return $saved;
}
$fields_update = $this->update_additional_fields_for_object( $item, $request );
if ( is_wp_error( $fields_update ) ) {
return $fields_update;
}
$item = WP_Application_Passwords::get_user_application_password( $user->ID, $item['uuid'] );
/** This action is documented in wp-includes/rest-api/endpoints/class-wp-rest-application-passwords-controller.php */
do_action( 'rest_after_insert_application_password', $item, $request, false );
$request->set_param( 'context', 'edit' );
return $this->prepare_item_for_response( $item, $request );
}
/**
* Checks if a given request has access to delete all application passwords for a user.
*
* @since 5.6.0
*
* @param WP_REST_Request $request Full details about the request.
* @return true|WP_Error True if the request has access to delete the item, WP_Error object otherwise.
*/
public function delete_items_permissions_check( $request ) {
$user = $this->get_user( $request );
if ( is_wp_error( $user ) ) {
return $user;
}
if ( ! current_user_can( 'delete_app_passwords', $user->ID ) ) {
return new WP_Error(
'rest_cannot_delete_application_passwords',
__( 'Sorry, you are not allowed to delete application passwords for this user.' ),
array( 'status' => rest_authorization_required_code() )
);
}
return true;
}
/**
* Deletes all application passwords for a user.
*
* @since 5.6.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function delete_items( $request ) {
$user = $this->get_user( $request );
if ( is_wp_error( $user ) ) {
return $user;
}
$deleted = WP_Application_Passwords::delete_all_application_passwords( $user->ID );
if ( is_wp_error( $deleted ) ) {
return $deleted;
}
return new WP_REST_Response(
array(
'deleted' => true,
'count' => $deleted,
)
);
}
/**
* Checks if a given request has access to delete a specific application password for a user.
*
* @since 5.6.0
*
* @param WP_REST_Request $request Full details about the request.
* @return true|WP_Error True if the request has access to delete the item, WP_Error object otherwise.
*/
public function delete_item_permissions_check( $request ) {
$user = $this->get_user( $request );
if ( is_wp_error( $user ) ) {
return $user;
}
if ( ! current_user_can( 'delete_app_password', $user->ID, $request['uuid'] ) ) {
return new WP_Error(
'rest_cannot_delete_application_password',
__( 'Sorry, you are not allowed to delete this application password.' ),
array( 'status' => rest_authorization_required_code() )
);
}
return true;
}
/**
* Deletes an application password for a user.
*
* @since 5.6.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function delete_item( $request ) {
$user = $this->get_user( $request );
if ( is_wp_error( $user ) ) {
return $user;
}
$password = $this->get_application_password( $request );
if ( is_wp_error( $password ) ) {
return $password;
}
$request->set_param( 'context', 'edit' );
$previous = $this->prepare_item_for_response( $password, $request );
$deleted = WP_Application_Passwords::delete_application_password( $user->ID, $password['uuid'] );
if ( is_wp_error( $deleted ) ) {
return $deleted;
}
return new WP_REST_Response(
array(
'deleted' => true,
'previous' => $previous->get_data(),
)
);
}
/**
* Checks if a given request has access to get the currently used application password for a user.
*
* @since 5.7.0
*
* @param WP_REST_Request $request Full details about the request.
* @return true|WP_Error True if the request has read access for the item, WP_Error object otherwise.
*/
public function get_current_item_permissions_check( $request ) {
$user = $this->get_user( $request );
if ( is_wp_error( $user ) ) {
return $user;
}
if ( get_current_user_id() !== $user->ID ) {
return new WP_Error(
'rest_cannot_introspect_app_password_for_non_authenticated_user',
__( 'The authenticated application password can only be introspected for the current user.' ),
array( 'status' => rest_authorization_required_code() )
);
}
return true;
}
/**
* Retrieves the application password being currently used for authentication of a user.
*
* @since 5.7.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function get_current_item( $request ) {
$user = $this->get_user( $request );
if ( is_wp_error( $user ) ) {
return $user;
}
$uuid = rest_get_authenticated_app_password();
if ( ! $uuid ) {
return new WP_Error(
'rest_no_authenticated_app_password',
__( 'Cannot introspect application password.' ),
array( 'status' => 404 )
);
}
$password = WP_Application_Passwords::get_user_application_password( $user->ID, $uuid );
if ( ! $password ) {
return new WP_Error(
'rest_application_password_not_found',
__( 'Application password not found.' ),
array( 'status' => 500 )
);
}
return $this->prepare_item_for_response( $password, $request );
}
/**
* Performs a permissions check for the request.
*
* @since 5.6.0
* @deprecated 5.7.0 Use `edit_user` directly or one of the specific meta capabilities introduced in 5.7.0.
*
* @param WP_REST_Request $request
* @return true|WP_Error
*/
protected function do_permissions_check( $request ) {
_deprecated_function( __METHOD__, '5.7.0' );
$user = $this->get_user( $request );
if ( is_wp_error( $user ) ) {
return $user;
}
if ( ! current_user_can( 'edit_user', $user->ID ) ) {
return new WP_Error(
'rest_cannot_manage_application_passwords',
__( 'Sorry, you are not allowed to manage application passwords for this user.' ),
array( 'status' => rest_authorization_required_code() )
);
}
return true;
}
/**
* Prepares an application password for a create or update operation.
*
* @since 5.6.0
*
* @param WP_REST_Request $request Request object.
* @return object|WP_Error The prepared item, or WP_Error object on failure.
*/
protected function prepare_item_for_database( $request ) {
$prepared = (object) array(
'name' => $request['name'],
);
if ( $request['app_id'] && ! $request['uuid'] ) {
$prepared->app_id = $request['app_id'];
}
/**
* Filters an application password before it is inserted via the REST API.
*
* @since 5.6.0
*
* @param stdClass $prepared An object representing a single application password prepared for inserting or updating the database.
* @param WP_REST_Request $request Request object.
*/
return apply_filters( 'rest_pre_insert_application_password', $prepared, $request );
}
/**
* Prepares the application password for the REST response.
*
* @since 5.6.0
*
* @param array $item WordPress representation of the item.
* @param WP_REST_Request $request Request object.
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function prepare_item_for_response( $item, $request ) {
$user = $this->get_user( $request );
if ( is_wp_error( $user ) ) {
return $user;
}
$fields = $this->get_fields_for_response( $request );
$prepared = array(
'uuid' => $item['uuid'],
'app_id' => empty( $item['app_id'] ) ? '' : $item['app_id'],
'name' => $item['name'],
'created' => gmdate( 'Y-m-d\TH:i:s', $item['created'] ),
'last_used' => $item['last_used'] ? gmdate( 'Y-m-d\TH:i:s', $item['last_used'] ) : null,
'last_ip' => $item['last_ip'] ? $item['last_ip'] : null,
);
if ( isset( $item['new_password'] ) ) {
$prepared['password'] = $item['new_password'];
}
$prepared = $this->add_additional_fields_to_object( $prepared, $request );
$prepared = $this->filter_response_by_context( $prepared, $request['context'] );
$response = new WP_REST_Response( $prepared );
if ( rest_is_field_included( '_links', $fields ) || rest_is_field_included( '_embedded', $fields ) ) {
$response->add_links( $this->prepare_links( $user, $item ) );
}
/**
* Filters the REST API response for an application password.
*
* @since 5.6.0
*
* @param WP_REST_Response $response The response object.
* @param array $item The application password array.
* @param WP_REST_Request $request The request object.
*/
return apply_filters( 'rest_prepare_application_password', $response, $item, $request );
}
/**
* Prepares links for the request.
*
* @since 5.6.0
*
* @param WP_User $user The requested user.
* @param array $item The application password.
* @return array The list of links.
*/
protected function prepare_links( WP_User $user, $item ) {
return array(
'self' => array(
'href' => rest_url(
sprintf(
'%s/users/%d/application-passwords/%s',
$this->namespace,
$user->ID,
$item['uuid']
)
),
),
);
}
/**
* Gets the requested user.
*
* @since 5.6.0
*
* @param WP_REST_Request $request The request object.
* @return WP_User|WP_Error The WordPress user associated with the request, or a WP_Error if none found.
*/
protected function get_user( $request ) {
if ( ! wp_is_application_passwords_available() ) {
return new WP_Error(
'application_passwords_disabled',
__( 'Application passwords are not available.' ),
array( 'status' => 501 )
);
}
$error = new WP_Error(
'rest_user_invalid_id',
__( 'Invalid user ID.' ),
array( 'status' => 404 )
);
$id = $request['user_id'];
if ( 'me' === $id ) {
if ( ! is_user_logged_in() ) {
return new WP_Error(
'rest_not_logged_in',
__( 'You are not currently logged in.' ),
array( 'status' => 401 )
);
}
$user = wp_get_current_user();
} else {
$id = (int) $id;
if ( $id <= 0 ) {
return $error;
}
$user = get_userdata( $id );
}
if ( empty( $user ) || ! $user->exists() ) {
return $error;
}
if ( is_multisite() && ! user_can( $user->ID, 'manage_sites' ) && ! is_user_member_of_blog( $user->ID ) ) {
return $error;
}
if ( ! wp_is_application_passwords_available_for_user( $user ) ) {
return new WP_Error(
'application_passwords_disabled_for_user',
__( 'Application passwords are not available for your account. Please contact the site administrator for assistance.' ),
array( 'status' => 501 )
);
}
return $user;
}
/**
* Gets the requested application password for a user.
*
* @since 5.6.0
*
* @param WP_REST_Request $request The request object.
* @return array|WP_Error The application password details if found, a WP_Error otherwise.
*/
protected function get_application_password( $request ) {
$user = $this->get_user( $request );
if ( is_wp_error( $user ) ) {
return $user;
}
$password = WP_Application_Passwords::get_user_application_password( $user->ID, $request['uuid'] );
if ( ! $password ) {
return new WP_Error(
'rest_application_password_not_found',
__( 'Application password not found.' ),
array( 'status' => 404 )
);
}
return $password;
}
/**
* Retrieves the query params for the collections.
*
* @since 5.6.0
*
* @return array Query parameters for the collection.
*/
public function get_collection_params() {
return array(
'context' => $this->get_context_param( array( 'default' => 'view' ) ),
);
}
/**
* Retrieves the application password's schema, conforming to JSON Schema.
*
* @since 5.6.0
*
* @return array Item schema data.
*/
public function get_item_schema() {
if ( $this->schema ) {
return $this->add_additional_fields_schema( $this->schema );
}
$this->schema = array(
'$schema' => 'http://json-schema.org/draft-04/schema#',
'title' => 'application-password',
'type' => 'object',
'properties' => array(
'uuid' => array(
'description' => __( 'The unique identifier for the application password.' ),
'type' => 'string',
'format' => 'uuid',
'context' => array( 'view', 'edit', 'embed' ),
'readonly' => true,
),
'app_id' => array(
'description' => __( 'A UUID provided by the application to uniquely identify it. It is recommended to use an UUID v5 with the URL or DNS namespace.' ),
'type' => 'string',
'format' => 'uuid',
'context' => array( 'view', 'edit', 'embed' ),
),
'name' => array(
'description' => __( 'The name of the application password.' ),
'type' => 'string',
'required' => true,
'context' => array( 'view', 'selective_refresh ) ? 'postMessage' : 'refresh';
// Icon
$wp_customize->add_setting(
'hdr_nav_contact_icon2',
array(
'default' => 'fa-hourglass-end',
'sanitize_callback' => 'specia_sanitize_html',
'capability' => 'edit_theme_options',
'priority' => 13,
)
);
$wp_customize->add_control(
'hdr_nav_contact_icon2',
array(
'label' => __('Icon','ferio'),
'type' => 'text',
'section' => 'hdr_nav_contact_info2',
)
);
// Title
$wp_customize->add_setting(
'hdr_nav_contact_ttl2',
array(
'sanitize_callback' => 'specia_sanitize_html',
'capability' => 'edit_theme_options',
'transport' => $selective_refresh,
'priority' => 14,
)
);
$wp_customize->add_control(
'hdr_nav_contact_ttl2',
array(
'label' => __('Title','ferio'),
'section' => 'hdr_nav_contact_info2',
'type' => 'text',
)
);
// Subtitle
$wp_customize->add_setting(
'hdr_nav_contact_subttl2',
array(
'sanitize_callback' => 'specia_sanitize_html',
'capability' => 'edit_theme_options',
'transport' => $selective_refresh,
'priority' => 15,
)
);
$wp_customize->add_control(
'hdr_nav_contact_subttl2',
array(
'label' => __('Subtitle','ferio'),
'section' => 'hdr_nav_contact_info2',
'type' => 'text',
)
);
// Link
$wp_customize->add_setting(
'hdr_nav_contact_link2',
array(
'sanitize_callback' => 'specia_sanitize_url',
'capability' => 'edit_theme_options',
'priority' => 16,
)
);
$wp_customize->add_control(
'hdr_nav_contact_link2',
array(
'label' => __('Link','ferio'),
'section' => 'hdr_nav_contact_info2',
'type' => 'text',
)
);
// Mobile Logo //
$wp_customize->add_setting(
'mobile_logo' ,
array(
'capability' => 'edit_theme_options',
'sanitize_callback' => 'specia_sanitize_url',
)
);