Star Rating Bundle Laravel Package

Getting Started

Minimal Steps

1. Install Dependencies: Add the repository and packages to composer.json:

   "repositories": [{
       "type": "package",
       "package": {
           "name": "fyneworks/star-rating",
           "version": "4.11.0",
           "source": {
               "type": "git",
               "url": "https://github.com/Fyneworks-jQuery/star-rating",
               "reference": "4.11.0"
           }
       }
   }],
   "require": {
       "fyneworks/star-rating": "4.11.0",
       "nurikabe/star-rating-bundle": "~2.0.1"
   }
   

   Run composer update nurikabe/star-rating-bundle.

2. Register the Bundle: Add to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 2/3):

   Nurikabe\StarRatingBundle\NurikabeStarRatingBundle::class => ['all' => true],
   

3. Load Assets: Include CSS/JS in your base template (e.g., base.html.twig):

   {% stylesheets '@NurikabeStarRatingBundle/Resources/public/rating.css' %}
       <link rel="stylesheet" href="{{ asset_url }}">
   {% endstylesheets %}
   {% javascripts '%kernel.project_dir%/vendor/fyneworks/star-rating/jquery.rating.js' %}
       <script src="{{ asset_url }}"></script>
   {% endjavascripts %}
   

   Dump assets if using Assetic:

   php bin/console assets:install
   php bin/console assetic:dump
   

4. First Use Case: Add a star rating to a form:

   // src/Form/ProductType.php
   $builder->add('rating', 'star_rating', [
       'choices' => [1 => '1', 2 => '2', 3 => '3', 4 => '4', 5 => '5'],
       'expanded' => true, // Radio buttons
       'multiple' => false,
   ]);
   

   Display static ratings in Twig:

   {{ product.rating|star_rating }}
   

Implementation Patterns

Usage Patterns

Form Integration

1. Basic Rating Field:

   $builder->add('userRating', 'star_rating', [
       'choices' => range(1, 5),
       'expanded' => true, // Radio buttons
       'multiple' => false,
       'label' => 'Rate this product',
   ]);
   

   • expanded: true (radio buttons) or false (star icons).
   • multiple: Ignored if expanded is true (checkboxes only work with expanded=false).

2. Custom Validation: Extend the StarRatingType to add constraints:

   use Symfony\Component\Form\AbstractType;
   use Symfony\Component\Form\FormBuilderInterface;
   use Symfony\Component\Validator\Constraints\NotBlank;
   
   class CustomStarRatingType extends AbstractType {
       public function buildForm(FormBuilderInterface $builder, array $options) {
           $builder->add('rating', 'star_rating', [
               'choices' => [1 => 'Poor', 2 => 'Fair', 3 => 'Good', 4 => 'Very Good', 5 => 'Excellent'],
               'constraints' => [new NotBlank(['message' => 'Please rate this item.'])],
           ]);
       }
   }
   

3. Dynamic Choices: Load choices from a database or service:

   $builder->add('rating', 'star_rating', [
       'choices' => $this->getRatingOptions(), // e.g., [1 => '1 Star', ...]
       'expanded' => false,
   ]);
   

Twig Filter for Static Displays

• Display a rating:

  {{ product.rating|star_rating }}
  

• Customize appearance:

  {{ product.rating|star_rating({
      'read_only': true,
      'star_size': 24,
      'empty_color': '#ddd',
      'full_color': '#ffd700'
  }) }}
  

  Note: Custom parameters depend on the underlying jQuery plugin’s options.

Asset Management

1. Symfony 4+ with Webpack Encore: Configure webpack.config.js:

   Encore
       .addEntry('star-rating', './vendor/fyneworks/star-rating/jquery.rating.js')
       .copyFiles({
           from: './vendor/fyneworks/star-rating/jquery.rating.css',
           to: 'build/[name].[ext]',
       });
   

   Include in Twig:

   {% block javascripts %}
       {{ parent() }}
       {{ encore_entry_script_tags('star-rating') }}
   {% endblock %}
   

2. Symfony 2/3 with Assetic: Ensure app/autoload.php includes the CSS/JS paths:

   # app/config/config.yml
   assetic:
       assets:
           star_rating_css:
               inputs:
                   - '@NurikabeStarRatingBundle/Resources/public/rating.css'
               output: 'css/star-rating.css'
           star_rating_js:
               inputs:
                   - '%kernel.project_dir%/vendor/fyneworks/star-rating/jquery.rating.js'
               output: 'js/star-rating.js'
   

Workflow Integration

1. CRUD Operations:

   • Create: Submit form data to a controller:

     public function createAction(Request $request) {
         $form = $this->createForm(ProductType::class);
         $form->handleRequest($request);
         if ($form->isSubmitted() && $form->isValid()) {
             $product = $form->getData();
             $product->setRating($form->get('rating')->getData());
             $em->persist($product);
             $em->flush();
         }
     }
     

   • Edit: Preload rating data:

     $form = $this->createForm(ProductType::class, $product);
     

2. API Integration: For APIs, use the Twig filter to render ratings in JSON responses:

   {# templates/api/product.json.twig #}
   {
       "id": {{ product.id }},
       "rating": {{ product.rating|star_rating|raw }}, {# Render as HTML snippet #}
       "rating_value": {{ product.rating }}
   }
   

Gotchas and Tips

Pitfalls

1. jQuery Conflicts:

   • Issue: The plugin may conflict with other jQuery plugins or modern frontend stacks (e.g., Vue/React).
   • Fix: Load jQuery and the star-rating plugin after other scripts or in a separate namespace:

     jQuery(document).ready(function($) {
         $('input.star-rating').rating();
     });
     

2. Assetic Deprecation:

   • Issue: Symfony 4+ drops Assetic. The bundle assumes Assetic for asset management.
   • Fix: Migrate to Webpack Encore or manually include assets:

     <link rel="stylesheet" href="{{ asset('vendor/fyneworks/star-rating/jquery.rating.css') }}">
     <script src="{{ asset('vendor/fyneworks/star-rating/jquery.rating.js') }}"></script>
     

3. Symfony 4+ FormType Registration:

   • Issue: The bundle uses buildForm, which is deprecated in Symfony 4+. Use configureOptions instead.
   • Fix: Extend the StarRatingType:

     use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\FormBuilderInterface;
     use Symfony\Component\OptionsResolver\OptionsResolver;
     
     class CustomStarRatingType extends AbstractType {
         public function configureOptions(OptionsResolver $resolver) {
             $resolver->setDefaults([
                 'choices' => range(1, 5),
                 'expanded' => true,
             ]);
         }
     
         public function buildForm(FormBuilderInterface $builder, array $options) {
             $builder->add('rating', 'choice', [
                 'choices' => $options['choices'],
                 'expanded' => $options['expanded'],
             ]);
         }
     
         public function getParent() {
             return 'choice';
         }
     }
     

4. Static Asset Paths:

   • Issue: Hardcoded paths in the bundle may break in custom setups.
   • Fix: Override Twig paths in config/packages/twig.yaml:

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

5. Missing Dependencies:

   • Issue: Forgetting to include jQuery before the star-rating plugin.
   • Fix: Ensure jQuery is loaded before the plugin: