=== Universal Reviews – Ratings, Forms Reviews, Listing Reviews & Elementor ===
Contributors: universalwp
Tags: reviews, product reviews, ratings, testimonials, elementor
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Collect, moderate and show star ratings and photo reviews on any post, product or business. Elementor widgets, blocks and review schema.

== Description ==

**Universal Reviews is a WordPress review plugin that lets visitors rate and review anything on your site, and gives you one clean place to manage what they say.**

Run a WooCommerce shop? A local business? An agency, a course, a directory or a membership site? You probably want the same few things: a simple review form, honest star ratings, a queue to approve reviews, and a good-looking way to show them. This plugin does exactly that, without turning your comments section into a rating system.

Reviews can be attached to posts, pages, custom post types, WooCommerce products, taxonomy terms, users or your whole business. Show them with **Elementor widgets**, **Gutenberg blocks** or **shortcodes**, whichever you prefer.

Reviews live in their own indexed database tables instead of the comments table or post meta. Rating summaries are precomputed, so your review lists and summaries don't run a `COUNT(*)` on the reviews table for every page view.

= Set it up in about three minutes =

1. Install and activate the plugin.
2. Open **Reviews** in the admin menu and look over **Forms**, **Review Types** and **Settings**. The defaults are sensible.
3. Edit a post, page or product and add `[unirev_reviews show_form=1]`, or drop in the **Reviews List** block, or use the **Reviews List** widget in Elementor.
4. Visit the page, leave a test review, then approve it under **Reviews → Reviews**.

You now have a rating summary, a review list and a review form on the page.

= Who is it for? =

* **Online stores** that want customer reviews and star ratings on WooCommerce product pages.
* **Local businesses and service providers** who want reviews of the business itself.
* **Agencies, freelancers and course creators** collecting testimonials.
* **Directories and membership sites** where people review listings, users or categories.
* **Elementor and block-editor users** who want review widgets that match their design.

The everyday workflow stays simple:

1. Create or adjust a review form.
2. Place the form and review list on your site.
3. Moderate incoming reviews.
4. Reply, feature or verify reviews when appropriate.
5. Show the rating summary and approved reviews to visitors.

### Elementor widgets

If you build with Elementor, you don't need to paste shortcodes any more. Universal Reviews adds two Elementor widgets:

* **Review Form** – let visitors submit a rating and review right from your Elementor page.
* **Reviews List** – show approved reviews with the rating summary, star filters, owner replies, a "Load more reviews" button and helpful votes.

Both widgets use the same forms, review types and moderation queue as the shortcodes and blocks, so you can switch between them at any time. Elementor is optional. The plugin works the same without it.

### Support and community

