Qcm Core Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require avoo/qcm-core-bundle "@dev-master"
   

   Add the bundle to AppKernel.php:

   new Qcm\Bundle\CoreBundle\QcmCoreBundle(),
   

2. Configure Routing: Import the routing in app/config/routing.yml:

   qcm_core:
       resource: "@QcmCoreBundle/Resources/config/routing.yml"
       prefix: /
   

3. Basic Configuration: Add to app/config/config.yml:

   imports:
       - { resource: "@QcmCoreBundle/Resources/config/core.yml" }
   

4. Security Setup: Configure security.yml as per the README.

5. First Use Case: Create a questionnaire entity by extending Qcm\Component\Questionnaire\Model\QuestionnaireInterface and register it as a Sylius resource.

Implementation Patterns

Core Workflows

1. Questionnaire Management:

   • Use Sylius' ResourceController to CRUD questionnaires.
   • Example entity:

     namespace AppBundle\Entity;
     
     use Qcm\Component\Questionnaire\Model\QuestionnaireInterface;
     use Doctrine\ORM\Mapping as ORM;
     
     class Questionnaire implements QuestionnaireInterface {
         // Implement required methods from QuestionnaireInterface
     }
     

2. Question and Answer Handling:

   • Extend Qcm\Component\Question\Model\QuestionInterface and Qcm\Component\Answer\Model\AnswerInterface.
   • Use the QcmCoreBundle's built-in forms for validation.

3. Statistics and Templates:

   • Override the default statistics service in config.yml:

     qcm_core:
         service:
             statistics:
                 class: AppBundle\Statistics\CustomStatistics
                 template: AppBundle\Template\CustomTemplate
     

   • Implement Qcm\Component\Template\TemplateInterface for custom rendering.

4. API Integration:

   • Leverage FOSRestBundle for RESTful endpoints (e.g., /api/questionnaires).
   • Use JMSSerializerBundle for JSON serialization/deserialization.

5. Pagination:

   • Use WhiteOctoberPagerfantaBundle for paginated results:

     $pagerfanta = $this->get('pagerfanta.doctrine.orm');
     $adapter = new DoctrineORMAdapter($em->getRepository('AppBundle:Questionnaire')->findAll());
     $pagerfanta->setAdapter($adapter)->setMaxPerPage(10);
     

Integration Tips

• Doctrine Extensions: Use beberlei/DoctrineExtensions for soft-deletes or timestamps if needed.
• Event Listeners: Attach listeners to qcm.questionnaire.pre_persist or qcm.answer.post_update events for custom logic.
• Validation: Extend Qcm\Component\Validator\Constraints for custom validation rules.

Gotchas and Tips

Common Pitfalls

1. Dependency Conflicts:

   • The bundle requires sylius/resource-bundle:0.11.*@dev, which may conflict with newer Sylius versions. Pin dependencies explicitly in composer.json:

     "conflict": {
         "sylius/resource-bundle": "0.11.*"
     }
     

2. Configuration Overrides:

   • Ensure core.yml is imported after other configurations to avoid precedence issues.
   • Override services before they are loaded (e.g., in config.yml, not services.yml).

3. Timeouts and Time Per Question:

   • If time_per_question is set, timeout is ignored. Validate this logic in your frontend:

     if (config.time_per_question) {
         timeout = questions.length * config.time_per_question;
     }
     

4. Serialization Issues:

   • Custom entities must implement Serializable or use @JMS\Serializer\Annotation for proper JSON handling.

5. Security:

   • The default sha512 encoder is weak. Upgrade to bcrypt or argon2 in security.yml:

     encoders:
         Qcm\Component\User\Model\UserInterface: bcrypt
     

Debugging Tips

1. Event Debugging:

   • Enable Symfony's event dispatcher logging:

     # app/config/config.yml
     framework:
         profiler: { only_exceptions: false }
     

   • Check qcm.* events in the profiler.

2. Database Schema:

   • Use doctrine:schema:update --dump-sql to verify migrations before applying.

3. Template Debugging:

   • Extend Qcm\Component\Template\TemplateInterface and add debug logs:

     public function render(QuestionnaireInterface $questionnaire) {
         error_log("Rendering questionnaire: " . $questionnaire->getId());
         return parent::render($questionnaire);
     }
     

Extension Points

1. Custom Question Types:

   • Create a new question class (e.g., MultipleChoiceQuestion) and register it via a service:

     services:
         app.qcm.question.multiple_choice:
             class: AppBundle\Entity\MultipleChoiceQuestion
             tags:
                 - { name: qcm.question_type, alias: multiple_choice }
     

2. Answer Validation:

   • Add custom validators to Qcm\Component\Answer\Model\Answer:

     use Symfony\Component\Validator\Constraints as Assert;
     
     class Answer {
         /**
          * @Assert\Length(max="200")
          */
         protected $content;
     }
     

3. API Extensions:

   • Extend Qcm\Bundle\CoreBundle\Controller\ApiController for custom API logic:

     namespace AppBundle\Controller;
     
     use Qcm\Bundle\CoreBundle\Controller\ApiController as BaseApiController;
     
     class CustomApiController extends BaseApiController {
         public function customAction() {
             // Override or extend API behavior
         }
     }
     

4. Statistics Enhancements:

   • Extend Qcm\Component\Statistics\Model\QuestionnaireStatistics to add custom metrics:

     class CustomStatistics extends QuestionnaireStatistics {
         public function getCustomMetric() {
             return $this->calculateCustomLogic();
         }
     }