Upgrade PHPStan to 2.x and raise analysis level from 6 to 10

- Bump phpstan/phpstan ^2.0 and szepeviktor/phpstan-wordpress ^2.0
- Move the analysis level into phpstan.neon (single source) and raise it to 10
- Add Val, a runtime coercion helper that narrows untyped WordPress boundary
  values (wpdb rows, REST params, superglobals, options) with explicit checks
  instead of blind casts, plus unit tests
- Type value-object fromRow() params as stdClass (what wpdb returns) and map
  columns through Val so unexpected shapes degrade safely
- Use %i identifier placeholders for table names in all wpdb::prepare() calls
  so every query string is a literal and identifiers are escaped by WordPress;
  raises the minimum WordPress version to 6.2 where %i was introduced
- Guard wpdb::prepare() null result before wpdb::query() in updateTax()
- Fix nullable get_permalink()/strtotime() handling, list types at REST and
  capability call sites, dead null-coalescing on checked superglobals, and
  narrow get_users() results before mapping
- Register Val method names with the ValidatedSanitizedInput sniff so it
  validates the real sanitizer around each superglobal read
- Update repository unit tests for the %i placeholder arguments

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

src/Auth/AccessSettings.php

@@ -3,6 +3,8 @@ declare(strict_types=1);
 
 namespace Unsupervised\Schedular\Auth;
 
