Fixing Newsletter Digest Scheduling: A Matter of Minutes

Sometimes the smallest oversights can lead to significant issues. Recently, we encountered a problem where our newsletter digest wasn't being sent as expected. The culprit? An overly precise time comparison.

The Problem: Exact-Minute Matching

The original scheduling logic used an isDue() function that compared both the hour and minute. However, the scheduler was designed to run hourly, specifically at minute 0. This meant that any time not precisely on the hour (e.g., ':00') would never trigger the newsletter digest. The digest effectively remained unsent.

The Solution: Focusing on the Hour

To resolve this, we modified the isDue() function to check only the hour. This ensures that the scheduler correctly identifies when the digest is due to be sent. A 7-day cooldown period was already in place, preventing duplicate sends, so relaxing the minute check didn't introduce any new risks.

// Previous implementation (simplified)
function isDue(DateTimeInterface $lastSent):
{
    $now = new DateTimeImmutable();
    return $now->format('H:i') === $lastSent->format('H:i');
}

// Corrected implementation (simplified)
function isDue(DateTimeInterface $lastSent):
{
    $now = new DateTimeImmutable();
    return $now->format('H') === $lastSent->format('H');
}

Ensuring Data Integrity in Testing

During the debugging process, we also identified an issue with our testing setup. The Post::create calls in our tests weren't including a published_at timestamp. This meant that the job's whereNotNull query, which relied on this timestamp, couldn't find any posts, further contributing to the digest not being sent during testing.

We've updated our Post::create calls to include a valid published_at timestamp. This ensures that our tests accurately reflect real-world scenarios and that the scheduling logic is properly exercised.

// Example of Post::create with published_at
Post::create([
    'title' => 'Test Post',
    'content' => 'This is a test post.',
    'published_at' => now(), // Add published_at timestamp
]);

Improving User Experience

As a final touch, we added a helper text hint to the Filament time field. This provides users with additional guidance on how to properly configure the scheduling settings, reducing the likelihood of future misconfigurations.

// Example Filament field with helper text
Forms\Components\TimePicker::make('scheduled_time')
    ->helperText('Please select the hour for the scheduled task.');

Key Takeaways

• Pay attention to the granularity of your time comparisons, especially when dealing with scheduled tasks.
• Ensure that your test data accurately reflects the conditions of your production environment.
• Provide clear and helpful guidance to users when configuring time-sensitive settings.