https://github.com/cjmellor/rating
A Laravel package that allows for ratings to be added to a Model
https://github.com/cjmellor/rating
laravel rating rating-system
Last synced: 7 months ago
JSON representation
A Laravel package that allows for ratings to be added to a Model
- Host: GitHub
- URL: https://github.com/cjmellor/rating
- Owner: cjmellor
- License: mit
- Created: 2022-08-08T22:17:54.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-07-08T16:41:39.000Z (over 1 year ago)
- Last Synced: 2024-09-28T10:07:22.307Z (about 1 year ago)
- Topics: laravel, rating, rating-system
- Language: PHP
- Homepage:
- Size: 83 KB
- Stars: 27
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
[](https://packagist.org/packages/cjmellor/rating)
[](https://github.com/cjmellor/rating/actions?query=workflow%3Arun-tests+branch%3Amain)
[](https://packagist.org/packages/cjmellor/rating)
?style=for-the-badge&logo=laravel)
?style=for-the-badge&logo=livewire&labelColor=rgba(15,%2023,%2042,%201)&logoColor=rgba(251,%20112,%20169,%201))
Imagine you have a Recipes Model and you want to have your Users' rate your culinary delights. This package allows you to achieve this.
### Example
Add a `CanBeRated` trait to the Model you want to be ratable.
```php
use Cjmellor\Rating\Concerns\CanBeRated;
class Recipe extends Model
{
use CanBeRated;
// ...
}
```
Now you can rate any Model.
```php
$recipe = Recipe::find(1);
$recipe->rate(4);
```
## Installation
You can install the package via composer:
```shell
composer require cjmellor/rating
```
You can publish and run the migrations with:
```shell
php artisan vendor:publish --tag="rating-migrations"
php artisan migrate
```
You can publish the config file with:
```shell
php artisan vendor:publish --tag="rating-config"
```
This is the contents of the published config file:
```php
return [
'users' => [
'table' => 'users',
'primary_key' => 'user_id',
],
'max_rating' => 5,
'undo_rating' => true,
];
```
## Usage
To rate a Model, you must add the `CanBeRated` trait to the Model in question.
```php
use Cjmellor\Rating\Concerns\CanBeRated;
class Recipe extends Model
{
use CanBeRated;
// ...
}
```
**Rate the Model**
```php
$recipe = Recipe::find(1);
$recipe->rate(score: 2);
```
**View Models' ratings**
```php
$recipe->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'
```php
$recipe->ratingPercent(maxLength: 5);
// 80.0
```
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:
```php
$recipe->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._
```php
$recipe->averageRating; // "4.0000"
$recipe->averageRatingByUser; // "5.0000"
$recipe->averageSumOfUser; // 5
$recipe->ratedByUsers; // 2
$recipe->ratedInTotal; // 2
$recipe->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**
```html
```
The component has customisable attributes, including:
```php
public string $iconBgColor = 'text-yellow-300';
public string $iconFgColor = 'text-yellow-400';
public string $iconBg = 'far fa-star';
public string $iconFg = 'fas fa-star';
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
```shell
composer test
```
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
## License
The MIT Licence (MIT). Please see [Licence File](LICENSE.md) for more information.