Skip to content

Reviews

Product reviews in Shopper, from the Review model and its ratings to approval, the admin moderation page and the Store API review endpoints.

Customers rate the products they bought and tell other customers what they think: a star rating from 1 to 5, an optional title and text, and whether they recommend the product. Each review is a row of the reviews table, linked to the product it rates and to the customer who wrote it.

A new review is pending until a merchant approves it. Only approved reviews reach the storefront: the Store API, the average rating on the dashboard and the rating rule of automatic collections all ignore pending reviews. Shopper stores and moderates reviews; collecting them on your storefront is up to your code, as shown in Review Submission.

Model

The model is Shopper\Core\Models\Review. It implements the Shopper\Core\Models\Contracts\Review contract. It has no key in config/shopper/models.php, so it cannot be swapped: to add a relationship to it, use resolveRelationUsing() as described in Models You Cannot Swap.

The HasPublicId trait fills public_id with a ULID when a review is created, and adds findByPublicId() and the wherePublicId scope. The Store API returns it as the id of each review. The model casts approved and is_recommended to booleans and has an approved scope.

Products receive reviews through the Shopper\Core\Models\Traits\InteractsWithReviews trait, described in HasReviews Contract.

Database Schema

Reviews are stored in the sh_reviews table (sh_ is the default table prefix):

ColumnTypeNullableDefaultDescription
idbigintnoautoPrimary key
public_idulidyesgeneratedPublic identifier, unique
is_recommendedbooleannofalseWhether the customer recommends the product
ratingintegerno-Star rating
titletextyesnullReview title
contenttextyesnullReview text
approvedbooleannofalseWhether the review is published
reviewrateable_typestringno-Morph type of the reviewed model, product for a product
reviewrateable_idbigintno-ID of the reviewed model
author_typestringno-Morph type of the author
author_idbigintno-ID of the author
created_attimestampyesnullCreation timestamp
updated_attimestampyesnullLast update timestamp

The rating column accepts any integer. The admin panel and the Store API count ratings from 1 to 5, so validate that range when you create a review. An index on reviewrateable_type, reviewrateable_id, approved and created_at serves the list of approved reviews of a product, newest first.

The reviewed model and the author are polymorphic columns without foreign keys. Deleting a product or a customer leaves their reviews in the table.

Relationships

A review belongs to the model it rates and to the customer who wrote it. Both relationships are polymorphic.

Reviewrateable (Product)

reviewrateable returns the reviewed product. A product review stores the product alias in reviewrateable_type, so the relationship returns an instance of the class configured for the product key, as explained in Morph Map:

$product = $review->reviewrateable;

Author (User)

author returns the customer, an instance of your User model. Shopper registers no morph alias for the User model, so author_type stores its class name, such as App\Models\User:

$customer = $review->author;

$name = $review->author?->full_name;

The author is null when the customer was deleted. To list the reviews of a customer, compare author_type with the value of getMorphClass(), as shown in Retrieving Reviews.

HasReviews Contract

The product model implements the Shopper\Core\Contracts\HasReviews contract with the InteractsWithReviews trait. The trait adds a ratings relationship, which returns every review of the product, pending ones included, and the rating methods below.

Product variants have no reviews of their own: a customer reviews the product. The trait works on any model, but the admin page and the Store API only read product reviews.

Rating Methods

The trait adds methods to read, count and average the reviews of a product. Several of them count pending reviews unless you ask otherwise, so check each one before you display its result to customers.

Getting Ratings

The ratings relationship is the most direct way to read the reviews of a product. Combine it with the approved scope for the storefront:

$reviews = $product->ratings()
    ->approved()
    ->with('author')
    ->latest()
    ->get();

The trait also has helpers that take an ID and return a collection of reviews ordered by created_at, newest first by default:

$product->getAllRatings($product->id);

$product->getApprovedRatings($product->id);

$product->getNotApprovedRatings($product->id);

$product->getRecentRatings($product->id, limit: 5);

$product->getRecentUserRatings($customer->id, limit: 5, approved: true);

getRecentRatings() returns approved reviews only. getRecentUserRatings() takes the ID of a customer and returns their reviews on every product. These helpers filter on reviewrateable_id or author_id without the morph type, so they mix models once a second model receives reviews. The ratings relationship has no such limit.

