Star Rating Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require brokoskokoli/star-rating-bundle
   

   (Note: The README mentions blackknight467/star-rating-bundle, but the package is now under brokoskokoli/star-rating-bundle.)

2. Enable the Bundle: Add to config/bundles.php (Symfony 4+):

   return [
       // ...
       Brokoskokoli\StarRatingBundle\StarRatingBundle::class => ['all' => true],
   ];
   

3. Configure Twig (Symfony 4+): Add to config/packages/twig.yaml:

   twig:
       paths:
           '%kernel.project_dir%/vendor/brokoskokoli/star-rating-bundle/Resources/views': BrokoskokoliStarRatingBundle
   

4. Include Assets: Add to your base template (e.g., base.html.twig):

   <link rel="stylesheet" href="{{ asset('bundles/starrating/css/rating.css') }}">
   <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
   <script src="{{ asset('bundles/starrating/js/rating.js') }}"></script>
   

First Use Case: Displaying a Read-Only Rating

Render a 4-star rating (e.g., for a product):

{{ render_rating(4, {'readonly': true}) }}

Implementation Patterns

Form Integration (Editable Ratings)

1. Form Type Setup: Add the rating form type to your entity (e.g., Product):

   use Brokoskokoli\StarRatingBundle\Form\Type\RatingType;
   
   // In ProductType.php
   $builder->add('rating', RatingType::class, [
       'label' => 'Rate this product',
       'required' => false,
       'max' => 5,
   ]);
   

2. Template Rendering: Use the form theme or embed the rating directly:

   {{ form_row(product.rating) }}
   

   (Ensure form_theme.html.twig extends the bundle’s theme if customization is needed.)

Dynamic Ratings with Twig Filters

Filter ratings in templates:

{% set averageRating = product.reviews|average_rating %}
{{ render_rating(averageRating, {'max': 5, 'readonly': true}) }}

AJAX Submissions

Handle form submissions via JavaScript:

$('form').on('submit', function(e) {
    e.preventDefault();
    $.post($(this).attr('action'), $(this).serialize(), function(data) {
        // Update UI dynamically (e.g., refresh rating)
        $('#rating-display').html(data.rating_html);
    });
});

Custom Styling

Override default CSS/JS:

1. Copy vendor/brokoskokoli/star-rating-bundle/Resources/public/css/rating.css to assets/css/.
2. Extend the bundle’s JavaScript in your asset pipeline.

Gotchas and Tips

Pitfalls

1. JQuery Dependency:

   • The bundle requires jQuery. Ensure it’s loaded before rating.js.
   • Debugging: Check browser console for jQuery is not defined errors.

2. Symfony 4+ Configuration:

   • The original README references appKernel.php (Symfony 2/3). Use config/bundles.php for Symfony 4+.
   • Twig paths must be updated to use the new bundle namespace (BrokoskokoliStarRatingBundle).

3. Asset Paths:

   • Hardcoded paths in the bundle (e.g., bundles/starrating/) may break if assets are moved. Use asset() or path() helpers:

     {{ asset('bundles/starrating/css/rating.css') }}
     

4. Form Theme Conflicts:

   • If using custom form themes, ensure the bundle’s rating_widget.html.twig is extended properly. Override in templates/BrokoskokoliStarRatingBundle/Form/.

Debugging Tips

1. Check Console Logs:

   • Look for Uncaught ReferenceError or TypeError in browser dev tools if ratings don’t render.

2. Validate Form Data:

   • The bundle expects ratings as integers (e.g., 1, 5). Validate in your controller:

     $request->request->get('product_rating', 0); // Default to 0 if invalid
     

3. Clear Cache:

   • After updating the bundle, run:

     php bin/console cache:clear
     

Extension Points

1. Custom Templates: Override the default template by copying:

   vendor/brokoskokoli/star-rating-bundle/Resources/views/Form/rating_widget.html.twig
   

   to:

   templates/BrokoskokoliStarRatingBundle/Form/rating_widget.html.twig
   

2. Add Icons: The bundle uses Font Awesome. Customize icons by modifying the Twig template or overriding CSS classes (e.g., .fa-star-o).

3. Localization: Extend the bundle’s translation files (e.g., translations/messages.en.xlf) for custom labels.

Performance Note

• For dynamic pages (e.g., SPAs), consider lazy-loading the bundle’s JS/CSS only when needed to reduce initial load time.