README

This is where your description should go. Limit it to a paragraph or two. Consider adding a small example.

Installation
Usage Examples
Testing
Changelog
Contributing
Credits
License

Installation

You can install the package via composer:

composer require centrex/ratings

You can publish the config file with:

php artisan vendor:publish --tag="ratings-config"

This is the contents of the published config file:

return [
    'users' => [
        'table' => 'users',
        'primary_key' => 'user_id',
    ],

    'max_rating' => 5,
    
    'undo_rating' => true,
];

Usage

Add a InterectsWithRating trait to the Model you want to be ratable.

use Centrex\Ratings\Concerns\InterectsWithRating;

class Product extends Model
{
    use InterectsWithRating;
    
    // ...
}

Now you can rate any Model.

Rate the Model

$product = Product::find(1);

$product->rate(4);

$product->rate(score: 2);

View Models' ratings

$product->ratings;

You can get an overall percentage of the amount of Users' who have rated a Model:

Imagine you want a five-star rating system, and you have a Model that has been rated a 3 and a 5 by two Users'

$product->ratingPercent(maxLength: 5);

This will equate to 80%. A float is returned. Changing the maxLength will recalculate the percentage.

You could then use this percentage for the score attribute of the component.

Note

By default, the maxLength is determined by a config option. You can override this by passing a value to the method.

Unrating Models

By default, you can unrate a Model. If you don't want Users' to unrate Models, set the undo_rating config option to true.

To unrate a Model, you can use the unrate method:

$product->unrate();

The package comes with a bunch of Attributes that you can use. The results of these are based off a single Model been rated by two Users' with a 3 and 5 rating.

$product->averageRating; // "4.0000"
$product->averageRatingByUser; // "5.0000"
$product->averageSumOfUser; // 5
$product->ratedByUsers; // 2
$product->ratedInTotal; // 2
$product->sumRating; // "8"

Livewire Component

To see the ratings in action, you can use the Livewire component. This allows you to show the ratings on the front-end statically and let the User's rate the Model by clicking on the stars.

Warning

You must have both Tailwind CSS and Font Awesome installed, though Font Awesome can be replaced with your own preferred icon set

Use the component

<livewire:rating size="text-7xl" score="55" :model="$product" />

The component has customisable attributes, including:

public string $iconBgColor = 'text-yellow-300';
public string $iconFgColor = 'text-yellow-400';
public float $score = 0;
public string $size = 'text-base';
public bool $static = false;

If you have the config for unrating a Model set to true, an icon shows that allows you to unrate the Model.

Testing

🧹 Keep a modern codebase with Pint:

composer lint

✅ Run refactors using Rector

composer refacto

⚗️ Run static analysis using PHPStan:

composer test:types

✅ Run unit tests using PEST

composer test:unit

🚀 Run the entire test suite:

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

License

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

centrex / ratings

Maintainers

Details