Migrate learner management start date to progress repositories

changelog/add-hpps-student-start-date

@@ -0,0 +1,4 @@
+Significance: minor
+Type: changed
+
+Migrate student start date editing to use progress repositories instead of direct comment meta access.

includes/admin/class-sensei-learner-management.php

@@ -468,85 +468,120 @@ public function edit_date_started() {
 		check_ajax_referer( 'edit_date_nonce', 'security' );
 
 		if ( ! empty( $_POST['data']['post_id'] ) && is_numeric( $_POST['data']['post_id'] ) ) {
-			$post_id = (int) sanitize_key( $_POST['data']['post_id'] );
+			$post_id = absint( wp_unslash( $_POST['data']['post_id'] ) );
 		} else {
-			exit( '' );
+			exit;
 		}
 
 		$post = get_post( $post_id );
 
 		if ( empty( $post ) || ! is_a( $post, 'WP_Post' ) ) {
-			exit( '' );
+			exit;
 		}
 
-		if ( ! empty( $_POST['data']['comment_id'] ) && is_numeric( $_POST['data']['comment_id'] ) ) {
-			$comment_id = (int) sanitize_key( $_POST['data']['comment_id'] );
+		if ( ! empty( $_POST['data']['user_id'] ) && is_numeric( $_POST['data']['user_id'] ) ) {
+			$user_id = absint( wp_unslash( $_POST['data']['user_id'] ) );
 		} else {
-			exit( '' );
+			exit;
 		}
 
-		$comment = get_comment( $comment_id );
+		$post_type = get_post_type( $post_id );
 
-		if ( empty( $comment ) ) {
-			exit( '' );
+		if ( ! in_array( $post_type, array( 'course', 'lesson' ), true ) ) {
+			exit;
 		}
 
-		$post_type = get_post_type( $post_id );
-
 		if ( 'lesson' === $post_type ) {
 			$can_edit_date = $this->can_user_manage_students( (int) Sensei()->lesson->get_course_id( $post_id ), intval( $post->post_author ) );
 		} else {
 			$can_edit_date = $this->can_user_manage_students( $post_id, intval( $post->post_author ) );
 		}
 
 		if ( ! $can_edit_date ) {
-			exit( '' );
+			exit;
 		}
 
 		if ( ! empty( $_POST['data']['new_dates']['start-date'] ) ) {
 			$date_string = sanitize_text_field( wp_unslash( $_POST['data']['new_dates']['start-date'] ) );
 		} else {
-			exit( '' );
+			exit;
 		}
 
 		if ( empty( $date_string ) ) {
-			exit( '' );
+			exit;
 		}
 
-		$date_started = get_comment_meta( $comment_id, 'start', true );
-
 		$expected_date_format = 'Y-m-d H:i:s';
 		if ( false === strpos( $date_string, ' ' ) ) {
 			$expected_date_format = 'Y-m-d';
 		}
 
-		$date = DateTimeImmutable::createFromFormat( $expected_date_format, $date_string );
+		$date = DateTimeImmutable::createFromFormat( $expected_date_format, $date_string, wp_timezone() );
 		if ( false === $date ) {
-			exit( '' );
+			exit;
+		}
+
+		$utc_date = $date->setTimezone( new \DateTimeZone( 'UTC' ) );
+
+		$repository = 'course' === $post_type
+			? Sensei()->course_progress_repository_factory->create()
+			: Sensei()->lesson_progress_repository_factory->create();
+
+		$progress = $repository->get( $post_id, $user_id );
+		if ( ! $progress ) {
+			exit;
+		}
+
+		$old_started_at     = $progress->get_started_at();
+		$started_at_changed = ( null === $old_started_at || $old_started_at->getTimestamp() !== $utc_date->getTimestamp() );
+
+		if ( $started_at_changed ) {
+			$progress->set_started_at( $utc_date );
+
+			/**
+			 * The repository and progress are created from the same factory, so their types
+			 * always match, but Psalm cannot correlate the two union types.
+			 *
+			 * @psalm-suppress PossiblyInvalidArgument
+			 */
+			$repository->save( $progress );
 		}
 
-		$formatted_date = gmdate( 'Y-m-d H:i:s', $date->getTimestamp() );
-		$updated        = (bool) update_comment_meta( $comment_id, 'start', $formatted_date, $date_started );
+		/**
+		 * Filters whether a student row was updated on the Students screen.
+		 *
+		 * Lets extensions persist additional date changes (e.g. course access dates) when a
+		 * student's dates are edited and report whether a change occurred so the row refreshes.
+		 *
+		 * @since $$next-version$$
+		 *
+		 * @hook sensei_students_row_updated
+		 *
+		 * @param {bool}   $started_at_changed Whether the start date was changed.
+		 * @param {int}    $post_id            Course or lesson ID.
+		 * @param {int}    $user_id            Student user ID.
+		 * @param {string} $post_type          Post type ('course' or 'lesson').
+		 * @return {bool} Whether the student row was updated.
+		 */
+		$updated = (bool) apply_filters( 'sensei_students_row_updated', $started_at_changed, $post_id, $user_id, $post_type );
 
 		/**
 		 * Filter sensei_learners_learner_updated
 		 *
-		 * This filter should return false if there was no update in the learner row.
+		 * @deprecated $$next-version$$ Use sensei_students_row_updated instead.
 		 *
-		 * @hook sensei_learners_learner_updated
-		 *
-		 * @param {bool} $updated    A flag indicating if there was an update in the learner row.
+		 * @param {bool} $updated    A flag indicating if there was an update in the student row.
 		 * @param {int}  $post_id    Lesson or course id.
-		 * @param {int}  $comment_id The comment id which tracks the progress of the learner.
+		 * @param {int}  $comment_id The comment id which tracks the progress of the student.
 		 * @return {bool} False if there were no updates.
 		 */
-		$updated = apply_filters( 'sensei_learners_learner_updated', $updated, $post_id, $comment_id );
+		$updated = (bool) apply_filters_deprecated( 'sensei_learners_learner_updated', array( $updated, $post_id, $progress->get_id() ), '$$next-version$$', 'sensei_students_row_updated' );
 
-		if ( false === $updated ) {
-			exit( '' );
+		if ( ! $updated ) {
+			wp_die();
 		}
 
-		exit( esc_html( $formatted_date ) );
+		wp_die( esc_html( $date->format( 'Y-m-d H:i:s' ) ) );
 	}
 
 	/**

includes/admin/class-sensei-learners-main.php

@@ -536,8 +536,16 @@ protected function get_row_data( $item ) {
 					$actions[] = $edit_start_date_form;
 				}
 
-				$date_started = get_comment_meta( $user_activity->comment_ID, 'start', true );
-				$date_input   = '<input class="edit-date-date-picker" data-name="start-date" type="text" value="' . esc_attr( $date_started ) . '">';
+				$student_progress = null;
+				if ( $post_id ) {
+					$progress_repository = 'course' === $post_type
+						? Sensei()->course_progress_repository_factory->create()
+						: Sensei()->lesson_progress_repository_factory->create();
+					$student_progress    = $progress_repository->get( (int) $post_id, $user_activity->user_id );
+				}
+				$student_started_at = $student_progress ? $student_progress->get_started_at() : null;
+				$date_started       = $student_started_at ? (string) wp_date( 'Y-m-d H:i:s', $student_started_at->getTimestamp() ) : '';
+				$date_input         = '<input class="edit-date-date-picker" data-name="start-date" type="text" value="' . esc_attr( $date_started ) . '">';
 
 				/**
 				 * Filter sensei_learners_main_column_data

includes/internal/student-progress/course-progress/models/class-course-progress-abstract.php

@@ -219,6 +219,19 @@ public function get_created_at(): DateTimeInterface {
 		return $this->created_at;
 	}
 
+	/**
+	 * Set the course start date.
+	 *
+	 * @internal
+	 *
+	 * @since $$next-version$$
+	 *
+	 * @param DateTimeInterface $started_at Course start date.
+	 */
+	public function set_started_at( DateTimeInterface $started_at ): void {
+		$this->started_at = $started_at;
+	}
+
 	/**
 	 * Set the course progress updated date.
 	 *

includes/internal/student-progress/course-progress/models/class-course-progress-interface.php

@@ -125,6 +125,17 @@ public function get_updated_at(): DateTimeInterface;
 	 */
 	public function get_created_at(): DateTimeInterface;
 
+	/**
+	 * Set the course start date.
+	 *
+	 * @internal
+	 *
+	 * @since $$next-version$$
+	 *
+	 * @param DateTimeInterface $started_at Course start date.
+	 */
+	public function set_started_at( DateTimeInterface $started_at ): void;
+
 	/**
 	 * Set the course progress updated date.
 	 *

includes/internal/student-progress/lesson-progress/models/class-lesson-progress-abstract.php

@@ -227,6 +227,19 @@ public function get_updated_at(): DateTimeInterface {
 		return $this->updated_at;
 	}
 
+	/**
+	 * Set the lesson start date.
+	 *
+	 * @internal
+	 *
+	 * @since $$next-version$$
+	 *
+	 * @param DateTimeInterface $started_at The start date.
+	 */
+	public function set_started_at( DateTimeInterface $started_at ): void {
+		$this->started_at = $started_at;
+	}
+
 	/**
 	 * Set lesson progress updated date.
 	 *

includes/internal/student-progress/lesson-progress/models/class-lesson-progress-interface.php

@@ -134,6 +134,17 @@ public function get_created_at(): DateTimeInterface;
 	 */
 	public function get_updated_at(): DateTimeInterface;
 
+	/**
+	 * Set the lesson start date.
+	 *
+	 * @internal
+	 *
+	 * @since $$next-version$$
+	 *
+	 * @param DateTimeInterface $started_at The start date.
+	 */
+	public function set_started_at( DateTimeInterface $started_at ): void;
+
 	/**
 	 * Set lesson progress updated date.
 	 *

tests/unit-tests/admin/test-class-sensei-learner-management.php

@@ -97,4 +97,87 @@ public function testAddNewLearners_ToLessonWhenCurrentUserIsNotTeacher_ReturnsFa
 		/* Assert. */
 		$this->assertFalse( $result );
 	}
+
+	/**
+	 * Tests that a valid start date edit is saved to the progress repository.
+	 *
+	 * @covers Sensei_Learner_Management::edit_date_started
+	 */
+	public function testEditDateStarted_ValidCourseDateGiven_SavesStartedAtToRepository() {
+		/* Arrange. */
+		wp_set_current_user( $this->factory->user->create( array( 'role' => 'administrator' ) ) );
+		$student_id = $this->factory->user->create();
+		$course_id  = $this->factory->course->create();
+		Sensei_Utils::user_start_course( $student_id, $course_id );
+
+		$start_date = '2024-01-15 10:30:00';
+
+		/* Act. */
+		$response = $this->invoke_edit_date_started(
+			array(
+				'post_id'   => $course_id,
+				'user_id'   => $student_id,
+				'new_dates' => array( 'start-date' => $start_date ),
+			)
+		);
+
+		/* Assert. */
+		$progress   = Sensei()->course_progress_repository_factory->create()->get( $course_id, $student_id );
+		$saved_date = wp_date( 'Y-m-d H:i:s', $progress->get_started_at()->getTimestamp(), wp_timezone() );
+		$this->assertSame( $start_date, $response, 'Response should be the formatted start date.' );
+		$this->assertSame( $start_date, $saved_date, 'Start date should be saved to the repository.' );
+	}
+
+	/**
+	 * Tests that submitting the same start date returns an empty response and does not report an update.
+	 *
+	 * @covers Sensei_Learner_Management::edit_date_started
+	 */
+	public function testEditDateStarted_UnchangedDateGiven_ReturnsEmptyResponse() {
+		/* Arrange. */
+		wp_set_current_user( $this->factory->user->create( array( 'role' => 'administrator' ) ) );
+		$student_id = $this->factory->user->create();
+		$course_id  = $this->factory->course->create();
+		Sensei_Utils::user_start_course( $student_id, $course_id );
+
+		$data = array(
+			'post_id'   => $course_id,
+			'user_id'   => $student_id,
+			'new_dates' => array( 'start-date' => '2024-01-15 10:30:00' ),
+		);
+		$this->invoke_edit_date_started( $data );
+
+		/* Act. */
+		$response = $this->invoke_edit_date_started( $data );
+
+		/* Assert. */
+		$this->assertSame( '', $response, 'Resubmitting the same date should return an empty response.' );
+	}
+
+	/**
+	 * Invokes the edit_date_started AJAX handler and returns the response body.
+	 *
+	 * The success and no-op paths exercised by these tests terminate via wp_die(), which the
+	 * test framework throws as WPDieException; this captures the emitted body and fails the
+	 * test if the handler returns without dying. (Validation-failure paths use exit and are
+	 * not exercised here.)
+	 *
+	 * @param array $data The POST data payload.
+	 *
+	 * @return string The response body emitted by the handler.
+	 */
+	private function invoke_edit_date_started( array $data ): string {
+		$nonce                = wp_create_nonce( 'edit_date_nonce' );
+		$_REQUEST['security'] = $nonce;
+		$_POST['security']    = $nonce;
+		$_POST['data']        = $data;
+
+		try {
+			$this->learner_management->edit_date_started();
+		} catch ( \WPDieException $e ) {
+			return $e->getMessage();
+		}
+
+		$this->fail( 'Expected edit_date_started() to call wp_die().' );
+	}
 }