Motwbundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require atm/motwbundle
   

   Publish the bundle's assets and configuration:

   php artisan vendor:publish --provider="Atm\MotwBundle\MotwBundle" --tag=config
   php artisan vendor:publish --provider="Atm\MotwBundle\MotwBundle" --tag=assets
   

2. Configuration Locate the published config at config/motw.php and adjust:

   • model_class: Specify your Eloquent model (e.g., App\Models\Product).
   • week_start_day: Set the day of the week for the "week" calculation (e.g., 1 for Monday).
   • cache_duration: Define how long to cache the "Model of the Week" (e.g., 604800 for 1 week in seconds).

3. First Use Case Fetch the current "Model of the Week" in a controller:

   use Atm\MotwBundle\Services\MotwService;
   
   public function showMotw(MotwService $motwService)
   {
       $motw = $motwService->getModelOfTheWeek();
       return view('motw.show', compact('motw'));
   }
   

4. Blade Integration Add a helper view snippet in resources/views/motw/_partials.blade.php:

   @motw
       <div class="motw-card">
           <h3>{{ $motw->name }}</h3>
           <p>{{ $motw->description }}</p>
       </div>
   @endmotw
   

Implementation Patterns

Core Workflows

1. Dynamic Model Selection Override the default model via dependency injection:

   public function __construct(MotwService $motwService, App\Models\Category $categoryModel)
   {
       $this->motwService = $motwService->setModel($categoryModel);
   }
   

2. Custom Query Logic Extend the bundle’s query builder by binding a custom resolver:

   // In a service provider
   $motwService->setQueryResolver(function ($query) {
       return $query->where('is_featured', true)->orderBy('popularity', 'desc');
   });
   

3. Weekly Rotation Schedule a weekly update via Laravel’s scheduler:

   // app/Console/Kernel.php
   protected function schedule(Schedule $schedule)
   {
       $schedule->call(function () {
           app(MotwService::class)->rotateModel();
       })->weekly()->mondays();
   }
   

4. API Endpoint Expose the MOTW via an API route:

   Route::get('/api/motw', function (MotwService $motwService) {
       return response()->json($motwService->getModelOfTheWeek());
   });
   

Integration Tips

• Caching: Leverage the built-in cache (default: file driver) for performance. Clear cache manually with:

  php artisan cache:clear
  

• Testing: Mock the MotwService in unit tests:

  $this->partialMock(MotwService::class, ['getModelOfTheWeek'])
       ->shouldReceive('getModelOfTheWeek')
       ->andReturn($fakeModel);
  

• Frontend: Use the @motw directive in Blade or fetch via JavaScript:

  fetch('/api/motw')
      .then(res => res.json())
      .then(motw => console.log(motw));
  

Gotchas and Tips

Pitfalls

1. Time Zone Sensitivity The "week" calculation uses the server’s timezone. Ensure config/app.php has the correct timezone (e.g., 'timezone' => 'America/New_York').

2. Cache Invalidation Manually clear the cache if the MOTW changes unexpectedly:

   php artisan motw:clear-cache
   

   (Add this command via a custom artisan command if needed.)

3. Model Requirements The bundle assumes the model has id, name, and description fields. Customize via:

   $motwService->setAttributes(['id', 'title', 'summary']);
   

4. Week Start Day Defaults to 0 (Sunday). Adjust in config/motw.php if your "week" starts on Monday (1).

Debugging

• Log Queries: Enable query logging in config/database.php:

  'log' => true,
  'log_query_params' => true,
  

• Check Cache: Inspect cached MOTW with:

  php artisan cache:table
  

  (For file-based cache, check storage/framework/cache/.)

Extension Points

1. Custom Resolvers Override the default resolver (e.g., for random selection):

   $motwService->setResolver(function ($model) {
       return $model::inRandomOrder()->first();
   });
   

2. Event Listeners Listen for MOTW changes:

   // In EventServiceProvider
   protected $listen = [
       'Atm\MotwBundle\Events\MotwRotated' => [
           'App\Listeners\LogMotwChange',
       ],
   ];
   

3. Translation Extend language files at resources/lang/{locale}/motw.php:

   return [
       'header' => 'Featured Item of the Week',
   ];
   

4. Database Observers Trigger MOTW rotation on model updates:

   // app/Observers/ProductObserver.php
   public function saved(Product $product)
   {
       if ($product->is_featured) {
           app(MotwService::class)->rotateModel();
       }
   }