README

Imagine you want to add star ratings to an Eloquent Model. This package enables that feature for you. Ratings can be from 0 to 5 stars, +1/-1 or any other range you like.

This package provides a HasRatings and AddsRatings traits that, once installed on a model, allows you to do things like this:

// Add a rating for a model
$model->createRating($rating = 4, $author = $user, $body = 'Very nice!');

// Calculate the average rating for a model
$model->averageRating();

// Sum the ratings for a model
$model->sumRating();

Installation

You can install the package via composer:

composer require agilepixels/laravel-rateable

The migrations for the ratings are loaded automatically. You can migrate the ratings table using:

php artisan migrate

A config file is included to specify the range for the ratings. By default, rating are between 0 and 5. However, you are free to use it otherwise. For instance, ratings like +1 or -1. You can publish the config-file with:

php artisan vendor:publish --provider="AgilePixels\Rateable\RateableServiceProvider" --tag="config"

Using the trait

To enable the ratings for a model, use the AgilePixels\Rateable\Traits\HasRatings trait on the model.

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;
use AgilePixels\Rateable\Traits\HasRating;

class Product extends Model
{
    use HasRating;
}

If you would like to calculate the ratings for the author model, you may use the AgilePixels\Rateable\Traits\AddsRatings trait on your User model (or any other model that is able to add a rating).

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;
use AgilePixels\Rateable\Traits\AddsRating;

class User extends Model
{
    use AddsRating;
}

Usage

The createRating Method

To create a rating for a model that HasRatings, you can use the creatRating() method. The method takes two variables: $rating and $author. The $rating can be an integer or a float within the range defined in your config file (default is 0 to 5). The $author refers to the model that AddsRatings which, in most cases, is your User model.

$product->createRating($rating, $author)

Optionally, you can also post a comment for a rating. This can be done through a third string variable called $body.

$product->createRating($rating, $author, $body)

The createComment Method

Once a rating is created, you might want to respond to the rating as owner of the web application. This can be done using the createComment() method. The method takes two variables: $author and $body.

$rating->createComment($author, $body)

Calculations

Of course, you may want to display some data about the models ratings. This package provides three methods to do so:

$product->averageRating();
$product->averageRatingAsPercentage();
$product->sumRating();

The data is also available as accessor. You may access the data like this:

$product->average_rating
$product->average_rating_as_percentage
$product->sum_rating

Credits

Lex de Willigen

License

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

agilepixels / laravel-rateable

Maintainers

Details