Competitionbundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require xlabs/competitionbundle
   

   Register the bundle in config/app.php under providers:

   Xlabs\CompetitionBundle\CompetitionBundle::class,
   

2. Publish Config & Migrations Run:

   php artisan vendor:publish --provider="Xlabs\CompetitionBundle\CompetitionBundle" --tag="config"
   php artisan vendor:publish --provider="Xlabs\CompetitionBundle\CompetitionBundle" --tag="migrations"
   

   Migrate the database:

   php artisan migrate
   

3. First Use Case: Creating a Competition Define a competition in config/competition.php:

   'competitions' => [
       'summer_challenge' => [
           'name' => 'Summer Coding Challenge',
           'start_date' => '2024-06-01',
           'end_date' => '2024-08-31',
           'rules' => 'Submit 3 PRs weekly.',
       ],
   ],
   

   Trigger a competition via a controller:

   use Xlabs\CompetitionBundle\Services\CompetitionService;
   
   public function startCompetition(CompetitionService $competitionService) {
       $competitionService->activate('summer_challenge');
   }
   

Implementation Patterns

Core Workflows

1. Competition Lifecycle Management

   • Activation/Deactivation: Use CompetitionService to toggle competitions dynamically:

     $competitionService->activate('summer_challenge');
     $competitionService->deactivate('summer_challenge');
     

   • Date-Based Triggers: Leverage CompetitionListener to auto-activate/deactivate based on start_date/end_date in config.

2. Participant Tracking

   • Attach competitions to users via middleware or events:

     // In a middleware
     $user->competitions()->attach('summer_challenge');
     

   • Query active competitions for a user:

     $user->competitions()->wherePivot('active', true)->get();
     

3. Scoring & Leaderboards

   • Extend the Competition model to add custom scoring logic:

     // app/Models/Competition.php
     public function calculateScore(User $user) {
         return $user->submissions()->where('competition_id', $this->id)->count();
     }
     

   • Generate leaderboards via a custom command or API endpoint:

     $leaderboard = Competition::with('participants')
         ->where('active', true)
         ->get()
         ->sortByDesc(function ($competition) {
             return $competition->participants->count();
         });
     

4. Event-Driven Extensions

   • Listen for competition events (e.g., CompetitionActivated) to trigger side effects:

     // EventSubscriber
     public function onCompetitionActivated(CompetitionActivated $event) {
         // Send notifications, log analytics, etc.
     }
     

Integration Tips

• Laravel Mix/Inertia.js: Use the bundle’s events to dynamically update UI (e.g., show/hide competition banners).
• Queue Jobs: Offload scoring calculations or notifications to queues:

  dispatch(new CalculateCompetitionScores($competitionId));
  

• API Resources: Expose competitions via API:

  Route::apiResource('competitions', CompetitionController::class)->middleware('auth:sanctum');
  

Gotchas and Tips

Pitfalls

1. Config Overrides

   • Ensure config/competition.php is not cached during development:

     php artisan config:clear
     

   • Tip: Use environment variables for dynamic dates:

     'start_date' => env('COMPETITION_SUMMER_START', '2024-06-01'),
     

2. Migration Conflicts

   • If extending the competitions table, create a new migration after publishing the bundle’s migrations to avoid overwrites.

3. Circular Dependencies

   • Avoid calling CompetitionService in model boot methods—use observers or events instead to prevent lazy-loading issues.

4. Time Zone Handling

   • Store dates in UTC in the database but display them in user-local time:

     $competition->start_date->setTimezone($user->timezone);
     

Debugging

• Event Debugging: Dump competition events in a subscriber:

  public function onCompetitionActivated(CompetitionActivated $event) {
      \Log::debug('Activated:', [$event->competition->name]);
  }
  

• Middleware Conflicts: If competitions aren’t attaching to users, check middleware priority in app/Http/Kernel.php.

Extension Points

1. Custom Competition Types

   • Extend the Competition model and create a trait for shared logic:

     // app/Models/CustomCompetition.php
     class CustomCompetition extends Competition {
         use HasCustomRules;
     }
     

2. Validation Rules

   • Add custom validation to the CompetitionRequest (if the bundle provides one) or create a form request:

     public function rules() {
         return [
             'name' => 'required|unique:competitions,name,'.$this->competition->id,
             'start_date' => 'required|date|after:yesterday',
         ];
     }
     

3. Third-Party Integrations

   • Use the bundle’s events to sync with tools like Discord, Slack, or Mailchimp:

     // Listen for CompetitionActivated
     event(new \App\Events\SyncCompetitionToDiscord($event->competition));