Merge pull request #50 from SonnySha/develop

Add Weekly Odd/Even scheduling methods for more specific schedule options and update documentation

Author: ludoguenet

README.md

@@ -114,8 +114,19 @@ $schedule->daily()->from('2025-01-01')->to('2025-12-31');
 $schedule->weekly(['monday', 'wednesday', 'friday'])->forYear(2025);
 
 // Weekly with time period (convenience method - combines weekly() and addPeriod())
-$schedule->weekDays(['monday', 'wednesday', 'friday'], '09:00', '17:00')
-    ->forYear(2025);
+$schedule->weekDays(['monday', 'wednesday', 'friday'], '09:00', '17:00')->forYear(2025);
+
+// Weekly odd (specific days) – runs only on odd-numbered weeks
+$schedule->weeklyOdd(['monday', 'wednesday', 'friday'])->forYear(2025);
+
+// Weekly odd with time period (convenience method - combines weeklyOdd() and addPeriod())
+$schedule->weekOddDays(['monday', 'wednesday', 'friday'], '09:00', '17:00')->forYear(2025)
+
+// Weekly even (specific days) – runs only on even-numbered weeks
+$schedule->weeklyEven(['monday', 'wednesday', 'friday'])->forYear(2025);
+
+// Weekly even with time period (convenience method - combines weeklyEven() and addPeriod())
+$schedule->weekEvenDays(['monday', 'wednesday', 'friday'], '09:00', '17:00')->forYear(2025)
 
 // Bi-weekly (week of the start date by default, optional anchor)
 $schedule->biweekly(['tuesday', 'thursday'])->from('2025-01-07')->to('2025-03-31');
@@ -140,6 +151,7 @@ $schedule->annually(['days_of_month' => [1, 15], 'start_month' => 4])->from('202
 
 ```php
 $schedule->from('2025-01-15');                          // Single date
+$schedule->on('2025-01-15');                            // Alias (alternative syntax) for from()
 $schedule->from('2025-01-01')->to('2025-12-31');        // Date range
 $schedule->between('2025-01-01', '2025-12-31');         // Alternative syntax
 $schedule->forYear(2025);                               // Entire year shortcut
@@ -164,6 +176,9 @@ $schedule->addPeriod('14:00', '17:00');
 // Check if there is at least one bookable slot on the day
 $isBookable = $doctor->isBookableAt('2025-01-15', 60);
 
+// Check if a specific time range is bookable
+$isBookable = $doctor->isBookableAtTime('2025-01-15', '9:00', '9:30');
+
 // Get bookable slots
 $slots = $doctor->getBookableSlots('2025-01-15', 60, 15);
 
@@ -186,7 +201,7 @@ $schedule->isAppointment();
 $schedule->isBlocked();
 ```
 
-> `isAvailableAt()` is deprecated in favor of `isBookableAt()` and `getBookableSlots()`. Use the bookable APIs for all new code.
+> `isAvailableAt()` is deprecated in favor of `isBookableAt()` `isBookableAtTime()` and `getBookableSlots()`. Use the bookable APIs for all new code.
 
 ---
 

src/Builders/ScheduleBuilder.php

@@ -13,7 +13,6 @@
 use Zap\Data\MonthlyFrequencyConfig;
 use Zap\Data\QuarterlyFrequencyConfig;
 use Zap\Data\SemiAnnuallyFrequencyConfig;
-use Zap\Data\WeeklyFrequencyConfig;
 use Zap\Enums\Frequency;
 use Zap\Enums\ScheduleTypes;
 use Zap\Models\Schedule;
@@ -154,16 +153,42 @@ public function daily(): self
     }
 
     /**
-     * Set schedule as weekly recurring.
+     * Internal helper to configure a weekly frequency for the schedule.
+     *
+     * This method centralizes the logic for setting weekly recurring schedules,
+     * including standard weeks, odd weeks, and time periods.
+     * It prevents code duplication across public methods like weekly(), weekDays(), weeklyOdd() and weekOddDays()
+     *
+     * @param  Frequency  $frequency  The frequency type (WEEKLY, WEEKLY_ODD, etc.)
+     * @param  array  $days  Array of days the schedule applies to
+     * @param  string|null  $startTime  Optional start time for the daily period
+     * @param  string|null  $endTime  Optional end time for the daily period
+     * @return self Returns the current instance for method chaining
      */
