Review Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sylius/review
   

   Add the bundle to config/bundles.php (if using Symfony) or register the service provider in config/app.php (Laravel):

   // Laravel: config/app.php
   'providers' => [
       Sylius\Review\ReviewServiceProvider::class,
   ],
   

2. Database Migrations: Run the migrations to create the required tables:

   php artisan migrate
   

   The package includes tables for reviews, review_translations, and reviewable (polymorphic relationship).

3. First Use Case:

   • Create a Reviewable Model: Extend Sylius\Component\Review\Model\ReviewableInterface (e.g., Product, Order).

     use Sylius\Component\Review\Model\ReviewableInterface;
     
     class Product implements ReviewableInterface
     {
         // ...
     }
     

   • Add a Review to a Model:

     $product = Product::find(1);
     $review = new Review();
     $review->setSubject($product);
     $review->setRating(5);
     $review->setContent('Great product!');
     $review->setAuthor($user); // Optional: Associate with a user
     $reviewRepository->add($review);
     

   • Fetch Reviews for a Model:

     $reviews = $reviewRepository->findBy(['subject' => $product]);
     

4. Routing (Symfony/Laravel): Define routes for listing, creating, and managing reviews (e.g., /products/{id}/reviews). Example Laravel route:

   Route::resource('products.reviews', ReviewController::class)->shallow();
   

Implementation Patterns

Core Workflows

1. Review Creation Pipeline:

   • Form Handling: Use a ReviewType (Symfony Form) or a custom Laravel FormRequest to validate and collect review data.

     // Symfony Form Example
     $form = $this->createForm(ReviewType::class, $review);
     

     // Laravel FormRequest Example
     public function rules()
     {
         return [
             'rating' => 'required|integer|min:1|max:5',
             'content' => 'required|string',
         ];
     }
     

   • Authorization: Gate access to review creation (e.g., only logged-in users or order owners).

     // Laravel Policy Example
     public function createReview(User $user, Product $product)
     {
         return $user->hasPurchased($product); // Custom logic
     }
     

2. Polymorphic Reviewable Models:

   • Dynamic Relationships: Use the ReviewableInterface to attach reviews to any model (e.g., Product, Order, Category).

     class Order implements ReviewableInterface
     {
         public function getReviewSubject(): string
         {
             return 'order';
         }
     }
     

   • Querying Reviews:

     // Find all reviews for any reviewable type
     $reviews = $reviewRepository->findAll();
     // Filter by subject type
     $productReviews = $reviewRepository->findBy(['subject' => $product]);
     

3. Rating Aggregation:

   • Calculate Average Rating:

     $averageRating = $reviewRepository->calculateAverageRating($product);
     

   • Display in Templates:

     @foreach($product->reviews as $review)
         <div class="rating">{{ $review->rating }}/5</div>
     @endforeach
     <div class="average-rating">
         Average: {{ number_format($averageRating, 1) }}/5
     </div>
     

4. Translation Support:

   • Multilingual Reviews: Use the ReviewTranslation entity to store localized content.

     $review->addTranslation('en', new ReviewTranslation());
     $review->getTranslation('en')->setContent('Great product!');
     

5. API Integration:

   • Expose Reviews via API (Laravel):

     Route::apiResource('products.reviews', ReviewApiController::class);
     

   • Serialize Reviews:

     public function toArray($request, Review $review)
     {
         return [
             'id' => $review->getId(),
             'rating' => $review->getRating(),
             'content' => $review->getContent(),
             'author' => $review->getAuthor()->name,
             'created_at' => $review->getCreatedAt()->format('Y-m-d'),
         ];
     }
     

Integration Tips

1. Event-Driven Extensions:

   • Listen for review-related events (e.g., ReviewCreatedEvent) to trigger notifications or update metrics.

     // Laravel Event Listener
     public function handle(ReviewCreatedEvent $event)
     {
         Notification::send($event->getReview()->getAuthor(), new ReviewPublished());
     }
     

2. Custom Validation:

   • Extend the Review entity or use form requests to enforce business rules (e.g., "Users can only review products they’ve purchased").

     public function authorize()
     {
         return $this->user()->hasPurchased($this->product);
     }
     

3. Caching:

   • Cache aggregated ratings to reduce database load:

     $averageRating = Cache::remember("product_{$product->id}_rating", now()->addHours(1), function() use ($product) {
         return $reviewRepository->calculateAverageRating($product);
     });
     

4. Moderation Workflow:

   • Add a ReviewState (e.g., pending, approved, rejected) and implement a moderation queue.

     $review->setState('pending');
     $reviewRepository->add($review);
     

Gotchas and Tips

Pitfalls

1. Polymorphic Relationships:

   • Issue: Forgetting to implement getReviewSubject() in custom Reviewable models can cause ReviewableInterface violations.
   • Fix: Ensure all reviewable models adhere to the interface:

     class Category implements ReviewableInterface
     {
         public function getReviewSubject(): string
         {
             return 'category';
         }
     }
     

2. Translation Mismatches:

   • Issue: Missing translations for a review can lead to NullReferenceException when accessing getTranslation().
   • Fix: Always initialize translations before saving:

     $review->addTranslation('en', new ReviewTranslation());
     $review->addTranslation('fr', new ReviewTranslation());
     

3. Rating Validation:

   • Issue: Default validation may not cover all edge cases (e.g., non-integer ratings or out-of-range values).
   • Fix: Customize validation in your ReviewType or FormRequest:

     $builder->add('rating', IntegerType::class, [
         'constraints' => [
             new Assert\NotBlank(),
             new Assert\Type(['type' => 'integer']),
             new Assert\GreaterThanOrEqual(['value' => 1]),
             new Assert\LessThanOrEqual(['value' => 5]),
         ],
     ]);
     

4. Performance with Large Datasets:

   • Issue: Querying all reviews for a high-traffic product can slow down the application.
   • Fix: Paginate or limit results:

     $reviews = $reviewRepository->findBy(['subject' => $product], ['limit' => 10]);
     

5. Database Locking:

   • Issue: Concurrent writes to the same reviewable entity (e.g., updating a product’s average rating) can cause race conditions.
   • Fix: Use database transactions or optimistic locking:

     DB::transaction(function () use ($product) {
         $reviewRepository->add($review);
         $product->updateAverageRating();
     });
     

Debugging Tips

1. Review Not Saving:

   • Check: Ensure the Reviewable model is correctly linked via setSubject().
   • Debug: Dump the entity before saving:

     dd($review->getSubject(), $review->getAuthor());
     

2. Missing Reviews in Queries:

   • Check: Verify the polymorphic relationship is set up correctly in the reviewable table.
   • Debug: Inspect the query builder:

     $qb = $reviewRepository->createQueryBuilder('r');
     dd($qb->getDQL());
     

3. Translation Not Persisting:

   • Check: Ensure translations are added to the review before flushing:

     $review->addTranslation('en', $translation);
     $entityManager->persist($review);
     

Extension Points

1. Custom Review States:
   • Extend the Review entity to add states (e.g., spam, flagged) and create a state machine:

     class Review extends BaseReview