unsupervised-scheduler/src/Auth/StudentController.php

<?php
declare(strict_types=1);

namespace Unsupervised\Schedular\Auth;

use Unsupervised\Schedular\Availability\AvailabilityRepository;
use Unsupervised\Schedular\Booking\BookingRepository;
use Unsupervised\Schedular\Booking\Lesson;
use Unsupervised\Schedular\GroupClass\Enrollment;
use Unsupervised\Schedular\GroupClass\EnrollmentRepository;
use Unsupervised\Schedular\GroupClass\SessionSchedule;
use Unsupervised\Schedular\Guardian\GuardianService;
use Unsupervised\Schedular\Offering\OfferingRepository;
use Unsupervised\Schedular\Payment\BillingMethodResolver;
use Unsupervised\Schedular\Payment\Payment;
use Unsupervised\Schedular\Val;

class StudentController {

	public function __construct(
		private BookingRepository $bookings,
		private AvailabilityRepository $availability,
		private OfferingRepository $offerings,
		private EnrollmentRepository $enrollments,
		private BillingMethodResolver $resolver,
		private StudentHistory $history,
		private StudentActions $actions,
		private GuardianService $guardians,
		private SessionSchedule $sessions,
	) {}

	public function renderPage(): void {
		if ( ! current_user_can( RoleManager::CAP_MANAGE_STUDENTS ) ) {
			wp_die( esc_html__( 'You do not have permission to view students.', 'unsupervised-schedular' ) );
		}

		// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only student selector.
		$studentId = absint( Val::int( $_GET['student_id'] ?? 0 ) );
		$student   = $studentId > 0 ? get_userdata( $studentId ) : false;

		if ( $student && in_array( RoleManager::STUDENT, (array) $student->roles, true ) ) {
			$this->renderDetail( $student );
			return;
		}

		$students = array_map(
			fn( \WP_User $user ): array => [
				'id'         => (int) $user->ID,
				'name'       => $user->display_name,
				// A child's own address is an undeliverable placeholder, so the
				// list shows the guardian's — the address an admin would use.
				'email'      => $this->guardians->contactFor( (int) $user->ID )['email'],
				'registered' => $user->user_registered,
				'upcoming'   => $this->bookings->countUpcomingForStudent( (int) $user->ID ),
				'enrolments' => $this->enrollments->countActiveForStudent( (int) $user->ID ),
				'guardian'   => $this->guardians->guardianOf( (int) $user->ID ),
				'children'   => $this->guardians->children( (int) $user->ID ),
			],
			array_filter(
				get_users(
					[
						'role'    => RoleManager::STUDENT,
						'orderby' => 'display_name',
						'order'   => 'ASC',
					]
				),
				static fn( mixed $user ): bool => $user instanceof \WP_User
			)
		);

		$pageSlug = 'us-students';
		include USC_PLUGIN_DIR . 'templates/admin/students.php';
	}

