Repeating Campaign Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bibsdb/repeating-campaign-bundle
   

   Add to config/app.php under providers:

   Bibsdb\RepeatingCampaignBundle\RepeatingCampaignServiceProvider::class,
   

2. Publish Config

   php artisan vendor:publish --provider="Bibsdb\RepeatingCampaignBundle\RepeatingCampaignServiceProvider"
   

   Edit config/repeating_campaign.php to define:

   • workdays (e.g., ['mon', 'tue', 'wed', 'thu', 'fri'])
   • weekend_days (e.g., ['sat', 'sun'])
   • Default campaign schedule (e.g., ['09:00', '17:00'] for 9 AM–5 PM).

3. First Use Case Trigger a campaign via the facade:

   use Bibsdb\RepeatingCampaignBundle\Facades\RepeatingCampaign;
   
   // Run a campaign for today (respects workdays/weekends)
   RepeatingCampaign::run('campaign_name');
   
   // Force a weekend run (bypasses workday checks)
   RepeatingCampaign::run('campaign_name', true);
   

Implementation Patterns

Core Workflows

1. Scheduling Campaigns Use the RepeatingCampaign facade to queue campaigns with day-specific logic:

   // Run only on workdays (default)
   RepeatingCampaign::schedule('daily_newsletter', '2024-01-01');
   
   // Run on weekends only
   RepeatingCampaign::schedule('weekend_promo', '2024-01-06', false, true);
   

   • Parameters:
     • campaign_name: Key for your campaign logic.
     • date: Optional override (defaults to today).
     • force_workday: Run even on weekends (default: true).
     • force_weekend: Run only on weekends (default: false).

2. Customizing Day Logic Extend the bundle’s DayChecker trait in a service:

   namespace App\Services;
   
   use Bibsdb\RepeatingCampaignBundle\Traits\DayChecker;
   
   class CustomCampaignChecker {
       use DayChecker;
   
       protected function isWorkday($date): bool {
           // Override logic (e.g., exclude holidays)
           return parent::isWorkday($date) && !in_array($date->format('Y-m-d'), config('holidays'));
       }
   }
   

3. Integrating with Queues Chain campaigns to Laravel’s queue system:

   RepeatingCampaign::run('campaign_name')
       ->then(function () {
           dispatch(new SendEmailJob());
       });
   

4. Event-Based Triggers Listen for campaign events in EventServiceProvider:

   protected $listen = [
       'Bibsdb\RepeatingCampaignBundle\Events\CampaignScheduled' => [
           'App\Listeners\LogCampaignSchedule',
       ],
   ];
   

Gotchas and Tips

Pitfalls

1. Time Zone Mismatches

   • The bundle uses the system’s default time zone. Explicitly set it in config/app.php:

     'timezone' => 'America/New_York',
     

   • Debug with:

     \Carbon\Carbon::now()->timezone(config('app.timezone'))->format('Y-m-d H:i');
     

2. Weekend Logic Overrides

   • The force_weekend flag excludes workdays entirely. Use sparingly to avoid conflicts:

     // ❌ Runs only on weekends (never on workdays)
     RepeatingCampaign::schedule('campaign', null, false, true);
     
     // ✅ Runs on weekends + optionally on workdays
     if ($this->isWeekend()) {
         RepeatingCampaign::run('campaign', true); // Force workday mode
     }
     

3. Config Caching

   • After editing config/repeating_campaign.php, clear the config cache:

     php artisan config:clear
     

4. Date Handling Quirks

   • The bundle uses Carbon internally. Ensure your input dates are Carbon instances:

     $date = Carbon::parse('2024-01-01');
     RepeatingCampaign::schedule('campaign', $date);
     

Tips

1. Debugging Day Checks Inspect the current day’s classification:

   dd(
       RepeatingCampaign::isWorkday(), // bool
       RepeatingCampaign::isWeekend()  // bool
   );
   

2. Bulk Scheduling Use Laravel’s collect() to schedule multiple campaigns:

   collect(['newsletter', 'promo'])
       ->each(fn ($campaign) => RepeatingCampaign::schedule($campaign));
   

3. Extending Campaign Logic Create a custom campaign runner:

   namespace App\Services;
   
   use Bibsdb\RepeatingCampaignBundle\RepeatingCampaign;
   
   class CustomCampaignRunner {
       public function run($campaign, $forceWorkday = true) {
           if ($this->shouldRun($campaign, $forceWorkday)) {
               // Custom logic here
               RepeatingCampaign::trigger($campaign);
           }
       }
   }
   

4. Testing Mock the DayChecker trait in PHPUnit:

   $mockChecker = $this->getMockBuilder(StdClass::class)
       ->setMethods(['isWorkday', 'isWeekend'])
       ->getMock();
   
   $mockChecker->method('isWorkday')->willReturn(true);
   RepeatingCampaign::setDayChecker($mockChecker);