unsupervised-scheduler/src/Auth/DeletedUserCleanup.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\Guardian\GuardianRepository;
use Unsupervised\Schedular\Guardian\GuardianService;
use Unsupervised\Schedular\Payment\PaymentService;

/**
 * Gives back what a deleted account was holding, and takes the accounts that
 * only existed underneath it with it.
 *
 * WordPress deletes a user without knowing anything about lessons, so a student
 * removed from **Users → Delete** used to leave their bookings behind: the
 * availability slots stayed marked booked and unbookable by anyone else, the
 * lessons stayed on the instructor's schedule under a name that no longer
 * resolved, and a group class kept a seat filled by nobody.
 *
 * So each upcoming booking is cancelled the same way a real cancellation is —
 * marked cancelled, its slot released, its still-pending payment voided. Past
 * lessons are deliberately left alone: they happened, they may have been paid
 * for, and the payment report has to keep adding up.
 *
 * A **guardian** takes their children with them. A child account is login-less
 * and exists only so the guardian has somebody to book for; without the
 * guardian nobody can reach it, book for it, or be billed for it, so leaving it
 * behind leaves an unreachable student on the roster holding slots that will
 * never be used. Each child's bookings are released on the same terms, the link
 * row goes, and the account is deleted.
 *
 * No account credit is issued for a paid lesson, unlike a cancellation the
 * student asks for. A credit only has value against future billing on the
 * account it belongs to, and that account is being deleted; a refund owed to
 * someone who has left is a decision for the studio to make and record, not one
 * to silently write into a table nobody will read again.
 */
class DeletedUserCleanup {

	/**
	 * Accounts already dealt with this request, so deleting a guardian's child
	 * — which fires `delete_user` again and re-enters this very handler — cannot
	 * loop or redo work. It also makes a self-referential or circular guardian
	 * link, however it got into the table, terminate rather than recurse.
	 *
	 * @var array<int, true>
	 */
	private array $handled = [];

	public function __construct(
		private BookingRepository $bookings,
		private AvailabilityRepository $availability,
		private EnrollmentRepository $enrollments,
		private PaymentService $payments,
		private GuardianRepository $links,
		private GuardianService $guardians,
	) {}

	public function register(): void {
		// `delete_user` fires before the row goes, which is what lets the lookups
		// below still find the account's bookings and children. `wpmu_delete_user`
		// is the multisite equivalent for a user removed from the network entirely.
		add_action( 'delete_user', [ $this, 'releaseBookings' ] );
		add_action( 'wpmu_delete_user', [ $this, 'releaseBookings' ] );
	}

	/**
	 * Release everything the account had booked ahead of it, then remove any
	 * children that only existed to be booked for.
	 */
	public function releaseBookings( int $userId ): void {
		if ( $userId <= 0 || isset( $this->handled[ $userId ] ) ) {
			return;
		}

		$this->handled[ $userId ] = true;

		$this->release( $userId );
		$this->removeChildren( $userId );
	}

	/**
	 * Cancel one account's upcoming lessons and active enrolments, freeing the
	 * slot and voiding the pending payment behind each.
	 */
	private function release( int $studentId ): void {
		// Upcoming and not already cancelled — the only bookings that are still
		// holding anything.
		foreach ( $this->bookings->findUpcomingForStudent( $studentId ) as $lesson ) {
			$this->bookings->updateStatus( (int) $lesson->id, Lesson::STATUS_CANCELLED );
			$this->availability->release( $lesson->slotId );
			$this->payments->voidPending( $lesson->paymentId );
		}

		foreach ( $this->enrollments->findByStudent( $studentId ) as $enrollment ) {
			if ( Enrollment::STATUS_ACTIVE !== $enrollment->status ) {
				continue;
			}

			$this->enrollments->updateStatus( (int) $enrollment->id, Enrollment::STATUS_CANCELLED );
			$this->payments->voidPending( $enrollment->paymentId );
		}
	}

	/**
	 * Delete every child linked to a departing guardian, releasing what each was
	 * holding first. Each child is marked handled *before* it is deleted, so the
	 * `delete_user` this fires re-enters and returns without redoing the release.
	 */
	private function removeChildren( int $guardianId ): void {
		foreach ( $this->links->findByGuardian( $guardianId ) as $link ) {
			$childId = $link->studentId;

			if ( $childId <= 0 || $childId === $guardianId || isset( $this->handled[ $childId ] ) ) {
				continue;
			}

			$this->handled[ $childId ] = true;

			$this->release( $childId );
			$this->links->delete( $guardianId, $childId );
			$this->guardians->deleteUser( $childId );
		}
	}
}