	private function renderDetail( \WP_User $student ): void {
		$canBilling = current_user_can( RoleManager::CAP_MANAGE_BILLING );

		// phpcs:ignore WordPress.Security.NonceVerification.Missing -- routing only; each action below verifies its own nonce.
		$action = sanitize_key( Val::string( wp_unslash( $_POST['usc_action'] ?? '' ) ) );

		$notice = '';
		$error  = '';

		if ( $canBilling && 'set_billing' === $action && check_admin_referer( 'usc_student_billing' ) ) {
			// phpcs:ignore WordPress.Security.NonceVerification.Missing -- nonce checked above.
			$method = sanitize_key( Val::string( wp_unslash( $_POST['payment_method'] ?? '' ) ) );
			if ( in_array( $method, Payment::VALID_METHODS, true ) ) {
				update_user_meta( (int) $student->ID, BillingMethodResolver::META_METHOD, $method );
			} else {
				delete_user_meta( (int) $student->ID, BillingMethodResolver::META_METHOD );
			}
		}

		if ( 'update_account' === $action && check_admin_referer( 'usc_student_actions' ) ) {
			// phpcs:disable WordPress.Security.NonceVerification.Missing -- nonce checked above.
			$displayName = sanitize_text_field( Val::string( wp_unslash( $_POST['display_name'] ?? '' ) ) );
			$email       = sanitize_email( Val::string( wp_unslash( $_POST['user_email'] ?? '' ) ) );
			// phpcs:enable WordPress.Security.NonceVerification.Missing

			$result = $this->actions->updateAccount( (int) $student->ID, $displayName, $email );
			if ( $result instanceof \WP_Error ) {
				$error = $result->get_error_message();
			} else {
				$notice  = __( 'Account details updated.', 'unsupervised-schedular' );
				$fresh   = get_userdata( (int) $student->ID );
				$student = $fresh instanceof \WP_User ? $fresh : $student;
			}
		}

		if ( 'cancel_lesson' === $action && check_admin_referer( 'usc_student_actions' ) ) {
			// phpcs:ignore WordPress.Security.NonceVerification.Missing -- nonce checked above.
			$lessonId = absint( Val::int( $_POST['lesson_id'] ?? 0 ) );
			if ( $this->actions->cancelLesson( $lessonId, (int) $student->ID ) ) {
				$notice = __( 'Lesson cancelled.', 'unsupervised-schedular' );
			} else {
				$error = __( 'This lesson could not be cancelled.', 'unsupervised-schedular' );
			}
		}

		if ( 'withdraw_enrollment' === $action && check_admin_referer( 'usc_student_actions' ) ) {
			// phpcs:ignore WordPress.Security.NonceVerification.Missing -- nonce checked above.
			$enrollmentId = absint( Val::int( $_POST['enrollment_id'] ?? 0 ) );
			if ( $this->actions->withdrawEnrollment( $enrollmentId, (int) $student->ID ) ) {
				$notice = __( 'Enrolment withdrawn.', 'unsupervised-schedular' );
			} else {
				$error = __( 'This enrolment could not be withdrawn.', 'unsupervised-schedular' );
			}
		}

		$billingOverride = Val::string( get_user_meta( (int) $student->ID, BillingMethodResolver::META_METHOD, true ) );
		$billingDefault  = $this->resolver->defaultMethod();

		$now  = current_time( 'mysql' );
		$rows = array_map(
			fn( Lesson $lesson ): array => $this->lessonRow( $lesson ),
			$this->bookings->findByStudent( (int) $student->ID )
		);

		// Group classes join the upcoming table so "what is this student booked
		// into next week?" has one answer instead of two. Only their upcoming
		// sessions are added: the enrolment table below already records the whole
		// history, and a term's worth of past dates would bury the lessons under
		// "Past lessons".
		$schedule = StudentSchedule::partition(
			array_merge( $rows, $this->groupSessionRows( (int) $student->ID, $now ) ),
			$now
		);
		$upcoming = $schedule['upcoming'];
		$past     = $schedule['past'];

		$enrolments = array_map(
			function ( Enrollment $enrollment ): array {
				$offering = $this->offerings->findById( $enrollment->offeringId );

				return [
					'id'       => (int) $enrollment->id,
					'offering' => $offering ? $offering->title : (string) $enrollment->offeringId,
					'status'   => $enrollment->status,
				];
			},
			$this->enrollments->findByStudent( (int) $student->ID )
		);

		$acceptances      = $this->history->policyAcceptances( (int) $student->ID );
		$registrationInfo = $this->history->registrationInfo( (int) $student->ID );
		$intake           = $this->history->intakeAnswers( (int) $student->ID );
		$payments         = $canBilling ? $this->history->payments( (int) $student->ID ) : [];
		$credits          = $canBilling ? $this->history->credits( (int) $student->ID ) : [];
		$creditCurrency   = $this->creditCurrency( $credits );

		// The family panel, and the account whose balance actually settles this
		// student's charges — a child's is their guardian's, so showing the
		// child's own (always empty) balance would be actively misleading.
		$guardian = $this->guardians->guardianOf( (int) $student->ID );
		$children = $this->guardians->children( (int) $student->ID );
		$payer    = $this->guardians->contactFor( (int) $student->ID );

		$creditBalance = $canBilling ? $this->history->creditBalance( $payer['id'] ) : 0.0;

		$backUrl  = admin_url( 'admin.php?page=us-students' );
		$pageSlug = 'us-students';
		include USC_PLUGIN_DIR . 'templates/admin/student-detail.php';
	}

	/**
	 * Currency to label the credit balance with — taken from the student's credits
	 * (they share a currency in practice), defaulting to CAD when they have none.
	 *
	 * @param list<array{created_at: string, amount: float, remaining: float, currency: string, reason: string, status: string}> $credits
	 */
	private function creditCurrency( array $credits ): string {
		return [] !== $credits ? (string) $credits[0]['currency'] : 'CAD';
	}

	/**
	 * Build a display row for a lesson (slot time, offering, instructor, status).
	 *
	 * @return array<string, mixed>
	 */
	private function lessonRow( Lesson $lesson ): array {
		$slot       = $this->availability->findById( $lesson->slotId );
		$offering   = null !== $lesson->offeringId ? $this->offerings->findById( $lesson->offeringId ) : null;
		$instructor = get_userdata( $lesson->instructorId );

		return [
			'id'         => (int) $lesson->id,
			'kind'       => 'lesson',
			'schedule'   => null,
			'start_dt'   => $slot ? $slot->startDt : '',
			'end_dt'     => $slot ? $slot->endDt : '',
			'offering'   => $offering ? $offering->title : '—',
			'instructor' => $instructor ? $instructor->display_name : (string) $lesson->instructorId,
			'status'     => $lesson->status,
		];
	}

	/**
	 * The student's upcoming group-class sessions, shaped like the lesson rows
	 * they sit beside. `kind` is what keeps the table honest: a session is a date
	 * in a term, not a booked slot, so the row offers no "Cancel" — withdrawing
	 * is done from the enrolment table, which removes the whole class at once.
	 *
	 * @return list<array<string, mixed>>
	 */
	private function groupSessionRows( int $studentId, string $now ): array {
		return array_map(
			static function ( array $session ): array {
				$instructor = get_userdata( $session['instructor_id'] );

				return [
					'id'         => $session['enrollment_id'],
					'kind'       => SessionSchedule::KIND,
					'start_dt'   => $session['start_dt'],
					'end_dt'     => $session['end_dt'],
					// Set when the class has no time to put on a clock; shown in the
					// When column in place of a date. See GroupClass\SessionSchedule.
					'schedule'   => $session['schedule'],
					'offering'   => $session['offering_title'],
					'instructor' => $instructor ? $instructor->display_name : (string) $session['instructor_id'],
					'status'     => $session['status'],
				];
			},
			$this->sessions->upcomingForStudent( $studentId, $now )
		);
	}
}