+use Unsupervised\Schedular\Val;
+
 /**
  * Site-owner toggles for whether WordPress administrators automatically receive
  * the studio-admin and/or instructor capabilities.
@@ -39,7 +41,7 @@ class AccessSettings {
 	 * single-account behaviour.
 	 */
 	private function flag( string $option ): bool {
-		return '0' !== (string) get_option( $option, '1' );
+		return '0' !== Val::string( get_option( $option, '1' ) );
 	}
 
 	public function renderPage(): void {

src/Auth/InstructorController.php

@@ -3,6 +3,8 @@ declare(strict_types=1);
 
 namespace Unsupervised\Schedular\Auth;
 
+use Unsupervised\Schedular\Val;
+
 /**
  * Studio-admin **Instructors** page: create instructor accounts and toggle each
  * instructor's managed capabilities. Gated on `manage_instructors`. A studio
@@ -24,7 +26,7 @@ class InstructorController {
 		}
 
 		// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only instructor selector.
-		$instructorId = absint( $_GET['instructor_id'] ?? 0 );
+		$instructorId = absint( Val::int( $_GET['instructor_id'] ?? 0 ) );
 		$instructor   = $instructorId > 0 ? get_userdata( $instructorId ) : false;
 
 		if ( $instructor && in_array( RoleManager::INSTRUCTOR, (array) $instructor->roles, true ) ) {
@@ -50,12 +52,15 @@ class InstructorController {
 				'email'      => $user->user_email,
 				'registered' => $user->user_registered,
 			],
-			get_users(
-				[
-					'role'    => RoleManager::INSTRUCTOR,
-					'orderby' => 'display_name',
-					'order'   => 'ASC',
-				]
+			array_filter(
+				get_users(
+					[
+						'role'    => RoleManager::INSTRUCTOR,
+						'orderby' => 'display_name',
+						'order'   => 'ASC',
+					]
+				),
+				static fn( mixed $user ): bool => $user instanceof \WP_User
 			)
 		);
 
@@ -66,7 +71,7 @@ class InstructorController {
 	private function handleFormAction(): string {
 		// Nonce is verified by the caller (renderPage) before this method runs.
 		// phpcs:disable WordPress.Security.NonceVerification.Missing
-		$action = sanitize_key( wp_unslash( $_POST['usc_action'] ?? '' ) );
+		$action = sanitize_key( Val::string( wp_unslash( $_POST['usc_action'] ?? '' ) ) );
 		// phpcs:enable WordPress.Security.NonceVerification.Missing
 
 		if ( 'create' === $action ) {
@@ -82,8 +87,8 @@ class InstructorController {
 
 	private function createInstructor(): string {
 		// phpcs:disable WordPress.Security.NonceVerification.Missing
-		$email = sanitize_email( wp_unslash( $_POST['email'] ?? '' ) );
-		$name  = sanitize_text_field( wp_unslash( $_POST['display_name'] ?? '' ) );
+		$email = sanitize_email( Val::string( wp_unslash( $_POST['email'] ?? '' ) ) );
+		$name  = sanitize_text_field( Val::string( wp_unslash( $_POST['display_name'] ?? '' ) ) );
 		// phpcs:enable WordPress.Security.NonceVerification.Missing
 
 		if ( ! is_email( $email ) ) {
@@ -125,8 +130,9 @@ class InstructorController {
 
 	private function updateCaps(): string {
 		// phpcs:disable WordPress.Security.NonceVerification.Missing
-		$instructorId = absint( $_POST['instructor_id'] ?? 0 );
-		$submitted    = array_map( 'sanitize_key', (array) wp_unslash( $_POST['capabilities'] ?? [] ) );
+		$instructorId = absint( Val::int( $_POST['instructor_id'] ?? 0 ) );
+		// phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- each capability key is sanitized with sanitize_key() in the array_map callback.
+		$submitted = array_values( array_map( static fn( mixed $cap ): string => sanitize_key( Val::string( $cap ) ), (array) wp_unslash( $_POST['capabilities'] ?? [] ) ) );
 		// phpcs:enable WordPress.Security.NonceVerification.Missing
 
 		$instructor = $instructorId > 0 ? get_userdata( $instructorId ) : false;

src/Auth/Invite.php

@@ -3,6 +3,8 @@ declare(strict_types=1);
 
 namespace Unsupervised\Schedular\Auth;
 
+use Unsupervised\Schedular\Val;
+
 class Invite {
 
 	public const STATUS_PENDING  = 'pending';
@@ -44,17 +46,17 @@ class Invite {
 		public readonly ?int $id = null,
 	) {}
 
-	public static function fromRow( object $row ): self {
+	public static function fromRow( \stdClass $row ): self {
 		return new self(
-			email:          $row->email,
-			token:          $row->token,
-			role:           $row->role,
-			status:         $row->status,
-			invitedBy:      null !== $row->invited_by ? (int) $row->invited_by : null,
-			acceptedUserId: null !== $row->accepted_user_id ? (int) $row->accepted_user_id : null,
-			acceptedAt:     $row->accepted_at,
-			createdAt:      $row->created_at ?? null,
-			id:             (int) $row->id,
+			email:          Val::string( $row->email ),
+			token:          Val::string( $row->token ),
+			role:           Val::string( $row->role ),
+			status:         Val::string( $row->status ),
+			invitedBy:      Val::intOrNull( $row->invited_by ),
+			acceptedUserId: Val::intOrNull( $row->accepted_user_id ),
+			acceptedAt:     Val::stringOrNull( $row->accepted_at ),
+			createdAt:      Val::stringOrNull( $row->created_at ?? null ),
+			id:             Val::int( $row->id ),
 		);
 	}
 

src/Auth/InviteRepository.php

@@ -32,7 +32,7 @@ class InviteRepository {
 
 	public function findByToken( string $token ): ?Invite {
 		$row = $this->db->get_row(
-			$this->db->prepare( "SELECT * FROM {$this->table} WHERE token = %s", $token )
+			$this->db->prepare( 'SELECT * FROM %i WHERE token = %s', $this->table, $token )
 		);
 
 		return $row ? Invite::fromRow( $row ) : null;
@@ -40,7 +40,7 @@ class InviteRepository {
 
 	public function findById( int $id ): ?Invite {
 		$row = $this->db->get_row(
-			$this->db->prepare( "SELECT * FROM {$this->table} WHERE id = %d", $id )
+			$this->db->prepare( 'SELECT * FROM %i WHERE id = %d', $this->table, $id )
 		);
 
 		return $row ? Invite::fromRow( $row ) : null;
@@ -52,7 +52,8 @@ class InviteRepository {
 	public function findPendingByEmail( string $email ): ?Invite {
 		$row = $this->db->get_row(
 			$this->db->prepare(
-				"SELECT * FROM {$this->table} WHERE email = %s AND status = %s ORDER BY id DESC LIMIT 1",
+				'SELECT * FROM %i WHERE email = %s AND status = %s ORDER BY id DESC LIMIT 1',
+				$this->table,
 				$email,
 				Invite::STATUS_PENDING
 			)
@@ -69,7 +70,8 @@ class InviteRepository {
 	public function findPending(): array {
 		$rows = $this->db->get_results(
 			$this->db->prepare(
-				"SELECT * FROM {$this->table} WHERE status = %s ORDER BY created_at DESC",
+				'SELECT * FROM %i WHERE status = %s ORDER BY created_at DESC',
+				$this->table,
 				Invite::STATUS_PENDING
 			)
 		);

src/Auth/LoginPage.php

@@ -3,12 +3,14 @@ declare(strict_types=1);
 
 namespace Unsupervised\Schedular\Auth;
 
+use Unsupervised\Schedular\Val;
+
 class LoginPage {
 
 	/**
 	 * Renders the student login shortcode output.
 	 *
-	 * @param array<string, string> $atts Shortcode attributes (unused — reserved for future options).
+	 * @param array<string> $atts Shortcode attributes (unused — reserved for future options).
 	 */
 	public function render( array $atts ): string { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.Found
 		if ( is_user_logged_in() ) {
@@ -26,9 +28,9 @@ class LoginPage {
 
 		if ( isset( $_POST['us_login'] ) && check_admin_referer( 'us_student_login' ) ) {
 			$credentials = [
-				'user_login'    => sanitize_user( wp_unslash( $_POST['log'] ?? '' ) ),
+				'user_login'    => sanitize_user( Val::string( wp_unslash( $_POST['log'] ?? '' ) ) ),
 				// phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- passwords must not be sanitized.
-				'user_password' => wp_unslash( $_POST['pwd'] ?? '' ),
+				'user_password' => Val::string( wp_unslash( $_POST['pwd'] ?? '' ) ),
 				'remember'      => isset( $_POST['rememberme'] ),
 			];
 

src/Auth/RegistrationController.php

@@ -3,6 +3,8 @@ declare(strict_types=1);
 
 namespace Unsupervised\Schedular\Auth;
 
+use Unsupervised\Schedular\Val;
+
 class RegistrationController {
 
 	/**
@@ -23,7 +25,7 @@ class RegistrationController {
 		}
 
 		$pendingInvites      = $this->invites->findPending();
-		$registrationPageId  = (int) get_option( self::OPTION_PAGE, 0 );
+		$registrationPageId  = Val::int( get_option( self::OPTION_PAGE, 0 ) );
 		$registrationPageUrl = $registrationPageId > 0 ? (string) get_permalink( $registrationPageId ) : '';
 
 		include USC_PLUGIN_DIR . 'templates/admin/invites.php';
@@ -37,14 +39,14 @@ class RegistrationController {
 	private function handleFormAction(): string {
 		// Nonce is verified by the caller (renderPage) before this method runs.
 		// phpcs:disable WordPress.Security.NonceVerification.Missing
-		$action = sanitize_key( wp_unslash( $_POST['usc_action'] ?? '' ) );
+		$action = sanitize_key( Val::string( wp_unslash( $_POST['usc_action'] ?? '' ) ) );
 
 		if ( 'set_page' === $action ) {
-			update_option( self::OPTION_PAGE, absint( $_POST['registration_page_id'] ?? 0 ) );
+			update_option( self::OPTION_PAGE, absint( Val::int( $_POST['registration_page_id'] ?? 0 ) ) );
 		}
 
 		if ( 'invite' === $action ) {
-			$email = sanitize_email( wp_unslash( $_POST['email'] ?? '' ) );
+			$email = sanitize_email( Val::string( wp_unslash( $_POST['email'] ?? '' ) ) );
 
 			if (
 				is_email( $email )
@@ -66,7 +68,7 @@ class RegistrationController {
 		}
 
 		if ( 'revoke' === $action ) {
-			$inviteId = absint( $_POST['invite_id'] ?? 0 );
+			$inviteId = absint( Val::int( $_POST['invite_id'] ?? 0 ) );
 			if ( $inviteId > 0 ) {
 				$this->invites->revoke( $inviteId );
 			}
@@ -80,7 +82,7 @@ class RegistrationController {
 	 * Build the registration URL for a raw invite token.
 	 */
 	private function registrationLink( string $rawToken ): string {
-		$pageId   = (int) get_option( self::OPTION_PAGE, 0 );
+		$pageId   = Val::int( get_option( self::OPTION_PAGE, 0 ) );
 		$linkBase = $pageId > 0 ? (string) get_permalink( $pageId ) : '';
 
 		return add_query_arg( 'us_invite', rawurlencode( $rawToken ), '' !== $linkBase ? $linkBase : home_url( '/' ) );

src/Auth/RegistrationPage.php

@@ -8,6 +8,7 @@ use Unsupervised\Schedular\Policy\Policy;
 use Unsupervised\Schedular\Policy\PolicyAcceptance;
 use Unsupervised\Schedular\Policy\PolicyRepository;
 use Unsupervised\Schedular\Policy\PolicyVersionRepository;
+use Unsupervised\Schedular\Val;
 
 class RegistrationPage {
 
@@ -21,7 +22,7 @@ class RegistrationPage {
 	/**
 	 * Renders the student registration shortcode output.
 	 *
-	 * @param array<string, string> $atts Shortcode attributes (unused — reserved for future options).
+	 * @param array<string> $atts Shortcode attributes (unused — reserved for future options).
 	 */
 	public function render( array $atts ): string { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.Found
 		if ( is_user_logged_in() ) {
@@ -29,7 +30,7 @@ class RegistrationPage {
 		}
 
 		// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- token identifies the invite; the form submit is nonce-checked below.
-		$token = sanitize_text_field( wp_unslash( $_REQUEST['us_invite'] ?? '' ) );
+		$token = sanitize_text_field( Val::string( wp_unslash( $_REQUEST['us_invite'] ?? '' ) ) );
 		// Only the token's hash is stored, so hash the submitted token for lookup.
 		$invite = '' !== $token ? $this->invites->findByToken( Invite::hashToken( $token ) ) : null;
 
@@ -64,12 +65,12 @@ class RegistrationPage {
 		}
 
 		// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only token used only to build the redirect target.
-		$token = sanitize_text_field( wp_unslash( $_GET['us_invite'] ?? '' ) );
+		$token = sanitize_text_field( Val::string( wp_unslash( $_GET['us_invite'] ?? '' ) ) );
 		if ( '' === $token ) {
 			return;
 		}
 
-		$pageId = (int) get_option( RegistrationController::OPTION_PAGE, 0 );
+		$pageId = Val::int( get_option( RegistrationController::OPTION_PAGE, 0 ) );
 		if ( $pageId <= 0 || is_page( $pageId ) ) {
 			return;
 		}
@@ -90,15 +91,16 @@ class RegistrationPage {
 		// The submit nonce is verified by the caller (render) before this runs.
 		// phpcs:disable WordPress.Security.NonceVerification.Missing
 		// phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- passwords must not be sanitized.
-		$password    = (string) wp_unslash( $_POST['password'] ?? '' );
-		$displayName = sanitize_text_field( wp_unslash( $_POST['display_name'] ?? '' ) );
+		$password    = Val::string( wp_unslash( $_POST['password'] ?? '' ) );
+		$displayName = sanitize_text_field( Val::string( wp_unslash( $_POST['display_name'] ?? '' ) ) );
 
 		if ( strlen( $password ) < 8 ) {
 			return esc_html__( 'Please choose a password of at least 8 characters.', 'unsupervised-schedular' );
 		}
 
 		$policyForms = $this->signupPolicies();
-		$accepted    = array_map( 'absint', (array) ( $_POST['accept'] ?? [] ) );
+		// phpcs:ignore WordPress.Security.ValidatedSanitizedInput.MissingUnslash, WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- each element is coerced to a positive int in the array_map callback; slashes cannot survive integer coercion.
+		$accepted = array_map( static fn( mixed $v ): int => absint( Val::int( $v ) ), (array) ( $_POST['accept'] ?? [] ) );
 		// phpcs:enable WordPress.Security.NonceVerification.Missing
 
 		foreach ( $policyForms as $form ) {
@@ -141,7 +143,7 @@ class RegistrationPage {
 	 */
 	private function recordAcceptances( array $policyForms, int $userId ): void {
 		// phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized, WordPress.Security.ValidatedSanitizedInput.MissingUnslash -- IP is stored verbatim for audit.
-		$ip = sanitize_text_field( wp_unslash( $_SERVER['REMOTE_ADDR'] ?? '' ) );
+		$ip = sanitize_text_field( Val::string( wp_unslash( $_SERVER['REMOTE_ADDR'] ?? '' ) ) );
 
 		foreach ( $policyForms as $form ) {
 			$this->acceptances->insert(

src/Auth/StudentController.php

@@ -11,6 +11,7 @@ use Unsupervised\Schedular\GroupClass\EnrollmentRepository;
 use Unsupervised\Schedular\Offering\OfferingRepository;
 use Unsupervised\Schedular\Payment\BillingMethodResolver;
 use Unsupervised\Schedular\Payment\Payment;
+use Unsupervised\Schedular\Val;
 
 class StudentController {
 
@@ -28,7 +29,7 @@ class StudentController {
 		}
 
 		// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only student selector.
-		$studentId = absint( $_GET['student_id'] ?? 0 );
+		$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 ) ) {
@@ -45,12 +46,15 @@ class StudentController {
 				'upcoming'   => $this->bookings->countUpcomingForStudent( (int) $user->ID ),
 				'enrolments' => $this->enrollments->countActiveForStudent( (int) $user->ID ),
 			],
-			get_users(
-				[
-					'role'    => RoleManager::STUDENT,
-					'orderby' => 'display_name',
-					'order'   => 'ASC',
-				]
+			array_filter(
+				get_users(
+					[
+						'role'    => RoleManager::STUDENT,
+						'orderby' => 'display_name',
+						'order'   => 'ASC',
+					]
+				),
+				static fn( mixed $user ): bool => $user instanceof \WP_User
 			)
 		);
 
@@ -63,7 +67,7 @@ class StudentController {
 
 		if ( $canBilling && isset( $_POST['usc_action'] ) && check_admin_referer( 'usc_student_billing' ) ) {
 			// phpcs:ignore WordPress.Security.NonceVerification.Missing -- nonce checked above.
-			$method = sanitize_key( wp_unslash( $_POST['payment_method'] ?? '' ) );
+			$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 {
@@ -71,7 +75,7 @@ class StudentController {
 			}
 		}
 
-		$billingOverride = (string) get_user_meta( (int) $student->ID, BillingMethodResolver::META_METHOD, true );
+		$billingOverride = Val::string( get_user_meta( (int) $student->ID, BillingMethodResolver::META_METHOD, true ) );
 		$billingDefault  = $this->resolver->defaultMethod();
 
 		$now  = current_time( 'mysql' );

src/Auth/StudentSchedule.php

@@ -3,6 +3,8 @@ declare(strict_types=1);
 
 namespace Unsupervised\Schedular\Auth;
 
+use Unsupervised\Schedular\Val;
+
 /**
  * Pure helper for splitting a student's dated rows into upcoming and past.
  */
@@ -21,7 +23,7 @@ class StudentSchedule {
 		$past     = [];
 
 		foreach ( $rows as $row ) {
-			$start = (string) ( $row['start_dt'] ?? '' );
+			$start = Val::string( $row['start_dt'] ?? '' );
 			if ( '' !== $start && $start >= $now ) {
 				$upcoming[] = $row;
 			} else {
@@ -29,12 +31,12 @@ class StudentSchedule {
 			}
 		}
 
-		usort( $upcoming, static fn( array $a, array $b ): int => strcmp( (string) ( $a['start_dt'] ?? '' ), (string) ( $b['start_dt'] ?? '' ) ) );
-		usort( $past, static fn( array $a, array $b ): int => strcmp( (string) ( $b['start_dt'] ?? '' ), (string) ( $a['start_dt'] ?? '' ) ) );
+		usort( $upcoming, static fn( array $a, array $b ): int => strcmp( Val::string( $a['start_dt'] ?? '' ), Val::string( $b['start_dt'] ?? '' ) ) );
+		usort( $past, static fn( array $a, array $b ): int => strcmp( Val::string( $b['start_dt'] ?? '' ), Val::string( $a['start_dt'] ?? '' ) ) );
 
 		return [
-			'upcoming' => array_values( $upcoming ),
-			'past'     => array_values( $past ),
+			'upcoming' => $upcoming,
+			'past'     => $past,
 		];
 	}
 }