Unsupervised/unsupervised-scheduler
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add lesson booking registration flow (offering, questions, policies) #20

Merged
thatguygriff merged 1 commits from feature/registration-flow into main 2026-06-07 14:30:01 +00:00
Conversation 0 Commits 1 Files Changed 15
+649 -68
15 changed files with 649 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files
assets/js/booking.js
+106 -17
View File
@@ -30,14 +30,21 @@
errorBox.style.display = 'block'; errorBox.style.display = 'block';
} }
function dayKey(dt) { function clearError() {
return String(dt).slice(0, 10); errorBox.style.display = 'none';
} }
function timeOf(dt) { function escHtml(str) {
return String(dt).slice(11, 16); return String(str)
.replace(/&/g, '&')
.replace(/</g, '&lt;')
.replace(/>/g, '&gt;')
.replace(/"/g, '&quot;');
} }
const dayKey = (dt) => String(dt).slice(0, 10);
const timeOf = (dt) => String(dt).slice(11, 16);
function dayLabel(key) { function dayLabel(key) {
const date = new Date(key + 'T00:00:00'); const date = new Date(key + 'T00:00:00');
if (Number.isNaN(date.getTime())) return key; if (Number.isNaN(date.getTime())) return key;
@@ -56,9 +63,7 @@
return [...groups.entries()].sort((a, b) => a[0].localeCompare(b[0])); return [...groups.entries()].sort((a, b) => a[0].localeCompare(b[0]));
} }
// Agenda-style calendar: available slots grouped by day. The richer booking // Agenda-style calendar: available slots grouped by day.
// UX (offering selection, intake questions, policy acceptance) lands with the
// booking-flow work.
function renderSlots(slots) { function renderSlots(slots) {
if (!slots.length) { if (!slots.length) {
slotList.innerHTML = '<p>No available lesson slots at this time.</p>'; slotList.innerHTML = '<p>No available lesson slots at this time.</p>';
@@ -78,24 +83,101 @@
`).join(''); `).join('');
slotList.querySelectorAll('.us-book-btn').forEach((btn) => { slotList.querySelectorAll('.us-book-btn').forEach((btn) => {
btn.addEventListener('click', () => bookSlot(Number(btn.dataset.slotId))); const slot = slots.find((s) => String(s.id) === btn.dataset.slotId);
btn.addEventListener('click', () => openRegistration(slot));
}); });
} }
function escHtml(str) { function questionField(q) {
return String(str) const name = `q_${q.id}`;
.replace(/&/g, '&amp;') const required = q.is_required ? 'required' : '';
.replace(/</g, '&lt;') let input;
.replace(/>/g, '&gt;') if (q.field_type === 'textarea') {
.replace(/"/g, '&quot;'); input = `<textarea name="${name}" ${required}></textarea>`;
} else if (q.field_type === 'select') {
const opts = (q.options || []).map((o) => `<option value="${escHtml(o)}">${escHtml(o)}</option>`).join('');
input = `<select name="${name}" ${required}><option value="">—</option>${opts}</select>`;
} else if (q.field_type === 'checkbox') {
input = `<input type="checkbox" name="${name}" value="1">`;
} else {
input = `<input type="text" name="${name}" ${required}>`;
}
return `<p class="us-question"><label>${escHtml(q.label)}<br>${input}</label></p>`;
} }
function bookSlot(slotId) { function policyField(p) {
errorBox.style.display = 'none'; return `
<div class="us-policy">
<h4>${escHtml(p.title)}</h4>
<div class="us-policy-body">${p.body || ''}</div>
<label><input type="checkbox" class="us-policy-accept" value="${p.policy_version_id}" required> I have read and agree to the ${escHtml(p.title)}.</label>
</div>`;
}
function openRegistration(slot) {
clearError();
const offeringId = Number(slot.offering_id) || 0;
const qPath = offeringId ? `offerings/${offeringId}/questions` : null;
Promise.all([
qPath ? apiFetch(qPath) : Promise.resolve([]),
apiFetch('policies?scope=booking'),
])
.then(([questions, policies]) => {
renderRegistration(slot, offeringId, questions, policies);
})
.catch((err) => showError(err.message));
}
function renderRegistration(slot, offeringId, questions, policies) {
const weekly = slot.recurrence_group
? `<p><label><input type="checkbox" id="us-weekly"> Reserve this time weekly for the term</label></p>`
: '';
slotList.innerHTML = `
<div class="us-register">
<h3>${escHtml(dayLabel(dayKey(slot.start_dt)))} · ${escHtml(timeOf(slot.start_dt))}–${escHtml(timeOf(slot.end_dt))}</h3>
<form id="us-register-form">
${questions.map(questionField).join('')}
${policies.map(policyField).join('')}
${weekly}
<p>
<button type="submit" class="us-book-btn">Confirm Booking</button>
<button type="button" id="us-cancel" class="us-cancel-btn">Back</button>
</p>
</form>
</div>`;
document.getElementById('us-cancel').addEventListener('click', loadSlots);
document.getElementById('us-register-form').addEventListener('submit', (e) => {
e.preventDefault();
submitBooking(e.target, slot, offeringId, questions);
});
}
function submitBooking(form, slot, offeringId, questions) {
clearError();
const answers = {};
questions.forEach((q) => {
const field = form.elements[`q_${q.id}`];
if (!field) return;
answers[q.id] = field.type === 'checkbox' ? (field.checked ? '1' : '0') : field.value;
});
const accepted = [...form.querySelectorAll('.us-policy-accept:checked')].map((c) => Number(c.value));
const weeklyEl = document.getElementById('us-weekly');
apiFetch('bookings', { apiFetch('bookings', {
method: 'POST', method: 'POST',
body: JSON.stringify({ slot_id: slotId }), body: JSON.stringify({
slot_id: slot.id,
offering_id: offeringId,
recurrence: weeklyEl && weeklyEl.checked ? 'weekly' : 'single',
answers,
accepted_policy_version_ids: accepted,
}),
}) })
.then(() => { .then(() => {
slotList.style.display = 'none'; slotList.style.display = 'none';
@@ -104,7 +186,14 @@
.catch((err) => showError(err.message)); .catch((err) => showError(err.message));
} }
function loadSlots() {
clearError();
slotList.style.display = 'block';
confirm.style.display = 'none';
apiFetch('availability') apiFetch('availability')
.then(renderSlots) .then(renderSlots)
.catch((err) => showError(err.message)); .catch((err) => showError(err.message));
}
loadSlots();
}()); }());
docs/features/lesson-booking.md
+8 -1
View File
@@ -61,12 +61,19 @@ kind `group_class`; see `group-classes.md`.
- `[us_student_login]` — front-end login form for students - `[us_student_login]` — front-end login form for students
## Implementation ## Implementation
- Repository: `Unsupervised\Schedular\Booking\BookingRepository` - Repository: `Unsupervised\Schedular\Booking\BookingRepository` (`insertSeries()` builds a weekly series sharing a `series_id`)
- Model: `Unsupervised\Schedular\Booking\Lesson` - Model: `Unsupervised\Schedular\Booking\Lesson`
- Registration gate: `Unsupervised\Schedular\Registration\RegistrationGate` — validates and records intake answers + booking-scoped policy acceptances; shared with group enrolment
- Admin controller: `Unsupervised\Schedular\Booking\LessonController` - Admin controller: `Unsupervised\Schedular\Booking\LessonController`
- REST endpoint: `Unsupervised\Schedular\Booking\BookingEndpoint` - REST endpoint: `Unsupervised\Schedular\Booking\BookingEndpoint`
- Frontend: `Unsupervised\Schedular\Booking\BookingPage`, `Unsupervised\Schedular\Auth\LoginPage` - Frontend: `Unsupervised\Schedular\Booking\BookingPage`, `Unsupervised\Schedular\Auth\LoginPage`
> **Payment seam:** payment is deferred to the Payments feature (#7). For now a
> booking is created with `status = pending` and `payment_id = null`; the
> instructor confirms via `PATCH /bookings/{id}/status`. When payments land, the
> pay→confirm + receipt step plugs into this seam. `GET /policies?scope=booking`
> returns just the booking-gate policies the form must collect.
## Tests ## Tests
- `tests/Unit/Booking/BookingRepositoryTest.php` - `tests/Unit/Booking/BookingRepositoryTest.php`
- `tests/Unit/Booking/LessonTest.php` - `tests/Unit/Booking/LessonTest.php`
src/Availability/AvailabilityRepository.php
+16
View File
@@ -141,6 +141,22 @@ class AvailabilityRepository {
return array_map( AvailabilitySlot::fromRow( ... ), $rows ?? [] ); return array_map( AvailabilitySlot::fromRow( ... ), $rows ?? [] );
} }
/**
* Unbooked slots that belong to a weekly-recurring group, ordered by start.
*
* @return list<AvailabilitySlot>
*/
public function findUnbookedInGroup( int $recurrenceGroup ): array {
$rows = $this->db->get_results(
$this->db->prepare(
"SELECT * FROM {$this->table} WHERE recurrence_group = %d AND is_booked = 0 ORDER BY start_dt ASC",
$recurrenceGroup
)
);
return array_map( AvailabilitySlot::fromRow( ... ), $rows ?? [] );
}
public function findById( int $id ): ?AvailabilitySlot { public function findById( int $id ): ?AvailabilitySlot {
$row = $this->db->get_row( $row = $this->db->get_row(
$this->db->prepare( "SELECT * FROM {$this->table} WHERE id = %d", $id ) $this->db->prepare( "SELECT * FROM {$this->table} WHERE id = %d", $id )
src/Booking/BookingEndpoint.php
+82 -4
View File
@@ -5,12 +5,17 @@ namespace Unsupervised\Schedular\Booking;
use Unsupervised\Schedular\Availability\AvailabilityRepository; use Unsupervised\Schedular\Availability\AvailabilityRepository;
use Unsupervised\Schedular\Auth\RoleManager; use Unsupervised\Schedular\Auth\RoleManager;
use Unsupervised\Schedular\Offering\OfferingRepository;
use Unsupervised\Schedular\Policy\PolicyAcceptance;
use Unsupervised\Schedular\Registration\RegistrationGate;
class BookingEndpoint { class BookingEndpoint {
public function __construct( public function __construct(
private AvailabilityRepository $availability, private AvailabilityRepository $availability,
private BookingRepository $bookings, private BookingRepository $bookings,
private OfferingRepository $offerings,
private RegistrationGate $gate,
) {} ) {}
public function registerRoutes( string $route_namespace ): void { public function registerRoutes( string $route_namespace ): void {
@@ -33,6 +38,22 @@ class BookingEndpoint {
'required' => true, 'required' => true,
'sanitize_callback' => 'absint', 'sanitize_callback' => 'absint',
], ],
'offering_id' => [
'type' => 'integer',
'default' => 0,
],
'recurrence' => [
'type' => 'string',
'default' => 'single',
],
'answers' => [
'type' => 'object',
'default' => [],
],
'accepted_policy_version_ids' => [
'type' => 'array',
'default' => [],
],
'notes' => [ 'notes' => [
'type' => 'string', 'type' => 'string',
'default' => '', 'default' => '',
@@ -84,26 +105,83 @@ class BookingEndpoint {
return new \WP_Error( 'slot_taken', __( 'This slot is already booked.', 'unsupervised-schedular' ), [ 'status' => 409 ] ); return new \WP_Error( 'slot_taken', __( 'This slot is already booked.', 'unsupervised-schedular' ), [ 'status' => 409 ] );
} }
$offeringId = absint( $request->get_param( 'offering_id' ) );
if ( 0 === $offeringId ) {
$offeringId = (int) ( $slot->offeringId ?? 0 );
}
if ( $offeringId > 0 && null === $this->offerings->findById( $offeringId ) ) {
return new \WP_Error( 'invalid_offering', __( 'Offering not found.', 'unsupervised-schedular' ), [ 'status' => 400 ] );
}
$answers = $this->answers( $request );
$acceptedVersionIds = array_map( 'absint', (array) $request->get_param( 'accepted_policy_version_ids' ) );
$gateError = $this->gate->validate( $offeringId, $answers, $acceptedVersionIds );
if ( $gateError instanceof \WP_Error ) {
return $gateError;
}
$studentId = get_current_user_id();
$notes = (string) $request->get_param( 'notes' ); $notes = (string) $request->get_param( 'notes' );
$lesson = new Lesson( $recurrence = Lesson::RECURRENCE_WEEKLY === $request->get_param( 'recurrence' )
? Lesson::RECURRENCE_WEEKLY
: Lesson::RECURRENCE_SINGLE;
$template = new Lesson(
slotId: $slotId, slotId: $slotId,
studentId: get_current_user_id(), studentId: $studentId,
instructorId: $slot->instructorId, instructorId: $slot->instructorId,
offeringId: $offeringId > 0 ? $offeringId : null,
recurrence: $recurrence,
notes: '' !== $notes ? $notes : null, notes: '' !== $notes ? $notes : null,
); );
$id = $this->bookings->insert( $lesson ); // Weekly reservation across the slot's recurring group; otherwise a single lesson.
if ( Lesson::RECURRENCE_WEEKLY === $recurrence && null !== $slot->recurrenceGroup ) {
$slotIds = array_map( static fn( $s ): int => (int) $s->id, $this->availability->findUnbookedInGroup( $slot->recurrenceGroup ) );
$ids = $this->bookings->insertSeries( $template, $slotIds );
foreach ( $slotIds as $reservedSlotId ) {
$this->availability->markBooked( $reservedSlotId );
}
$anchorId = $ids[0] ?? 0;
} else {
$anchorId = $this->bookings->insert( $template );
$this->availability->markBooked( $slotId ); $this->availability->markBooked( $slotId );
$ids = [ $anchorId ];
}
$this->gate->record( PolicyAcceptance::REG_LESSON, $anchorId, $studentId, $offeringId, $answers, $acceptedVersionIds, $this->clientIp() );
return new \WP_REST_Response( return new \WP_REST_Response(
[ [
'id' => $id, 'ids' => $ids,
'status' => Lesson::STATUS_PENDING, 'status' => Lesson::STATUS_PENDING,
], ],
201 201
); );
} }
/**
* Extract a question_id => value map from the request.
*
* @return array<int, string>
*/
private function answers( \WP_REST_Request $request ): array {
$out = [];
foreach ( (array) $request->get_param( 'answers' ) as $questionId => $value ) {
$out[ (int) $questionId ] = sanitize_text_field( (string) $value );
}
return $out;
}
private function clientIp(): ?string {
// phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized, WordPress.Security.ValidatedSanitizedInput.MissingUnslash -- IP stored verbatim for audit.
$ip = sanitize_text_field( wp_unslash( $_SERVER['REMOTE_ADDR'] ?? '' ) );
return '' !== $ip ? $ip : null;
}
public function updateStatus( \WP_REST_Request $request ): \WP_REST_Response|\WP_Error { public function updateStatus( \WP_REST_Request $request ): \WP_REST_Response|\WP_Error {
$id = absint( $request->get_param( 'id' ) ); $id = absint( $request->get_param( 'id' ) );
$lesson = $this->bookings->findById( $id ); $lesson = $this->bookings->findById( $id );
src/Booking/BookingRepository.php
+51 -1
View File
@@ -16,18 +16,68 @@ class BookingRepository {
$this->table, $this->table,
[ [
'slot_id' => $lesson->slotId, 'slot_id' => $lesson->slotId,
'offering_id' => $lesson->offeringId,
'student_id' => $lesson->studentId, 'student_id' => $lesson->studentId,
'instructor_id' => $lesson->instructorId, 'instructor_id' => $lesson->instructorId,
'recurrence' => $lesson->recurrence,
'series_id' => $lesson->seriesId,
'status' => $lesson->status, 'status' => $lesson->status,
'payment_id' => $lesson->paymentId,
'notes' => $lesson->notes, 'notes' => $lesson->notes,
'created_at' => current_time( 'mysql' ), 'created_at' => current_time( 'mysql' ),
], ],
[ '%d', '%d', '%d', '%s', '%s', '%s' ] [ '%d', '%d', '%d', '%d', '%s', '%d', '%s', '%d', '%s', '%s' ]
); );
return $this->db->insert_id; return $this->db->insert_id;
} }
/**
* Create a weekly lesson series — one lesson per slot, all sharing a
* `series_id` (the id of the first lesson row).
*
* @param list<int> $slotIds Availability slot IDs to reserve, in order.
* @return list<int> Inserted lesson IDs.
*/
public function insertSeries( Lesson $template, array $slotIds ): array {
$ids = [];
$seriesId = 0;
foreach ( $slotIds as $slotId ) {
$id = $this->insert(
new Lesson(
slotId: $slotId,
studentId: $template->studentId,
instructorId: $template->instructorId,
offeringId: $template->offeringId,
recurrence: Lesson::RECURRENCE_WEEKLY,
seriesId: $seriesId > 0 ? $seriesId : null,
status: $template->status,
notes: $template->notes,
)
);
if ( 0 === $seriesId ) {
$seriesId = $id;
$this->setSeriesId( $id, $seriesId );
}
$ids[] = $id;
}
return $ids;
}
private function setSeriesId( int $id, int $seriesId ): void {
$this->db->update(
$this->table,
[ 'series_id' => $seriesId ],
[ 'id' => $id ],
[ '%d' ],
[ '%d' ]
);
}
public function findById( int $id ): ?Lesson { public function findById( int $id ): ?Lesson {
$row = $this->db->get_row( $row = $this->db->get_row(
$this->db->prepare( "SELECT * FROM {$this->table} WHERE id = %d", $id ) $this->db->prepare( "SELECT * FROM {$this->table} WHERE id = %d", $id )
src/Booking/Lesson.php
+22
View File
@@ -16,11 +16,25 @@ class Lesson {
*/ */
public const VALID_STATUSES = [ self::STATUS_PENDING, self::STATUS_CONFIRMED, self::STATUS_CANCELLED ]; public const VALID_STATUSES = [ self::STATUS_PENDING, self::STATUS_CONFIRMED, self::STATUS_CANCELLED ];
public const RECURRENCE_SINGLE = 'single';
public const RECURRENCE_WEEKLY = 'weekly';
/**
* All valid recurrence values.
*
* @var list<string>
*/
public const VALID_RECURRENCES = [ self::RECURRENCE_SINGLE, self::RECURRENCE_WEEKLY ];
public function __construct( public function __construct(
public readonly int $slotId, public readonly int $slotId,
public readonly int $studentId, public readonly int $studentId,
public readonly int $instructorId, public readonly int $instructorId,
public readonly ?int $offeringId = null,
public readonly string $recurrence = self::RECURRENCE_SINGLE,
public readonly ?int $seriesId = null,
public readonly string $status = self::STATUS_PENDING, public readonly string $status = self::STATUS_PENDING,
public readonly ?int $paymentId = null,
public readonly ?string $notes = null, public readonly ?string $notes = null,
public readonly ?int $id = null, public readonly ?int $id = null,
) {} ) {}
@@ -30,7 +44,11 @@ class Lesson {
slotId: (int) $row->slot_id, slotId: (int) $row->slot_id,
studentId: (int) $row->student_id, studentId: (int) $row->student_id,
instructorId: (int) $row->instructor_id, instructorId: (int) $row->instructor_id,
offeringId: null !== $row->offering_id ? (int) $row->offering_id : null,
recurrence: $row->recurrence,
seriesId: null !== $row->series_id ? (int) $row->series_id : null,
status: $row->status, status: $row->status,
paymentId: null !== $row->payment_id ? (int) $row->payment_id : null,
notes: $row->notes, notes: $row->notes,
id: (int) $row->id, id: (int) $row->id,
); );
@@ -45,9 +63,13 @@ class Lesson {
return [ return [
'id' => $this->id, 'id' => $this->id,
'slot_id' => $this->slotId, 'slot_id' => $this->slotId,
'offering_id' => $this->offeringId,
'student_id' => $this->studentId, 'student_id' => $this->studentId,
'instructor_id' => $this->instructorId, 'instructor_id' => $this->instructorId,
'recurrence' => $this->recurrence,
'series_id' => $this->seriesId,
'status' => $this->status, 'status' => $this->status,
'payment_id' => $this->paymentId,
'notes' => $this->notes, 'notes' => $this->notes,
]; ];
} }
src/Plugin.php
+5 -1
View File
@@ -12,7 +12,9 @@ use Unsupervised\Schedular\Policy\AcceptanceRepository;
use Unsupervised\Schedular\Policy\PolicyRepository; use Unsupervised\Schedular\Policy\PolicyRepository;
use Unsupervised\Schedular\Policy\PolicyService; use Unsupervised\Schedular\Policy\PolicyService;
use Unsupervised\Schedular\Policy\PolicyVersionRepository; use Unsupervised\Schedular\Policy\PolicyVersionRepository;
use Unsupervised\Schedular\Registration\AnswerRepository;
use Unsupervised\Schedular\Registration\QuestionRepository; use Unsupervised\Schedular\Registration\QuestionRepository;
use Unsupervised\Schedular\Registration\RegistrationGate;
class Plugin { class Plugin {
@@ -24,15 +26,17 @@ class Plugin {
$bookings = new BookingRepository( $wpdb ); $bookings = new BookingRepository( $wpdb );
$offerings = new OfferingRepository( $wpdb ); $offerings = new OfferingRepository( $wpdb );
$questions = new QuestionRepository( $wpdb ); $questions = new QuestionRepository( $wpdb );
$answers = new AnswerRepository( $wpdb );
$policies = new PolicyRepository( $wpdb ); $policies = new PolicyRepository( $wpdb );
$policyVersions = new PolicyVersionRepository( $wpdb ); $policyVersions = new PolicyVersionRepository( $wpdb );
$policyService = new PolicyService( $policies, $policyVersions ); $policyService = new PolicyService( $policies, $policyVersions );
$acceptances = new AcceptanceRepository( $wpdb ); $acceptances = new AcceptanceRepository( $wpdb );
$invites = new InviteRepository( $wpdb ); $invites = new InviteRepository( $wpdb );
$registrationGate = new RegistrationGate( $questions, $answers, $policies, $policyVersions, $acceptances );
( new RoleManager() )->register(); ( new RoleManager() )->register();
( new AdminMenu( $availability, $bookings, $offerings, $questions, $policies, $policyVersions, $policyService, $invites ) )->register(); ( new AdminMenu( $availability, $bookings, $offerings, $questions, $policies, $policyVersions, $policyService, $invites ) )->register();
( new RestRegistrar( $availability, $bookings, $offerings, $questions, $policies, $policyVersions, $policyService ) )->register(); ( new RestRegistrar( $availability, $bookings, $offerings, $questions, $policies, $policyVersions, $policyService, $registrationGate ) )->register();
( new ShortcodeRegistrar( $invites, $policies, $policyVersions, $acceptances ) )->register(); ( new ShortcodeRegistrar( $invites, $policies, $policyVersions, $acceptances ) )->register();
} }
} }
src/Policy/PolicyEndpoint.php
+10 -3
View File
@@ -69,12 +69,19 @@ class PolicyEndpoint {
} }
/** /**
* Public: the current published version of every policy (the registration gate). * Public: the current published version of every policy (the registration
* gate). Pass `?scope=signup|booking` to limit to that gate (includes
* `both`-scoped policies).
*/ */
public function index(): \WP_REST_Response { public function index( \WP_REST_Request $request ): \WP_REST_Response {
$scope = (string) $request->get_param( 'scope' );
$policies = in_array( $scope, [ Policy::SCOPE_SIGNUP, Policy::SCOPE_BOOKING ], true )
? $this->policies->findForScope( $scope )
: $this->policies->findAll();
$out = []; $out = [];
foreach ( $this->policies->findAll() as $policy ) { foreach ( $policies as $policy ) {
if ( null === $policy->currentVersionId ) { if ( null === $policy->currentVersionId ) {
continue; continue;
} }
src/Registration/RegistrationGate.php
+120
View File
@@ -0,0 +1,120 @@
<?php
declare(strict_types=1);
namespace Unsupervised\Schedular\Registration;
use Unsupervised\Schedular\Policy\AcceptanceRepository;
use Unsupervised\Schedular\Policy\Policy;
use Unsupervised\Schedular\Policy\PolicyAcceptance;
use Unsupervised\Schedular\Policy\PolicyRepository;
use Unsupervised\Schedular\Policy\PolicyVersionRepository;
/**
* Shared registration gate: validates and records the intake-question answers
* and booking-scoped policy acceptances common to lesson bookings and group
* enrolments.
*/
class RegistrationGate {
public function __construct(
private QuestionRepository $questions,
private AnswerRepository $answers,
private PolicyRepository $policies,
private PolicyVersionRepository $versions,
private AcceptanceRepository $acceptances,
) {}
/**
* Validate that required questions are answered and all booking-scoped
* published policies are accepted. Returns null when the gate passes.
*
* @param array<int, string> $answers question_id => answer value
* @param list<int> $acceptedVersionIds Accepted policy version IDs
*/
public function validate( int $offeringId, array $answers, array $acceptedVersionIds ): ?\WP_Error {
foreach ( $this->questions->findByOffering( $offeringId, true ) as $question ) {
if ( $question->isRequired && '' === trim( (string) ( $answers[ (int) $question->id ] ?? '' ) ) ) {
return new \WP_Error(
'missing_answer',
__( 'Please answer all required questions.', 'unsupervised-schedular' ),
[ 'status' => 400 ]
);
}
}
foreach ( $this->requiredPolicyVersionIds() as $versionId ) {
if ( ! in_array( $versionId, $acceptedVersionIds, true ) ) {
return new \WP_Error(
'policy_required',
__( 'You must accept all required policies.', 'unsupervised-schedular' ),
[ 'status' => 400 ]
);
}
}
return null;
}
/**
* Persist answers and policy acceptances for a created registration.
*
* @param array<int, string> $answers question_id => answer value
* @param list<int> $acceptedVersionIds Accepted policy version IDs
*/
public function record( string $registrationType, int $registrationId, int $studentId, int $offeringId, array $answers, array $acceptedVersionIds, ?string $ipAddress = null ): void {
foreach ( $this->questions->findByOffering( $offeringId, true ) as $question ) {
$value = (string) ( $answers[ (int) $question->id ] ?? '' );
if ( '' === $value ) {
continue;
}
$this->answers->insert(
new Answer(
questionId: (int) $question->id,
registrationType: $registrationType,
registrationId: $registrationId,
studentId: $studentId,
answerValue: $value,
)
);
}
foreach ( $this->requiredPolicyVersionIds() as $versionId ) {
if ( ! in_array( $versionId, $acceptedVersionIds, true ) ) {
continue;
}
$this->acceptances->insert(
new PolicyAcceptance(
policyVersionId: $versionId,
studentId: $studentId,
registrationType: $registrationType,
registrationId: $registrationId,
ipAddress: $ipAddress,
)
);
}
}
/**
* Current published version IDs of every booking-scoped policy.
*
* @return list<int>
*/
private function requiredPolicyVersionIds(): array {
$ids = [];
foreach ( $this->policies->findForScope( Policy::SCOPE_BOOKING ) as $policy ) {
if ( null === $policy->currentVersionId ) {
continue;
}
$version = $this->versions->findById( $policy->currentVersionId );
if ( null !== $version && $version->isPublished() ) {
$ids[] = (int) $version->id;
}
}
return $ids;
}
}
src/RestRegistrar.php
+3 -2
View File
@@ -15,6 +15,7 @@ use Unsupervised\Schedular\Policy\PolicyService;
use Unsupervised\Schedular\Policy\PolicyVersionRepository; use Unsupervised\Schedular\Policy\PolicyVersionRepository;
use Unsupervised\Schedular\Registration\QuestionEndpoint; use Unsupervised\Schedular\Registration\QuestionEndpoint;
use Unsupervised\Schedular\Registration\QuestionRepository; use Unsupervised\Schedular\Registration\QuestionRepository;
use Unsupervised\Schedular\Registration\RegistrationGate;
class RestRegistrar { class RestRegistrar {
@@ -26,9 +27,9 @@ class RestRegistrar {
private QuestionEndpoint $questionEndpoint; private QuestionEndpoint $questionEndpoint;
private PolicyEndpoint $policyEndpoint; private PolicyEndpoint $policyEndpoint;
public function __construct( AvailabilityRepository $availability, BookingRepository $bookings, OfferingRepository $offerings, QuestionRepository $questions, PolicyRepository $policies, PolicyVersionRepository $policyVersions, PolicyService $policyService ) { public function __construct( AvailabilityRepository $availability, BookingRepository $bookings, OfferingRepository $offerings, QuestionRepository $questions, PolicyRepository $policies, PolicyVersionRepository $policyVersions, PolicyService $policyService, RegistrationGate $gate ) {
$this->availabilityEndpoint = new AvailabilityEndpoint( $availability ); $this->availabilityEndpoint = new AvailabilityEndpoint( $availability );
$this->bookingEndpoint = new BookingEndpoint( $availability, $bookings ); $this->bookingEndpoint = new BookingEndpoint( $availability, $bookings, $offerings, $gate );
$this->offeringEndpoint = new OfferingEndpoint( $offerings ); $this->offeringEndpoint = new OfferingEndpoint( $offerings );
$this->questionEndpoint = new QuestionEndpoint( $questions, $offerings ); $this->questionEndpoint = new QuestionEndpoint( $questions, $offerings );
$this->policyEndpoint = new PolicyEndpoint( $policies, $policyVersions, $policyService ); $this->policyEndpoint = new PolicyEndpoint( $policies, $policyVersions, $policyService );
src/Schema.php
+7 -1
View File
@@ -32,15 +32,21 @@ class Schema {
"CREATE TABLE {$prefix}us_lessons ( "CREATE TABLE {$prefix}us_lessons (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
slot_id BIGINT UNSIGNED NOT NULL, slot_id BIGINT UNSIGNED NOT NULL,
offering_id BIGINT UNSIGNED DEFAULT NULL,
student_id BIGINT UNSIGNED NOT NULL, student_id BIGINT UNSIGNED NOT NULL,
instructor_id BIGINT UNSIGNED NOT NULL, instructor_id BIGINT UNSIGNED NOT NULL,
recurrence VARCHAR(10) NOT NULL DEFAULT 'single',
series_id BIGINT UNSIGNED DEFAULT NULL,
status VARCHAR(20) NOT NULL DEFAULT 'pending', status VARCHAR(20) NOT NULL DEFAULT 'pending',
payment_id BIGINT UNSIGNED DEFAULT NULL,
notes TEXT, notes TEXT,
created_at DATETIME NOT NULL, created_at DATETIME NOT NULL,
PRIMARY KEY (id), PRIMARY KEY (id),
KEY slot_id (slot_id), KEY slot_id (slot_id),
KEY offering_id (offering_id),
KEY student_id (student_id), KEY student_id (student_id),
KEY instructor_id (instructor_id) KEY instructor_id (instructor_id),
KEY series_id (series_id)
) {$charset};", ) {$charset};",
"CREATE TABLE {$prefix}us_offerings ( "CREATE TABLE {$prefix}us_offerings (
tests/Unit/Booking/BookingRepositoryTest.php
+34 -2
View File
@@ -34,19 +34,43 @@ class BookingRepositoryTest extends TestCase
Mockery::on(static function (array $data): bool { Mockery::on(static function (array $data): bool {
return $data['slot_id'] === 10 return $data['slot_id'] === 10
&& $data['student_id'] === 5 && $data['student_id'] === 5
&& $data['offering_id'] === 7
&& $data['recurrence'] === Lesson::RECURRENCE_SINGLE
&& $data['status'] === Lesson::STATUS_PENDING; && $data['status'] === Lesson::STATUS_PENDING;
}), }),
['%d', '%d', '%d', '%s', '%s', '%s'] ['%d', '%d', '%d', '%d', '%s', '%d', '%s', '%d', '%s', '%s']
); );
$this->db->insert_id = 77; $this->db->insert_id = 77;
$lesson = new Lesson(slotId: 10, studentId: 5, instructorId: 3); $lesson = new Lesson(slotId: 10, studentId: 5, instructorId: 3, offeringId: 7);
$result = $this->repo->insert($lesson); $result = $this->repo->insert($lesson);
self::assertSame(77, $result); self::assertSame(77, $result);
} }
public function testInsertSeriesSharesSeriesIdAcrossSlots(): void
{
Functions\when('current_time')->justReturn('2026-04-01 12:00:00');
$ids = [40, 41, 42];
$this->db->shouldReceive('insert')
->times(3)
->andReturnUsing(function () use (&$ids): void {
$this->db->insert_id = array_shift($ids);
});
// The first lesson is back-filled with its own id as the series id.
$this->db->shouldReceive('update')
->once()
->with('wp_us_lessons', ['series_id' => 40], ['id' => 40], ['%d'], ['%d']);
$template = new Lesson(slotId: 0, studentId: 5, instructorId: 3, offeringId: 7);
$result = $this->repo->insertSeries($template, [100, 101, 102]);
self::assertSame([40, 41, 42], $result);
}
public function testFindByIdReturnsNullWhenNotFound(): void public function testFindByIdReturnsNullWhenNotFound(): void
{ {
$this->db->shouldReceive('prepare')->andReturn('SELECT ...'); $this->db->shouldReceive('prepare')->andReturn('SELECT ...');
@@ -60,9 +84,13 @@ class BookingRepositoryTest extends TestCase
$row = (object) [ $row = (object) [
'id' => '15', 'id' => '15',
'slot_id' => '10', 'slot_id' => '10',
'offering_id' => null,
'student_id' => '5', 'student_id' => '5',
'instructor_id' => '3', 'instructor_id' => '3',
'recurrence' => Lesson::RECURRENCE_SINGLE,
'series_id' => null,
'status' => 'pending', 'status' => 'pending',
'payment_id' => null,
'notes' => null, 'notes' => null,
]; ];
@@ -109,9 +137,13 @@ class BookingRepositoryTest extends TestCase
$row = (object) [ $row = (object) [
'id' => '1', 'id' => '1',
'slot_id' => '2', 'slot_id' => '2',
'offering_id' => null,
'student_id' => '5', 'student_id' => '5',
'instructor_id' => '3', 'instructor_id' => '3',
'recurrence' => Lesson::RECURRENCE_SINGLE,
'series_id' => null,
'status' => 'pending', 'status' => 'pending',
'payment_id' => null,
'notes' => null, 'notes' => null,
]; ];
tests/Unit/Booking/LessonTest.php
+22 -11
View File
@@ -28,41 +28,52 @@ class LessonTest extends TestCase
$lesson = new Lesson(slotId: 1, studentId: 2, instructorId: 3); $lesson = new Lesson(slotId: 1, studentId: 2, instructorId: 3);
self::assertSame(Lesson::STATUS_PENDING, $lesson->status); self::assertSame(Lesson::STATUS_PENDING, $lesson->status);
self::assertNull($lesson->offeringId);
self::assertSame(Lesson::RECURRENCE_SINGLE, $lesson->recurrence);
self::assertNull($lesson->seriesId);
self::assertNull($lesson->paymentId);
self::assertNull($lesson->notes); self::assertNull($lesson->notes);
self::assertNull($lesson->id); self::assertNull($lesson->id);
} }
public function testRecurrenceConstants(): void
{
self::assertContains(Lesson::RECURRENCE_SINGLE, Lesson::VALID_RECURRENCES);
self::assertContains(Lesson::RECURRENCE_WEEKLY, Lesson::VALID_RECURRENCES);
}
public function testFromRowMapsCorrectly(): void public function testFromRowMapsCorrectly(): void
{ {
$row = (object) [ $row = (object) [
'id' => '99', 'id' => '99',
'slot_id' => '10', 'slot_id' => '10',
'offering_id' => '7',
'student_id' => '20', 'student_id' => '20',
'instructor_id' => '30', 'instructor_id' => '30',
'recurrence' => Lesson::RECURRENCE_WEEKLY,
'series_id' => '99',
'status' => 'confirmed', 'status' => 'confirmed',
'payment_id' => null,
'notes' => 'Bring your guitar.', 'notes' => 'Bring your guitar.',
]; ];
$lesson = Lesson::fromRow($row); $lesson = Lesson::fromRow($row);
self::assertSame(99, $lesson->id); self::assertSame(99, $lesson->id);
self::assertSame(10, $lesson->slotId); self::assertSame(7, $lesson->offeringId);
self::assertSame(20, $lesson->studentId); self::assertSame(Lesson::RECURRENCE_WEEKLY, $lesson->recurrence);
self::assertSame(30, $lesson->instructorId); self::assertSame(99, $lesson->seriesId);
self::assertNull($lesson->paymentId);
self::assertSame('confirmed', $lesson->status); self::assertSame('confirmed', $lesson->status);
self::assertSame('Bring your guitar.', $lesson->notes);
} }
public function testToArrayContainsExpectedKeys(): void public function testToArrayContainsExpectedKeys(): void
{ {
$lesson = new Lesson(1, 2, 3, Lesson::STATUS_PENDING, 'Note', 5); $lesson = new Lesson(slotId: 1, studentId: 2, instructorId: 3, notes: 'Note', id: 5);
$arr = $lesson->toArray(); $arr = $lesson->toArray();
self::assertArrayHasKey('id', $arr); foreach (['id', 'slot_id', 'offering_id', 'student_id', 'instructor_id', 'recurrence', 'series_id', 'status', 'payment_id', 'notes'] as $key) {
self::assertArrayHasKey('slot_id', $arr); self::assertArrayHasKey($key, $arr);
self::assertArrayHasKey('student_id', $arr); }
self::assertArrayHasKey('instructor_id', $arr);
self::assertArrayHasKey('status', $arr);
self::assertArrayHasKey('notes', $arr);
} }
} }
tests/Unit/Registration/RegistrationGateTest.php
+105
View File
@@ -0,0 +1,105 @@
<?php
declare(strict_types=1);
namespace Unsupervised\Schedular\Tests\Unit\Registration;
use Mockery;
use Unsupervised\Schedular\Policy\AcceptanceRepository;
use Unsupervised\Schedular\Policy\Policy;
use Unsupervised\Schedular\Policy\PolicyAcceptance;
use Unsupervised\Schedular\Policy\PolicyRepository;
use Unsupervised\Schedular\Policy\PolicyVersion;
use Unsupervised\Schedular\Policy\PolicyVersionRepository;
use Unsupervised\Schedular\Registration\Answer;
use Unsupervised\Schedular\Registration\AnswerRepository;
use Unsupervised\Schedular\Registration\Question;
use Unsupervised\Schedular\Registration\QuestionRepository;
use Unsupervised\Schedular\Registration\RegistrationGate;
use Unsupervised\Schedular\Tests\Unit\TestCase;
class RegistrationGateTest extends TestCase
{
private QuestionRepository $questions;
private AnswerRepository $answers;
private PolicyRepository $policies;
private PolicyVersionRepository $versions;
private AcceptanceRepository $acceptances;
private RegistrationGate $gate;
protected function setUp(): void
{
parent::setUp();
$this->questions = Mockery::mock(QuestionRepository::class);
$this->answers = Mockery::mock(AnswerRepository::class);
$this->policies = Mockery::mock(PolicyRepository::class);
$this->versions = Mockery::mock(PolicyVersionRepository::class);
$this->acceptances = Mockery::mock(AcceptanceRepository::class);
$this->gate = new RegistrationGate(
$this->questions,
$this->answers,
$this->policies,
$this->versions,
$this->acceptances
);
}
private function requiredQuestion(): Question
{
return new Question(offeringId: 7, label: 'Level?', isRequired: true, id: 3);
}
private function bookingPolicy(): Policy
{
return new Policy('Cancellation', 'cancellation', currentVersionId: 9, acceptanceScope: Policy::SCOPE_BOOKING, id: 1);
}
public function testValidatePassesWhenAnswersAndPoliciesProvided(): void
{
$this->questions->shouldReceive('findByOffering')->with(7, true)->andReturn([$this->requiredQuestion()]);
$this->policies->shouldReceive('findForScope')->with(Policy::SCOPE_BOOKING)->andReturn([$this->bookingPolicy()]);
$this->versions->shouldReceive('findById')->with(9)->andReturn(new PolicyVersion(1, 1, 'body', PolicyVersion::STATUS_PUBLISHED, null, 9));
self::assertNull($this->gate->validate(7, [3 => 'Beginner'], [9]));
}
public function testValidateFailsWhenRequiredQuestionUnanswered(): void
{
$this->questions->shouldReceive('findByOffering')->with(7, true)->andReturn([$this->requiredQuestion()]);
$result = $this->gate->validate(7, [3 => ' '], [9]);
self::assertInstanceOf(\WP_Error::class, $result);
self::assertSame('missing_answer', $result->get_error_code());
}
public function testValidateFailsWhenPolicyNotAccepted(): void
{
$this->questions->shouldReceive('findByOffering')->with(7, true)->andReturn([$this->requiredQuestion()]);
$this->policies->shouldReceive('findForScope')->with(Policy::SCOPE_BOOKING)->andReturn([$this->bookingPolicy()]);
$this->versions->shouldReceive('findById')->with(9)->andReturn(new PolicyVersion(1, 1, 'body', PolicyVersion::STATUS_PUBLISHED, null, 9));
$result = $this->gate->validate(7, [3 => 'Beginner'], []);
self::assertInstanceOf(\WP_Error::class, $result);
self::assertSame('policy_required', $result->get_error_code());
}
public function testRecordPersistsAnswersAndAcceptances(): void
{
$this->questions->shouldReceive('findByOffering')->with(7, true)->andReturn([$this->requiredQuestion()]);
$this->policies->shouldReceive('findForScope')->with(Policy::SCOPE_BOOKING)->andReturn([$this->bookingPolicy()]);
$this->versions->shouldReceive('findById')->with(9)->andReturn(new PolicyVersion(1, 1, 'body', PolicyVersion::STATUS_PUBLISHED, null, 9));
$this->answers->shouldReceive('insert')
->once()
->with(Mockery::on(static fn (Answer $a): bool => $a->questionId === 3 && $a->registrationId === 50 && $a->answerValue === 'Beginner'));
$this->acceptances->shouldReceive('insert')
->once()
->with(Mockery::on(static fn (PolicyAcceptance $a): bool => $a->policyVersionId === 9 && $a->registrationType === PolicyAcceptance::REG_LESSON && $a->registrationId === 50));
$this->gate->record(PolicyAcceptance::REG_LESSON, 50, 5, 7, [3 => 'Beginner'], [9], '203.0.113.7');
}
}
tests/bootstrap.php
+33
View File
@@ -13,3 +13,36 @@ define('USC_VERSION', '1.0.0');
define('USC_PLUGIN_FILE', dirname(__DIR__) . '/unsupervised-schedular.php'); define('USC_PLUGIN_FILE', dirname(__DIR__) . '/unsupervised-schedular.php');
define('USC_PLUGIN_DIR', dirname(__DIR__) . '/'); define('USC_PLUGIN_DIR', dirname(__DIR__) . '/');
define('USC_PLUGIN_URL', 'http://example.com/wp-content/plugins/unsupervised-schedular/'); define('USC_PLUGIN_URL', 'http://example.com/wp-content/plugins/unsupervised-schedular/');
// Minimal WP_Error stub for code under test that returns error objects.
if (! class_exists('WP_Error')) {
class WP_Error
{
/** @var array<string, list<string>> */
public array $errors = [];
/** @var array<string, mixed> */
public array $error_data = [];
public function __construct(string $code = '', string $message = '', mixed $data = '')
{
if ('' !== $code) {
$this->errors[$code][] = $message;
if ('' !== $data) {
$this->error_data[$code] = $data;
}
}
}
public function get_error_code(): string
{
return (string) (array_key_first($this->errors) ?? '');
}
public function get_error_message(): string
{
$code = $this->get_error_code();
return '' !== $code ? ($this->errors[$code][0] ?? '') : '';
}
}
}