WP-PostRatings

About this plugin

<?php the_ratings(); ?>

wp postratings list
wp postratings list --limit=50 --format=json
wp postratings get 42
wp postratings delete 42 --yes
wp postratings delete --all --what=logs

GET  /wp-json/postratings/v1/post/<id>
POST /wp-json/postratings/v1/post/<id>/rate

Questions

How do I change the colour of the ratings?

Go to WP-Admin -> Ratings -> Settings and look under Individual Rating Text and Value. Each step on the scale has its own pair of colour swatches, in the Rated and Not rated columns, which is what the old stars_crystal and stars_dark image sets were for.

Hovering uses the rated colour. If you would rather tell “about to pick” apart from “already recorded”, set --wp-postratings-color-hover in your theme.

How do I change the size, spacing or hover colour?

Anything beyond the two colours is a CSS custom property on .wp-postratings, so this is all it takes in your theme:

.wp-postratings {
    --wp-postratings-size: 24px;
    --wp-postratings-gap: 4px;
    --wp-postratings-color-hover: #f7c56b;
}

Before 2.0.0 a different colour meant a whole extra folder of images, which is why the plugin shipped stars, stars_crystal and stars_dark separately. They are all the same shape now.

How do I use my own rating shape?

Register it with the wp_postratings_shapes filter. It then appears on the Ratings Settings screen like any built-in shape, and unlike the old approach of dropping a folder into wp-content/plugins/wp-postratings/images/, it survives an update.

add_filter( 'wp_postratings_shapes', function ( $shapes ) {
    $shapes['diamond'] = array(
        'type'  => 'scale',
        'label' => 'Diamonds',
        'path'  => 'M12 2l10 10-10 10L2 12z',
    );

    return $shapes;
} );

The path is SVG path data drawn in a 24×24 box. For an up/down control use 'type' => 'updown' and supply 'up' and 'down' paths instead of 'path'.

For a scale whose points are numbers rather than a repeated glyph, use 'type' => 'numeric' and supply no path at all — the position is the glyph:

add_filter( 'wp_postratings_shapes', function ( $shapes ) {
    $shapes['points'] = array(
        'type'  => 'numeric',
        'label' => 'Points',
    );

    return $shapes;
} );

A numeric shape is still a scale, so it appears under Scale on the settings screen and everything that reads a rating goes on reading it the same way. Only the drawing changes.

Every visitor can rate over and over, or every rating log entry shows the same IP

This is about the Header That Contains The IP field on the Ratings Settings screen.

Leave it blank unless your site is genuinely behind a reverse proxy or CDN such as Cloudflare. Blank means the plugin uses the address your web server actually saw, which is what you want on a normal host.

If you are behind a proxy, name the exact header your proxy sets, for example HTTP_CF_CONNECTING_IP for Cloudflare or HTTP_X_FORWARDED_FOR for most load balancers. Two things are worth knowing:

• A visitor can send any header they like. If you name a header your own stack does not set and overwrite, anyone can put whatever they want in it and rate as many times as they please.
• X-Forwarded-For is a list, client, proxy1, proxy2. As of 2.0.0 the plugin reads the first valid address in that list rather than storing the whole string. Before 2.0.0 it stored the whole string, which meant a visitor could append one more address and appear to be somebody new on every request.

Because the stored value has changed shape, rating logs recorded through such a header before 2.0.0 will not match any more, and some visitors may be able to rate one more time. Logs recorded without the field set are unaffected.

How To Change Schema Type?

<?php  
add_filter( 'wp_postratings_schema_itemtype', 'wp_postratings_schema_itemtype' );  
function wp_postratings_schema_itemtype( $itemtype ) {  
    return 'itemscope itemtype="https://schema.org/Recipe"';  
}  
?>

The default schema type is ‘Article’, if you want to change it to ‘Recipe’, you need to make use of the wp_postratings_schema_itemtype filter as shown in the sample code above.

How To Add Your Site Logo For Google Rich Snippets

<?php  
add_filter( 'wp_postratings_site_logo', 'wp_postratings_site_logo' );  
function wp_postratings_site_logo( $url ) {  
    return 'https://example.com/logo.png';  
}  
?>

By default, the plugin will use your site header image URL as your site logo. If you want to change it, you need to make use of the wp_postratings_site_logo filter as shown in the sample code above.

How To Change The Text Screen Readers Announce?

add_filter( 'wp_postratings_ratings_image_alt', function ( $label ) {
    return $label;
} );

This is the description a screen reader reads out for a displayed rating, such as “4 votes, average: 3.70 out of 5”. Since 2.0.0 the ratings are drawn with CSS rather than images, so there is no alt or title attribute involved; the value becomes the aria-label on the rating.

Returning an empty string removes it, which is what this filter was usually used for. Be aware that it leaves the rating with no accessible name at all, so anyone using a screen reader is told nothing about it. Prefer rewording it over removing it.

How To Display Comment Author Ratings?

add_filter( 'wp_postratings_display_comment_author_ratings', '__return_true' );

By default, the comment author ratings are not displayed. If you want to display the ratings, you need to make use of the wp_postratings_display_comment_author_ratings filter as shown in the sample code above.