Rating Counts

countRating() returns the number of reviews of the product, pending ones included. sumRating() returns the sum of the ratings, wrapped in a collection:

$all = $product->countRating();

$published = $product->ratings()->approved()->count();

$sum = $product->sumRating(onlyApproved: true)->first();

Average Ratings

averageRating() returns the average rating wrapped in a collection. Pass round to round it in the query and onlyApproved to leave out pending reviews, which it counts by default:

$average = $product->averageRating(round: 1, onlyApproved: true)->first();

The value is null when the product has no review. On a product list, load the count and the average with the products instead of calling these methods once per product:

use Illuminate\Database\Eloquent\Builder;
use Shopper\Core\Models\Contracts\Product;

$products = resolve(Product::class)::query()
    ->publish()
    ->withCount(['ratings as reviews_count' => fn (Builder $query) => $query->approved()])
    ->withAvg(['ratings as average_rating' => fn (Builder $query) => $query->approved()], 'rating')
    ->paginate(12);

Rating Percentage

ratingPercent() returns the share of reviews with exactly the given rating, as a percentage rounded to one decimal. It counts pending reviews:

$fiveStars = $product->ratingPercent(5);

For the rating distribution of a product page, group the approved reviews by rating in one query:

$distribution = $product->ratings()
    ->approved()
    ->selectRaw('rating, COUNT(*) as total')
    ->groupBy('rating')
    ->pluck('total', 'rating');

The contract also declares averageCustomerServiceRating(), averageQualityRating(), averageFriendlyRating(), averagePricingRating() and the matching count*Rating() methods. They read columns that the reviews table does not have, and throw a QueryException: do not call them.

Configuration

Reviews are on by default. Their settings are the feature flag, the admin components and the Store API options described in From a Storefront.

Disabling Reviews

If your store does not collect reviews, disable the feature in config/shopper/features.php:

config/shopper/features.php
use Shopper\Enum\FeatureState;

return [
    'review' => FeatureState::Disabled,
];

The reviews page is no longer registered and the Reviews item leaves the sidebar. The flag only changes these two: the Store API review endpoints, the rating of the Top Selling Products widget on the Dashboard and the rating rule of automatic collections keep reading the reviews already stored. The Configuration page lists every feature flag.

Components

The reviews section of the admin panel is made of one page and one slide-over. To replace either with your own Livewire component, publish the component file of the section:

php artisan shopper:component:publish review

The command creates config/shopper/components/review.php:

config/shopper/components/review.php
use Shopper\Livewire;

return [
    'pages' => [
        'review-index' => Livewire\Pages\Reviews\Index::class,
    ],
    'components' => [
        'slide-overs.review-detail' => Livewire\SlideOvers\ReviewDetail::class,
    ],
];

To add content above or below the reviews table without replacing the page, register a view on the REVIEWS_TABLE_BEFORE or REVIEWS_TABLE_AFTER render hook of Shopper\View\CatalogRenderHook. The Configuration page explains how component overriding works.

Usage

The examples below read products through the product contract, so they keep working after you swap the product model.

Creating Reviews

A review is created pending, because the approved column defaults to false. The model has no $fillable list: pass only validated fields, or a request that sends approved publishes its own review.

Via Product Model

rating() creates a review of the product, with the customer as its author:

use Shopper\Core\Models\Contracts\Product;

$product = resolve(Product::class)::query()
    ->where('slug', 'classic-t-shirt')
    ->firstOrFail();

$review = $product->rating([
    'rating' => 5,
    'title' => 'Fits perfectly',
    'content' => 'Soft cotton, true to size, and it kept its shape after ten washes.',
    'is_recommended' => true,
], $customer);

Via Review Model

createRating() does the same from the review model, with the product as its first argument:

use Shopper\Core\Models\Review;

$review = (new Review)->createRating($product, [
    'rating' => 4,
    'title' => 'Good quality',
    'content' => 'Nice fabric, the color is a little darker than on the photos.',
    'is_recommended' => true,
], $customer);

Direct Creation

Through the ratings relationship, Eloquent fills reviewrateable_type and reviewrateable_id. Fill the author columns yourself, with the morph class of the customer:

$review = $product->ratings()->create([
    'rating' => 5,
    'title' => 'Best purchase this year',
    'is_recommended' => true,
    'author_type' => $customer->getMorphClass(),
    'author_id' => $customer->getKey(),
]);

