Spatie Opening Hours

https://github.com/spatie/opening-hours
Admin
A helper to query and format a set of opening hours, allowing for regular schedules, exceptions, and...
Tokens:35,511
Snippets:454
Trust Score:10
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### nextOpen Usage Examples

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-openinghours.md

Examples demonstrating how to find the next opening time with and without a cap.

```php
$next = $hours->nextOpen(new DateTime('2024-12-24 12:00:00'));
// Returns DateTime for 2024-12-24 13:00:00

$next = $hours->nextOpen(
    new DateTime('2024-12-25 10:00:00'),
    cap: new DateTime('2024-12-31 23:59:59')
);
// Returns capped date if not found before cap
```

--------------------------------

### Example Code Placeholder

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/MANIFEST.md

A generic placeholder for method examples.

```php
// Example code
```

--------------------------------

### previousOpen Usage Example

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-openinghours.md

Example demonstrating how to find the previous opening time.

```php
$opened = $hours->previousOpen(new DateTime('2024-12-24 14:00:00'));
// Returns DateTime for 2024-12-24 13:00:00
```

--------------------------------

### nextClose Usage Example

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-openinghours.md

Example demonstrating how to find the next closing time.

```php
$closing = $hours->nextClose(new DateTime('2024-12-24 10:00:00'));
// Returns DateTime for 2024-12-24 12:00:00
```

--------------------------------

### Common daily schedule examples

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/configuration.md

Examples showing how to represent closed days, standard hours, and split shifts.

```php
'monday' => []                        // Closed all day
'monday' => ['09:00-17:00']          // Open 9am to 5pm
'monday' => ['09:00-12:00', '13:00-17:00']  // Open with lunch break
```

--------------------------------

### Install OpeningHours via Composer

Source: https://github.com/spatie/opening-hours/blob/master/README.md

Use this command to add the package to your project dependencies.

```bash
composer require spatie/opening-hours
```

--------------------------------

### Example of timezone conversion

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/configuration.md

Demonstrates how the library handles internal conversion between input and output timezones.

```php
// Business in Amsterdam, user in New York
$hours = OpeningHours::create([
    'monday' => ['09:00-17:00'],
    'timezone' => [
        'input' => 'Europe/Amsterdam',
        'output' => 'America/New_York',
    ]
]);

// From user in NY perspective:
$hours->nextOpen(new DateTime('2024-12-24 09:00:00', new DateTimeZone('America/New_York')));
// Internally converts to Amsterdam time, calculates, returns in NY time
```

--------------------------------

### Day::fromName Usage Examples

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/types.md

Demonstrates case-insensitive string conversion and error handling.

```php
Day::fromName('monday');        // Day::MONDAY
Day::fromName('TUESDAY');       // Day::TUESDAY
Day::fromName('invalid');       // Throws InvalidDayName
```

--------------------------------

### Usage Examples for asStructuredData

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-openinghours.md

Demonstrates generating structured data arrays and encoding them to JSON with optional timezone parameters.

```php
$structured = $hours->asStructuredData();
// Returns schema.org compatible array

echo json_encode($hours->asStructuredData('H:i', 'Europe/Amsterdam'));
```

--------------------------------

### Implement Nightclub Hours with Overflow

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/configuration.md

Example of creating an OpeningHours instance with overflow enabled to handle shifts that extend past midnight.

```php
// Nightclub hours
$hours = OpeningHours::create([
    'overflow' => true,
    'thursday' => ['21:00-04:00'],
    'friday' => ['21:00-04:00'],
    'saturday' => ['21:00-04:00'],
    'sunday' => [],
    'monday to wednesday' => [],
]);

// Check if open at 2am Saturday morning (from Friday night opening)
$hours->isOpenAt(new DateTime('2024-12-28 02:00:00')); // true
```

--------------------------------

### getDayLimit()

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-openinghours.md

Gets the current day limit.

```APIDOC
## getDayLimit()

### Description
Gets the current day limit.

### Return Type
`int`
```

--------------------------------

### Day::onDateTime Usage Example

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/types.md

Determines the day of the week for a specific date.

```php
Day::onDateTime(new DateTime('2024-12-24')); // Returns appropriate day
```

--------------------------------

### Retrieve Exceptions

Source: https://github.com/spatie/opening-hours/blob/master/README.md

Get an array of all defined exceptions keyed by date.

```php
$openingHours->exceptions();
```

--------------------------------

### Day::toISO Usage Examples

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/types.md

Converts enum cases to their corresponding ISO 8601 weekday numbers.

```php
Day::MONDAY->toISO();    // 1
Day::SUNDAY->toISO();    // 7
```

--------------------------------

### Initialize Opening Hours with Data

Source: https://github.com/spatie/opening-hours/blob/master/README.md

Create an instance with daily hours and associated metadata. Metadata can be accessed via forDay or forDate methods.

```php
$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
```

--------------------------------

### Initialize OpeningHours and Query Status

Source: https://github.com/spatie/opening-hours/blob/master/README.md

Create an instance with a weekly schedule and exceptions, then query the current status.

