Feedback Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer (note: dev-trunk is unstable; prefer a stable release if available):

   composer require activpik/feedback-bundle:dev-trunk
   

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

   new Activpik\Feedback\ActivpikFeedbackBundle(),
   

3. Configure Services Define a feedback source (e.g., Redmine) in config/services.yaml:

   services:
       activpik.feedback_source:
           class: Activpik\FeedbackBundle\Vendor\RedmineFeedback\RedmineFeedbackSource
           arguments:
               - "https://urltoredmine/redmine/projects/myproject/issues.json"
               - "%env(REDMINE_API_KEY)%"
               - "%env(REDMINE_PROJECT_ID)%"
               - "Priority"
   

4. Route the Bundle Add to config/routes.yaml (Symfony 4+):

   activpik_feedback:
       resource: "@ActivpikFeedbackBundle/Controller/"
       type: annotation
       prefix: /
   

5. First Use Case: Display a Feedback Badge In a controller:

   use Activpik\FeedbackBundle\Form\FeedbackType;
   
   public function showAction()
   {
       $feedbackType = new FeedbackType();
       return $this->render('page.html.twig', [
           'feedback_form' => $this->createForm($feedbackType)->createView()
       ]);
   }
   

   In Twig (templates/page.html.twig):

   {{ include('ActivpikFeedbackBundle:Feedback:badge.html.twig') }}
   

Implementation Patterns

Workflows

1. Integrating Feedback into Existing Pages

   • Step 1: Include the badge in Twig:

     {% block stylesheets %}
         {{ parent() }}
         <link rel="stylesheet" href="{{ asset('bundles/activpikfeedback/css/feedback.css') }}">
     {% endblock %}
     
     {% block javascripts %}
         {{ parent() }}
         <script src="{{ asset('bundles/activpikfeedback/js/feedback.js') }}"></script>
     {% endblock %}
     

   • Step 2: Place the badge in your layout:

     {{ include('ActivpikFeedbackBundle:Feedback:badge.html.twig') }}
     

2. Handling Feedback Submissions

   • The bundle routes submissions to ActivpikFeedbackBundle:Feedback:submit. Extend the controller to process submissions (e.g., log to Redmine):

     // src/Controller/FeedbackController.php
     namespace App\Controller;
     
     use Activpik\FeedbackBundle\Controller\FeedbackController as BaseFeedbackController;
     
     class FeedbackController extends BaseFeedbackController
     {
         public function submitAction()
         {
             $data = $this->getRequest()->request->all();
             // Custom logic (e.g., validate, enrich, or forward to Redmine)
             return parent::submitAction();
         }
     }
     

3. Dynamic Feedback Sources

   • Override the default RedmineFeedbackSource for other backends (e.g., Jira, custom API):

     # config/services.yaml
     services:
         activpik.feedback_source.custom:
             class: App\Service\CustomFeedbackSource
             arguments: ["%env(CUSTOM_API_URL)%"]
             tags: ['activpik.feedback_source']
     

Integration Tips

• Symfony Forms Integration Use the FeedbackType form to standardize feedback fields (e.g., name, email, message). Extend it for custom fields:

  use Activpik\FeedbackBundle\Form\FeedbackType;
  use Symfony\Component\Form\AbstractType;
  use Symfony\Component\Form\FormBuilderInterface;
  
  class ExtendedFeedbackType extends FeedbackType
  {
      public function buildForm(FormBuilderInterface $builder, array $options)
      {
          parent::buildForm($builder, $options);
          $builder->add('custom_field', TextType::class);
      }
  }
  

• Twig Embedding For reusable feedback modals/dialogs, create a custom Twig extension or macro:

  {% macro feedbackModal(feedbackForm) %}
      <div class="feedback-modal">
          {{ form_start(feedbackForm) }}
              {{ form_widget(feedbackForm) }}
              <button type="submit">Send</button>
          {{ form_end(feedbackForm) }}
      </div>
  {% endmacro %}
  

• Asset Management Override bundle assets by copying vendor/activpik/feedback-bundle/Resources/public/ to public/bundles/activpikfeedback/ and customizing CSS/JS.

Gotchas and Tips

Pitfalls

1. Unstable dev-trunk

   • The package lacks unit tests and may break. Test thoroughly in staging.
   • Workaround: Fork the repo and apply fixes for critical issues.

2. Missing Documentation

   • The README is minimal. Expect to reverse-engineer:
     • Controller logic in src/Controller/FeedbackController.php.
     • Form fields in src/Form/FeedbackType.php.
   • Tip: Use Xdebug to trace the submitAction() flow.

3. Hardcoded Asset Paths

   • The bundle assumes assets are in bundles/activpikfeedback/. If using Symfony Flex or custom asset paths, override them:

     <link rel="stylesheet" href="{{ asset('custom-path/feedback.css') }}">
     

4. Redmine Dependency

   • The default RedmineFeedbackSource tightly couples the bundle to Redmine. If using another issue tracker, implement a new source class and tag it:

     tags: ['activpik.feedback_source']
     

Debugging

1. Form Validation Errors

   • Check the FeedbackType constraints and ensure your Twig form includes error rendering:

     {{ form_errors(feedback_form) }}
     

2. JavaScript Errors

   • Verify feedback.js loads after jQuery (if dependent). Use browser dev tools to check for:
     • Missing $ (jQuery) or console errors.
     • Fix: Load scripts in the correct order or polyfill dependencies.

3. Routing Conflicts

   • The bundle’s prefix: / in routing.yml may clash with other routes. Use a unique prefix:

     prefix: /feedback
     

Extension Points

1. Custom Feedback Sources

   • Implement Activpik\FeedbackBundle\Feedback\FeedbackSourceInterface:

     class MyFeedbackSource implements FeedbackSourceInterface
     {
         public function submit(array $data): bool
         {
             // Custom logic (e.g., API call)
             return true;
         }
     }
     

   • Register as a service with the activpik.feedback_source tag.

2. Event Listeners

   • Subscribe to feedback submission events (if the bundle emits them). Example:

     // src/EventListener/FeedbackListener.php
     use Symfony\Component\HttpKernel\Event\RequestEvent;
     
     class FeedbackListener
     {
         public function onKernelRequest(RequestEvent $event)
         {
             if ($event->isMainRequest() && $event->getRequest()->get('_route') === 'activpik_feedback_submit') {
                 // Log or modify request data
             }
         }
     }
     

     Register in services.yaml:

     services:
         App\EventListener\FeedbackListener:
             tags: ['kernel.event_listener', { event: 'kernel.request', method: 'onKernelRequest' }]
     

3. Twig Overrides

   • Override templates by copying vendor/activpik/feedback-bundle/Resources/views/ to templates/bundles/ActivpikFeedbackBundle/ and modifying:
     • Feedback/badge.html.twig (styling/positioning).
     • Feedback/submit.html.twig (custom submission logic).

Configuration Quirks

• Environment Variables The example uses %env(REDMINE_API_KEY)%, but the bundle may not support Symfony’s env vars by default. Use a parameter:

  # config/packages/parameters.yaml
  parameters:
      redmine.api_key: '%env(REDMINE_API_KEY)%'
  

  Then inject the parameter into the service.

• Priority Argument The Priority argument in RedmineFeedbackSource is hardcoded. Extend the class to make it configurable:

  class ConfigurableRedmineFeedbackSource extends RedmineFeedbackSource
  {
      public function __construct(string $url, string $apiKey, string $projectId, ?string $defaultPriority = null)
      {
          $this->defaultPriority = $defaultPriority;
          parent::__construct($url, $apiKey, $projectId, $defaultPriority);
      }
  }