spatie/opening-hours

The filters property allows you to pass callables (closures or function references) that take a DateTime as a parameter and return the settings for that date. This is useful for complex logic like calculating Easter Monday.

Precedence Rules:

1. The first filter that returns a non-null value takes precedence.
2. The filters array has precedence over filters inside the exceptions array.
3. If a callable is found in the exceptions property, it is automatically added to the filters.

Warning: Filters are executed for every date checked and cannot be cached. Avoid heavy processing inside filters to prevent performance issues.

$openingHours = OpeningHours::create([
    'monday' => [
       '09:00-12:00',
    ],
    'filters' => [
        function ($date) {
            $year         = intval($date->format('Y'));
            $easterMonday = new DateTimeImmutable('2018-03-21 +'.(easter_days($year) + 1).'days');
            if ($date->format('m-d') === $easterMonday->format('m-d')) {
                return []; // Closed on Easter Monday
            }
        },
    ],
]);

You can retrieve the next upcoming DateTime when a business will open or close relative to a given time:

• nextOpen(DateTimeInterface $dateTime): Returns the next DateTime when the business opens.
• nextClose(DateTimeInterface $dateTime): Returns the next DateTime when the business closes.
• currentOpenRange(DateTimeInterface $dateTime): Returns a range object if the business is currently open at the given time, otherwise returns null.

// The next open datetime is tomorrow morning, because we’re closed on 25th of December.
$nextOpen = $openingHours->nextOpen(new DateTime('2016-12-25 10:00:00')); // 2016-12-26 09:00:00

// The next close datetime is at noon.
$nextClose = $openingHours->nextClose(new DateTime('2016-12-24 10:00:00')); // 2016-12-24 12:00:00

$now = new DateTime('now');
$range = $openingHours->currentOpenRange($now);

if ($range) {
    echo "It's open since " . $range->start() . "\n";
    echo "It will close at " . $range->end() . "\n";
} else {
    echo "It's closed since " . $openingHours->previousClose($now)->format('l H:i') . "\n";
    echo "It will re-open at " . $openingHours->nextOpen($now)->format('l H:i') . "\n";
}

Use these methods to inspect the schedule structure:

• forDay(string $day): Returns an OpeningHoursForDay object for a specific day (lowercase English name).
• forDate(DateTimeInterface $dateTime): Returns an OpeningHoursForDay object for a specific date, accounting for exceptions.
• exceptions(): Returns an array of OpeningHoursForDay objects for all exception dates, keyed by Y-m-d.
• forWeek(): Returns an array of OpeningHoursForDay objects for a regular week.
• forWeekCombined(): Returns an array where keys are the first day of a group and values are arrays of days sharing the same hours.
• forWeekConsecutiveDays(): Returns an array of concatenated adjacent days with the same hours. Warning: This does not loop from Sunday to Monday.

$openingHours->forDay('monday');
$openingHours->forDate(new DateTime('2016-12-25'));
$openingHours->exceptions();
$openingHours->forWeek();
$openingHours->forWeekCombined();
$openingHours->forWeekConsecutiveDays();

Use OpeningHours::create() to initialize a schedule from an array. If no timezone is provided, the package assumes provided DateTime objects already match the schedule's timezone.

You can specify an input and output timezone to handle conversions automatically. If an output timezone is provided, methods returning dates (like nextOpen) will convert the result back to the original timezone so the object reflects local time while the internal logic uses the business timezone.

To handle overlapping ranges during creation, use the 'overflow' => true option in the array or use the createAndMergeOverlappingRanges() shortcut.

// Basic creation
$openingHours = OpeningHours::create([
    'monday' => ['09:00-12:00', '13:00-18:00'],
]);

// Creation with specific input and output timezones
$openingHours = OpeningHours::create([
    'monday' => ['09:00-12:00', '13:00-18:00'],
    'timezone' => [
        'input' => 'America/New_York',
        'output' => 'Europe/Oslo',
    ],
]);

// Merging overlapping ranges
$ranges = [
  'monday' => ['08:00-11:00', '10:00-12:00'],
];
$mergedRanges = OpeningHours::mergeOverlappingRanges($ranges); // Monday becomes ['08:00-12:00']
$openingHours = OpeningHours::createAndMergeOverlappingRanges($ranges);

The OpeningHours class provides several methods to check status:

• isOpen(): Checks if the business is open right now.
• isClosed(): Checks if the business is closed right now.
• isOpenAt(DateTimeInterface $dateTime): Checks if open at a specific time.
• isClosedAt(DateTimeInterface $dateTime): Checks if closed at a specific time.
• isOpenOn(string $day): Checks if open on a specific day (e.g., 'monday'). If a date string is passed (e.g., '2020-09-03' or '09-03'), it checks both the regular schedule and exceptions.
• isClosedOn(string $day): Checks if closed on a regular scheduled day.
• isAlwaysOpen(): Returns true if the business is open 24/7 with no exceptions.
• isAlwaysClosed(): Returns true if the business is never open (empty schedule).

$openingHours->isOpen();
$openingHours->isOpenAt(new DateTime('2016-26-09 20:00'));
$openingHours->isOpenOn('saturday');
$openingHours->isOpenOn('2020-09-03');

if ($openingHours->isAlwaysOpen()) {
    echo 'This business is open all day long every day.';
}

You can attach arbitrary data to specific time ranges or exceptions. This data can be a string or any other value (like an associative array).

To use this, structure your input using either the shorthand (where the value is an array containing the hours and a 'data' key) or the explicit 'hours' key format.

$openingHours = OpeningHours::create([
    'monday' => [
        'data' => 'Typical Monday',
        '09:00-12:00',
        '13:00-18:00',
    ],
    'tuesday' => [
        '09:00-12:00',
        '13:00-18:00',
        [
            '19:00-21:00',
            'data' => 'Extra on Tuesday evening',
        ],
    ],
    'exceptions' => [
        '2016-12-25' => [
            'data' => 'Closed for Christmas',
        ],
    ],
]);

echo $openingHours->forDay('monday')->data; // Typical Monday
echo $openingHours->forDate(new DateTime('2016-12-25'))->data; // Closed for Christmas
echo $openingHours->forDay('tuesday')[2]->data; // Extra on Tuesday evening