Getting Started

Minimal Setup

Installation:

composer require blackknight467/star-rating-bundle:2.*

Enable the bundle in config/bundles.php (Symfony 3+):

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

Include Assets: Add to your base template (base.html.twig):

{% block stylesheets %}
    {{ parent() }}
    {% stylesheets 'bundles/starrating/css/rating.css' %}
        <link rel="stylesheet" href="{{ asset_url }}">
    {% endstylesheets %}
{% endblock %}

{% block javascripts %}
    {{ parent() }}
    <script src="//ajax.googleapis.com/ajax/libs/jquery/2.0.3/jquery.min.js"></script>
    <script src="{{ asset('bundles/starrating/js/rating.js') }}"></script>
{% endblock %}

First Use Case: Render a read-only rating in a Twig template:
```
{{ render_rating(3, { 'readonly': true }) }}
```
Render an editable rating in a form:
```
{{ form_widget(form.rating) }}
```

Implementation Patterns

Form Integration

Form Type Setup: Use the rating form type in your entity:

// src/Entity/Product.php
use blackknight467\StarRatingBundle\Form\Type\RatingType;

class Product
{
    private $rating;

    public function buildForm(BuilderInterface $builder, array $options)
    {
        $builder->add('rating', RatingType::class, [
            'required' => false,
            'data' => $this->rating,
        ]);
    }
}

Validation & Submission: Handle submission in your controller:

public function update(Request $request, Product $product)
{
    $form = $this->createForm(ProductType::class, $product);
    $form->handleRequest($request);

    if ($form->isSubmitted() && $form->isValid()) {
        $product->setRating($form->get('rating')->getData());
        $em->persist($product);
        $em->flush();
    }
}

Dynamic Rendering

Twig Filters: Use the rating filter to display ratings dynamically:

{% set rating = product.rating|rating %}
<div class="rating">{{ rating }}</div>

Custom Styling: Override CSS/JS by extending the bundle’s assets:

{% stylesheets 'bundles/starrating/css/rating.css' output='css/extended-rating.css' %}
    <link rel="stylesheet" href="{{ asset_url }}">
{% endstylesheets %}

AJAX Submissions

Unobtrusive JS: Initialize ratings with AJAX support:

$(document).ready(function() {
    $('.rating').rating({
        ajax: {
            url: '/api/rate',
            method: 'POST',
            data: function() {
                return { id: $(this).data('product-id') };
            }
        }
    });
});

Controller Endpoint:

#[Route('/api/rate', name: 'api_rate', methods: ['POST'])]
public function rate(Request $request): JsonResponse
{
    $product = $this->getDoctrine()->getRepository(Product::class)
        ->find($request->request->get('id'));
    $product->setRating($request->request->get('rating'));
    $em->flush();

    return new JsonResponse(['success' => true]);
}

Gotchas and Tips

Common Pitfalls

JQuery Dependency:
- Issue: Bundle fails if jQuery is not loaded before rating.js.
- Fix: Ensure jQuery is included in the <head> or before the bundle’s JS.

CSRF Token Mismatch:

Issue: AJAX submissions may fail due to missing CSRF tokens.

Fix: Include _token in AJAX data:

data: function() {
    return {
        id: $(this).data('product-id'),
        _token: '{{ csrf_token() }}'
    };
}

Symfony 3+ Configuration:
- Issue: appKernel.php is deprecated in Symfony 3+. Use config/bundles.php instead.
- Fix: Update bundle registration as shown in Getting Started.

Debugging Tips

Console Errors:
- Check browser console for Uncaught ReferenceError: $ is not defined (missing jQuery) or TypeError: $(...).rating is not a function (JS loaded out of order).

Form Data Binding:

Ensure the submitted data matches the expected format (e.g., 1–5 for 5-star ratings). Use data_transformer if needed:

$builder->add('rating', RatingType::class, [
    'data_transformer' => new CallbackTransformer(
        function ($value) { return (int) $value; },
        function ($value) { return $value; }
    ),
]);

Extension Points

Custom Templates: Override the default Twig template by creating templates/StarRatingBundle/rating.html.twig:

{# Custom template example #}
<div class="custom-rating">
    {% for i in 1..5 %}
        <i class="fa fa-star{% if i <= data %} active{% endif %}"></i>
    {% endfor %}
</div>

Configuration: Override bundle defaults via config/packages/starrating.yaml:

star_rating:
    max_stars: 5          # Default: 5
    star_size: '2x'       # Options: '1x', '2x', '3x', '4x'
    readonly_class: 'disabled'  # CSS class for readonly ratings

Event Listeners: Extend functionality via events (e.g., log ratings):

// src/EventListener/RatingListener.php
use blackknight467\StarRatingBundle\Event\RatingEvent;

class RatingListener
{
    public function onRate(RatingEvent $event)
    {
        if ($event->getRating() > 3) {
            // Trigger a notification
        }
    }
}

services:
    App\EventListener\RatingListener:
        tags:
            - { name: kernel.event_listener, event: star_rating.rate, method: onRate }

Star Rating Bundle Laravel Package