Products Review Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation:

   composer require baks-dev/products-review
   php bin/console baks:assets:install
   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

2. Publish Assets: Verify assets (CSS/JS) are published to public/vendor/baks/products-review.
3. First Review Submission:
   • Use the provided Blade template (e.g., @include('products-review::review.form')) in a product view.
   • Submit a test review via the frontend to confirm CRUD workflows.

Where to Look First

• Configuration: Check config/products-review.php (auto-generated after installation) for settings like:
  • Moderation thresholds.
  • Allowed rating ranges.
  • Email notifications.
• Models: Review app/Models/ProductsReview/ (or vendor namespace) for:
  • Review.php (core model).
  • ReviewRating.php (if ratings are supported).
• Migrations: Inspect database/migrations/ for schema changes (e.g., reviews, review_ratings tables).
• Console Commands: List available commands with:

  php bin/console list baks
  

  Example: Moderation tools like baks:review:approve.

First Use Case: Basic Review Flow

1. Display a Review Form:

   @include('products-review::review.form', ['productId' => $product->id])
   

2. Handle Submission: The package likely uses a controller (e.g., ProductsReviewController) or form request (e.g., StoreReviewRequest). Extend if needed:

   use Baks\ProductsReview\Http\Requests\StoreReviewRequest;
   
   public function store(StoreReviewRequest $request) {
       // Custom logic (e.g., pre-submission hooks)
       $review = $request->review();
       // ...
   }
   

3. Display Reviews:

   @foreach($product->reviews as $review)
       @include('products-review::review.card', ['review' => $review])
   @endforeach
   

Implementation Patterns

Core Workflows

1. Review CRUD

• Create: Use the provided form request (StoreReviewRequest) or extend the Review model’s create() method.
• Read: Fetch reviews via Eloquent:

  $reviews = \Baks\ProductsReview\Models\Review::with('user', 'ratings')->where('product_id', $product->id)->get();
  

• Update/Delete: Implement soft deletes (if enabled) or use standard Eloquent methods:

  $review->update(['content' => 'Updated text']);
  $review->delete(); // or forceDelete()
  

2. Ratings System

• Submit a Rating:

  $review->ratings()->create(['value' => 5, 'user_id' => auth()->id()]);
  

• Calculate Average Rating:

  $average = $review->ratings()->avg('value');
  

3. Moderation

• Pending Reviews: Query pending reviews:

  $pending = \Baks\ProductsReview\Models\Review::where('status', 'pending')->get();
  

• Approve/Reject:

  php bin/console baks:review:approve {reviewId}
  php bin/console baks:review:reject {reviewId}
  

  Or programmatically:

  $review->approve(); // or reject()
  

4. Asset Management

• Customize Templates: Override Blade templates by publishing them:

  php artisan vendor:publish --tag=products-review-views
  

  Then edit files in resources/views/vendor/products-review/.

• Extend CSS/JS: Publish assets and extend:

  php artisan vendor:publish --tag=products-review-assets
  

  Add custom styles to public/vendor/baks/products-review/css/app.css.

Integration Tips

Laravel Ecosystem

• Service Providers: Bind custom logic via the package’s service provider (e.g., Baks\ProductsReview\ProductsReviewServiceProvider).

  $this->app->extend('review.moderator', function ($moderator) {
      return new CustomModerator($moderator);
  });
  

• Events: Listen to review events (e.g., ReviewCreated, ReviewApproved):

  \Baks\ProductsReview\Events\ReviewCreated::class => [ReviewListener::class, 'handle'],
  

• Middleware: Protect review routes:

  Route::middleware(['auth', 'verified'])->group(function () {
      // Review routes
  });
  

Database

• Custom Fields: Add columns via a migration:

  Schema::table('reviews', function (Blueprint $table) {
      $table->string('custom_field')->nullable();
  });
  

• Indexing: Optimize queries by adding indexes:

  Schema::table('review_ratings', function (Blueprint $table) {
      $table->index(['review_id', 'user_id']);
  });
  

Frontend

• API Endpoints: If the package lacks an API, create one:

  Route::post('/api/reviews', [ReviewController::class, 'store']);
  

• SPA Integration: Use Laravel Sanctum/Passport for authentication:

  axios.post('/api/reviews', { content: 'Review text' }, {
      headers: { 'Authorization': `Bearer ${user.token}` }
  });
  

Testing

• Unit Tests: Extend the existing PHPUnit group:

  public function testReviewCreation()
  {
      $this->actingAs($user)
           ->post('/reviews', ['product_id' => 1, 'content' => 'Great product!'])
           ->assertRedirect('/products/1');
  }
  

• Feature Tests: Test moderation flows:

  public function testModerationWorkflow()
  {
      $review = \Baks\ProductsReview\Models\Review::factory()->create(['status' => 'pending']);
      $this->artisan('baks:review:approve', ['id' => $review->id])
           ->assertExitCode(0);
      $this->assertEquals('approved', $review->fresh()->status);
  }
  

Gotchas and Tips

Pitfalls

1. Schema Conflicts:

   • Issue: The package’s migrations may conflict with existing reviews or products tables.
   • Fix: Rename tables in the package’s migrations or use a custom namespace:

     Schema::create('baks_reviews', function (Blueprint $table) {
         // ...
     });
     

   • Tip: Run doctrine:migrations:diff in a staging DB first to preview changes.

2. Asset Overwrites:

   • Issue: Publishing assets may overwrite existing files in public/vendor/.
   • Fix: Use unique directory names or merge assets manually.

3. Moderation Logic:

   • Issue: Default moderation rules (e.g., auto-approve after 24h) may not fit your workflow.
   • Fix: Override the moderator service:

     $this->app->singleton('review.moderator', function () {
         return new CustomModerator();
     });
     

4. Missing API:

   • Issue: The package may lack REST/GraphQL endpoints for reviews.
   • Fix: Build a custom API layer or use Laravel’s API resources:

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

5. PHP 8.4+ Requirements:

   • Issue: Older Laravel/PHP versions may break compatibility.
   • Fix: Upgrade or use a compatibility layer (e.g., spatie/laravel-php-version).

6. No Frontend Framework:

   • Issue: Blade templates may not integrate with Vue/React.
   • Fix: Use Laravel Mix/Vite to compile assets or create a custom API.

Debugging Tips

1. Console Command Errors:

   • Enable verbose output:

     php bin/console baks:assets:install -v
     

   • Check logs for Doctrine errors:

     tail -f storage/logs/laravel.log | grep doctrine
     

2. Migration Failures:

   • Rollback and retry:

     php bin/console doctrine:migrations:rollback
     php bin/console doctrine:migrations:migrate
     

   • Use --pretend to dry-run:

     php bin/console doctrine:migrations:diff --pretend
     

3. Review Submission Issues:

   • Validate the form request:

     $request->validate([
         'content' => 'required|string|max:2000',
         'rating' => 'required|integer|between:1,5',
     ]);
     

   • Check for