Raffler Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   • Add devtime/raffler-bundle to composer.json under "require".
   • Run composer update devtime/raffler-bundle.
   • Enable the bundle in AppKernel.php.

2. First Use Case:

   • Configure the raffle in config.yml under devtime_raffler:

     devtime_raffler:
         participants: ["Alice", "Bob", "Charlie"]
     

   • Run the raffle via CLI:

     php app/console devtime:raffler:draw
     

   • Output the winner in a template:

     {{ raffler.winner }}
     

3. Where to Look First:

   • Check src/Devtime/Bundle/RafflerBundle/Command/DrawCommand.php for CLI usage.
   • Review src/Devtime/Bundle/RafflerBundle/Resources/config/services.yml for service configuration.
   • Inspect src/Devtime/Bundle/RafflerBundle/DependencyInjection/Configuration.php for bundle settings.

Implementation Patterns

Core Workflows

1. Participant Management:

   • Dynamically load participants from a database (extend ParticipantProvider service).
   • Example: Override devtime_raffler.participant_provider in services.yml:

     devtime_raffler.participant_provider:
         class: AppBundle\Service\CustomParticipantProvider
         arguments: ["@doctrine.orm.entity_manager"]
     

2. Raffle Execution:

   • Trigger raffles programmatically via the Raffler service:

     $winner = $this->get('raffler')->draw();
     

   • Schedule raffles using Symfony’s CronBundle or TaskBundle.

3. Frontend Integration:

   • Use the included Backbone.js views/models (located in Resources/public/js/) to display raffle results or participant lists.
   • Extend the RafflerView to customize UI behavior.

4. Event-Driven Raffles:

   • Subscribe to events (e.g., raffle.draw) to log or notify winners:

     $dispatcher->addListener('raffle.draw', function($event) {
         // Send email, log winner, etc.
     });
     

Integration Tips

• Database Backing: Use the Participant entity (src/Devtime/Bundle/RafflerBundle/Entity/Participant.php) as a base for your own entity, extending it with additional fields (e.g., email, priority).

• Testing: Mock the ParticipantProvider in PHPUnit tests:

  $provider = $this->createMock('Devtime\Bundle\RafflerBundle\Provider\ParticipantProvider');
  $provider->method('getParticipants')->willReturn(['Alice', 'Bob']);
  $this->container->set('devtime_raffler.participant_provider', $provider);
  

• Localization: Override translation messages in Resources/translations/messages.en.yml for winner notifications or UI labels.

Gotchas and Tips

Pitfalls

1. Backbone.js Dependencies:

   • The bundle assumes Backbone.js and Twitter Bootstrap are loaded. Ensure these are included in your base template:

     {{ parent() }}
     <script src="{{ asset('bundles/devtimeraffler/js/backbone.js') }}"></script>
     <script src="{{ asset('bundles/devtimeraffler/js/raffler.js') }}"></script>
     

2. Randomness in Testing:

   • The draw() method uses PHP’s mt_rand(). For deterministic tests, mock the Raffler service or use a fixed seed:

     mt_srand(123); // Seed for testing
     

3. Configuration Overrides:

   • Forgetting to clear the cache after modifying config.yml will ignore new settings. Run:

     php app/console cache:clear
     

4. Participant Duplicates:

   • The bundle does not validate for duplicate participants. Add logic in your custom ParticipantProvider to deduplicate:

     return array_unique($participants);
     

Debugging

• CLI Errors: If devtime:raffler:draw fails, check:

  • Participant list is non-empty (count($participants) > 0).
  • The ParticipantProvider service is properly configured.

• Frontend Issues: Inspect the browser console for Backbone.js errors. Common fixes:

  • Ensure data-devtime-raffler attributes are correctly set on HTML elements.
  • Verify Backbone models/views are initialized before DOM ready.

Extension Points

1. Custom Participant Logic: Extend ParticipantProviderInterface to fetch participants from APIs or external systems:

   class ApiParticipantProvider implements ParticipantProviderInterface {
       public function getParticipants() {
           return $this->httpClient->get('/api/participants')->json();
       }
   }
   

2. Winner Notifications: Subclass Raffler to add post-draw actions:

   class CustomRaffler extends Raffler {
       protected function postDraw($winner) {
           $this->mailer->sendWinnerEmail($winner);
       }
   }
   

   Register it in services.yml:

   devtime_raffler.raffler:
       class: AppBundle\Service\CustomRaffler
   

3. Weighted Raffles: Modify the draw() method to support weighted participants:

   $weights = [0.5, 0.3, 0.2]; // 50%, 30%, 20% chance
   $winner = $participants[array_rand($participants, 1, $weights)];
   

4. Multi-Winner Raffles: Extend the bundle to draw multiple winners by updating the draw() method:

   public function drawMultiple($count = 1) {
       $winners = [];
       for ($i = 0; $i < $count; $i++) {
           $winners[] = $this->draw();
       }
       return $winners;
   }