Availability windows were stored and served as a single bookable row, so a
9:00 AM-4:00 PM window showed to students as one giant slot and booking it
consumed the whole day; past and multi-day windows also leaked into the
booking page as nonsense entries.

- Split windows into consecutive lesson-length slots on save (REST and admin
  form); each chunk is independently bookable and weekly recurrence creates a
  series per chunk so "reserve this time weekly" holds the same hour each week
- Reject windows spanning multiple days or shorter than the lesson length
  (400 invalid_window)
- Never return slots whose start has passed from GET /availability
- Migrate pre-split rows: Plugin::boot re-runs the Installer on version change
  and AvailabilityRepository::splitOversizedWindows() rewrites unbooked
  same-day oversized windows in place
- Display all times in 12-hour AM/PM form (booking page, wp-admin lists,
  editor previews)
- Add a List | Week view toggle to the student booking page and the
  instructor availability page, with previous/next-week navigation honouring
  the site's start_of_week option (new WeekCalendar helper)

Co-Authored-By: Claude Fable 5 <[email protected]>

2026-07-05 16:00:47 -03:00

5.2 KiB

Raw Blame History

Feature: Availability Management

Overview

Instructors define same-day date/time windows during which they are available for private lessons. On save, a window is split into consecutive lesson-length slots (09:00–16:00 with 60-minute lessons becomes seven rows), each independently bookable by students. Windows may be generated as a weekly-recurring series.

Data Model — `{prefix}us_availability`

Column	Type	Notes
`id`	BIGINT UNSIGNED	Primary key
`instructor_id`	BIGINT UNSIGNED	WordPress user ID
`offering_id`	BIGINT UNSIGNED	Nullable FK → `us_offerings.id` (private-lesson type)
`start_dt`	DATETIME	Slot start — stored as `Y-m-d H:i:s`
`end_dt`	DATETIME	Slot end — always `start_dt + duration_minutes`
`duration_minutes`	SMALLINT	Lesson length (e.g. 30, 60)
`is_booked`	TINYINT(1)	0 = available, 1 = booked
`recurrence_group`	BIGINT UNSIGNED	Nullable — weekly-recurring windows share one group id
`created_at`	DATETIME	Insertion time

A slot's duration_minutes is matched against the offering a student picks: a 30-minute private offering can only be booked into a slot whose duration_minutes accommodates it.

Window Splitting

AvailabilitySlot::splitByDuration() chunks a submitted window into consecutive duration_minutes slots; AvailabilityRepository::createFromWindow() persists one row per chunk. A trailing remainder shorter than the lesson length is dropped. Windows must start and end on the same day and fit at least one lesson (REST responds 400 invalid_window otherwise; the admin form is a no-op). AvailabilityRepository::splitOversizedWindows() is a data migration (run by Installer on activation or version change) that rewrites pre-split rows.

Weekly-Recurring Windows

Instructors may generate a window weekly across a date range. Each lesson-length chunk becomes its own weekly series: occurrences of the same time-of-day share one recurrence_group id, so a recurring set can be added or removed together while individual occurrences are still booked independently.

Admin Interface

Instructors access My Availability in wp-admin (?page=us-availability).

Add availability: provide a same-day start/end window, lesson length, and (optionally) a linked private-lesson offering
Add a weekly series: tick weekly repeat and choose the number of weeks
Delete a slot: only allowed if is_booked = 0
Current slots can be shown as a list or a weekly calendar (usc_view=week, navigated with usc_week=Y-m-d); the grid honours the site's start_of_week option via Availability\WeekCalendar

Public Calendar

The front-end booking shortcode renders open slots from GET /availability either as an agenda-style list grouped by day or as a weekly calendar with previous/next-week navigation (toggle rendered by assets/js/booking.js; the site's start_of_week option is passed through the usScheduler JS config).

REST API

Method	Endpoint	Permission
`GET`	`/wp-json/us-scheduler/v1/availability`	`book_lesson`
`POST`	`/wp-json/us-scheduler/v1/availability`	`manage_availability`
`DELETE`	`/wp-json/us-scheduler/v1/availability/{id}`	`manage_availability` + slot owner

GET supports query params: instructor_id, offering_id, duration_minutes, from (datetime), to (datetime). Slots whose start has already passed are never returned.

POST validates start_dt/end_dt (admin form and REST alike) via AvailabilitySlot::normalizeDateTime(): the canonical Y-m-d H:i[:s] and HTML datetime-local (Y-m-d\TH:i[:s]) forms are normalised to Y-m-d H:i:s; anything else — or an end not after the start — is rejected (REST responds 400 invalid_datetime; the admin form is a no-op). A valid window is stored as lesson-length slots and 201 returns { "ids": [...] } for every row created.

Times are displayed in 12-hour AM/PM form in the booking calendar and wp-admin lists.

Implementation

Repository: Unsupervised\Schedular\Availability\AvailabilityRepository
Model: Unsupervised\Schedular\Availability\AvailabilitySlot
Week bucketing: Unsupervised\Schedular\Availability\WeekCalendar
Admin controller: Unsupervised\Schedular\Availability\AvailabilityController
REST endpoint: Unsupervised\Schedular\Availability\AvailabilityEndpoint

Tests

tests/Unit/Availability/AvailabilityRepositoryTest.php
tests/Unit/Availability/AvailabilitySlotTest.php
tests/Unit/Availability/AvailabilityEndpointTest.php
tests/Unit/Availability/WeekCalendarTest.php

5.2 KiB Raw Blame History Unescape Escape