xt 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 $post Optional. Post to check. Defaults to the current post.
* @return bool True if the current post has any of the given terms
* (or any term, if no term specified). False otherwise.
*/
function has_term( $term = '', $taxonomy = '', $post = null ) {
$post = get_post( $post );
if ( ! $post ) {
return false;
}
$r = is_object_in_term( $post->ID, $taxonomy, $term );
if ( is_wp_error( $r ) ) {
return false;
}
return $r;
}
_family;
}
if (
$has_font_style_support &&
! $should_skip_font_style &&
isset( $block_attributes['style']['typography']['fontStyle'] )
) {
$typography_block_styles['fontStyle'] = wp_typography_get_preset_inline_style_value(
$block_attributes['style']['typography']['fontStyle'],
'font-style'
);
}
if (
$has_font_weight_support &&
! $should_skip_font_weight &&
isset( $block_attributes['style']['typography']['fontWeight'] )
) {
$typography_block_styles['fontWeight'] = wp_typography_get_preset_inline_style_value(
$block_attributes['style']['typography']['fontWeight'],
'font-weight'
);
}
if ( $has_line_height_support && ! $should_skip_line_height ) {
$typography_block_styles['lineHeight'] = isset( $block_attributes['style']['typography']['lineHeight'] )
? $block_attributes['style']['typography']['lineHeight']
: null;
}
if ( $has_text_align_support && ! $should_skip_text_align ) {
$typography_block_styles['textAlign'] = isset( $block_attributes['style']['typography']['textAlign'] )
? $block_attributes['style']['typography']['textAlign']
: null;
}
if ( $has_text_columns_support && ! $should_skip_text_columns && isset( $block_attributes['style']['typography']['textColumns'] ) ) {
$typography_block_styles['textColumns'] = isset( $block_attributes['style']['typography']['textColumns'] )
? $block_attributes['style']['typography']['textColumns']
: null;
}
if (
$has_text_decoration_support &&
! $should_skip_text_decoration &&
isset( $block_attributes['style']['typography']['textDecoration'] )
) {
$typography_block_styles['textDecoration'] = wp_typography_get_preset_inline_style_value(
$block_attributes['style']['typography']['textDecoration'],
'text-decoration'
);
}
if (
$has_text_transform_support &&
! $should_skip_text_transform &&
isset( $block_attributes['style']['typography']['textTransform'] )
) {
$typography_block_styles['textTransform'] = wp_typography_get_preset_inline_style_value(
$block_attributes['style']['typography']['textTransform'],
'text-transform'
);
}
if (
$has_letter_spacing_support &&
! $should_skip_letter_spacing &&
isset( $block_attributes['style']['typography']['letterSpacing'] )
) {
$typography_block_styles['letterSpacing'] = wp_typography_get_preset_inline_style_value(
$block_attributes['style']['typography']['letterSpacing'],
'letter-spacing'
);
}
if ( $has_writing_mode_support &&
! $should_skip_writing_mode &&
isset( $block_attributes['style']['typography']['writingMode'] )
) {
$typography_block_styles['writingMode'] = isset( $block_attributes['style']['typography']['writingMode'] )
? $block_attributes['style']['typography']['writingMode']
: null;
}
$attributes = array();
$classnames = array();
$styles = wp_style_engine_get_styles(
array( 'typography' => $typography_block_styles ),
array( 'convert_vars_to_classnames' => true )
);
if ( ! empty( $styles['classnames'] ) ) {
$classnames[] = $styles['classnames'];
}
if ( $has_text_align_support && ! $should_skip_text_align && isset( $block_attributes['style']['typography']['textAlign'] ) ) {
$classnames[] = 'has-text-align-' . $block_attributes['style']['typography']['textAlign'];
}
if ( ! empty( $classnames ) ) {
$attributes['class'] = implode( ' ', $classnames );
}
if ( ! empty( $styles['css'] ) ) {
$attributes['style'] = $styles['css'];
}
return $attributes;
}
/**
* Generates an inline style value for a typography feature e.g. text decoration,
* text transform, and font style.
*
* Note: This function is for backwards compatibility.
* * It is necessary to parse older blocks whose typography styles contain presets.
* * It mostly replaces the deprecated `wp_typography_get_css_variable_inline_style()`,
* but skips compiling a CSS declaration as the style engine takes over this role.
* @link https://github.com/wordpress/gutenberg/pull/27555
*
* @since 6.1.0
*
* @param string $style_value A raw style value for a single typography feature from a block's style attribute.
* @param string $css_property Slug for the CSS property the inline style sets.
* @return string A CSS inline style value.
*/
function wp_typography_get_preset_inline_style_value( $style_value, $css_property ) {
// If the style value is not a preset CSS variable go no further.
if ( empty( $style_value ) || ! str_contains( $style_value, "var:preset|{$css_property}|" ) ) {
return $style_value;
}
/*
* For backwards compatibility.
* Presets were removed in WordPress/gutenberg#27555.
* A preset CSS variable is the style.
* Gets the style value from the string and return CSS style.
*/
$index_to_splice = strrpos( $style_value, '|' ) + 1;
$slug = _wp_to_kebab_case( substr( $style_value, $index_to_splice ) );
// Return the actual CSS inline style value,
// e.g. `var(--wp--preset--text-decoration--underline);`.
return sprintf( 'var(--wp--preset--%s--%s);', $css_property, $slug );
}
/**
* Renders typography styles/content to the block wrapper.
*
* @since 6.1.0
*
* @param string $block_content Rendered block content.
* @param array $block Block object.
* @return string Filtered block content.
*/
function wp_render_typography_support( $block_content, $block ) {
if ( ! isset( $block['attrs']['style']['typography']['fontSize'] ) ) {
return $block_content;
}
$custom_font_size = $block['attrs']['style']['typography']['fontSize'];
$fluid_font_size = wp_get_typography_font_size_value( array( 'size' => $custom_font_size ) );
/*
* Checks that $fluid_font_size does not match $custom_font_size,
* which means it's been mutated by the fluid font size functions.
*/
if ( ! empty( $fluid_font_size ) && $fluid_font_size !== $custom_font_size ) {
// Replaces the first instance of `font-size:$custom_font_size` with `font-size:$fluid_font_size`.
return preg_replace( '/font-size\s*:\s*' . preg_quote( $custom_font_size, '/' ) . '\s*;?/', 'font-size:' . esc_attr( $fluid_font_size ) . ';', $block_content, 1 );
}
return $block_content;
}
/**
* Checks a string for a unit and value and returns an array
* consisting of `'value'` and `'unit'`, e.g. array( '42', 'rem' ).
*
* @since 6.1.0
*
* @param string|int|float $raw_value Raw size value from theme.json.
* @param array $options {
* Optional. An associative array of options. Default is empty array.
*
* @type string $coerce_to Coerce the value to rem or px. Default `'rem'`.
* @type int $root_size_value Value of root font size for rem|em <-> px conversion. Default `16`.
* @type string[] $acceptable_units An array of font size units. Default `array( 'rem', 'px', 'em' )`;
* }
* @return array|null An array consisting of `'value'` and `'unit'` properties on success.
* `null` on failure.
*/
function wp_get_typography_value_and_unit( $raw_value, $options = array() ) {
if ( ! is_string( $raw_value ) && ! is_int( $raw_value ) && ! is_float( $raw_value ) ) {
_doing_it_wrong(
__FUNCTION__,
__( 'Raw size value must be a string, integer, or float.' ),
'6.1.0'
);
return null;
}
if ( empty( $raw_value ) ) {
return null;
}
// Converts numbers to pixel values by default.
if ( is_numeric( $raw_value ) ) {
$raw_value = $raw_value . 'px';
}
$defaults = array(
'coerce_to' => '',
'root_size_value' => 16,
'acceptable_units' => array( 'rem', 'px', 'em' ),
);
$options = wp_parse_args( $options, $defaults );
$acceptable_units_group = implode( '|', $options['acceptable_units'] );
$pattern = '/^(\d*\.?\d+)(' . $acceptable_units_group . '){1,1}$/';
preg_match( $pattern, $raw_value, $matches );
// Bails out if not a number value and a px or rem unit.
if ( ! isset( $matches[1] ) || ! isset( $matches[2] ) ) {
return null;
}
$value = $matches[1];
$unit = $matches[2];
/*
* Default browser font size. Later, possibly could inject some JS to
* compute this `getComputedStyle( document.querySelector( "html" ) ).fontSize`.
*/
if ( 'px' === $options['coerce_to'] && ( 'em' === $unit || 'rem' === $unit ) ) {
$value = $value * $options['root_size_value'];
$unit = $options['coerce_to'];
}
if ( 'px' === $unit && ( 'em' === $options['coerce_to'] || 'rem' === $options['coerce_to'] ) ) {
$value = $value / $options['root_size_value'];
$unit = $options['coerce_to'];
}
/*
* No calculation is required if swapping between em and rem yet,
* since we assume a root size value. Later we might like to differentiate between
* :root font size (rem) and parent element font size (em) relativity.
*/
if ( ( 'em' === $options['coerce_to'] || 'rem' === $options['coerce_to'] ) && ( 'em' === $unit || 'rem' === $unit ) ) {
$unit = $options['coerce_to'];
}
return array(
'value' => round( $value, 3 ),
'unit' => $unit,
);
}
/**
* Internal implementation of CSS clamp() based on available min/max viewport
* width and min/max font sizes.
*
* @since 6.1.0
* @since 6.3.0 Checks for unsupported min/max viewport values that cause invalid clamp values.
* @since 6.5.0 Returns early when min and max viewport subtraction is zero to avoid division by zero.
* @access private
*
* @param array $args {
* Optional. An associative array of values to calculate a fluid formula
* for font size. Default is empty array.
*
* @type string $maximum_viewport_width Maximum size up to which type will have fluidity.
* @type string $minimum_viewport_width Minimum viewport size from which type will have fluidity.
* @type string $maximum_font_size Maximum font size for any clamp() calculation.
* @type string $minimum_font_size Minimum font size for any clamp() calculation.
* @type int $scale_factor A scale factor to determine how fast a font scales within boundaries.
* }
* @return string|null A font-size value using clamp() on success, otherwise null.
*/
function wp_get_computed_fluid_typography_value( $args = array() ) {
$maximum_viewport_width_raw = isset( $args['maximum_viewport_width'] ) ? $args['maximum_viewport_width'] : null;
$minimum_viewport_width_raw = isset( $args['minimum_viewport_width'] ) ? $args['minimum_viewport_width'] : null;
$maximum_font_size_raw = isset( $args['maximum_font_size'] ) ? $args['maximum_font_size'] : null;
$minimum_font_size_raw = isset( $args['minimum_font_size'] ) ? $args['minimum_font_size'] : null;
$scale_factor = isset( $args['scale_factor'] ) ? $args['scale_factor'] : null;
// Normalizes the minimum font size in order to use the value for calculations.
$minimum_font_size = wp_get_typography_value_and_unit( $minimum_font_size_raw );
/*
* We get a 'preferred' unit to keep units consistent when calculating,
* otherwise the result will not be accurate.
*/
$font_size_unit = isset( $minimum_font_size['unit'] ) ? $minimum_font_size['unit'] : 'rem';
// Normalizes the maximum font size in order to use the value for calculations.
$maximum_font_size = wp_get_typography_value_and_unit(
$maximum_font_size_raw,
array(
'coerce_to' => $font_size_unit,
)
);
// Checks for mandatory min and max sizes, and protects against unsupported units.
if ( ! $maximum_font_size || ! $minimum_font_size ) {
return null;
}
// Uses rem for accessible fluid target font scaling.
$minimum_font_size_rem = wp_get_typography_value_and_unit(
$minimum_font_size_raw,
array(
'coerce_to' => 'rem',
)
);
// Viewport widths defined for fluid typography. Normalize units.
$maximum_viewport_width = wp_get_typography_value_and_unit(
$maximum_viewport_width_raw,
array(
'coerce_to' => $font_size_unit,
)
);
$minimum_viewport_width = wp_get_typography_value_and_unit(
$minimum_viewport_width_raw,
array(
'coerce_to' => $font_size_unit,
)
);
// Protects against unsupported units in min and max viewport widths.
if ( ! $minimum_viewport_width || ! $maximum_viewport_width ) {
return null;
}
// Calculates the linear factor denominator. If it's 0, we cannot calculate a fluid value.
$linear_factor_denominator = $maximum_viewport_width['value'] - $minimum_viewport_width['value'];
if ( empty( $linear_factor_denominator ) ) {
return null;
}
/*
* Build CSS rule.
* Borrowed from https://websemantics.uk/tools/responsive-font-calculator/.
*/
$view_port_width_offset = round( $minimum_viewport_width['value'] / 100, 3 ) . $font_size_unit;
$linear_factor = 100 * ( ( $maximum_font_size['value'] - $minimum_font_size['value'] ) / ( $linear_factor_denominator ) );
$linear_factor_scaled = round( $linear_factor * $scale_factor, 3 );
$linear_factor_scaled = empty( $linear_factor_scaled ) ? 1 : $linear_factor_scaled;
$fluid_target_font_size = implode( '', $minimum_font_size_rem ) . " + ((1vw - $view_port_width_offset) * $linear_factor_scaled)";
return "clamp($minimum_font_size_raw, $fluid_target_font_size, $maximum_font_size_raw)";
}
/**
* Returns a font-size value based on a given font-size preset.
* Takes into account fluid typography parameters and attempts to return a CSS
* formula depending on available, valid values.
*
* @since 6.1.0
* @since 6.1.1 Adjusted rules for min and max font sizes.
* @since 6.2.0 Added 'settings.typography.fluid.minFontSize' support.
* @since 6.3.0 Using layout.wideSize as max viewport width, and logarithmic scale factor to calculate minimum font scale.
* @since 6.4.0 Added configurable min and max viewport width values to the typography.fluid theme.json schema.
* @since 6.6.0 Deprecated bool argument $should_use_fluid_typography.
* @since 6.7.0 Font size presets can enable fluid typography individually, even if it’s disabled globally.
*
* @param array $preset {
* Required. fontSizes preset value as seen in theme.json.
*
* @type string $name Name of the font size preset.
* @type string $slug Kebab-case, unique identifier for the font size preset.
* @type string|int|float $size CSS font-size value, including units if applicable.
* }
* @param bool|array $settings Optional Theme JSON settings array that overrides any global theme settings.
* Default is false.
* @return string|null Font-size value or null if a size is not passed in $preset.
*/
function wp_get_typography_font_size_value( $preset, $settings = array() ) {
if ( ! isset( $preset['size'] ) ) {
return null;
}
/*
* Catches falsy values and 0/'0'. Fluid calculations cannot be performed on `0`.
* Also returns early when a preset font size explicitly disables fluid typography with `false`.
*/
$fluid_font_size_settings = $preset['fluid'] ?? null;
if ( false === $fluid_font_size_settings || empty( $preset['size'] ) ) {
return $preset['size'];
}
/*
* As a boolean (deprecated since 6.6), $settings acts as an override to switch fluid typography "on" (`true`) or "off" (`false`).
*/
if ( is_bool( $settings ) ) {
_deprecated_argument( __FUNCTION__, '6.6.0', __( '`boolean` type for second argument `$settings` is deprecated. Use `array()` instead.' ) );
$settings = array(
'typography' => array(
'fluid' => $settings,
),
);
}
// Fallback to global settings as default.
$global_settings = wp_get_global_settings();
$settings = wp_parse_args(
$settings,
$global_settings
);
$typography_settings = $settings['typography'] ?? array();
/*
* Return early when fluid typography is disabled in the settings, and there
* are no local settings to enable it for the individual preset.
*
* If this condition isn't met, either the settings or individual preset settings
* have enabled fluid typography.
*/
if ( empty( $typography_settings['fluid'] ) && empty( $fluid_font_size_settings ) ) {
return $preset['size'];
}
$fluid_settings = isset( $typography_settings['fluid'] ) ? $typography_settings['fluid'] : array();
$layout_settings = isset( $settings['layout'] ) ? $settings['layout'] : array();
// Defaults.
$default_maximum_viewport_width = '1600px';
$default_minimum_viewport_width = '320px';
$default_minimum_font_size_factor_max = 0.75;
$default_minimum_font_size_factor_min = 0.25;
$default_scale_factor = 1;
$default_minimum_font_size_limit = '14px';
// Defaults overrides.
$minimum_viewport_width = isset( $fluid_settings['minViewportWidth'] ) ? $fluid_settings['minViewportWidth'] : $default_minimum_viewport_width;
$maximum_viewport_width = isset( $layout_settings['wideSize'] ) && ! empty( wp_get_typography_value_and_unit( $layout_settings['wideSize'] ) ) ? $layout_settings['wideSize'] : $default_maximum_viewport_width;
if ( isset( $fluid_settings['maxViewportWidth'] ) ) {
$maximum_viewport_width = $fluid_settings['maxViewportWidth'];
}
$has_min_font_size = isset( $fluid_settings['minFontSize'] ) && ! empty( wp_get_typography_value_and_unit( $fluid_settings['minFontSize'] ) );
$minimum_font_size_limit = $has_min_font_size ? $fluid_settings['minFontSize'] : $default_minimum_font_size_limit;
// Try to grab explicit min and max fluid font sizes.
$minimum_font_size_raw = isset( $fluid_font_size_settings['min'] ) ? $fluid_font_size_settings['min'] : null;
$maximum_font_size_raw = isset( $fluid_font_size_settings['max'] ) ? $fluid_font_size_settings['max'] : null;
// Font sizes.
$preferred_size = wp_get_typography_value_and_unit( $preset['size'] );
// Protects against unsupported units.
if ( empty( $preferred_size['unit'] ) ) {
return $preset['size'];
}
/*
* Normalizes the minimum font size limit according to the incoming unit,
* in order to perform comparative checks.
*/
$minimum_font_size_limit = wp_get_typography_value_and_unit(
$minimum_font_size_limit,
array(
'coerce_to' => $preferred_size['unit'],
)
);
// Don't enforce minimum font size if a font size has explicitly set a min and max value.
if ( ! empty( $minimum_font_size_limit ) && ( ! $minimum_font_size_raw && ! $maximum_font_size_raw ) ) {
/*
* If a minimum size was not passed to this function
* and the user-defined font size is lower than $minimum_font_size_limit,
* do not calculate a fluid value.
*/
if ( $preferred_size['value'] <= $minimum_font_size_limit['value'] ) {
return $preset['size'];
}
}
// If no fluid max font size is available use the incoming value.
if ( ! $maximum_font_size_raw ) {
$maximum_font_size_raw = $preferred_size['value'] . $preferred_size['unit'];
}
/*
* If no minimumFontSize is provided, create one using
* the given font size multiplied by the min font size scale factor.
*/
if ( ! $minimum_font_size_raw ) {
$preferred_font_size_in_px = 'px' === $preferred_size['unit'] ? $preferred_size['value'] : $preferred_size['value'] * 16;
/*
* The scale factor is a multiplier that affects how quickly the curve will move towards the minimum,
* that is, how quickly the size factor reaches 0 given increasing font size values.
* For a - b * log2(), lower values of b will make the curve move towards the minimum faster.
* The scale factor is constrained between min and max values.
*/
$minimum_font_size_factor = min( max( 1 - 0.075 * log( $preferred_font_size_in_px, 2 ), $default_minimum_font_size_factor_min ), $default_minimum_font_size_factor_max );
$calculated_minimum_font_size = round( $preferred_size['value'] * $minimum_font_size_factor, 3 );
// Only use calculated min font size if it's > $minimum_font_size_limit value.
if ( ! empty( $minimum_font_size_limit ) && $calculated_minimum_font_size <= $minimum_font_size_limit['value'] ) {
$minimum_font_size_raw = $minimum_font_size_limit['value'] . $minimum_font_size_limit['unit'];
} else {
$minimum_font_size_raw = $calculated_minimum_font_size . $preferred_size['unit'];
}
}
$fluid_font_size_value = wp_get_computed_fluid_typography_value(
array(
'minimum_viewport_width' => $minimum_viewport_width,
'maximum_viewport_width' => $maximum_viewport_width,
'minimum_font_size' => $minimum_font_size_raw,
'maximum_font_size' => $maximum_font_size_raw,
'scale_factor' => $default_scale_factor,
)
);
if ( ! empty( $fluid_font_size_value ) ) {
return $fluid_font_size_value;
}
return $preset['size'];
}
// Register the block support.
WP_Block_Supports::get_instance()->register(
'typography',
array(
'register_attribute' => 'wp_register_typography_support',
'apply' => 'wp_apply_typography_support',
)
);