```php
// Add the use at the top of each file where you want to use the OpeningHours class:
use Spatie\OpeningHours\OpeningHours;

$openingHours = OpeningHours::create([
    'monday'     => ['09:00-12:00', '13:00-18:00'],
    'tuesday'    => ['09:00-12:00', '13:00-18:00'],
    'wednesday'  => ['09:00-12:00'],
    'thursday'   => ['09:00-12:00', '13:00-18:00'],
    'friday'     => ['09:00-12:00', '13:00-20:00'],
    'saturday'   => ['09:00-12:00', '13:00-16:00'],
    'sunday'     => [],
    'exceptions' => [
        '2016-11-11' => ['09:00-12:00'],
        '2016-12-25' => [],
        '01-01'      => [],                // Recurring on each 1st of January
        '12-25'      => ['09:00-12:00'],   // Recurring on each 25th of December
    ],
]);

// This will allow you to display things like:

$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";
}
```

--------------------------------

### Retrieve TimeRange start and end

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-value-objects.md

Methods to access the start and end times of a range.

```php
public function start(): Time
```

```php
public function end(): Time
```

--------------------------------

### Retrieve current open range start

Source: https://github.com/spatie/opening-hours/blob/master/README.md

Returns the start time of the current open range, accounting for night ranges.

```php
$date = $openingHours->currentOpenRangeStart(new DateTime('2016-12-24 11:00:00'));

if ($date) {
    echo "It's open since ".$date->format('H:i');
} else {
    echo "It's closed";
}
```

--------------------------------

### currentOpenRangeStart

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-openinghours.md

Returns the start of the current open range, or null if closed.

```APIDOC
## public function currentOpenRangeStart(DateTimeInterface $dateTime): ?DateTimeInterface

### Description
Returns the start of the current open range, or null if closed.

### Return Type
DateTimeInterface|null
```

--------------------------------

### Initialize OpeningHours

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/README.md

Create an instance of OpeningHours by passing an array of weekly schedules and exceptions.

```php
use Spatie\OpeningHours\OpeningHours;

$hours = OpeningHours::create([
    'monday to friday' => ['09:00-12:00', '13:00-18:00'],
    'saturday' => ['09:00-12:00', '13:00-16:00'],
    'sunday' => [],
    'exceptions' => [
        '2024-12-25' => [],  // Closed Christmas
        '12-25' => ['09:00-12:00'],  // Recurring Christmas
    ],
]);
```

--------------------------------

### Create Test Fixtures for OpeningHours

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/usage-patterns.md

Define helper functions to generate consistent OpeningHours instances for testing scenarios.

```php
function createAlwaysOpenHours() {
    return OpeningHours::create([
        'monday' => ['00:00-24:00'],
        'tuesday' => ['00:00-24:00'],
        'wednesday' => ['00:00-24:00'],
        'thursday' => ['00:00-24:00'],
        'friday' => ['00:00-24:00'],
        'saturday' => ['00:00-24:00'],
        'sunday' => ['00:00-24:00'],
    ]);
}

function createNormalHours() {
    return OpeningHours::create([
        'monday to friday' => ['09:00-17:00'],
        'saturday to sunday' => []
    ]);
}
```

--------------------------------

### Define Opening Hours Configuration Array

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/types.md

Structure for defining weekly schedules, exceptions, filters, and configuration options for OpeningHours::create().

```php
[
    // Day names (required, at least one)
    'monday' => [
        '09:00-12:00',              // Simple time range string
        '13:00-17:00',
        [                           // Array with hours and optional data
            'hours' => '19:00-21:00',
            'data' => 'Evening shift'
        ],
    ],
    'tuesday' => ['09:00-17:00'],   // Single range
    'wednesday' => [],               // Closed (empty array)
    'thursday to friday' => [        // Range of days with same hours
        '09:00-17:00'
    ],
    
    // Exceptions (optional)
    'exceptions' => [
        '2024-12-25' => [],                          // Specific date (closed)
        '12-25' => ['09:00-12:00'],                  // Recurring date (every Christmas)
        '2024-06-25 to 2024-07-01' => [],           // Date range (one year)
        '06-25 to 07-01' => ['10:00-14:00'],        // Recurring date range
        function ($date) {
            // Custom callable filter
            if ($date->format('N') === 5) {
                return []; // Custom logic
            }
        }
    ],
    
    // Filters (optional)
    'filters' => [
        function (DateTimeInterface $date) {
            if ($date->format('m-d') === '01-01') {
                return []; // Closed on New Year
            }
            // Return nothing to skip filter
        },
    ],
    
    // Configuration (optional)
    'overflow' => true,                     // Allow ranges that span midnight
    'data' => 'Custom business data',       // Any custom data
    'timezone' => 'Europe/Amsterdam',       // Input timezone
    'timezone' => [                         // Or separate input/output timezones
        'input' => 'America/New_York',
        'output' => 'Europe/Amsterdam'
    ],
    'dateTimeClass' => DateTime::class,     // Class for returned DateTime objects
]
```

--------------------------------

### Configure SaaS Support Hours

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/usage-patterns.md

Sets up support hours with timezone conversion and dynamic holiday filtering.

```php
$support = OpeningHours::create([
    'monday to friday' => ['08:00-18:00'],
    'saturday' => ['10:00-14:00'],
    'sunday' => [],
    'timezone' => [
        'input' => 'America/New_York',
        'output' => 'UTC'
    ],
    'filters' => [
        function (DateTimeInterface $date) {
            // Check against holiday list from database
            if (isUSHoliday($date)) {
                return [];
            }
        }
    ]
]);
```

