Skip to content

Commit b80d6d8

Browse files
codebyraycodebyray
authored
Merge pull request #60 from codebyray/2.x
2.x
2 parents c2e7b58 + 4ea0afe commit b80d6d8

File tree

4 files changed

+420
-52
lines changed

4 files changed

+420
-52
lines changed

‎README.md

Lines changed: 106 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,12 @@
44
NOTE: This is a complete rewrite from v1. It is not compatible with previous versions of this package.
55

66

7-
Laravel Review Ratable is a flexible package that enables you to attach reviews (with multiple ratings) to any Eloquent model in your Laravel application. The package supports multiple departments, configurable rating boundaries, review approval, and a decoupled service contract so you can easily integrate, test, and extend the functionality.
7+
Laravel Review Ratable is a flexible package that enables you to attach reviews (with multiple ratings) to any Eloquent model in your Laravel application.
8+
The package supports multiple departments, configurable rating boundaries, review approval, and a decoupled service contract so you can easily integrate, test, and extend the functionality.
89

910
## Features
1011

11-
- **Polymorphic Reviews & Ratings:** Attach written reviews along with multiple rating values to any model.
12+
- **Reviews & Ratings:** Attach written reviews along with multiple rating values to any model.
1213
- **Configurable Settings:** Define custom rating keys, labels, and value boundaries (min/max) via a config file.
1314
- **Department Support:** Organize ratings by department (e.g. default, sales, support) with their own criteria.
1415
- **Review Approval:** Set a default approval status for reviews (and override per review if needed).
@@ -46,7 +47,7 @@ php artisan migrate
4647

4748
## Configuration
4849

49-
The package configuration file is located at config/laravel-review-ratable.php. Here you can adjust global settings such as:
50+
The package configuration file is located at config/review-ratable.php. Here you can adjust global settings such as:
5051

