Laravel Review Rateable Laravel Package

Getting Started

ReviewRateable Core v2.3.0 is an additive release: you can update the package without running any database migration. Existing rating queries keep their prior all-criteria behavior, so the safest first step is to confirm your current rating screens still behave as expected, then adopt the new criterion-specific helpers where you need per-key breakdowns.

Start by locating the model that uses the package’s review/rating trait—typically a Product, Post, or similar model. The first practical use case is a product rating summary:

$counts = $product->ratingCountsForKey('overall');
$stats = $product->ratingStatsForKey('overall');
$reviews = $product->getReviewsByRatingForKey(5, 'overall');

These are the methods to reach for when your UI needs a star distribution, aggregate statistics, or a filtered review list for one criterion such as overall, quality, or service. For application code that should not depend directly on the model helpers, inject the new CriterionRatingContract instead.

If this is a fresh install rather than an upgrade, follow the package’s normal installation steps first—Composer install, publish config and migrations if required, and add the package trait to your reviewable model. For this specific release, no new migration is required.

Implementation Patterns

Criterion-specific rating summaries. Use ratingCountsForKey() to build star distributions for a single criterion, and ratingStatsForKey() when you need aggregate values such as average and total. This is a better fit than the existing all-criteria query methods when the UI has tabs or sections for overall, quality, delivery, etc.

$distribution = $product->ratingCountsForKey('quality');
$summary = $product->ratingStatsForKey('quality');

Filtered review lists. getReviewsByRatingForKey($rating, $key) is useful for “show all 5-star quality reviews” screens, API endpoints, and moderation-adjacent views. Keep the criterion explicit in the call site rather than relying on implicit defaults, especially if your application exposes multiple rating keys.

Prefer contract injection in services. The new CriterionRatingContract is the integration point for service classes, actions, and controllers that should be testable without binding to an Eloquent model helper. Bind or resolve it through Laravel’s container and inject it where criterion-based queries are part of your domain logic.

public function __construct(private CriterionRatingContract $criterionRatings)
{
}

Use the contract when you need consistent behavior across models or when you want to mock rating queries in tests. Use the model helpers for simple controller/Blade usage where direct access is clearer.

Department scoping is a first-class concern. By default, these queries use the default department and approved reviews. If your application uses departments, pass the intended department explicitly. Pass null only when you intentionally want to count a key across departments. Treat null as a deliberate “global” mode, not a default fallback.

Approval state should be explicit. The helpers return approved reviews by default. For moderation queues, admin reporting, or “pending reviews” screens, request unapproved reviews using the package’s exposed argument or contract option. Do not assume the default includes pending content.

Keep existing aggregate methods for all-criteria screens. The release notes confirm that existing rating query methods retain their all-criteria behavior. That is useful for overall summary widgets, but it also means those methods are not a drop-in replacement for criterion-filtered views. Choose the method based on whether the screen is criterion-specific or intentionally cross-criterion.

A common workflow:

1. Use existing all-criteria methods for the top-level product score.
2. Use ratingCountsForKey() and ratingStatsForKey() for per-criterion tabs.
3. Use getReviewsByRatingForKey() for drill-down review lists.
4. Inject CriterionRatingContract in service-layer code that needs the same behavior.
5. Cache expensive distributions where the same criterion summary is rendered repeatedly.

Gotchas and Tips

• The default department is default. If your app uses named departments, omitting the department argument will silently scope results to default. This is the most likely source of “missing ratings” after adoption.
• null department means across departments. Do not pass null casually. It changes the query semantics from “this department” to “all departments.”
• Approved-only is the default. Admin and moderation views need to explicitly request unapproved reviews. If counts look lower than expected, check approval filtering first.
• Existing methods are unchanged. The release preserves all-criteria behavior for existing rating query methods. Do not assume old methods now accept or apply a criterion.
• No migration required. Updating to v2.3.0 should not require schema changes. If you use config or package caches in deployment, clear them as part of your normal release process.
• Contract binding is the extension point. If you need to customize criterion-based queries, override the CriterionRatingContract binding in a service provider rather than scattering model-specific logic.
• Watch query count on distribution screens. Rendering counts and stats for multiple criteria can produce several queries. Cache per-product/per-criterion summaries where appropriate, and invalidate on review creation or approval changes.
• Test department and approval permutations. Cover at least: default department with approved reviews, named department, null department, and unapproved review access. These combinations are where behavior is easiest to misread.
• Keep criteria keys consistent. Use the same key names in storage, UI labels, and query calls. A typo in a criterion key can look like missing data rather than an error.