* [Support Forum](https://wordpress.org/support/plugin/universal-reviews/) – ask questions and report issues.
* [Facebook Community](https://www.facebook.com/profile.php?id=61594808884671) – share feedback and follow updates.

### Collect reviews

* Create review forms with a drag-and-drop field builder.
* Rating field is included by default and uses a 1–5 star scale, in whole or half steps per review type.
* Let reviewers attach photos (JPEG, PNG, WebP or AVIF) with configurable size and count limits. SVG is never accepted.
* Available field types include rating, heading, text, textarea, select, radio, checkbox, number, email, URL, phone, date and hidden fields.
* Mark fields as required, use half-width layouts, add placeholders and help text, and assign custom CSS classes.
* Add headings and text blocks between fields with configurable HTML tag, size, color and alignment.
* Custom field answers are saved with the review and available to moderators.
* Import and export form templates as JSON.
* Preview forms before publishing them.
* Create review types such as Product, Service or Place, each with its own moderation policy, allowed targets and schema.org type.

### Protect submissions

Universal Reviews includes several layers of basic anti-abuse protection without requiring a CAPTCHA.

* Honeypot field.
* Signed time trap with an expiring token.
* Per-IP rate limiting.
* One-review-per-person-per-item protection within a configurable time window.
* Consent checkbox.
* Same-site origin validation.
* Validation of review types and public targets.
* HTTP 429 responses when the configured rate limit is exceeded.

Default protection includes a limit of 12 submissions per 60 minutes per IP and a 72-hour duplicate-review window.

### Moderate reviews

The React-powered admin dashboard gives moderators a focused place to work through incoming reviews.

* Filter reviews by status.
* Search and sort reviews.
* Cursor-based pagination for large review collections.
* Approve, reject, mark as spam, trash, feature or delete reviews.
* Apply moderation actions individually or in bulk.
* Reply to reviews as the site owner.
* Mark reviews as verified.
* View the original form answers.
* Keep a review change history.
* Receive a daily digest when reviews are waiting for moderation.
* Disable the digest with the `unirev_digest_enabled` filter.

The moderation interface uses server-side filtering, sorting and pagination so the browser does not need to load the complete review database.

### Display reviews

Add reviews to your site with Elementor widgets, Gutenberg blocks or shortcodes.

Available shortcodes:

`[unirev_form]`

`[unirev_reviews]`

`[unirev_summary]`

The Reviews List and Review Form blocks are server-rendered. In the block editor you get a live preview, a dropdown of your saved forms, a searchable picker for posts, products, terms and users, and colour and size controls for the button, fields and star rating.

Front-end features include:

* Rating summary with average rating and total review count.
* 5-to-1 star distribution.
* Star-rating filtering such as 4+ stars.
* "Helpful" vote button on each review.
* "Load more reviews" button for long review lists.
* Photo reviews with image thumbnails.
* Owner replies.
* Verified review badges.
* Keyboard-friendly star selection.
* Inline validation and form status messages.
* Loading and success states.
* Theme-friendly CSS variables using the `--unirev-*` naming system.

Plugin CSS and JavaScript are loaded only on pages that actually show a Universal Reviews widget, and in the page head when a post contains the shortcode or block, so your layout doesn't jump.

### SEO and structured data

Universal Reviews can output AggregateRating JSON-LD (the review schema behind star ratings in search results) for supported public review targets.

Structured data is printed only when the page actually displays the target's review list or summary and the target has approved reviews. The plugin uses the schema.org type configured for the review type and avoids outputting review structured data for private content.

This keeps structured data tied to the content visitors can actually see rather than adding review markup site-wide.

Schema output is built to play nicely with other plugins: it uses the correct worst rating for half-star types, a stable `@id`, merges multiple reviewed items into one `@graph`, limits types to a list of valid schema.org types (filter `unirev_schema_types`), and has a `unirev_schema_output` filter so you can avoid duplicates with WooCommerce or your SEO plugin.

Important: structured data does not guarantee rich results in search engines. Search engines decide whether and how eligible structured data is displayed.

### Performance

Universal Reviews is designed for larger review collections.

* Reviews use dedicated database tables.
* Important review, moderation and lookup queries are indexed.
* Rating totals and distributions are precomputed.
* Public review lists and summaries do not run COUNT(*) on the reviews table for every page view.
* Background jobs support retry, cancellation and recovery from stuck jobs.
* Jobs and logs older than 30 days are automatically purged.
* Optional persistent object caching such as Redis or Memcached can make repeated public queries cheaper, but it is not required.

The architecture is intended to remain practical as a site grows from hundreds of reviews to much larger collections.

### Import, export and diagnostics

The Tools area includes:

* Streaming CSV export.
* Streaming JSON export.
* Spreadsheet formula-injection protection during export.
* Batched CSV import with up to 5,000 rows per file.
* Row-level import errors.
* Background jobs.
* Job retry and cancellation.
* Logs.
* Database table-size diagnostics.
* Automatic cleanup of old jobs and logs.

### Privacy

Privacy controls are built into the review workflow.

* Reviewer IP addresses are not stored by default.
* WordPress privacy exporter integration.
* WordPress privacy eraser integration.
* Custom form answers are included in privacy handling.
* Erasing personal data anonymises reviewer name, email and IP where applicable while keeping the review text as a business record.
* Optional data-retention settings.
* Review data remains after deactivation.
* Data is deleted on uninstall only when "Delete all data on uninstall" is enabled.
* Multisite sites manage their own uninstall-data setting.
* No telemetry is sent by the plugin.

Always configure retention, consent and privacy settings according to your site's legal and business requirements.

== Installation ==

### Install from your dashboard (easiest)

1. Go to **Plugins → Add New Plugin**.
2. Search for **Universal Reviews**.
3. Click **Install Now**, then **Activate**.

### Upload the ZIP from WordPress admin

1. Download the `universal-reviews` plugin ZIP.
2. In WordPress, go to **Plugins → Add New Plugin**.
3. Select **Upload Plugin**.
4. Choose the `universal-reviews.zip` file.
5. Click **Install Now**.
6. After installation finishes, click **Activate Plugin**.

### Install manually

1. Download the plugin ZIP.
2. Extract the `universal-reviews` folder.
3. Upload the folder to `/wp-content/plugins/`.
4. Open **Plugins → Installed Plugins** in WordPress.
5. Find **Universal Reviews**.
6. Click **Activate**.

### After activation

After activation, open **Reviews** in the WordPress admin menu.

Start with:

1. **Reviews → Forms** — review the default form or create another form.
2. **Reviews → Review Types** — configure Product, Service, Place or another review type.
3. **Reviews → Settings** — check moderation, anti-abuse, display, privacy and notification settings.
4. Add a review form and review list using a shortcode or Gutenberg block.
5. Submit a test review from the front end.
6. Open **Reviews → Reviews** and test the complete moderation workflow.
7. Approve the test review and confirm that the review list and summary appear correctly.

For the quickest setup, add this shortcode to a post, page or product:

`[unirev_reviews show_form=1]`

This displays the review list and enables the form for the current supported target.

Using Elementor? Edit the page, search the widget panel for **Reviews List** or **Review Form**, and drag it where you want it.

Requirements: WordPress 6.2 or newer and PHP 7.4 or newer. WooCommerce and Elementor are optional.

### Deactivation and uninstall

Deactivating Universal Reviews does not remove review data.

By default, database tables and settings remain available after deactivation. If you want WordPress to remove the plugin's stored data during uninstall, enable **Settings → Privacy → Delete all data on uninstall** before deleting the plugin.

Use this option carefully because uninstall data deletion is intended to be permanent.

== Frequently Asked Questions ==

= Does Universal Reviews require WooCommerce? =

No. WooCommerce is not required.

Reviews can target WordPress posts and custom post types, taxonomy terms, users, the site/business and other supported targets. WooCommerce products are supported as the `product` post type.

Universal Reviews does not read WooCommerce orders for purchase verification. A moderator can mark a review as verified from the Reviews screen, and developers can add their own verification logic through the `unirev_verification_providers` filter.

= Can I use Universal Reviews for custom post types? =

Yes. The `post` target type can work with WordPress post types, including custom post types, when the target is public and supported by the plugin's target validation.

= Does Universal Reviews work with Elementor? =

Yes. Version 1.0.2 adds Elementor widgets for the Review Form and the Reviews List. Drag them onto any Elementor page, template or product layout. They share the same forms, review types and moderation queue as the blocks and shortcodes.

= Can I use it without a page builder? =

Yes. Elementor is optional. Universal Reviews also works with the WordPress block editor and with shortcodes, and you don't need a special theme.

= How do I add star ratings and customer reviews to a WordPress page? =

Add `[unirev_reviews show_form=1]` to the page, insert the **Reviews List** block, or drop in the **Reviews List** widget in Elementor. Visitors will see the rating summary, the approved reviews and the review form.

= How do I show reviews on WooCommerce product pages? =

WooCommerce products are supported as a review target. Add the shortcode, block or Elementor widget to your product description, product template or product layout. Universal Reviews doesn't take over the built-in WooCommerce reviews tab.

= Can visitors upload photos with their review? =

Yes. Reviewers can attach JPEG, PNG, WebP or AVIF photos, and you control the size and number of photos. SVG uploads are never accepted. Photos that can't be verified as real images are rejected, and photos are deleted when a review is rejected or marked as spam.

= Can I collect reviews for my business instead of a page? =

Yes. Use the `business` target type to collect reviews about your company as a whole, then show them anywhere with the same widgets, blocks and shortcodes.

= Can I customize the review form? =

Yes. The form builder supports multiple field types, required fields, half-width layouts, placeholders, help text, headings, text blocks and custom CSS classes. Form styling uses `--unirev-*` CSS variables.

= Can I create different review forms? =

Yes. Forms can be created and managed from **Reviews → Forms**. Forms can be associated with supported review types and embedded with the form shortcode or Review Form block.

= Can I use half-star ratings? =

Yes, since version 1.0.1. Choose **Half stars** under **Star steps** when editing a review type in **Reviews → Review Types**. Types default to whole stars (1 to 5).

= Does the plugin store IP addresses? =

Not by default. IP storage is disabled by default and can be enabled from the privacy settings when a site needs it.

= Does the plugin use CAPTCHA? =

No CAPTCHA is required. Universal Reviews uses a honeypot, signed time trap, rate limiting, duplicate-review protection, consent and request validation.

= What happens when I deactivate the plugin? =

Deactivation does not delete reviews, settings or database tables.

Data is removed during uninstall only when **Delete all data on uninstall** has been enabled in **Settings → Privacy**.

= Do I need Redis or another object cache? =

No. Universal Reviews does not require Redis or Memcached.

Rating aggregates are precomputed in a summary table. A persistent object cache can further reduce repeated public queries when available.

= Does the plugin add review schema automatically? =

When enabled, Universal Reviews can output AggregateRating JSON-LD for supported targets whose review list or summary is actually displayed and which have approved reviews.

Structured data eligibility does not guarantee a search-engine rich result.

= Does Universal Reviews guarantee Google star snippets? =

No. The plugin outputs supported structured data according to its configuration and visible review content, but search engines independently decide whether structured data qualifies for or appears as a rich result.

= Can visitors mark reviews as helpful? =

Yes. Version 1.0.2 adds a "Helpful" vote button on each review. Voting can be enabled in the display settings, and votes have their own rate limit.

= Does the review list have pagination? =

Yes. Long lists show a "Load more reviews" button that loads the next page of reviews without reloading the page.

= Does it work with full-page caching? =

Yes. Review forms and vote buttons on cached pages fetch fresh security tokens when the visitor interacts, so they no longer fail with expired nonces.

= Will it work with Hindi, Arabic, Chinese and emoji text? =

Yes. Titles, names, answers and avatar initials are cut on character boundaries, so non-Latin text and emoji are no longer corrupted.

= Can the business owner reply to reviews? =

Yes. Moderators with the appropriate capability can add owner replies. Replies are displayed beneath the review on the front end.

= Can I import existing reviews? =

Version 1.0.0 includes Universal Reviews CSV import. Import files can contain up to 5,000 rows per file and report row-level errors.

Dedicated migration importers for other review plugins are planned for the Pro roadmap.

= Does the plugin send telemetry? =

No. Universal Reviews does not send telemetry.

= What happens to privacy data when a review is erased? =

Universal Reviews integrates with the WordPress privacy exporter and eraser. Personal information such as reviewer name, email and stored IP data can be anonymised while the review text remains as a business record.

= Where is the source code for the compiled admin app? =

The admin dashboard (`assets/admin/index.js` and `assets/admin/index.css`) is compiled from the human-readable TypeScript/React source in the `admin-src/` folder, which ships inside the plugin. To rebuild it, run `npm install` and then `npm run build` in the plugin folder (esbuild bundles the JavaScript and the Tailwind CLI builds the CSS; see `admin-src/README.md`). The bundle includes React, React DOM, Radix UI, lucide-react, class-variance-authority, clsx and tailwind-merge, all under MIT-compatible licences. The front-end script (`assets/admin/frontend.js`), the block editor scripts (`blocks/*/edit.js`) and the PHP are not minified.

== Shortcodes ==

### Review form

`[unirev_form]`

Default attributes:

* `slug` — Form slug. Default: `unirev_form`.
* `type` — Review type. Default: `product`.
* `target_type` — Target type. Default: `post`.
* `target_id` — Target ID. Defaults to the current supported post when available.

Example:

`[unirev_form type="product" target_type="post" target_id="123"]`

### Review list

`[unirev_reviews]`

Available attributes:

* `type`
* `target_type`
* `target_id`
* `per_page`
* `sort`
* `min_rating`
* `allow_rating_filter`
* `show_form`

Example:

`[unirev_reviews type="product" target_type="post" target_id="123" per_page="10" show_form="1"]`

### Rating summary

`[unirev_summary]`

Available attributes:

* `type`
* `target_type`
* `target_id`

Example:

`[unirev_summary type="product" target_type="post" target_id="123"]`

Supported target types include:

* `post` — WordPress posts and supported post types.
* `product` — WooCommerce products.
* `term` — taxonomy terms.
* `user` — users.
* `business` — the business/site target.

== Blocks ==

### Reviews List

Block name: `unirev/reviews-list`

Attributes:

* `reviewType`
* `targetType`
* `targetId`
* `perPage`
* `sort`
* `minRating`
* `allowRatingFilter`

### Review Form

Block name: `unirev/review-form`

Attributes:

* `formSlug`
* `reviewType`
* `targetType`
* `targetId`

Both blocks are server-rendered.
== Screenshots ==

1. Dashboard — review metrics, trends, rating distribution and recent activity.
2. Reviews moderation — status filters, search, bulk actions, owner replies and review history.
3. Review form builder — configurable fields, ordering and form preview.
4. Review Types — target and schema configuration.
5. Settings — moderation, anti-abuse, display, privacy and notifications.
6. Dashboard in dark mode.

== Changelog ==

= 1.0.2 =
* New: Review Form block's "Form" field is a dropdown of your saved forms, and adds full color/size style controls for the button, fields and star rating.
* New: Elementor widgets for Review Form and Reviews List.
* New: "Load more reviews" button on review lists (cursor pagination) and a "Helpful" vote button on each review.
* Added: an admin notice (with the exact config) when the server is Nginx, since the upload folder's `.htaccess` protection doesn't apply there.
* Improved: schema.org output uses the correct worst rating for half-star types, a stable `@id`, merges multiple reviewed items into one `@graph`, an allow-list of valid types (filter `unirev_schema_types`) and a `unirev_schema_output` filter to avoid duplicates with WooCommerce or SEO plugins.
* Improved: the duplicate-review guard also checks the reviewer's IP via a privacy-safe one-way hash — works regardless of the "store IP" setting, so a different email no longer bypasses it.
* Improved: Reviews List and Review Form blocks use block API v3, add editor previews, colour and font-size controls, and a searchable picker (posts, products, terms and users) instead of a raw ID field.
* Improved: admin rating-distribution chart is cached in a transient, same as the status-count badge.
* Improved: the public reviews API is now rate-limited per IP, separate from the submission limit; it also no longer runs a total count or resolves target titles, and returns nothing for posts that are no longer public.
* Improved: front-end CSS/JS load in the page head when a post contains the shortcode or block (no layout shift), and rate-limit counters use the persistent object cache when one is available instead of writing database options on every hit.
* Improved: the time-trap token is bound to the visitor's IP; helpful votes use their own rate-limit bucket instead of the submission quota.
* Improved: the submit error no longer reveals whether an item ID exists.
* Improved: admin menu badge counts are cached in a short-lived transient; identical pending background jobs are no longer queued twice.
* Improved: bulk moderation now uses one lookup and one update per status group instead of several queries per review.
* Fixed: Review Form and Reviews List block previews were unstyled in the editor; they now match the front-end.
* Fixed: titles, names, answers and avatar initials are now cut on character boundaries, so Hindi, Arabic, CJK and emoji text is no longer corrupted.
* Fixed: "Highest rated" pagination skipped half-star (4.5) reviews after the first page.
* Fixed: a new auto-approved review now updates the review count, average rating and schema.org data immediately instead of waiting for WP-Cron.
* Fixed: review forms and vote buttons on full-page-cached pages no longer fail with stale nonce or time-trap tokens; fresh tokens are fetched on interaction.
* Fixed: a rate-limit window of 0 no longer disables the limit; window, reviews-per-page and cron interval settings are now range-limited.
* Privacy: the personal-data eraser also removes log entries containing the reviewer's email, and vote records older than one year are pruned.
* Security: photos that cannot be verified (unreadable image header, including AVIF) are rejected; photos are deleted when a review is rejected or marked spam.

= 1.0.1 =
* New: photo reviews (JPEG, PNG, WebP and AVIF uploads with size and count limits; SVG is never accepted) and optional half-star ratings per review type.
* Improved: spam-check filter, vote nonce, admin REST rate limit and settings/summary caching; fixed empty stars showing as filled in review lists.

= 1.0.0 =
* Initial release.
* Dedicated indexed review tables.
* `[unirev_form]`, `[unirev_reviews]` and `[unirev_summary]` shortcodes.
* Reviews List and Review Form Gutenberg blocks.
* Drag-and-drop review form builder.
* Review types with configurable targets and schema.org types.
* Review moderation with bulk actions.
* Owner replies, helpful votes and verified reviews.
* Review history and form-answer inspection.
* Honeypot, signed time trap, rate limiting and duplicate-review protection.
* Streaming CSV/JSON export.
* Batched CSV import with row-level errors.
* Background jobs, logs and diagnostics.
* Precomputed rating summaries and distributions.
* Conditional CSS and JavaScript loading.
* AggregateRating JSON-LD for eligible visible review content.
* WordPress privacy exporter and eraser integration.
* No telemetry.

== Upgrade Notice ==

= 1.0.2 =
Adds Elementor widgets, a "Load more reviews" button, a Helpful vote button, new block controls and many security, performance and schema improvements. Recommended for all sites.

= 1.0.1 =
Adds photo reviews and half-star ratings, plus security and performance improvements. The database updates automatically on first load.

= 1.0.0 =
Initial release of Universal Reviews.