jobmetric/laravel-star

This is a star rating management package for any object in Laravel that you can use in your projects.

2.0.0 2025-08-05 20:16 UTC

Requires

• php: >=8.0.1
• jobmetric/laravel-package-core: ^1.7
• laravel/framework: >=9.19

MIT

• Majid Mohammadian

• package
• management
• laravel
• star
• jobmetric

README

Laravel Star

A modern, flexible, and test-covered Laravel package that allows your models to handle star rating functionality (e.g., 1 to 5 stars).
This package provides a clean API for both starable (e.g., articles, posts) and starrer (e.g., users, devices) models.

💾 Installation

Install via composer:

composer require jobmetric/laravel-star

Then publish and run the migration:

php artisan migrate

✨ Usage

Step 1: Add HasStar to your starable model (e.g., Article)

use JobMetric\Star\HasStar;

class Article extends Model
{
    use HasStar;
}

Step 2: Add CanStar to your starrer model (e.g., User)

use JobMetric\Star\CanStar;

class User extends Model
{
    use CanStar;
}

✅ Main Features

Add or Update a Star Rating

$article->addStar(4, $user);

You can also pass extra options like device ID:

$article->addStar(5, null, ['device_id' => 'abc-123']);

Remove a Star Rating

$article->removeStar($user);
$article->removeStar(null, 'abc-123');

Check if a Star Exists

$article->hasStar($user); // true/false

Get Star Count and Average

$article->starCount(); // e.g., 10
$article->starAvg();   // e.g., 4.3

Get Summary

$article->starSummary(); 
// => collect([5 => 3, 4 => 5, 3 => 2])

Get Latest Stars

$article->latestStars(5); // returns latest 5 stars

Forget Stars (All for a user or device)

$article->forgetStars($user);

🎯 Conditional Methods

Rating Checks

$article->isRatedAs(4, $user);     // true
$article->isRatedAbove(3, $user);  // true
$article->isRatedBelow(5, $user);  // true

Get Rated Value

$article->getRatedValue($user); // e.g., 4

📦 CanStar Feature Set

Check if a model has starred something

$user->hasStarred($article); // true/false

Get rate value

$user->starredRate($article); // e.g., 5

Remove star from a model

$user->removeStarFrom($article);

Count by Rate or Total

$user->countStarGiven(5); // e.g., 2
$user->totalStarsGiven(); // e.g., 12

Summary of Ratings Given

$user->starSummary(); 
// => collect([5 => 4, 3 => 2])

Models that user has starred

$user->starredItems(); // Collection of models
$user->starredItems(Article::class);

Stars to specific model type

$user->starsToType(Article::class); // Collection of stars

Latest Stars Given

$user->latestStarsGiven(5); // Collection of latest 5 stars

🧱 Star Model Columns

Field	Description
starable_type	Polymorphic class of starable (e.g., Post)
starable_id	ID of the starable model
starred_by_type	Polymorphic class of starrer (e.g., User)
starred_by_id	ID of the starrer
rate	Star rating (e.g., 1 to 5)
ip	IP address of the request
device_id	Optional device identifier
source	Source of the request (e.g., web, app, api)
created_at	Timestamp when the star was created
updated_at	Timestamp when the star was last updated

🧪 Events

Event	Triggered When
StarAddEvent	A new star is created and saved
StarRemovingEvent	A star is about to be deleted
StarRemovedEvent	A star has been successfully deleted
StarUpdatingEvent	A star is about to be updated
StarUpdatedEvent	A star has been successfully updated

Contributing

Thank you for considering contributing to the Laravel Star! The contribution guide can be found in the CONTRIBUTING.md.

License

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