--------------------------------

### Create TimeRange from Midnight

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-value-objects.md

Creates a range starting at 00:00 and ending at the provided Time object.

```php
public static function fromMidnight(Time $end, mixed $data = null): self
```

```php
$morning = TimeRange::fromMidnight(Time::fromString('06:00'));
// Result: 00:00-06:00
```

--------------------------------

### Display Documentation File Structure

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/MANIFEST.md

A visual representation of the documentation directory tree.

```text
/workspace/home/output/
├── README.md
├── api-openinghours.md
├── api-value-objects.md
├── types.md
├── configuration.md
├── errors.md
├── helpers-and-enums.md
├── usage-patterns.md
├── INDEX.txt
├── COMPLETENESS_REPORT.md
└── MANIFEST.md (this file)
```

--------------------------------

### OpeningHours::create() Configuration Array

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/types.md

The configuration array defines the weekly schedule, specific date exceptions, custom filters, and operational settings like timezones and midnight overflow.

```APIDOC
## OpeningHours::create() Configuration

### Description
Defines the operating hours, exceptions, and configuration settings for the OpeningHours instance.

### Parameters
- **monday-sunday** (array) - Optional - Defines hours for specific days of the week. Keys are case-sensitive.
- **exceptions** (array) - Optional - Defines special dates, recurring dates, or date ranges with custom hours or closures.
- **filters** (array) - Optional - Contains callable filters to determine closures based on custom logic.
- **overflow** (bool) - Optional - If true, allows time ranges that span across midnight.
- **data** (mixed) - Optional - Custom data associated with the schedule.
- **timezone** (string|DateTimeZone|array) - Optional - Configures the input and output timezones.
- **dateTimeClass** (class-string) - Optional - Specifies the class used for returned DateTime objects.
```

--------------------------------

### Configure timezones via constructor

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/configuration.md

Pass input and output timezones as arguments to the create method.

```php
OpeningHours::create(
    $data,                          // No timezone in data
    'America/New_York',             // Input timezone
    'Europe/Amsterdam'              // Output timezone
);
```

--------------------------------

### Get previous close time

Source: https://github.com/spatie/opening-hours/blob/master/README.md

Retrieves the previous closing time relative to a provided DateTime object.

```php
OpeningHours::previousClose(
    ?DateTimeInterface $dateTime = null,
    ?DateTimeInterface $searchUntil = null,
    ?DateTimeInterface $cap = null,
) : DateTimeInterface`
```

```php
$openingHours->nextClose(new DateTime('2016-12-24 11:00:00'));
```

--------------------------------

### Create OpeningHoursForDay instances

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-value-objects.md

Use the fromStrings factory method to initialize a day with time range strings or structured data arrays.

```php
$day = OpeningHoursForDay::fromStrings([
    '09:00-12:00',
    '13:00-17:00',
]);

// With data
$day = OpeningHoursForDay::fromStrings([
    'hours' => ['09:00-12:00', '13:00-17:00'],
    'data' => 'Normal day'
]);
```

--------------------------------

### Run tests with Composer

Source: https://github.com/spatie/opening-hours/blob/master/README.md

Execute the project's test suite using the Composer package manager.

```bash
composer test
```

--------------------------------

### Retrieve Current Open Range

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/usage-patterns.md

Fetch the current open time range object to access start and end times.

```php
$range = $hours->currentOpenRange(new DateTime());
if ($range) {
    echo "Open since " . $range->start();
    echo "Until " . $range->end();
} else {
    echo "Currently closed";
}
```

--------------------------------

### Retrieve Consecutive Days Schedule in PHP

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/usage-patterns.md

Get a schedule grouped by adjacent days that share the same hours, excluding wrap-around.

```php
// Adjacent days with same hours (no wrap-around)
$consecutive = $hours->forWeekConsecutiveDays();
```

--------------------------------

### OpeningHours::create

Source: https://github.com/spatie/opening-hours/blob/master/README.md

Static factory method to initialize the OpeningHours object with a schedule and optional timezone configurations.

```APIDOC
## OpeningHours::create(array $data, $timezone = null, $outputTimezone = null)

### Description
Creates an instance of OpeningHours. If no timezone is specified, it assumes input dates match the schedule timezone.

### Parameters
- **$data** (array) - Required - The schedule definition.
- **$timezone** (mixed) - Optional - Timezone for input/output conversion.
- **$outputTimezone** (mixed) - Optional - Specific output timezone.
```

--------------------------------

### Configure 24/7 Service

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/configuration.md

Sets up a service that is always open, with an optional check method.

```php
$always = OpeningHours::create([
    'monday' => ['00:00-24:00'],
    'tuesday' => ['00:00-24:00'],
    'wednesday' => ['00:00-24:00'],
    'thursday' => ['00:00-24:00'],
    'friday' => ['00:00-24:00'],
    'saturday' => ['00:00-24:00'],
    'sunday' => ['00:00-24:00'],
]);

