alhawari/rateify

A simple Laravel package for adding rating functionality (1–5 stars) to any model.

v1.0.1 2025-11-12 07:48 UTC

Requires

• php: >=8.0
• illuminate/support: ^9.0|^12.0

MIT

• Alhawari-Code

README

A robust, flexible, and easy-to-use Laravel package for adding star ratings (1-5) to any Eloquent model. Perfect for product reviews, content ratings, and user feedback systems.

✨ Features

• Rate any Eloquent model
• Support for rating comments
• Prevent duplicate ratings
• Calculate average ratings
• Get rating counts
• Check if a user has rated an item
• Remove ratings
• Fully customizable (min/max rating values)
• RESTful API endpoints
• Secure with built-in authentication
• Comprehensive validation
• Well-documented code

🚀 Installation

1. Install the package via Composer:

composer require alhawari/rateify

1. Publish the configuration file (optional):

php artisan vendor:publish --provider="Alhawari\\Rateify\\RateifyServiceProvider" --tag=config

1. Publish and run the migrations:

php artisan vendor:publish --provider="Alhawari\\Rateify\\RateifyServiceProvider" --tag=migrations
php artisan migrate

⚙️ Configuration

The configuration file allows you to customize the rating system:

return [
    'max_rating' => 5,  // Maximum rating value
    'min_rating' => 1,  // Minimum rating value
];

🛠 Usage

1. Add the Rateable Trait to Your Model

use Alhawari\Rateify\Traits\Rateable;
use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    use Rateable;
    
    // Optional: Add custom logic to control who can rate
    public function canBeRated($userId): bool
    {
        return $this->user_id !== $userId; // Prevent users from rating their own posts
    }
}

2. Basic Usage

// Get the average rating
$averageRating = $post->averageRating();

// Get the number of ratings
$ratingCount = $post->ratingsCount();

// Check if a user has rated the post
$hasRated = $post->isRatedBy($userId);

// Get a user's rating
$userRating = $post->getUserRating($userId);

// Rate a post
$rating = $post->rate($userId, 5, 'Great post!');

// Rate using the authenticated user
$rating = $post->rateByUser(4, 'Nice!');

// Remove a rating
$removed = $post->removeRating($userId);

🌐 API Endpoints

Rate or Update a Rating

POST /rateify/rate

Parameters:

Parameter	Type	Required	Description
model	string	Yes	Fully qualified model class
id	int	Yes	ID of the model to rate
value	int	Yes	Rating value (1-5)
comment	string	No	Optional comment with the rating

Example Response:

{
    "success": true,
    "message": "Rating saved successfully.",
    "data": {
        "rating": 5,
        "comment": "Great post!",
        "average": 4.5,
        "count": 10,
        "user_rating": 5
    }
}

Remove a Rating

DELETE /rateify/rate

Parameters:

Parameter	Type	Required	Description
model	string	Yes	Fully qualified model class
id	int	Yes	ID of the model

🔒 Permissions

By default, all API endpoints are protected by the auth middleware, so only authenticated users can rate items.

🧪 Testing

composer test

🤝 Contributing

Please see contact at [e-mail] .

🔐 Security

If you discover any security related issues, please email [e-mail] or use issue tracker.

📝 License

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

📚 Credits

• Your Name
• All Contributors

⭐ If you find this package useful, please consider giving it a star on GitHub.