Motwbundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require xlabs/motwbundle
   

   Publish the bundle’s assets and migrations:

   php artisan vendor:publish --provider="Xlabs\MotwBundle\MotwServiceProvider" --tag=motw-migrations
   php artisan vendor:publish --provider="Xlabs\MotwBundle\MotwServiceProvider" --tag=motw-config
   php artisan migrate
   

2. Configure the Bundle Edit config/motw.php to define:

   • model (the Eloquent model to track as "Model of the Week").
   • voting_duration (default: 7 days).
   • notification_channels (e.g., ['mail', 'database']).

3. First Use Case: Displaying the Current Model of the Week

   use Xlabs\MotwBundle\Facades\Motw;
   
   $motw = Motw::current(); // Returns the current Model of the Week
   echo "Current MOTW: " . $motw->name;
   

4. Blade Integration Add to your layout:

   @motw('Xlabs\MotwBundle\Views::motw-badge', ['model' => $motw])
   

Implementation Patterns

Core Workflows

1. Voting System

   • Trigger Votes: Use the Motw::vote() method to cast a vote for a model:

     Motw::vote($modelId); // $modelId is the primary key of the model being voted for
     

   • Weighted Votes: Extend the Xlabs\MotwBundle\Contracts\VoteWeight interface to customize vote logic (e.g., admin votes count double).

2. Scheduling

   • The bundle auto-resets the MOTW weekly via Laravel’s scheduler. Add to app/Console/Kernel.php:

     $schedule->command('motw:reset')->weekly();
     

3. Notifications

   • Customize notifications by publishing the bundle’s views:

     php artisan vendor:publish --provider="Xlabs\MotwBundle\MotwServiceProvider" --tag=motw-views
     

   • Extend the Xlabs\MotwBundle\Events\MotwUpdated event to send custom notifications.

4. API Endpoints

   • Use the MotwController (published with --tag=motw-controllers) to expose endpoints like:
     • GET /api/motw → Current MOTW.
     • POST /api/motw/{model}/vote → Cast a vote.

Integration Tips

• Eloquent Models: Ensure your model implements Xlabs\MotwBundle\Contracts\MotwModel (e.g., adds a getMotwKey() method for unique identification).
• Caching: Cache the current MOTW to reduce database load:

  $motw = Cache::remember('motw.current', now()->addHours(1), fn() => Motw::current());
  

• Frontend Integration: Use JavaScript to fetch and display the MOTW dynamically:

  fetch('/api/motw')
    .then(res => res.json())
    .then(motw => document.getElementById('motw-badge').innerHTML = motw.name);
  

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • If you’ve manually added columns (e.g., votes_count), drop and re-run migrations after publishing to avoid conflicts.

2. Vote Duplication

   • The bundle assumes one vote per user per week. Override Xlabs\MotwBundle\Services\VoteService to enforce stricter rules (e.g., IP-based voting).

3. Time Zone Issues

   • The weekly reset uses Laravel’s now(). Configure your APP_TIMEZONE in .env to match your expectations (e.g., UTC for consistency).

4. Model Eligibility

   • By default, all records of the configured model are eligible. Override Xlabs\MotwBundle\Contracts\MotwEligibility to filter models (e.g., exclude inactive ones):

     public function isEligible($model): bool {
         return $model->is_active && $model->published_at <= now();
     }
     

Debugging

• Log Votes: Enable debug mode in config/motw.php ('debug' => true) to log votes to storage/logs/motw.log.
• Check Scheduler: Verify the motw:reset command runs via:

  php artisan schedule:work
  

• Test Votes: Use Tinker to simulate votes:

  php artisan tinker
  >>> \Xlabs\MotwBundle\Facades\Motw::vote(1); // Vote for model with ID 1
  

Extension Points

1. Custom Vote Logic

   • Extend Xlabs\MotwBundle\Services\VoteCalculator to implement custom scoring (e.g., decaying votes over time).

2. Alternative Storage

   • Replace the default MotwRepository to use Redis or another cache layer for performance:

     $this->app->bind(
         \Xlabs\MotwBundle\Contracts\MotwRepository::class,
         \YourApp\Motw\RedisMotwRepository::class
     );
     

3. Frontend Badges

   • Override the default badge view (resources/views/vendor/motw/badge.blade.php) to match your theme:

     <div class="motw-badge {{ $model->is_motw ? 'active' : 'inactive' }}">
         {{ $model->name }}
     </div>
     

4. Multi-Tenancy

   • Use middleware to scope the MOTW to the current tenant:

     Motw::setModel($tenant->motwModel); // Dynamically set the model class