Querying

Calendar resolution begins with:

$query = $calendar->query();

Queries do not modify the underlying calendar definition.

Single Date

$day = $calendar
    ->query()
    ->on('2026-10-05');

Returns a Day.

Week

$week = $calendar
    ->query()
    ->weekOf('2026-10-07');

weekOf() returns the ISO week containing the date:

Monday → Sunday

Range

$range = $calendar
    ->query()
    ->between(
        '2026-10-01',
        '2026-10-31'
    );

Ranges are inclusive.

Filtering by Status

open closed full day_off holiday

$result = $calendar
    ->query()
    ->status('open')
    ->between($from, $to);

Multiple statuses may be provided:

$result = $calendar
    ->query()
    ->status('open', 'full')
    ->between($from, $to);

Day Statuses

Each resolved day has one of the following statuses:

Status	Meaning
`open`	The day has at least one available slot.
`closed`	No availability schedule applies to the day.
`full`	Availability exists, but all generated slots are busy.
`day_off`	The day was explicitly marked as a day off.
`holiday`	The day was explicitly marked as a holiday.

The main distinction between closed and full is that a closed day has no applicable availability, while a full day has availability but no remaining available slots.

Available Days

$result = $calendar
    ->query()
    ->available()
    ->between($from, $to);

available() keeps only days containing at least one available slot.

Available Slots

$result = $calendar
    ->query()
    ->availableSlots()
    ->between($from, $to);

This removes busy slots from returned Day objects.

It does not recalculate the original status of the day.

Selecting Fields

$result = $calendar
    ->query()
    ->select('date', 'status')
    ->between($from, $to);

The following fields can be selected:

Day
├── date               string   "2026-10-05"
├── weekday            int      1
├── available          bool     true
├── status             string   "open"
└── slots              array
    ├── [0]
    │   ├── start      string   "09:00"
    │   ├── end        string   "10:00"
    │   ├── available  bool     true
    │   └── status     string   "available"
    │
    └── [1]
        ├── start      string   "10:00"
        ├── end        string   "11:00"
        ├── available  bool     false
        └── status     string   "busy"

For example, without field selection, a serialized day may look like:

{
  "date": "2026-10-05",
  "weekday": 1,
  "available": true,
  "status": "open",
  "slots": [
    {
      "start": "09:00",
      "end": "10:00",
      "available": true,
      "status": "available"
    },
    {
      "start": "10:00",
      "end": "11:00",
      "available": false,
      "status": "busy"
    }
  ]
}

Using select() limits the serialized representation:

$day = $calendar
    ->query()
    ->select('date', 'status')
    ->on('2026-10-05');

$day->toArray();

{
  "date": "2026-10-05",
  "status": "open"
}

Note

select() controls serialization only. It does not remove information from the Day object.

$day = $calendar
    ->query()
    ->select('status')
    ->on('2026-10-05');

$day->toArray();

// ['status' => 'open']

$day->date();
$day->slots();
$day->available();

All domain methods remain available.

Combining Filters

Query operations can be combined:

$result = $calendar
    ->query()
    ->status('open')
    ->availableSlots()
    ->select('date', 'slots')
    ->between(
        '2026-10-05',
        '2026-10-12'
    );

This means:

keep open days;
remove busy slots;
serialize only the date and slots;
resolve the requested range.