wp_star_rating() │ WP 3.8.0

Output a HTML element with a star rating for a given rating.

Outputs a HTML element with the star rating exposed on a 0..5 scale in half star increments (ie. 1, 1.5, 2 stars). Optionally, if specified, the number of ratings may also be displayed by passing the $number parameter.

1 time — 0.000057 sec (very fast) | 50000 times — 1.30 sec (fast) | PHP 7.0.2, WP 4.4.2

No Hooks.

Return

String. Star rating HTML.

Usage

wp_star_rating( $args );
$args(array)

Array of star ratings arguments.

Default: array()

  • rating(int|float)
    The rating to display, expressed in either a 0.5 rating increment, or percentage.

  • type(string)
    Format that the $rating is in. Valid values are 'rating' (default), or, 'percent'.
    Default: 'rating'

  • number(int)
    The number of ratings that makes up this rating.

  • echo(true|false)
    Whether to echo the generated markup. False to return the markup instead of echoing it.
    Default: true

Examples

0

#1 Rating (stars) output 

wp_star_rating( ['rating'=>7.5, 'type'=>'rating', 'number'=>0 ] );

/* Will withdraw:
<div class="star-rating" title="Rating 7.5"><span class="screen-reader-text">Rating 7.5</span>
	<div class="star star-full"></div>
	<div class="star star-full"></div>
	<div class="star star-full"></div>
	<div class="star star-full"></div>
	<div class="star star-full"></div>
	<div class="star star-full"></div>
	<div class="star star-full"></div>
	<div class="star star-half"></div>
</div>
*/

It looks like this:

wp_star_rating( ['rating'=>85, 'type'=>'percent', 'number'=>654 ] );

/* Will withdraw:
<div class="star-rating" title="Rating 4.5 based on 654 votes"><span class="screen-reader-text">Rating 4.5 based on 654 votes</span>
	<div class="star star-full"></div>
	<div class="star star-full"></div>
	<div class="star star-full"></div>
	<div class="star star-full"></div>
	<div class="star star-half"></div>
</div>
*/

It looks like this:

0

#2 Output in the front-end

In the front-end function does not work and there is better to make their own similar function. But if you have 'dashicons' fonts on front, then it makes sense to use this function, for this you need to include the function file and css styles:

<?php
// for use on front
require_once ABSPATH .'wp-admin/includes/template.php';

// connect icons
add_action( 'wp_enqueue_scripts', function(){
	wp_enqueue_style( 'dashicons' );
} );

// add styles
add_action( 'wp_head', function(){
	?>
	<style>
	.screen-reader-text{ position: absolute; margin: -1px; padding: 0; 
		height: 1px; width: 1px; overflow: hidden; clip: rect(0 0 0 0); 
		border: 0; word-wrap: normal!important; 
	}
	.star-rating .star-full:before { content: "\f155"; }
	.star-rating .star-half:before { content: "\f459"; }
	.star-rating .star-empty:before { content: "\f154"; }
	.star-rating .star {
		color: #0074A2;
		display: inline-block;
		font-family: dashicons;
		font-size: 20px;
		font-style: normal;
		font-weight: 400;
		height: 20px;
		line-height: 1;
		text-align: center;
		text-decoration: inherit;
		vertical-align: top;
		width: 20px;
	}
	</style>
	<?php
} );

// Output HTML
wp_star_rating( [ 'rating'=>4.5, 'type'=>'rating', 'number'=>521 ] );

/* We get:

<div class="star-rating" data-title="4,5 rating based on 521 ratings">
	<span class="screen-reader-text">4,5 rating based on 521 ratings</span>
	<div class="star star-full"></div>
	<div class="star star-full"></div>
	<div class="star star-full"></div>
	<div class="star star-full"></div>
	<div class="star star-half"></div>
</div>

*/

Changelog

Since 3.8.0 Introduced.
Since 4.4.0 Introduced the echo parameter.

Code of wp_star_rating() WP 5.9.3

wp-admin/includes/template.php 
function wp_star_rating( $args = array() ) {
	$defaults    = array(
		'rating' => 0,
		'type'   => 'rating',
		'number' => 0,
		'echo'   => true,
	);
	$parsed_args = wp_parse_args( $args, $defaults );

	// Non-English decimal places when the $rating is coming from a string.
	$rating = (float) str_replace( ',', '.', $parsed_args['rating'] );

	// Convert percentage to star rating, 0..5 in .5 increments.
	if ( 'percent' === $parsed_args['type'] ) {
		$rating = round( $rating / 10, 0 ) / 2;
	}

	// Calculate the number of each type of star needed.
	$full_stars  = floor( $rating );
	$half_stars  = ceil( $rating - $full_stars );
	$empty_stars = 5 - $full_stars - $half_stars;

	if ( $parsed_args['number'] ) {
		/* translators: 1: The rating, 2: The number of ratings. */
		$format = _n( '%1$s rating based on %2$s rating', '%1$s rating based on %2$s ratings', $parsed_args['number'] );
		$title  = sprintf( $format, number_format_i18n( $rating, 1 ), number_format_i18n( $parsed_args['number'] ) );
	} else {
		/* translators: %s: The rating. */
		$title = sprintf( __( '%s rating' ), number_format_i18n( $rating, 1 ) );
	}

	$output  = '<div class="star-rating">';
	$output .= '<span class="screen-reader-text">' . $title . '</span>';
	$output .= str_repeat( '<div class="star star-full" aria-hidden="true"></div>', $full_stars );
	$output .= str_repeat( '<div class="star star-half" aria-hidden="true"></div>', $half_stars );
	$output .= str_repeat( '<div class="star star-empty" aria-hidden="true"></div>', $empty_stars );
	$output .= '</div>';

	if ( $parsed_args['echo'] ) {
		echo $output;
	}

	return $output;
}

Uncategorized