5152
- Rating Value Boundaries:
5253
- min_rating_value: Minimum rating value.
@@ -139,7 +140,7 @@ $product = Product::findOrFail($productId);
139140
// Prepare the updated data.
140141
$data = [
141142
'review' => 'Updated review text', // New review text.
142-
'department' => 'default', // Optionally, change the department.
143+
'department' => 'sales', // Optionally, change the department.
143144
'recommend' => false, // Update recommendation flag.
144145
'approved' => true, // Update approval status if needed.
145146
'ratings' => [
@@ -176,7 +177,7 @@ $product->deleteReview($reviewId);
176177
$product = Product::findOrFail($productId);
177178

178179
// Get approved reviews (with related ratings)
179-
// Default: approved = true, withRatings = true
180+
// Default: approved: true, withRatings: true
180181
$product->getReviews();
181182

182183
// Get not approved reviews (with related ratings)
@@ -187,6 +188,53 @@ $product->getReviews(approved: false);
187188
$product->getReviews(true, false);
188189
$product->getReviews(withRatings: false);
189190
```
191+
192+
### Fetch approved or not approved reviews/ratings by department
193+
```php
194+
// Approved reviews department with ratings
195+
$product = Product::findOrFail($productId);
196+
197+
// Get approved reviews by department (with related ratings)
198+
// Default: approved: true, withRatings: true
199+
$product->getReviewsByDepartment("sales");
200+
201+
// Get not approved reviews department (with related ratings)
202+
$product->getReviewsByDepartment("sales", false);
203+
$product->getReviewsByDepartment(department: "sales", approved: false);
204+
205+
// Get approved reviews department (without related ratings)
206+
$product->getReviewsByDepartment("sales", true, false);
207+
$product->getReviewsByDepartment(department: "sales", withRatings: false);
208+
```
209+
210+
### Get reviews/ratings based on a star rating.
211+
```php
212+
// Fetch the product
213+
$product = Product::findOrFail($productId);
214+
215+
// Get approved reviews by star rating. The below call will return all 5-star
216+
// reviews/ratings for the "support" department.
217+
// Defaults: starValue: null, department: "default", approved: true, withRatings: true
218+
$product->getReviewsByRating(5, department: "support");
219+
220+
// If you only want the reviews and not the ratings, add withRatings: false:
221+
$product->getReviewsByRating(5, department: "support", withRatings: false);
222+
```
223+
224+
### Get the total number of reviews.
225+
```php
226+
// Approved reviews department with ratings
227+
$product = Product::findOrFail($productId);
228+
229+
// Get the total number of reviews for the reviewable resource.
230+
// Default: approved = true
231+
$product->totalReviews();
232+
233+
// Get the total number of reviews for the reviewable resource by department.
234+
// Defaults: department = "default", approved = true
235+
$product->totalDepartmentReviews(department: "sales");
236+
```
237+
190238
### Fetch the average rating:
191239
```php
192240
// Retrieve a Product instance (assuming Product uses the ReviewRatable trait)
@@ -217,25 +265,68 @@ $overallRating = $product->overallAverageRating();
217265
// Returns float
218266
3.5
219267
```
220-
### Get all reviews with or without ratings:
221-
```php
268+
269+
### Count the total number of reviews:
270+
````php
222271
// Retrieve a Product instance (assuming Product uses the ReviewRatable trait)
223272
$product = Product::find($productId);
224273

225-
// Get all approved reviews with their ratings eager loaded.
226-
$reviewsWithRatings = $product->getReviews(true, true);
274+
// Returns the total number of reviews.
275+
$totalReviews = $product->totalReviews();
227276

228-
// Get all approved reviews without eager loading ratings.
229-
$reviewsWithoutRatings = $product->getReviews(true, false);
230-
```
277+
// Get the total for a specific department
278+
// Defaults: department: "default", approved = true
279+
$totalDepartmentReviews = $product->totalDepartmentReviews();
280+
````
231281

232-
### Count total number of reviews:
282+
### Return an array of rating value ⇒ count, for the full model or for a given department.
233283
````php
234284
// Retrieve a Product instance (assuming Product uses the ReviewRatable trait)
235285
$product = Product::find($productId);
236286

237-
// Returns the total number of reviews.
238-
$totalReviews = $product->totalReviews();
287+
// Returns the total number of ratings.
288+
// Defaults: department: "default", approved = true
289+
$totalReviews = $product->ratingCounts();
290+
291+
// Returns, where the array key is the star rating and the value is the total count
292+
array:5▼
293+
1 => 0
294+
2 => 1
295+
3 => 8
296+
4 => 0
297+
5 => 3
298+
]
299+
````
300+
301+
### Returns a muti-denominational array with ratings stats for a given department.
302+
````php
303+
// Retrieve a Product instance (assuming the Product uses the ReviewRatable trait)
304+
$product = Product::find($productId);
305+
306+
// Get the stats for a given department or the default.
307+
// Defaults: department: "default", approved = true
308+
$totalReviews = $product->ratingStats();
309+
310+
// Returns, where the "counts" array holds the count for each star rating.
311+
// And the "percentages" holds to percentage for each star rating.
312+
// Finally, the total number of star ratings is returned.
313+
array:3▼
314+
"counts" => array:5 [▶
315+
1 => 0
316+
2 => 1
317+
3 => 8
318+
4 => 0
319+
5 => 3
320+
]
321+
"percentages" => array:5 [▶
322+
1 => 0.0
323+
2 => 8.0
324+
3 => 67.0
325+
4 => 0.0
326+
5 => 25.0
327+
]
328+
"total" => 12
329+
]
239330
````
240331

241332
## Example Usage in a Controller

‎src/Contracts/ReviewRateableContract.php

Lines changed: 58 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -30,15 +30,15 @@ public function addReview(array $data, ?int $userId = null): mixed;
3030
* @param array $data
3131
* @return bool
3232
*/
33-
public function updateReview(int $reviewId, array $data): bool;
33+
public function updateReview(int $reviewId = null, array $data = null): bool;
3434

3535
/**
3636
* Mark a review as approved by its ID.
3737
*
3838
* @param int $reviewId
3939
* @return bool
4040
*/
41-
public function approveReview(int $reviewId): bool;
41+
public function approveReview(int $reviewId = null): bool;
4242

4343
/**
4444
* Get the average rating for a given key.
@@ -47,7 +47,7 @@ public function approveReview(int $reviewId): bool;
4747
* @param bool $approved
4848
* @return float|null
4949
*/
50-
public function averageRating(string $key, bool $approved = true): ?float;
50+
public function averageRating(string $key = null, bool $approved = true): ?float;
5151

5252
/**
5353
* Get overall average ratings for all keys.
@@ -65,7 +65,7 @@ public function averageRatings(bool $approved = true): array;
6565
* @param bool $approved
6666
* @return float|null
6767
*/
68-
public function averageRatingByDepartment(string $department, string $key, bool $approved = true): ?float;
68+
public function averageRatingByDepartment(string $department = "default", string $key = null, bool $approved = true): ?float;
6969

7070
/**
7171
* Get overall average ratings for all keys within a department.
@@ -74,7 +74,7 @@ public function averageRatingByDepartment(string $department, string $key, bool
7474
* @param bool $approved
7575
* @return array
7676
*/
77-
public function averageRatingsByDepartment(string $department, bool $approved = true): array;
77+
public function averageRatingsByDepartment(string $department = "default", bool $approved = true): array;
7878

7979
/**
8080
* Get all reviews (with attached ratings) for the attached model.
@@ -85,6 +85,17 @@ public function averageRatingsByDepartment(string $department, bool $approved =
8585
*/
8686
public function getReviews(bool $approved = true, bool $withRatings = true): Collection;
8787

88+
/**
89+
* Get all reviews (with attached ratings) for a department,
90+
* filtered by the approved status.
91+
*
92+
* @param string $department
93+
* @param bool $approved
94+
* @param bool $withRatings
95+
* @return Collection
96+
*/
97+
public function getReviewsByDepartment(string $department = "default", bool $approved = true, bool $withRatings = true): Collection;
98+
8899
/**
89100
* Get the total number of reviews for the attached model.
90101
*
@@ -93,6 +104,15 @@ public function getReviews(bool $approved = true, bool $withRatings = true): Col
93104
*/
94105
public function totalReviews(bool $approved = true): int;
95106

107+
/**
108+
* Get the total number of reviews for the model by department.
109+
*
110+
* @param string $department
111+
* @param bool $approved
112+
* @return int
113+
*/
114+
public function totalDepartmentReviews(string $department = "default", bool $approved = true): int;
115+
96116
/**
97117
* Get the overall average rating for all ratings attached to the model.
98118
*
@@ -107,6 +127,38 @@ public function overallAverageRating(bool $approved = true): ?float;
107127
* @param int $reviewId
108128
* @return bool
109129
*/
110-
public function deleteReview(int $reviewId): bool;
130+
public function deleteReview(int $reviewId = null): bool;
111131

132+
/**
133+
* Return an array of rating value ⇒ count, for the full model
134+
* or for a given department.
135+
*
136+
* @param string|null $department
137+
* @param bool $approved
138+
* @return array
139+
*/
140+
public function ratingCounts(?string $department = "default", bool $approved = true): array;
141+
142+
/**
143+
* Return an array with:
144+
* • counts: [1 => x, 2 => y, …, 5 => z]
145+
* • percentages: [1 => pct1, …, 5 => pct5]
146+
* • total: total number of ratings
147+
*
148+
* @param string|null $department
149+
* @param bool $approved
150+
* @return array
151+
*/
152+
public function ratingStats(?string $department = "default", bool $approved = true): array;
153+
154+
/**
155+
* Return reviews based on star ratings.
156+
*
157+
* @param int|null $starValue
158+
* @param string $department
159+
* @param bool $approved
160+
* @param bool $withRatings
161+
* @return Collection
162+
*/
163+
public function getReviewsByRating(int $starValue = null, string $department = "default", bool $approved = true, bool $withRatings = true): Collection;
112164
}

0 commit comments

Comments
 (0)