// Or check with
if ($hours->isAlwaysOpen()) {
    // ...
}
```

--------------------------------

### OpeningHours::isOpen(): bool

Source: https://github.com/spatie/opening-hours/blob/master/README.md

Checks if the business is open right now.

```APIDOC
## OpeningHours::isOpen()

### Description
Checks if the business is open right now.

### Returns
- **bool** - True if open, false otherwise.
```

--------------------------------

### Query OpeningHours

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/README.md

Perform status checks, retrieve schedules, and calculate time differences using the initialized instance.

```php
// Status checks
$hours->isOpen();                    // Is currently open?
$hours->isOpenOn('monday');          // Open on Mondays?
$hours->isOpenAt(new DateTime());    // Open at specific time?

// Find next/previous times
$hours->nextOpen();                  // When do we open next?
$hours->nextClose();                 // When do we close next?
$hours->previousOpen();              // When did we open last?
$hours->previousClose();             // When did we close last?

// Get schedules
$hours->forWeek();                   // Full weekly schedule
$hours->forDay('monday');            // Schedule for one day
$hours->forDate(new DateTime());     // Schedule for specific date

// Time calculations
$hours->diffInOpenHours($start, $end);    // Open hours between times
$hours->diffInClosedHours($start, $end);  // Closed hours between times

// Current range
$range = $hours->currentOpenRange(new DateTime());
if ($range) {
    echo "Open since " . $range->start() . " until " . $range->end();
}
```

--------------------------------

### Handle SearchLimitReached Exception

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/errors.md

Demonstrates catching the SearchLimitReached exception or using the cap parameter to avoid it.

```php
try {
    $next = $hours->nextOpen(searchUntil: new DateTime('+60 days'));
} catch (SearchLimitReached $e) {
    // Try again with further limit
}
```

```php
$next = $hours->nextOpen(cap: new DateTime('+60 days'));
// Returns cap date if not found
```

```php
use Spatie\OpeningHours\Exceptions\SearchLimitReached;

try {
    $next = $hours->nextOpen(
        searchUntil: new DateTime('2024-12-31')
    );
} catch (SearchLimitReached $e) {
    echo "Search limit reached: " . $e->getMessage();
}
```

--------------------------------

### Work with ISO Weekdays

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/helpers-and-enums.md

Retrieve closing days as ISO integers where 1 represents Monday and 7 represents Sunday.

```php
$isoDays = $hours->regularClosingDaysISO();
// Returns: [7] if Sunday is closed

foreach ($isoDays as $isoDay) {
    // 1 = Monday, 7 = Sunday
    echo "Closed on ISO day $isoDay" . PHP_EOL;
}
```

--------------------------------

### Configure daily opening hours

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/configuration.md

Define time ranges for a specific day using simple strings or arrays with associated data.

```php
'monday' => [
    '09:00-12:00',                    // Simple time range
    '13:00-17:00',                    // Multiple ranges per day
    [
        'hours' => '19:00-21:00',     // With associated data
        'data' => 'Evening shift'
    ]
]
```

--------------------------------

### nextOpen

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-openinghours.md

Returns the next date and time when the business opens.

```APIDOC
## nextOpen

### Description
Returns the next date and time when the business opens.

### Signature
`public function nextOpen(?DateTimeInterface $dateTime = null, ?DateTimeInterface $searchUntil = null, ?DateTimeInterface $cap = null): DateTimeInterface`

### Parameters
- **$dateTime** (DateTimeInterface|null) - Optional - Start time for search (current time if null)
- **$searchUntil** (DateTimeInterface|null) - Optional - Throw exception if not found before this date
- **$cap** (DateTimeInterface|null) - Optional - Return this date if not found before it (instead of throwing)

### Returns
- **DateTimeInterface** - The next opening time.

### Throws
- **MaximumLimitExceeded** - If not found within day limit and no cap provided.
- **SearchLimitReached** - If searchUntil is specified and exceeded.
```

--------------------------------

### Scheduling method parameter signature

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/README.md

Standard signature for scheduling methods like nextOpen, showing optional parameters for date-time, search limits, and caps.

```php
$hours->nextOpen(
    ?DateTimeInterface $dateTime = null,        // Default: now
    ?DateTimeInterface $searchUntil = null,     // Default: search up to day limit
    ?DateTimeInterface $cap = null              // Default: throw if not found
): DateTimeInterface
```

--------------------------------

### Manage MaximumLimitExceeded Scenarios

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/errors.md

Workarounds and error handling for when search operations exceed the default day limit.

```php
$hours->setDayLimit(30);
$next = $hours->nextOpen();
```

```php
$next = $hours->nextOpen(
    $dateTime,
    cap: new DateTime('2024-12-31')
);
```

```php
try {
    $next = $hours->nextOpen(
        $dateTime,
        searchUntil: new DateTime('2024-12-31')
    );
} catch (SearchLimitReached $e) {
    // Caught at specific date instead
}
```

```php
if (!$hours->isAlwaysClosed()) {
    $next = $hours->nextOpen();
}
```

```php
use Spatie\OpeningHours\Exceptions\MaximumLimitExceeded;

try {
    $next = $hours->nextOpen();
} catch (MaximumLimitExceeded $e) {
    echo "No open time found within limit: " . $e->getMessage();
}
```

--------------------------------

### Handle specific configuration exceptions

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/usage-patterns.md

Catch granular exceptions like OverlappingTimeRanges, InvalidDayName, or InvalidTimeString when creating an instance.

```php
use Spatie\OpeningHours\Exceptions\{
    InvalidTimeString,
    OverlappingTimeRanges,
    InvalidDayName,
};