Do not write get_class($product) in reviewrateable_type: the product stores its product alias, and the Store API and the admin panel look reviews up by that alias.

Updating Reviews

Update a review like any Eloquent model. updateRating() on the product finds the review by its ID and updates it:

$review->update([
    'rating' => 4,
    'content' => 'Still great after six months, one seam came loose.',
]);

$product->updateRating($review->id, ['title' => 'Great, with one flaw']);

Approval Management

updatedApproved() publishes or unpublishes a review. The approved scope keeps the published ones:

use Shopper\Core\Models\Review;

$review->updatedApproved(true);

$review->updatedApproved(false);

$published = Review::query()->approved()->count();

The Approve, Reject and Mark as spam actions of the admin panel call the same method: approving sets approved to true, and both rejecting and marking as spam set it to false. A rejected review stays in the table, and a merchant can approve it later.

Deleting Reviews

Reviews are deleted for good, the model has no soft deletes. Delete a review directly, or through the product with its ID:

$review->delete();

$product->deleteRating($review->id);

Retrieving Reviews

Query the Review model for reviews across products, such as the moderation queue or the reviews of one customer:

use Shopper\Core\Models\Review;

$pending = Review::query()
    ->where('approved', false)
    ->with(['author', 'reviewrateable'])
    ->oldest()
    ->get();

$customerReviews = Review::query()
    ->where('author_type', $customer->getMorphClass())
    ->where('author_id', $customer->getKey())
    ->with('reviewrateable')
    ->latest()
    ->get();

$review = Review::findByPublicId('01JZ8Q4X7M2N3P5R6S7T8V9W0Y');

Storefront Example

A storefront built in the same Laravel application reads and creates reviews with the model. The examples below show a product page and a review form.

Review Display

The product page loads the count and the average of the approved reviews with the product, then paginates the reviews:

app/Http/Controllers/ProductController.php
<?php

namespace App\Http\Controllers;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\View\View;
use Shopper\Core\Models\Contracts\Product;

class ProductController extends Controller
{
    public function show(string $slug): View
    {
        $product = resolve(Product::class)::query()
            ->publish()
            ->where('slug', $slug)
            ->withCount(['ratings as reviews_count' => fn (Builder $query) => $query->approved()])
            ->withAvg(['ratings as average_rating' => fn (Builder $query) => $query->approved()], 'rating')
            ->firstOrFail();

        $reviews = $product->ratings()
            ->approved()
            ->with('author')
            ->latest()
            ->paginate(10);

        return view('products.show', ['product' => $product, 'reviews' => $reviews]);
    }
}

The view shows the summary, then each review:

resources/views/products/show.blade.php
<p>{{ number_format((float) $product->average_rating, 1) }} out of 5, from {{ $product->reviews_count }} reviews</p>

@foreach ($reviews as $review)
    <article>
        <h3>{{ $review->title }}</h3>
        <p>{{ $review->rating }}/5 by {{ $review->author?->first_name }}, {{ $review->created_at->diffForHumans() }}</p>
        <p>{{ $review->content }}</p>

        @if ($review->is_recommended)
            <p>Recommends this product</p>
        @endif
    </article>
@endforeach

{{ $reviews->links() }}

Review Submission

The review form posts to a route of your application. The controller validates the fields, refuses a second review of the same product by the same customer, and creates the review pending:

app/Http/Controllers/ProductReviewController.php
<?php

namespace App\Http\Controllers;

use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Shopper\Core\Models\Contracts\Product;

class ProductReviewController extends Controller
{
    public function store(Request $request, string $slug): RedirectResponse
    {
        $product = resolve(Product::class)::query()
            ->publish()
            ->where('slug', $slug)
            ->firstOrFail();

        $validated = $request->validate([
            'rating' => ['required', 'integer', 'between:1,5'],
            'title' => ['nullable', 'string', 'max:255'],
            'content' => ['nullable', 'string', 'max:2000'],
            'is_recommended' => ['boolean'],
        ]);

        $customer = $request->user();

        $alreadyReviewed = $product->ratings()
            ->where('author_type', $customer->getMorphClass())
            ->where('author_id', $customer->getKey())
            ->exists();

        if ($alreadyReviewed) {
            return back()->withErrors(['rating' => 'You have already reviewed this product.']);
        }

        $product->rating($validated, $customer);

        return back()->with('status', 'Thank you, your review will appear once it is approved.');
    }
}

