Reviews
Complete reference for the Review model, ratings, and product review management in Shopper.
Reviews allow customers to rate and review products. Shopper provides a flexible review system with approval workflows, rating calculations, and polymorphic relationships.
Model
The model used is Shopper\Core\Models\Review. It implements Shopper\Core\Models\Contracts\Review. Unlike products or brands, the Review model is not configurable via config/shopper/models.php and has no admin model wrapper.
Products gain review capabilities through the Shopper\Core\Contracts\HasReviews interface and the Shopper\Core\Models\Traits\InteractsWithReviews trait, which provides the interface's methods. Shopper\Core\Models\Product already implements and uses both, so Shopper\Models\Product has them too.
Database Schema
Reviews are stored in the sh_reviews table (the sh_ prefix comes from table_prefix in config/shopper/core.php).
| Column | Type | Nullable | Default | Description |
|---|---|---|---|---|
id | bigint | no | auto | Primary key |
rating | integer | no | - | Rating value (typically 1-5) |
title | text | yes | null | Review title |
content | text | yes | null | Review content |
is_recommended | boolean | no | false | Customer recommends product |
approved | boolean | no | false | Review approval status |
reviewrateable_id | bigint | no | - | Polymorphic relation ID (product) |
reviewrateable_type | string | no | - | Polymorphic relation type |
author_id | bigint | no | - | Polymorphic relation ID (user) |
author_type | string | no | - | Polymorphic relation type |
created_at | timestamp | yes | null | Creation timestamp |
updated_at | timestamp | yes | null | Last update timestamp |
Shopper registers a morph map for its models, so reviewrateable_type stores the alias product, not a class name. author_type stores your user model's morph class (App\Models\User unless your application maps it). When you write or query these columns yourself, use $model->getMorphClass(), never get_class($model) or Product::class.
Relationships
Reviewrateable (Product)
// Get the reviewed entity (usually a product)
$review->reviewrateable; // Instance of config('shopper.models.product')Author (User)
// Get the review author
$review->author; // User modelHasReviews Contract
Products implement the HasReviews contract and use the InteractsWithReviews trait, which provides the contract's methods:
use Shopper\Core\Contracts\HasReviews;
use Shopper\Core\Models\Traits\InteractsWithReviews;
class Product extends Model implements HasReviews
{
use InteractsWithReviews;
}Rating Methods
Getting Ratings
Each get*Ratings() method takes an id as its first argument (the product id, or the customer id for getRecentUserRatings()) and returns a collection of Review models ordered by creation date.
// Get all ratings for a product, pending ones included
$product->ratings; // Collection of Review models
// Get all ratings, newest first ('asc' for oldest first)
$product->getAllRatings($product->id, 'desc');
// Get only approved ratings
$product->getApprovedRatings($product->id);
// Get pending (not approved) ratings
$product->getNotApprovedRatings($product->id);
// Get the 5 most recent approved ratings
$product->getRecentRatings($product->id, 5);
// Get a customer's 5 most recent approved ratings, across all products
$product->getRecentUserRatings($userId, 5, approved: true);Rating Counts
// Count all ratings, pending ones included
$product->countRating(); // Returns integer
// Get rating sum
$product->sumRating(); // Collection with sum
// Get the sum of approved ratings only
$product->sumRating(onlyApproved: true);Average Ratings
averageRating() returns a collection holding a single value: call first() to read it. The value is null when the product has no review, and some database drivers return it as a numeric string, so cast it to float before using it as a number.
// Get average rating
$product->averageRating(); // Collection with average
// Get average rating rounded to 1 decimal
(float) $product->averageRating(round: 1)->first(); // e.g., 4.5
// Get average rating of approved reviews only
(float) $product->averageRating(round: 1, onlyApproved: true)->first();Rating Percentage
// Get percentage of 5-star ratings, pending reviews included
$product->ratingPercent(5); // e.g., 85.5
// Useful for displaying rating distribution
$distribution = [
5 => $product->ratingPercent(5),
4 => $product->ratingPercent(4),
3 => $product->ratingPercent(3),
2 => $product->ratingPercent(2),
1 => $product->ratingPercent(1),
];Creating Reviews
Via Product Model
use Shopper\Models\Product;
$product = Product::query()->find($id);
// Create a review
$review = $product->rating([
'rating' => 5,
'title' => 'Excellent product!',
'content' => 'This product exceeded my expectations.',
'is_recommended' => true,
'approved' => false, // Pending approval
], $user);Via Review Model
use Shopper\Core\Models\Review;
$review = new Review;
$review = $review->createRating($product, [
'rating' => 4,
'title' => 'Good quality',
'content' => 'Happy with my purchase.',
'is_recommended' => true,
], $user);Direct Creation
$review = Review::query()->create([
'rating' => 5,
'title' => 'Love it!',
'content' => 'Best purchase I made.',
'is_recommended' => true,
'approved' => false,
'reviewrateable_id' => $product->id,
'reviewrateable_type' => $product->getMorphClass(),
'author_id' => $user->id,
'author_type' => $user->getMorphClass(),
]);Updating Reviews
// Via product model
$product->updateRating($reviewId, [
'rating' => 4,
'content' => 'Updated review content.',
]);
// Via review model
$review = new Review;
$review->updateRating($reviewId, [
'title' => 'Updated title',
'content' => 'Updated content',
]);Approval Management
// Approve a review
$review->updatedApproved(true);
// Unapprove a review
$review->updatedApproved(false);
// Direct update
$review->update(['approved' => true]);Deleting Reviews
// Via product model
$product->deleteRating($reviewId);
// Via review model
$review = new Review;
$review->deleteRating($reviewId);
// Direct delete
Review::query()->findOrFail($reviewId)->delete();Retrieving Reviews
use Shopper\Core\Models\Review;
// Get all reviews
$reviews = Review::query()
->with(['author', 'reviewrateable'])
->latest()
->get();
// Get pending reviews
$pending = Review::query()
->where('approved', false)
->with('author')
->get();
// Get approved reviews for a product
$productReviews = Review::query()
->where('reviewrateable_id', $product->id)
->where('reviewrateable_type', $product->getMorphClass())
->where('approved', true)
->with('author')
->latest()
->paginate(10);
// Get reviews by user
$userReviews = Review::query()
->where('author_id', $user->id)
->where('author_type', $user->getMorphClass())
->with('reviewrateable')
->get();Configuration
Disabling Reviews
If your store doesn't need product reviews, disable the feature in config/shopper/features.php:
use Shopper\Enum\FeatureState;
return [
'review' => FeatureState::Disabled,
];This removes the reviews page and its sidebar link from the admin panel. The Review model and the product rating methods keep working, so your storefront can still use them.
Permissions
The permissions seeder creates five permissions for reviews, listed in the products group of the role permissions screen:
| Permission | Description |
|---|---|
browse_reviews | Open the reviews list and a review's detail panel |
read_reviews | Created with the others, not checked by the 2.x reviews pages |
add_reviews | Created with the others, not checked: the admin panel does not create reviews |
edit_reviews | Approve a review, or set an approved review back to pending |
delete_reviews | Delete reviews, one at a time or in bulk |
Components
To customize the admin UI for review management:
php artisan shopper:component:publish reviewCreates 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,
],
];Storefront Example
Review Display
namespace App\Http\Controllers;
use Shopper\Models\Product;
class ProductController extends Controller
{
public function show(string $slug)
{
$product = Product::findBySlug($slug);
// Get approved reviews
$reviews = $product->ratings()
->where('approved', true)
->with('author')
->latest()
->paginate(10);
// Get rating stats
$averageRating = (float) $product->averageRating(1, onlyApproved: true)->first();
$reviewCount = $product->ratings()->where('approved', true)->count();
// Rating distribution
$distribution = [];
for ($i = 5; $i >= 1; $i--) {
$count = $product->ratings()
->where('approved', true)
->where('rating', $i)
->count();
$distribution[$i] = [
'count' => $count,
'percentage' => $reviewCount > 0 ? ($count / $reviewCount) * 100 : 0,
];
}
return view('products.show', compact(
'product',
'reviews',
'averageRating',
'reviewCount',
'distribution'
));
}
}Review Submission
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use Shopper\Models\Product;
class ReviewController extends Controller
{
public function store(Request $request, Product $product)
{
$validated = $request->validate([
'rating' => 'required|integer|min:1|max:5',
'title' => 'nullable|string|max:255',
'content' => 'nullable|string|max:2000',
'is_recommended' => 'boolean',
]);
// Check if user already reviewed this product
$existingReview = $product->ratings()
->where('author_id', auth()->id())
->where('author_type', auth()->user()->getMorphClass())
->exists();
if ($existingReview) {
return back()->with('error', 'You have already reviewed this product.');
}
// Create review (pending approval)
$product->rating([
...$validated,
'approved' => false,
], auth()->user());
return back()->with('success', 'Thank you! Your review is pending approval.');
}
}Review Management (Admin)
Shopper's admin panel already lists, approves and deletes reviews. Write a controller like this one only for a back office of your own.
namespace App\Http\Controllers\Admin;
use App\Http\Controllers\Controller;
use Shopper\Core\Models\Review;
class ReviewController extends Controller
{
public function index()
{
$reviews = Review::query()
->with(['author', 'reviewrateable'])
->latest()
->paginate(20);
return view('admin.reviews.index', compact('reviews'));
}
public function approve(Review $review)
{
$review->updatedApproved(true);
return back()->with('success', 'Review approved.');
}
public function reject(Review $review)
{
$review->delete();
return back()->with('success', 'Review deleted.');
}
}Blade Template Example
{{-- Product rating summary --}}
<div class="rating-summary">
<div class="average">
<span class="score">{{ $averageRating ?? 0 }}</span>
<span class="max">/5</span>
</div>
<div class="stars">
@for ($i = 1; $i <= 5; $i++)
<svg class="{{ $i <= round($averageRating) ? 'text-yellow-400' : 'text-gray-300' }}">
<!-- Star icon -->
</svg>
@endfor
</div>
<p>Based on {{ $reviewCount }} reviews</p>
</div>
{{-- Rating distribution --}}
<div class="distribution">
@foreach ($distribution as $rating => $data)
<div class="row">
<span>{{ $rating }} stars</span>
<div class="bar" style="width: {{ $data['percentage'] }}%"></div>
<span>{{ $data['count'] }}</span>
</div>
@endforeach
</div>
{{-- Reviews list --}}
@foreach ($reviews as $review)
<div class="review">
<div class="header">
<span class="author">{{ $review->author->full_name }}</span>
<span class="rating">{{ $review->rating }}/5</span>
<span class="date">{{ $review->created_at->diffForHumans() }}</span>
</div>
@if ($review->title)
<h4>{{ $review->title }}</h4>
@endif
<p>{{ $review->content }}</p>
@if ($review->is_recommended)
<span class="recommended">Recommends this product</span>
@endif
</div>
@endforeachUse Cases
| Method | Use Case |
|---|---|
averageRating() | Display product rating stars |
countRating() | Show total review count |
ratingPercent() | Build rating distribution chart |
getApprovedRatings() | Display reviews on product page |
getNotApprovedRatings() | Admin review moderation queue |
getRecentUserRatings() | Customer review history |
Last updated on
Edit on GitHub