Game Quizz Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aldaflux/game-quizz-bundle
   

   Ensure your composer.json meets the PHP (>=7.3.2) and Symfony (>=5.2) requirements.

2. Enable the Bundle Add to config/bundles.php:

   return [
       // ...
       Aldaflux\GameQuizzBundle\AldafluxGameQuizzBundle::class => ['all' => true],
   ];
   

3. Configure the Bundle Publish the default config (if needed) and update config/packages/aldaflux_game_quizz.yaml:

   aldaflux_game_quizz:
       fields:
           video:
               youtube: true
               videolink: true
           audio:
               question: true
               reponse: true
       folders:
           public: '%kernel.project_dir%/public'
           audio: 'sons'
           video: 'game_quizz_data/videos'
       google_json: '%kernel.project_dir%/path/to/google_id.json'  # Required for TTS
   

4. Symlink Assets

   php bin/console assets:install --symlink
   

5. First Use Case: Create a Quiz

   • Run migrations (if the bundle includes Doctrine entities):

     php bin/console doctrine:migrations:diff
     php bin/console doctrine:migrations:migrate
     

   • Access the admin panel at /game/admin to create a quiz via the provided CRUD interface.

Implementation Patterns

Core Workflows

1. Quiz Creation & Management

• Admin Interface: Use the annotated routes (/game/admin) to:
  • Add/edit/delete quizzes via a form-driven UI.
  • Upload media (video/audio) using the configured folders (audio, video).
  • Configure quiz settings (e.g., time limits, scoring) via YAML or admin UI.
• Entity Structure: Inspect the bundle’s Doctrine entities (likely Quiz, Question, Answer) to extend or customize fields. Example:

  // Extend a question entity (if needed)
  namespace App\Entity;
  use Aldaflux\GameQuizzBundle\Entity\Question as BaseQuestion;
  
  class Question extends BaseQuestion {
      // Add custom fields
  }
  

2. Playback & Game Logic

• Game Routes: Use /game/play to trigger quiz sessions.
  • Pass quiz IDs via URL or session:

    <a href="{{ path('quizz_game_play_bundle_play', {'id': quiz.id}) }}">Start Quiz</a>
    

  • Handle responses with Twig/Templates:

    {% extends 'AldafluxGameQuizzBundle::base.html.twig' %}
    {% block body %}
        {{ include('AldafluxGameQuizzBundle::question.html.twig', {
            question: currentQuestion,
            answers: currentAnswers
        }) }}
    {% endblock %}
    

3. Media Handling

• Video/Audio Uploads:
  • Configure allowed formats in fields.video/fields.audio.
  • Upload files to public/{audio|video}/ folders (symlinked via assets:install).
  • Embed YouTube videos by setting youtube: true and providing URLs.
• Text-to-Speech (TTS):
  • Use Google Cloud TTS (requires google_json path) to generate audio for questions/answers.
  • Example usage in a controller:

    use Google\Cloud\TextToSpeech\V1\TextToSpeechClient;
    
    $client = new TextToSpeechClient();
    $response = $client->synthesizeSpeech([
        'input' => ['text' => 'Your question here'],
        'voice' => ['languageCode' => 'en-US', 'name' => 'en-US-Wavenet-D'],
    ]);
    file_put_contents('public/sons/question.mp3', $response->getAudioContent());
    

4. Customization via Twig

• Override templates by copying files from: vendor/aldaflux/game-quizz-bundle/Resources/views/ to templates/bundles/AldafluxGameQuizzBundle/.
• Example: Customize the question template (question.html.twig):

  {% extends 'AldafluxGameQuizzBundle::question.html.twig' %}
  {% block answer_item %}
      <div class="custom-answer">
          {{ parent() }}
          <span class="feedback">{{ answer.feedback }}</span>
      </div>
  {% endblock %}
  

5. API Integration (if needed)

• Expose quiz data via Symfony’s serializer:

  use Symfony\Component\Serializer\SerializerInterface;
  
  class QuizApiController {
      public function __construct(private SerializerInterface $serializer) {}
  
      public function getQuiz(int $id): JsonResponse {
          $quiz = $this->quizRepository->find($id);
          return new JsonResponse($this->serializer->serialize($quiz, 'json'));
      }
  }
  

Gotchas and Tips

Pitfalls

1. Google TTS Configuration:

   • Issue: Missing google_json path causes TTS failures.
   • Fix: Ensure the JSON key file is placed at the configured path and has proper permissions.
   • Debug: Check logs for Google\Api\Core\ApiException errors.

2. Media Uploads:

   • Issue: Uploaded files may not appear due to missing symlinks.
   • Fix: Re-run php bin/console assets:install --symlink after config changes.
   • Tip: Verify folders.public points to the correct public/ directory.

3. Doctrine Migrations:

   • Issue: Custom entity extensions may break migrations.
   • Fix: Run doctrine:migrations:diff after extending entities and update manually if needed.

4. Route Conflicts:

   • Issue: /game/admin or /game/play may conflict with existing routes.
   • Fix: Override routes in config/routes.yaml:

     aldaflux_game_quizz:
         resource: '@AldafluxGameQuizzBundle/Controller/AdminController.php'
         prefix: '/custom/prefix/admin'
     

5. Twig Template Overrides:

   • Issue: Overrides may not apply due to caching.
   • Fix: Clear cache:

     php bin/console cache:clear
     

Debugging Tips

• Enable Debug Mode: Set APP_DEBUG=1 in .env for detailed error logs.
• Check Bundle Events: Listen for events like aldaflux_game_quizz.question.save to debug custom logic:

  // src/EventListener/CustomQuizListener.php
  namespace App\EventListener;
  use Aldaflux\GameQuizzBundle\Event\QuizEvents;
  
  class CustomQuizListener {
      public function onQuestionSave(QuestionEvent $event) {
          // Log or modify question data
      }
  }
  

  Register in services.yaml:

  services:
      App\EventListener\CustomQuizListener:
          tags:
              - { name: kernel.event_listener, event: aldaflux_game_quizz.question.save, method: onQuestionSave }
  

Extension Points

1. Custom Fields:

   • Extend entities (e.g., Question) to add fields like difficulty or tags.
   • Update the admin form type (QuestionType) to include new fields:

     // src/Form/QuestionTypeExtension.php
     use Symfony\Component\Form\AbstractTypeExtension;
     use Aldaflux\GameQuizzBundle\Form\Type\QuestionType;
     
     class QuestionTypeExtension extends AbstractTypeExtension {
         public function buildForm(FormBuilderInterface $builder, array $options) {
             $builder->add('difficulty', ChoiceType::class, ['choices' => ['Easy', 'Medium', 'Hard']]);
         }
         public static function getExtendedType(): string { return QuestionType::class; }
     }
     

2. Validation:

   • Add constraints to entities:

     use Symfony\Component\Validator\Constraints as Assert;
     
     class Question {
         /**
          * @Assert\Length(min=10)
          */
         private $content;
     }
     

3. API Endpoints:

   • Create a custom controller to fetch quizzes programmatically:

     #[Route('/api/quizzes', name: 'api_quizzes')]
     class QuizApiController {
         #[Route('/{id}', name: 'api_quiz_detail')]
         public function detail(Quiz $quiz): JsonResponse {
             return $this->json($quiz->toArray());
         }
     }
     

4. Localization:

   • Override translation files in translations/bundles/AldafluxGameQuizzBundle.en.yaml:

     question:
         title: "Custom Question Title"