Register the route behind the auth middleware, so every review has a customer:

routes/web.php
use App\Http\Controllers\ProductReviewController;

Route::post('/products/{slug}/reviews', [ProductReviewController::class, 'store'])
    ->middleware('auth')
    ->name('products.reviews.store');

Events

Shopper dispatches no review event of its own. Listen to the Eloquent model events instead. The admin panel approves and rejects reviews with update(), so the updated event fires on each moderation. This listener emails the customer when their review is published:

app/Providers/AppServiceProvider.php
use App\Notifications\ReviewPublished;
use Shopper\Core\Models\Review;

public function boot(): void
{
    Review::updated(function (Review $review): void {
        if ($review->wasChanged('approved') && $review->approved) {
            $review->author?->notify(new ReviewPublished($review));
        }
    });
}

The Events page covers listeners and queues.

Permissions

The admin panel checks three permissions of the reviews resource, in the Products group:

PermissionAllows
reviews.browseOpening the reviews page and a review
reviews.editApproving and rejecting a review
reviews.deleteDeleting a review, one at a time or in bulk, and marking a review as spam

The Reviews sidebar item is shown to users who have products.browse, while the page itself checks reviews.browse. reviews.read and reviews.create are seeded with the others, but the admin panel never checks them. Shopper 2.x named these permissions browse_reviews, edit_reviews and so on; the Access Control page explains how the upgrade renames them.

In the Admin

Merchants moderate reviews under Customers, Reviews. The page opens with the average rating, the number of reviews and how many arrived in the last 30 days, the share of 5-star reviews and the number of reviews pending moderation, then a breakdown by rating and the share of customers who recommend the product. The table has All, Pending and Approved tabs, lists the customer, product, rating, status and date of each review, and filters by rating, product, customer and recommendation. A review opens in a slide-over with the Approve, Reject and Mark as spam actions. The User Guide walks through these screens.

From a Storefront

The Store API exposes the approved reviews under the store prefix, set by SHOPPER_API_PREFIX. There is no endpoint to submit a review: a storefront that collects reviews posts them to a route of its own Laravel application, as in Review Submission.

EndpointReturns
GET /store/products/{slug}/reviewsThe approved reviews of a published product, paginated, newest first. Filter with filter[rating]=5, sort with sort=rating or sort=-created_at
GET /store/reviewsThe latest approved reviews across the store, for a testimonials block. Not paginated, capped at latest_limit

A review resource has the type reviews and carries title, content, rating, is_recommended, created_at and an author object. The author is reduced to a display name, the first name and the initial of the last name such as Sarah K., and an avatar picture URL. The author's ID never leaves the API.

The product reviews endpoint adds the aggregates of the approved reviews to meta, so a product page needs one request:

{
    "meta": {
        "reviews_count": 5,
        "average_rating": 4.2,
        "rating_distribution": { "1": 0, "2": 1, "3": 0, "4": 1, "5": 3 }
    }
}

On the products endpoints, include=rating adds rating, the average of the approved reviews rounded to one decimal, and reviews_count to each product:

curl "https://example.com/store/products?include=rating"

The rating filter and the created_at and rating sorts of the product reviews endpoint come from Shopper\Api\Http\Resources\ReviewResource, and Extending the Allowlists shows how to change them. The number of reviews /store/reviews returns, 20 by default, is set by reviews.latest_limit in config/shopper/api.php:

config/shopper/api.php
'reviews' => [
    'latest_limit' => 20,
],

The review endpoints are not filtered by the channel of the request, as noted in Channels, and they do not read the review feature flag: they keep answering after you disable reviews in the admin panel.

The JavaScript SDK wraps both endpoints:

import Shopper from '@shopperlabs/shopper-sdk'

const sdk = new Shopper({ baseUrl: 'https://example.com' })

const { data, meta } = await sdk.store.product.reviews('classic-t-shirt', {
    filter: { rating: 5 },
    page: { size: 10 },
})

const testimonials = await sdk.store.review.latest()

The Store API Catalog guide covers the review endpoints.

Last updated on

Edit on GitHub