fajarwz/laravel-review

Flexible and powerful review system for Laravel, let any model review and be reviewed.

1.2.0 2024-08-27 14:39 UTC

Requires (Dev)

• larastan/larastan: ^2.0
• laravel/pint: ^1.17
• orchestra/testbench: ^9.2

MIT

• fajarwz

• laravel
• review
• Rating
• fajarwz
• laravel-review

README

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 [e-mail]

Credits

• fajarwz
• All Contributors

License

The MIT License (MIT). Please see License File for more information.