CarbonPeriod: 7 Examples of Date Time Lists For Reports and Calendars

The Carbon class for dates and times is a part of Laravel by default, but there's also a less-known class, CarbonPeriod. It can help generate the ARRAY of datetimes, often useful for report tables and calendars. In this tutorial, let's look at the 5 most practical examples of CarbonPeriod.

Example 1. List of Hours Or Minute Intervals

What if you need an array list of working hours limited by start/end times?

• 9:00
• 10:00
• 11:00
• ...
• 18:00

Look at this CarbonInterval snippet:

use Carbon\Carbon;
use Carbon\CarbonPeriod;
 
$startPeriod = Carbon::parse('9:00');
$endPeriod   = Carbon::parse('18:00');
 
$period = CarbonPeriod::create($startPeriod, '1 hour', $endPeriod);
$hours  = [];
 
foreach ($period as $date) {
    $hours[] = $date->format('H:i');
}

Result:

array:10 [
  0 => "09:00"
  1 => "10:00"
  2 => "11:00"
  3 => "12:00"
  4 => "13:00"
  5 => "14:00"
  6 => "15:00"
  7 => "16:00"
  8 => "17:00"
  9 => "18:00"
]

As you can see, each CarbonPeriod element is a Carbon class instance that you can format however you want.

But it's not necessarily about the hours only. You can also change the period to smaller intervals, like "45 minutes":

$period = CarbonPeriod::create($startPeriod, '45 minutes', $endPeriod);

Result:

array:13 [
  0 => "09:00"
  1 => "09:45"
  2 => "10:30"
  3 => "11:15"
  4 => "12:00"
  5 => "12:45"
  6 => "13:30"
  7 => "14:15"
  8 => "15:00"
  9 => "15:45"
  10 => "16:30"
  11 => "17:15"
  12 => "18:00"
]

You can also skip the first or last entry using the excludeStartDate or excludeEndDate methods.

$period = CarbonPeriod::create($startPeriod, '45 minutes', $endPeriod)
    ->excludeStartDate()
    ->excludeEndDate();

array:11
  0 => "09:45"
  1 => "10:30"
  2 => "11:15"
  3 => "12:00"
  4 => "12:45"
  5 => "13:30"
  6 => "14:15"
  7 => "15:00"
  8 => "15:45"
  9 => "16:30"
  10 => "17:15"
]

Or change representation to a 12-hour format:

foreach ($period as $date) {
    $hours[] = $date->format('h:i A');
}

array:11 [
  0 => "09:45 AM"
  1 => "10:30 AM"
  2 => "11:15 AM"
  3 => "12:00 PM"
  4 => "12:45 PM"
  5 => "01:30 PM"
  6 => "02:15 PM"
  7 => "03:00 PM"
  8 => "03:45 PM"
  9 => "04:30 PM"
  10 => "05:15 PM"
]

Example 2. List of Dates By Weekdays

Let's say you want to schedule appointments, but have open slots only for Mondays and plan to do so for the current month.

use Carbon\CarbonPeriod;
 
$period = CarbonPeriod::between(now()->startOfMonth(), now()->endOfMonth())
    ->filter(fn ($date) => $date->isMonday());
$dates = [];
 
foreach ($period as $date) {
    $dates[] = $date->format('M j, l, Y');
}

Result:

array:5 [
  0 => "Jul 3, Monday, 2023"
  1 => "Jul 10, Monday, 2023"
  2 => "Jul 17, Monday, 2023"
  3 => "Jul 24, Monday, 2023"
  4 => "Jul 31, Monday, 2023"
]

As you can see, you can initialize the period with the ::between($start, $end) method and then add extra filters.

Of course, there are many more functions, not only ->isMonday().

Looking at the Carbon documentation, we can find these:

$dt->isWeekday();
$dt->isWeekend();
$dt->isTuesday();
// ...
$dt->isSunday();
 
$dt->isLastOfMonth();
$dt->isYesterday();
$dt->isToday();
$dt->isTomorrow();
$dt->isNextWeek();
$dt->isLastWeek();
 
// ... and more

Example 3. List of Weeks

What if you want to...