try {
    $hours = OpeningHours::create($config);
} catch (OverlappingTimeRanges $e) {
    echo "Ranges overlap: " . $e->getMessage();
} catch (InvalidDayName $e) {
    echo "Invalid day: " . $e->getMessage();
} catch (InvalidTimeString $e) {
    echo "Invalid time: " . $e->getMessage();
}
```

--------------------------------

### nextOpen Method Definition

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-openinghours.md

Method signature for finding the next opening time.

```php
public function nextOpen(
    ?DateTimeInterface $dateTime = null,
    ?DateTimeInterface $searchUntil = null,
    ?DateTimeInterface $cap = null,
): DateTimeInterface
```

--------------------------------

### Retrieve Weekly Schedule in PHP

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/usage-patterns.md

Iterate through the full weekly schedule to display opening hours for each day.

```php
$week = $hours->forWeek();
foreach ($week as $day => $schedule) {
    echo ucfirst($day) . ': ' . $schedule . PHP_EOL;
}

// Output:
// Monday: 09:00-12:00,13:00-18:00
// Tuesday: 09:00-12:00,13:00-18:00
// ...
```

--------------------------------

### Configuring with Custom Data

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/usage-patterns.md

Attach metadata to specific days or the entire schedule for retrieval during queries.

```php
$hours = OpeningHours::create([
    'monday' => [
        'hours' => ['09:00-17:00'],
        'data' => 'Main office'
    ],
    'friday' => [
        'hours' => ['09:00-12:00', '13:00-20:00'],
        'data' => 'Late night Friday'
    ],
    'data' => 'Business metadata'
]);

// Access
$mondayData = $hours->forDay('monday')->data; // 'Main office'
$businessData = $hours->data; // 'Business metadata'
```

--------------------------------

### Define Method Documentation Format

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/MANIFEST.md

Template for documenting class methods including signature, parameters, return types, and exceptions.

```markdown
### methodName

```php
public function methodName(
    param1Type $param1,
    param2Type $param2 = default
): ReturnType
```

**Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| $param1 | type | Yes | — | Description |
| $param2 | type | No | default | Description |

**Return type:** `Type`

**Throws:** `ExceptionType` - when/why

**Examples:**

```php
// Example code
```
```

--------------------------------

### Format Time as String

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-value-objects.md

Demonstrates formatting a Time object using various PHP date format strings.

```php
$time = Time::fromString('14:30');
$time->format();           // "14:30"
$time->format('H:i:s');    // "14:30:00"
$time->format('h:i a');    // "02:30 pm"
```

--------------------------------

### Day Enum Usage in Methods

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/types.md

Demonstrates that methods accepting day names also accept Day enum cases.

```php
$hours->forDay('monday');           // Works
$hours->forDay(Day::MONDAY);        // Also works
```

--------------------------------

### Time Comparison Methods

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-value-objects.md

Methods for comparing two Time instances or calculating the interval between them.

```php
public function isSame(self $time): bool
```

```php
public function isAfter(self $time): bool
```

```php
public function isBefore(self $time): bool
```

```php
public function isSameOrAfter(self $time): bool
```

```php
public function isSameOrBefore(self $time): bool
```

```php
public function diff(self $time): DateInterval
```

```php
$morning = Time::fromString('09:00');
$evening = Time::fromString('17:00');
$diff = $morning->diff($evening);
echo $diff->h; // 8
```

--------------------------------

### Create from Schema.org JSON

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/usage-patterns.md

Instantiate OpeningHours directly from a JSON string containing OpeningHoursSpecification objects.

```php
$json = '[
    {
        "@type": "OpeningHoursSpecification",
        "opens": "08:00",
        "closes": "12:00",
        "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]
    },
    {
        "@type": "OpeningHoursSpecification",
        "opens": "14:00",
        "closes": "18:00",
        "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]
    }
]';

$hours = OpeningHours::createFromStructuredData($json);
```

--------------------------------

### Implement Dynamic Filters

Source: https://github.com/spatie/opening-hours/blob/master/README.md

Use closures to define dynamic opening hours based on specific dates. Note that excessive use of complex filters can impact performance.

```php
$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
                // Any valid exception-array can be returned here (range of hours, with or without data)
            }
            // Else the filter does not apply to the given date
        },
    ],
]);
```

--------------------------------

### OpeningHours::asStructuredData

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/README.md

Exports the current opening hours configuration to schema.org format.

```APIDOC
## OpeningHours::asStructuredData

### Description
Exports the opening hours configuration to a format compatible with schema.org/OpeningHoursSpecification.

### Returns
- **array** - The structured data representation.