-    public function weekly(array $days = []): self
+    private function setWeeklyFrequency(Frequency $frequency, array $days, ?string $startTime = null, ?string $endTime = null): self
     {
         $this->attributes['is_recurring'] = true;
-        $this->attributes['frequency'] = Frequency::WEEKLY;
-        $this->attributes['frequency_config'] = WeeklyFrequencyConfig::fromArray([
+        $this->attributes['frequency'] = $frequency;
+
+        $configClass = app($frequency->configClass());
+        $this->attributes['frequency_config'] = $configClass->fromArray([
             'days' => $days,
         ]);
 
+        if ($startTime !== null && $endTime !== null) {
+            $this->addPeriod($startTime, $endTime, null);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Set schedule as weekly recurring.
+     */
+    public function weekly(array $days = []): self
+    {
+        $this->setWeeklyFrequency(Frequency::WEEKLY, $days);
+
         return $this;
     }
 
@@ -172,13 +197,47 @@ public function weekly(array $days = []): self
      */
     public function weekDays(array $days, string $startTime, string $endTime): self
     {
-        $this->attributes['is_recurring'] = true;
-        $this->attributes['frequency'] = Frequency::WEEKLY;
-        $this->attributes['frequency_config'] = WeeklyFrequencyConfig::fromArray([
-            'days' => $days,
-        ]);
+        $this->setWeeklyFrequency(Frequency::WEEKLY, $days, $startTime, $endTime);
+
+        return $this;
+    }
+
+    /**
+     * Set schedule as weekly recurring on odd weeks.
+     */
+    public function weeklyOdd(array $days = []): self
+    {
+        $this->setWeeklyFrequency(Frequency::WEEKLY_ODD, $days);
 
-        $this->addPeriod($startTime, $endTime, null);
+        return $this;
+    }
+
+    /**
+     * Set schedule as weekly recurring on odd weeks and add a time period.
+     */
+    public function weekOddDays(array $days, string $startTime, string $endTime): self
+    {
+        $this->setWeeklyFrequency(Frequency::WEEKLY_ODD, $days, $startTime, $endTime);
+
+        return $this;
+    }
+
+    /**
+     * Set schedule as weekly recurring on even weeks.
+     */
+    public function weeklyEven(array $days = []): self
+    {
+        $this->setWeeklyFrequency(Frequency::WEEKLY_EVEN, $days);
+
+        return $this;
+    }
+
+    /**
+     * Set schedule as weekly recurring on even weeks and add a time period.
+     */
+    public function weekEvenDays(array $days, string $startTime, string $endTime): self
+    {
+        $this->setWeeklyFrequency(Frequency::WEEKLY_EVEN, $days, $startTime, $endTime);
 
         return $this;
     }
@@ -311,6 +370,14 @@ public function noOverlap(): self
         return $this->withRule('no_overlap');
     }
 
+    /**
+     * Add allow overlap rule.
+     */
+    public function allowOverlap(): self
+    {
+        return $this->withRule('no_overlap', ['enabled' => false]);
+    }
+
     /**
      * Set schedule as availability type (allows overlaps).
      */

src/Data/WeeklyEvenOddFrequencyConfig/AbstractWeeklyOddEvenFrequencyConfig.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace Zap\Data\WeeklyEvenOddFrequencyConfig;
+
+use Zap\Data\FrequencyConfig;
+use Zap\Helper\DateHelper;
+use Zap\Models\Schedule;
+
+/**
+ * @property-read list<string> $daysOfWeek
+ */
+abstract class AbstractWeeklyOddEvenFrequencyConfig extends FrequencyConfig
+{
+    public function __construct(
+        public array $days = []
+    ) {}
+
+    abstract protected function isWeekTypeMatch(\Carbon\CarbonInterface $date): bool;
+
+    public function shouldCreateInstance(\Carbon\CarbonInterface $date): bool
+    {
+        return empty($this->days) || in_array(strtolower($date->format('l')), $this->days);
+    }
+
+    public function shouldCreateRecurringInstance(Schedule $schedule, \Carbon\CarbonInterface $date): bool
+    {
+        $allowedDays = ! empty($this->days) ? $this->days : ['monday'];
+        $allowedDayNumbers = DateHelper::getDayNumbers($allowedDays);
+
+        return $this->isWeekTypeMatch($date) && in_array($date->dayOfWeek, $allowedDayNumbers);
+    }
+
+    public function getNextRecurrence(\Carbon\CarbonInterface $current): \Carbon\CarbonInterface
+    {
+        return $this->getNextWeeklyOccurrence($current, $this->days);
+    }
+
+    protected function getNextWeeklyOccurrence(\Carbon\CarbonInterface $current, array $allowedDays): \Carbon\CarbonInterface
+    {
+        $next = $current->copy()->addDay();
+        $allowedDayNumbers = DateHelper::getDayNumbers($allowedDays);
+
+        while (true) {
+            $isAllowedDay = in_array($next->dayOfWeek, $allowedDayNumbers);
+
+            if ($this->isWeekTypeMatch($next) && $isAllowedDay) {
+                break;
+            }
+
+            $next->addDay();
+
+            if ($next->diffInDays($current) > 14) {
+                break;
+            }
+        }
+
+        return $next;
+    }
+}

src/Data/WeeklyEvenOddFrequencyConfig/WeeklyEvenFrequencyConfig.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace Zap\Data\WeeklyEvenOddFrequencyConfig;
+
+use Zap\Helper\DateHelper;
+
+/**
+ * @property-read list<string> $daysOfWeek
+ */
+class WeeklyEvenFrequencyConfig extends AbstractWeeklyOddEvenFrequencyConfig
+{
+    public static function fromArray(array $data): self
+    {
+        if (! array_key_exists('days', $data)) {
+            throw new \InvalidArgumentException("Missing 'days' key in WeeklyEvenFrequencyConfig data array.");
+        }
+
+        return new self(
+            days: $data['days'] ?? []
+        );
+    }
+
+    protected function isWeekTypeMatch(\Carbon\CarbonInterface $date): bool
+    {
+        return DateHelper::isDateInEvenIsoWeek($date);
+    }
+}

src/Data/WeeklyEvenOddFrequencyConfig/WeeklyOddFrequencyConfig.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace Zap\Data\WeeklyEvenOddFrequencyConfig;
+
+use Zap\Helper\DateHelper;
+
+/**
+ * @property-read list<string> $daysOfWeek
+ */
+class WeeklyOddFrequencyConfig extends AbstractWeeklyOddEvenFrequencyConfig
+{
+    public static function fromArray(array $data): self
+    {
+        if (! array_key_exists('days', $data)) {
+            throw new \InvalidArgumentException("Missing 'days' key in WeeklyOddFrequencyConfig data array.");
+        }
+
+        return new self(
+            days: $data['days'] ?? []
+        );
+    }
+
+    protected function isWeekTypeMatch(\Carbon\CarbonInterface $date): bool
+    {
+        return DateHelper::isDateInOddIsoWeek($date);
+    }
+}

src/Data/WeeklyFrequencyConfig.php

@@ -2,6 +2,7 @@
 
 namespace Zap\Data;
 
+use Zap\Helper\DateHelper;
 use Zap\Models\Schedule;
 
 /**
@@ -37,18 +38,7 @@ public function shouldCreateInstance(\Carbon\CarbonInterface $date): bool
     public function shouldCreateRecurringInstance(Schedule $schedule, \Carbon\CarbonInterface $date): bool
     {
         $allowedDays = ! empty($this->days) ? $this->days : ['monday'];
-        $allowedDayNumbers = array_map(function ($day) {
-            return match (strtolower($day)) {
-                'sunday' => 0,
-                'monday' => 1,
-                'tuesday' => 2,
-                'wednesday' => 3,
-                'thursday' => 4,
-                'friday' => 5,
-                'saturday' => 6,
-                default => 1, // Default to Monday
-            };
-        }, $allowedDays);
+        $allowedDayNumbers = DateHelper::getDayNumbers($allowedDays);
 
         return in_array($date->dayOfWeek, $allowedDayNumbers);
     }
@@ -57,19 +47,7 @@ protected function getNextWeeklyOccurrence(\Carbon\CarbonInterface $current, arr
     {
         $next = $current->copy()->addDay();
 
-        // Convert day names to numbers (0 = Sunday, 1 = Monday, etc.)
-        $allowedDayNumbers = array_map(function ($day) {
-            return match (strtolower($day)) {
-                'sunday' => 0,
-                'monday' => 1,
-                'tuesday' => 2,
-                'wednesday' => 3,
-                'thursday' => 4,
-                'friday' => 5,
-                'saturday' => 6,
-                default => 1, // Default to Monday
-            };
-        }, $allowedDays);
+        $allowedDayNumbers = DateHelper::getDayNumbers($allowedDays);
 
         // Find the next allowed day
         while (! in_array($next->dayOfWeek, $allowedDayNumbers)) {

src/Enums/Frequency.php

@@ -9,6 +9,8 @@ enum Frequency: string
 {
     case DAILY = 'daily';
     case WEEKLY = 'weekly';
+    case WEEKLY_ODD = 'weekly_odd';
+    case WEEKLY_EVEN = 'weekly_even';
     case BIWEEKLY = 'biweekly';
     case MONTHLY = 'monthly';
     case BIMONTHLY = 'bimonthly';
@@ -21,6 +23,8 @@ public function getNextRecurrence(CarbonInterface $current): CarbonInterface
         return match ($this) {
             self::DAILY => $current->copy()->addDay(),
             self::WEEKLY => $current->copy()->addWeek(),
+            self::WEEKLY_ODD => \Zap\Helper\DateHelper::nextWeekOdd($current),
+            self::WEEKLY_EVEN => \Zap\Helper\DateHelper::nextWeekEven($current),
             self::BIWEEKLY => $current->copy()->addWeeks(2),
             self::MONTHLY => $current->copy()->addMonth(),
             self::BIMONTHLY => $current->copy()->addMonths(2),
@@ -38,6 +42,8 @@ public function configClass(): string
         return match ($this) {
             self::DAILY => \Zap\Data\DailyFrequencyConfig::class,
             self::WEEKLY => \Zap\Data\WeeklyFrequencyConfig::class,
+            self::WEEKLY_ODD => \Zap\Data\WeeklyEvenOddFrequencyConfig\WeeklyOddFrequencyConfig::class,
+            self::WEEKLY_EVEN => \Zap\Data\WeeklyEvenOddFrequencyConfig\WeeklyEvenFrequencyConfig::class,
             self::BIWEEKLY => \Zap\Data\BiWeeklyFrequencyConfig::class,
             self::MONTHLY => \Zap\Data\MonthlyFrequencyConfig::class,
             self::BIMONTHLY => \Zap\Data\BiMonthlyFrequencyConfig::class,
@@ -47,6 +53,15 @@ public function configClass(): string
         };
     }
 
+    public static function weeklyFrequencies(): array
+    {
+        return [
+            self::WEEKLY,
+            self::WEEKLY_ODD,
+            self::WEEKLY_EVEN,
+        ];
+    }
+
     public static function filteredByWeekday(): array
     {
         return [