Awesome
Laravel Review
<!-- [![Total Downloads](https://img.shields.io/packagist/dt/fajarwz/laravel-review.svg?style=flat-square)](https://packagist.org/packages/fajarwz/laravel-review) -->Installation
You can install the package via composer:
composer require fajarwz/laravel-review
You can publish and run the migrations with:
php artisan vendor:publish --provider="Fajarwz\LaravelReview\LaravelReviewServiceProvider"
php artisan migrate
Setup
Models Setup
Include the necessary traits in your models:
Reviewed/Reviewable Model
For models that can be reviewed, use the CanBeReviewed
trait:
use Fajarwz\LaravelReview\Traits\CanBeReviewed;
class Mentor extends Model
{
use CanBeReviewed;
// Optionally, use CanReview if the model can also act as a reviewer
// use CanReview;
}
Reviewer Model
For models that can submit reviews, use the CanReview
trait:
use Fajarwz\LaravelReview\Traits\CanReview;
class Mentee extends Model
{
use CanReview;
}
Usage
Creating a Review
To create a new review:
$mentee = Mentee::find(1);
$mentor = Mentor::find(1);
// Create an approved review
$mentee->review($mentor, 4.5);
// Create an unapproved review
$mentee->review($mentor, 3.0, 'Needs improvement', false);
The review()
method takes a reviewable model and a rating. Optionally, set the review content to add a review and set the $isApproved
parameter to false
to create an unapproved review.
Only approved reviews are calculated in the review_summaries
table. Updating an unapproved review will not affect the summary.
If the reviewer model has already submitted a review for the same reviewable model, a Fajarwz\LaravelReview\Exceptions\DuplicateReviewException
will be thrown.
To update a review, use updateReview()
instead.
Updating a review
To update an existing review:
$mentee->updateReview($mentor, 5, 'Mentor is even better now!');
The updateReview()
method accepts three parameters: a reviewable model, a rating, and an optional review text.
Unreviewing a model
To cancel an existing review:
$mentee->unreview($mentor);
If the reviewer model has not previously reviewed the model, a Fajarwz\LaravelReview\Exceptions\ReviewNotFoundException
will be thrown.
Approving a Review
To approve a review:
$review = $mentor->receivedReviews()->first();
$review->approve();
Unapproving a Review
To unapprove a review:
$review = $mentor->receivedReviews()->first();
$review->unapprove();
Querying Reviews
Get all received reviews
By default, only approved reviews are retrieved:
$mentor->receivedReviews()->get();
To get the latest received reviews:
$mentor->latestReceivedReviews()->paginate();
To get the top-rated received reviews:
$mentor->topRatedReceivedReviews()->paginate();
To include both approved and unapproved reviews:
$mentor->receivedReviews()->withUnapproved()->get();
To include reviewer information:
Mentor::with('receivedReviews.reviewer')->paginate();
This query will eager load the reviewer information for each received review.
Note: Consider using appropriate eager loading strategies based on your application's needs to optimize query performance.
Get a review received from a specified reviewer
To retrieve a review that a reviewer has given to reviewable:
$review = $mentor->getReceivedReview($mentee);
This method returns a single Review
instance or null
if no review exists.
To include unapproved reviews in the search, pass true
as the second parameter:
$includeUnapproved = true;
$review = $mentor->getReceivedReview($mentee, $includeUnapproved);
Get all given reviews
To get all reviews given by a model:
$mentee->givenReviews()->get();
To include reviewable model information:
Mentee::with('givenReviews.reviewable')->paginate();
This will eager load the reviewable model for each review given by the model.
Get a review given from a specified reviewable model
To retrieve a given review that a reviewable has received from reviewer:
$review = $mentee->getGivenReview($mentor);
This method returns a single Review
instance or null
if no review exists.
To include unapproved reviews in the search, pass true
as the second parameter:
$includeUnapproved = true;
$review = $mentor->getGivenReview($mentee, $includeUnapproved);
Checking for Reviews
Check if a reviewable model has received a review from a specific reviewer
if ($mentor->hasReceivedReview($mentee)) {
// The mentor has received a review from the mentee
}
To include unapproved reviews in the check, pass true
as the second parameter:
$includeUnapproved = true;
if ($mentor->hasReceivedReview($mentee, $includeUnapproved)) {
// The mentor has received a review from the mentee
}
Check if the current model has given a review to the specified model
if ($mentee->hasGivenReview($mentor)) {
// The mentee has given a review to the mentor
}
To include unapproved reviews in the check, pass true
as the second parameter:
$includeUnapproved = true;
if ($mentee->hasGivenReview($mentor, $includeUnapproved)) {
// The mentee has given a review to the mentor
}
Review Model
The Fajarwz\LaravelReview\Models\Review
model includes methods for managing and querying reviews:
Approve a Review
To approve a review, use the approve()
method. This sets the approved_at
timestamp to the current date and time, indicating that the review has been approved. It also updates the review summary of the associated model.
use Fajarwz\LaravelReview\Models\Review;
$review = Review::find($id);
$review->approve();
Unapprove a Review
To unapprove a review, use the unapprove()
method. This sets the approved_at
timestamp to null, indicating that the review is no longer approved. It also updates the review summary of the associated model to decrement the rating count if necessary.
$review = Review::find($id);
$review->unapprove();
Check If a Review Is Approved
To check if a review is approved, use the isApproved()
method. This method returns true if the approved_at
timestamp is not null, and false otherwise.
$review = Review::find($id);
if ($review->isApproved()) {
// The review is approved
}
Query Approved Reviews
By default, the Review model applies a global scope to only include approved reviews. To query only approved reviews, you can use the model's standard query methods:
$approvedReviews = Review::all();
Query Unapproved Reviews
To include unapproved reviews in your query, use the withUnapproved()
method. This removes the global scope that filters out unapproved reviews, allowing you to query both approved and unapproved reviews.
$allReviews = Review::withUnapproved()->get();
Get the Reviewer
To get the model that reviewed the item, use the reviewer()
method. This method returns a polymorphic relationship to the reviewer model.
$review = Review::find($id);
$reviewer = $review->reviewer;
Get the Reviewable Model
To get the model that was reviewed, use the reviewable()
method. This method returns a polymorphic relationship to the reviewed model.
$review = Review::find($id);
$reviewable = $review->reviewable;
ReviewSummary Model
The Fajarwz\LaravelReview\Models\ReviewSummary
model represents a summary of reviews for a specific reviewable model.
Attributes
average_rating
: The average rating of all reviews for the reviewable model.review_count
: The total number of reviews for the reviewable model.
Get the Reviewable Model
The reviewable()
method defines a polymorphic relationship to the model that is being reviewed. It allows you to access the model that this review summary belongs to.
use Fajarwz\LaravelReview\Models\ReviewSummary;
$reviewSummary = ReviewSummary::find($id);
$reviewable = $reviewSummary->reviewable;
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
We welcome contributions. Please open issues or pull requests with your suggestions or improvements.
Getting Help
For questions, discussions, or seeking assistance, please use the GitHub Discussions forum. This will help keep issues focused on bug reports and feature requests.
Security Vulnerabilities
Please contact hi@fajarwz.com
Credits
License
The MIT License (MIT). Please see License File for more information.