### Example
```php
$structured = $hours->asStructuredData();
echo json_encode($structured);
```
```

--------------------------------

### Create TimeRange from Definition

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-value-objects.md

Accepts either a string or an array to create a TimeRange instance.

```php
public static function fromDefinition(mixed $value): self
```

--------------------------------

### Configuring with Filters

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/usage-patterns.md

Apply custom logic to override schedules based on specific dates, such as holidays or seasonal changes.

```php
$hours = OpeningHours::create([
    'monday to friday' => ['09:00-17:00'],
    'saturday' => ['10:00-14:00'],
    'sunday' => [],
    'filters' => [
        function (DateTimeInterface $date) {
            // Public holidays (example)
            $holidays = ['2024-12-25', '2024-12-26'];
            if (in_array($date->format('Y-m-d'), $holidays)) {
                return []; // Closed
            }
        },
        function (DateTimeInterface $date) {
            // Summer hours (July-August)
            if (in_array($date->format('m'), ['07', '08'])) {
                return ['08:00-18:00']; // Extended
            }
        }
    ]
]);
```

--------------------------------

### Test Status Methods

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/usage-patterns.md

Validate opening status using day-based queries and specific DateTime objects.

```php
$hours = createNormalHours();

// Test queries
assert($hours->isOpenOn('monday'));
assert(!$hours->isOpenOn('sunday'));
assert(!$hours->isClosedOn('monday'));

// Test date checks
$monday = new DateTime('2024-12-23'); // Monday
assert($hours->isOpenAt($monday->setTime(10, 0, 0)));
assert(!$hours->isOpenAt($monday->setTime(8, 0, 0)));
```

--------------------------------

### isOpen

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-openinghours.md

Checks if the business is open right now.

```APIDOC
## isOpen()

### Description
Checks if the business is open right now.

### Return
- **bool** - True if open, false otherwise
```

--------------------------------

### Configure Single Timezone

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/usage-patterns.md

Set a single timezone for the opening hours instance.

```php
$hours = OpeningHours::create([
    'monday to friday' => ['09:00-17:00'],
    'timezone' => 'Europe/Amsterdam'
]);
```

--------------------------------

### forDate

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-openinghours.md

Returns opening hours for a specific date, considering exceptions.

```APIDOC
## public function forDate(DateTimeInterface $date)

### Description
Returns opening hours for a specific date, considering exceptions.

### Parameters
- **$date** (DateTimeInterface) - Required - The date to query

### Return Type
OpeningHoursForDay
```

--------------------------------

### Validate Input Before Creation

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/errors.md

Use the isValid method to check configuration data before attempting to instantiate the OpeningHours object.

```php
use Spatie\OpeningHours\OpeningHours;

if (OpeningHours::isValid($userInput)) {
    $hours = OpeningHours::create($userInput);
} else {
    echo "Invalid opening hours configuration";
}
```

--------------------------------

### Configure day ranges

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/configuration.md

Use 'to' or '-' separators to apply the same hours to multiple consecutive days.

```php
$data = [
    'monday to friday' => ['09:00-17:00'],
    'saturday' => ['09:00-13:00'],
    'sunday' => [],
]
```

--------------------------------

### Embed in Schema.org JSON-LD

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/usage-patterns.md

Integrate opening hours into a full LocalBusiness Schema.org JSON-LD structure.

```php
$hours = OpeningHours::create([...]);

// Get structured data for website
$structured = $hours->asStructuredData();

// Embed in HTML
echo json_encode([
    '@context' => 'https://schema.org',
    '@type' => 'LocalBusiness',
    'name' => 'My Business',
    'openingHoursSpecification' => $structured
], JSON_PRETTY_PRINT);
```

--------------------------------

### Accessing OpeningHoursForDay via Array Interfaces

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/README.md

Demonstrates counting, indexing, iterating, and checking existence of time ranges within a day. Note that these objects are immutable and will throw an exception if modification is attempted.

```php
$day = $hours->forDay('monday');

// Count ranges
count($day);                    // 2

// Access by index
$firstRange = $day[0];         // TimeRange
$secondRange = $day[1];        // TimeRange

// Iterate
foreach ($day as $range) {
    echo $range;               // "09:00-12:00", etc.
}

// Check existence
isset($day[0]);                 // true
isset($day[5]);                 // false

// Cannot modify (immutable)
$day[0] = $newRange;           // Throws NonMutableOffsets
```

--------------------------------

### Create OpeningHours from structured data

Source: https://github.com/spatie/opening-hours/blob/master/README.md

Initializes an OpeningHours instance using a JSON string or array following the schema.org OpeningHoursSpecification format.

```php
$openingHours = OpeningHours::createFromStructuredData('[
    {
        "@type": "OpeningHoursSpecification",
        "opens": "08:00",
        "closes": "12:00",
        "dayOfWeek": [
            "https://schema.org/Monday",
            "https://schema.org/Tuesday",
            "https://schema.org/Wednesday",
            "https://schema.org/Thursday",
            "https://schema.org/Friday"
        ]
    },
    {
        "@type": "OpeningHoursSpecification",
        "opens": "14:00",
        "closes": "18:00",
        "dayOfWeek": [
            "Monday",
            "Tuesday",
            "Wednesday",
            "Thursday",
            "Friday"
        ]
    },
    {
        "@type": "OpeningHoursSpecification",
        "opens": "00:00",
        "closes": "00:00",
        "validFrom": "2023-12-25",
        "validThrough": "2023-12-25"
    }
]');
```

--------------------------------

### Configure custom data

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/configuration.md

Define custom data for an OpeningHours instance using strings, arrays, or objects.

```php
'data' => 'My Business Name',

// Or complex data
'data' => [
    'name' => 'My Business',
    'address' => '123 Main St',
    'phone' => '+1-555-0123',
],

// Or even objects
'data' => new BusinessInfo(...),
```

--------------------------------

### Group Weekly Schedule by Hours in PHP

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/usage-patterns.md

Combine days that share identical opening hours into a single entry.

```php
// Days with same hours grouped together
$combined = $hours->forWeekCombined();
foreach ($combined as $firstDay => $data) {
    $days = implode(', ', $data['days']);
    echo "$days: " . $data['opening_hours'] . PHP_EOL;
}

// Output might be:
// monday, tuesday, thursday: 09:00-12:00,13:00-18:00
// wednesday: 09:00-12:00
// ...
```

--------------------------------

### Retrieve Custom Data

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/helpers-and-enums.md

Attach arbitrary data to time ranges during initialization and access it via the forDay method.

```php
$hours = OpeningHours::create([
    'monday' => [
        'hours' => ['09:00-12:00', '13:00-17:00'],
        'data' => ['location' => 'Main office', 'manager' => 'John']
    ]
]);

$mondayData = $hours->forDay('monday')->data;
// Result: ['location' => 'Main office', 'manager' => 'John']
```

--------------------------------

### Configure Timezones

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/configuration.md

Updates the input or output timezone settings for an existing OpeningHours instance.

```php
$hours->setTimezone('Europe/Amsterdam');
$hours->setOutputTimezone('America/New_York');
```

--------------------------------

### Integrating with Schema.org OpeningHoursSpecification

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/README.md

Provides methods to create an OpeningHours instance from structured data and export existing hours into the Schema.org format.

```php
// Create from schema.org data
$hours = OpeningHours::createFromStructuredData($jsonOrArray);

// Export to schema.org format
$structured = $hours->asStructuredData();
echo json_encode($structured);
```

--------------------------------

### OpeningHours::create

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-openinghours.md

Creates an OpeningHours instance from an associative array definition.

```APIDOC
## OpeningHours::create

### Description
Creates an OpeningHours instance from an associative array definition.

### Signature
`public static function create(array $data, string|DateTimeZone|null $timezone = null, string|DateTimeZone|null $outputTimezone = null): self`

### Parameters
- **$data** (array) - Required - Array defining opening hours with keys for day names, exceptions, filters, etc.
- **$timezone** (string|DateTimeZone|null) - Optional - Input timezone.
- **$outputTimezone** (string|DateTimeZone|null) - Optional - Output timezone.

### Returns
- **OpeningHours** - The created instance.

### Throws
- `InvalidDateRange`, `OverlappingTimeRanges`, `InvalidTimezone`
```

--------------------------------

### Access instance data

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/configuration.md

Retrieve custom data directly from the OpeningHours instance property.

```php
$hours = OpeningHours::create([
    'monday' => ['09:00-17:00'],
    'data' => 'My Business'
]);

echo $hours->data; // "My Business"
```

--------------------------------

### diffInOpenMinutes

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-openinghours.md

Calculates open minutes between two dates/times.

```APIDOC
## public function diffInOpenMinutes(DateTimeInterface $startDate, DateTimeInterface $endDate): float

### Description
Calculates open minutes between two dates/times.

### Return Type
float (minutes)
```

--------------------------------

### Schedule with safety caps

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/usage-patterns.md

Prevent MaximumLimitExceeded exceptions by providing a cap parameter to scheduling methods.

```php
try {
    $next = $hours->nextOpen(
        cap: new DateTime('+30 days')
    );
} catch (\Spatie\OpeningHours\Exceptions\MaximumLimitExceeded $e) {
    // Won't happen because of cap
}
```

--------------------------------

### Configure day-level data

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/configuration.md

Assign specific data to individual days or exceptions within the configuration array.

```php
'monday' => [
    'hours' => ['09:00-17:00'],
    'data' => 'Monday hours'
],
'exceptions' => [
    '2024-12-25' => [
        'hours' => ['10:00-14:00'],
        'data' => 'Christmas schedule'
    ]
]
```

--------------------------------

### Export OpeningHours as structured data

Source: https://github.com/spatie/opening-hours/blob/master/README.md

Converts the current instance into an array compatible with schema.org specifications, supporting custom time formats and timezones.

```php
$openingHours->asStructuredData();
$openingHours->asStructuredData('H:i:s'); // Customize time format, could be 'h:i a', 'G:i', etc.
$openingHours->asStructuredData('H:iP', '-05:00'); // Add a timezone
// Timezone can be numeric or string like "America/Toronto" or a DateTimeZone instance
// But be careful, the time is arbitrary applied on 1970-01-01, so it does not handle daylight
// saving time, meaning Europe/Paris is always +01:00 even in summer time.
```

--------------------------------

### Validate opening hours configuration

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-openinghours.md

Check if an array is valid for creating an OpeningHours instance before initialization.

```php
if (OpeningHours::isValid($userInput)) {
    $hours = OpeningHours::create($userInput);
} else {
    echo "Invalid opening hours configuration";
}
```

--------------------------------

### Find Next Opening Time

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/usage-patterns.md

Determine the next opening time, optionally providing a reference time, a safety cap, or handling search limits.

```php
// When do we open next?
$nextOpen = $hours->nextOpen();

// When do we open after a specific time?
$nextOpen = $hours->nextOpen(new DateTime('2024-12-24 12:00:00'));

// With a safety limit (max 30 days)
$nextOpen = $hours->nextOpen(
    cap: new DateTime('+30 days')
);

// Or throw if not found within limit
try {
    $nextOpen = $hours->nextOpen(
        searchUntil: new DateTime('+14 days')
    );
} catch (\Spatie\OpeningHours\Exceptions\SearchLimitReached $e) {
    echo "Not opening within 2 weeks";
}
```

--------------------------------

### isOpenAt

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-openinghours.md

Checks if the business is open at a specific date and time.

```APIDOC
## isOpenAt(DateTimeInterface $dateTime)

### Description
Checks if the business is open at a specific date and time.

### Parameters
- **$dateTime** (DateTimeInterface) - Required - DateTime to check

### Return
- **bool** - True if open, false otherwise
```

--------------------------------

### OpeningHours::nextOpen

Source: https://github.com/spatie/opening-hours/blob/master/README.md

Returns the next open DateTime.

```APIDOC
## OpeningHours::nextOpen(?DateTimeInterface $dateTime, ?DateTimeInterface $searchUntil, ?DateTimeInterface $cap)

### Description
Returns the next open DateTime from the given DateTime. If no DateTime is provided, it defaults to now.

### Parameters
- **$dateTime** (DateTimeInterface) - Optional - The starting point for the search.
- **$searchUntil** (DateTimeInterface) - Optional - A date to throw an exception if no open time is found before this moment.
- **$cap** (DateTimeInterface) - Optional - A date to return if no open time is found before this moment.

### Returns
- **DateTimeInterface** - The next open date and time.
```

--------------------------------

### map(callable $callback)

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-openinghours.md

Maps over regular opening hours days.

```APIDOC
## map(callable $callback)

### Description
Maps over regular opening hours days.

### Parameters
- **$callback** (callable) - Required - Callback receiving (OpeningHoursForDay, string dayName)

### Return Type
array
```

--------------------------------

### previousOpen Method Definition

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-openinghours.md

Method signature for finding the previous opening time.

```php
public function previousOpen(
    DateTimeInterface $dateTime,
    ?DateTimeInterface $searchUntil = null,
    ?DateTimeInterface $cap = null,
): DateTimeInterface
```

--------------------------------

### OpeningHours::isOpenOn(string $day): bool

Source: https://github.com/spatie/opening-hours/blob/master/README.md

Checks if the business is open on a specific day or date.

```APIDOC
## OpeningHours::isOpenOn(string $day)

### Description
Checks if the business is open on a day in the regular schedule. If a date string is provided, it checks if the business is open considering both regular schedules and exceptions.

### Parameters
- **$day** (string) - Required - The day name (e.g., 'saturday') or a date string (e.g., '2020-09-03').

### Returns
- **bool** - True if open, false otherwise.
```

--------------------------------

### Handle NonMutableOffsets Exception

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/errors.md

Illustrates the immutability of OpeningHoursForDay objects and how to catch the resulting exception.

```php
$day = OpeningHoursForDay::fromStrings(['09:00-17:00']);
$range = $day[0]; // ✓ Reading is OK

// Invalid:
$day[0] = TimeRange::fromString('10:00-18:00'); // ✗ Throws
unset($day[0]); // ✗ Throws
```

```php
use Spatie\OpeningHours\Exceptions\NonMutableOffsets;

try {
    $day[0] = $newRange;
} catch (NonMutableOffsets $e) {
    echo "Cannot modify opening hours day";
}
```

--------------------------------

### Configure 24/7 Service with Maintenance

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/usage-patterns.md

Configures a service that is generally open 24/7 but includes specific maintenance windows.

```php
$service = OpeningHours::create([
    'overflow' => true,
    'monday' => ['00:00-22:00'],  // Down for maintenance 10pm-midnight
    'tuesday' => ['00:00-24:00'],
    'wednesday' => ['00:00-24:00'],
    'thursday' => ['00:00-24:00'],
    'friday' => ['00:00-24:00'],
    'saturday' => ['00:00-24:00'],
    'sunday' => ['00:00-22:00'],
]);
```

--------------------------------

### Configure DateTime Class

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/configuration.md

Specifies the class used for returned DateTime objects. Ensure the chosen class implements DateTimeInterface.

```php
'dateTimeClass' => DateTimeImmutable::class,

// Now methods return DateTimeImmutable instead of DateTime
$next = $hours->nextOpen(); // DateTimeImmutable instance
```

--------------------------------

### OpeningHours::forWeek

Source: https://github.com/spatie/opening-hours/blob/master/README.md

Retrieves the schedule for a full week.

```APIDOC
## OpeningHours::forWeek()

### Description
Returns an array of OpeningHoursForDay objects representing the regular weekly schedule.
```

--------------------------------

### Check all regular opening hours

Source: https://github.com/spatie/opening-hours/blob/master/_autodocs/api-openinghours.md

Verifies if every regular opening hour day satisfies the provided condition.

```php
$allOpen = $hours->every(fn($day) => !$day->isEmpty());
```
Tokens:
Raw