Add inline object caching to HPPS repositories

AGENTS.md

@@ -35,6 +35,7 @@ Composer production dependencies that may conflict with other plugins are scoped
 
 - **CRITICAL: WordPress filters persist between test cases.** Always remove filters added during a test in `tearDown()` or the test will leak state into other tests.
 - **Use `assertSame()` over `assertEquals()`** — strict type + equality comparison.
+- **Use assertion messages when a test has multiple assertions** — pass the `$message` parameter to differentiate which assertion failed (e.g., `self::assertSame( 1, $id, 'ID should be 1' )`).
 - **Text domain is `sensei-lms`** (not `sensei`). All user-facing strings MUST use this.
 - **Never concatenate translatable strings** — use `sprintf()` with placeholders.
 - **Never use `extract()`, `eval()`, or `create_function()`.**
@@ -45,6 +46,7 @@ Composer production dependencies that may conflict with other plugins are scoped
 - **Branch naming**: `type/description` — e.g. `fix/course-average-query`, `add/show-tailored-course-outline`, `feature/ai-make-quiz`
 - **PRs**: Must reference an issue (`Resolves #123`), include testing instructions, and follow `.github/PULL_REQUEST_TEMPLATE.md`.
 - **Changelogs**: Every user-facing change MUST have a changelog entry before opening a PR. Run `npm run changelog` (entries stored in `changelog/`).
+- Use the `$$next-version$$` placeholder for the `@since` parameter.
 
 ## Boundaries
 

changelog/add-hpps-inline-caching

@@ -0,0 +1,4 @@
+Significance: minor
+Type: added
+
+Add object caching to HPPS (High-Performance Progress Storage) repositories

includes/internal/quiz-submission/answer/repositories/class-tables-based-answer-repository.php

@@ -9,6 +9,8 @@
 
 use DateTimeImmutable;
 use DateTimeZone;
+use Sensei\Internal\Cache_Prefix;
+use Sensei\Internal\Services\Progress_Storage_Settings;
 use Sensei\Internal\Quiz_Submission\Answer\Models\Answer_Interface;
 use Sensei\Internal\Quiz_Submission\Answer\Models\Tables_Based_Answer;
 use Sensei\Internal\Quiz_Submission\Submission\Models\Submission_Interface;
@@ -26,6 +28,17 @@
  * @since 4.16.1
  */
 class Tables_Based_Answer_Repository implements Answer_Repository_Interface {
+	use Cache_Prefix;
+
+	/**
+	 * Cache group for quiz answers.
+	 *
+	 * @since $$next-version$$
+	 *
+	 * @var string
+	 */
+	private const CACHE_GROUP = 'sensei_quiz_answers';
+
 	/**
 	 * WordPress database object.
 	 *
@@ -102,14 +115,21 @@ public function create( Submission_Interface $submission, int $question_id, stri
 			]
 		);
 
-		return new Tables_Based_Answer(
+		$answer = new Tables_Based_Answer(
 			$this->wpdb->insert_id,
 			$submission_id,
 			$question_id,
 			$value,
 			$current_datetime,
 			$current_datetime
 		);
+
+		if ( $this->wpdb->insert_id && Progress_Storage_Settings::is_cache_enabled() ) {
+			$cache_key = (string) $submission_id;
+			wp_cache_delete( self::get_prefixed_key( $cache_key, self::CACHE_GROUP ), self::CACHE_GROUP );
+		}
+
+		return $answer;
 	}
 
 	/**
@@ -135,6 +155,15 @@ public function get_all( int $submission_id ): array {
 		 */
 		$submission_id = (int) apply_filters( 'sensei_quiz_answer_get_all_submission_id', $submission_id, 'tables' );
 
+		$cache_key = (string) $submission_id;
+
+		if ( Progress_Storage_Settings::is_cache_enabled() ) {
+			$cached = wp_cache_get( self::get_prefixed_key( $cache_key, self::CACHE_GROUP ), self::CACHE_GROUP );
+			if ( false !== $cached ) {
+				return $cached;
+			}
+		}
+
 		$query = $this->wpdb->prepare(
 			// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
 			"SELECT * FROM {$this->get_table_name()} WHERE submission_id = %d",
@@ -154,6 +183,10 @@ public function get_all( int $submission_id ): array {
 			);
 		}
 
+		if ( Progress_Storage_Settings::is_cache_enabled() ) {
+			wp_cache_set( self::get_prefixed_key( $cache_key, self::CACHE_GROUP ), $answers, self::CACHE_GROUP );
+		}
+
 		return $answers;
 	}
 
@@ -187,6 +220,11 @@ public function delete_all( Submission_Interface $submission ): void {
 				'%d',
 			]
 		);
+
+		if ( Progress_Storage_Settings::is_cache_enabled() ) {
+			$cache_key = (string) $submission_id;
+			wp_cache_delete( self::get_prefixed_key( $cache_key, self::CACHE_GROUP ), self::CACHE_GROUP );
+		}
 	}
 
 	/**

includes/internal/quiz-submission/grade/repositories/class-tables-based-grade-repository.php

@@ -11,6 +11,8 @@
 	exit;
 }
 
+use Sensei\Internal\Cache_Prefix;
+use Sensei\Internal\Services\Progress_Storage_Settings;
 use Sensei\Internal\Quiz_Submission\Answer\Models\Answer_Interface;
 use Sensei\Internal\Quiz_Submission\Grade\Models\Tables_Based_Grade;
 use Sensei\Internal\Quiz_Submission\Grade\Models\Grade_Interface;
@@ -25,6 +27,17 @@
  * @since 4.16.1
  */
 class Tables_Based_Grade_Repository implements Grade_Repository_Interface {
+	use Cache_Prefix;
+
+	/**
+	 * Cache group for quiz grades.
+	 *
+	 * @since $$next-version$$
+	 *
+	 * @var string
+	 */
+	private const CACHE_GROUP = 'sensei_quiz_grades';
+
 	/**
 	 * WordPress database object.
 	 *
@@ -105,7 +118,7 @@ public function create( Submission_Interface $submission, Answer_Interface $answ
 			]
 		);
 
-		return new Tables_Based_Grade(
+		$grade = new Tables_Based_Grade(
 			$this->wpdb->insert_id,
 			$answer_id,
 			$question_id,
@@ -114,6 +127,13 @@ public function create( Submission_Interface $submission, Answer_Interface $answ
 			$current_date,
 			$current_date
 		);
+
+		if ( $this->wpdb->insert_id && Progress_Storage_Settings::is_cache_enabled() ) {
+			$cache_key = (string) $submission->get_id();
+			wp_cache_delete( self::get_prefixed_key( $cache_key, self::CACHE_GROUP ), self::CACHE_GROUP );
+		}
+
+		return $grade;
 	}
 
 	/**
@@ -139,8 +159,21 @@ public function get_all( int $submission_id ): array {
 		 */
 		$submission_id = (int) apply_filters( 'sensei_quiz_grade_get_all_submission_id', $submission_id, 'tables' );
 
+		$cache_key = (string) $submission_id;
+
+		if ( Progress_Storage_Settings::is_cache_enabled() ) {
+			$cached = wp_cache_get( self::get_prefixed_key( $cache_key, self::CACHE_GROUP ), self::CACHE_GROUP );
+			if ( false !== $cached ) {
+				return $cached;
+			}
+		}
+
 		$answer_ids = $this->get_answer_ids_by_submission_id( $submission_id );
 		if ( empty( $answer_ids ) ) {
+			if ( Progress_Storage_Settings::is_cache_enabled() ) {
+				wp_cache_set( self::get_prefixed_key( $cache_key, self::CACHE_GROUP ), array(), self::CACHE_GROUP );
+			}
+
 			return [];
 		}
 
@@ -162,6 +195,10 @@ public function get_all( int $submission_id ): array {
 			);
 		}
 
+		if ( Progress_Storage_Settings::is_cache_enabled() ) {
+			wp_cache_set( self::get_prefixed_key( $cache_key, self::CACHE_GROUP ), $grades, self::CACHE_GROUP );
+		}
+
 		return $grades;
 	}
 
@@ -177,6 +214,11 @@ public function save_many( Submission_Interface $submission, array $grades ): vo
 		foreach ( $grades as $grade ) {
 			$this->save( $grade );
 		}
+
+		if ( Progress_Storage_Settings::is_cache_enabled() ) {
+			$cache_key = (string) $submission->get_id();
+			wp_cache_delete( self::get_prefixed_key( $cache_key, self::CACHE_GROUP ), self::CACHE_GROUP );
+		}
 	}
 
 	/**
@@ -209,6 +251,11 @@ public function delete_all( Submission_Interface $submission ): void {
 		$delete_query = 'DELETE FROM ' . $this->get_table_name() . ' WHERE answer_id IN (' . $placeholders . ')';
 		// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared
 		$this->wpdb->query( $this->wpdb->prepare( $delete_query, ...$answer_ids ) );
+
+		if ( Progress_Storage_Settings::is_cache_enabled() ) {
+			$cache_key = (string) $submission_id;
+			wp_cache_delete( self::get_prefixed_key( $cache_key, self::CACHE_GROUP ), self::CACHE_GROUP );
+		}
 	}
 
 	/**
@@ -244,6 +291,7 @@ private function save( Grade_Interface $grade ): void {
 	 * Get all answer IDs for a submission.
 	 *
 	 * @param int $submission_id The submission ID.
+	 * @return array The answer IDs.
 	 */
 	private function get_answer_ids_by_submission_id( int $submission_id ): array {
 		$answers_query = $this->wpdb->prepare(

includes/internal/quiz-submission/submission/repositories/class-tables-based-submission-repository.php

@@ -9,6 +9,8 @@
 
 use DateTimeImmutable;
 use DateTimeZone;
+use Sensei\Internal\Cache_Prefix;
+use Sensei\Internal\Services\Progress_Storage_Settings;
 use Sensei\Internal\Quiz_Submission\Submission\Models\Submission_Interface;
 use Sensei\Internal\Quiz_Submission\Submission\Models\Tables_Based_Submission;
 use wpdb;
@@ -25,6 +27,17 @@
  * @since 4.16.1
  */
 class Tables_Based_Submission_Repository implements Submission_Repository_Interface {
+	use Cache_Prefix;
+
+	/**
+	 * Cache group for quiz submissions.
+	 *
+	 * @since $$next-version$$
+	 *
+	 * @var string
+	 */
+	private const CACHE_GROUP = 'sensei_quiz_submissions';
+
 	/**
 	 * WordPress database object.
 	 *
@@ -88,14 +101,21 @@ public function create( int $quiz_id, int $user_id, float $final_grade = null ):
 			]
 		);
 
-		return new Tables_Based_Submission(
+		$submission = new Tables_Based_Submission(
 			$this->wpdb->insert_id,
 			$quiz_id,
 			$user_id,
 			$final_grade,
 			$current_datetime,
 			$current_datetime
 		);
+
+		if ( $this->wpdb->insert_id && Progress_Storage_Settings::is_cache_enabled() ) {
+			$cache_key = $quiz_id . '_' . $user_id;
+			wp_cache_set( self::get_prefixed_key( $cache_key, self::CACHE_GROUP ), $submission, self::CACHE_GROUP );
+		}
+
+		return $submission;
 	}
 
 	/**
@@ -154,6 +174,15 @@ public function get( int $quiz_id, int $user_id ): ?Submission_Interface {
 		 */
 		$quiz_id = apply_filters( 'sensei_quiz_submission_get_quiz_id', $quiz_id );
 
+		$cache_key = $quiz_id . '_' . $user_id;
+
+		if ( Progress_Storage_Settings::is_cache_enabled() ) {
+			$cached = wp_cache_get( self::get_prefixed_key( $cache_key, self::CACHE_GROUP ), self::CACHE_GROUP );
+			if ( false !== $cached ) {
+				return self::$cache_not_found === $cached ? null : $cached;
+			}
+		}
+
 		$query = $this->wpdb->prepare(
 			// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
 			"SELECT * FROM {$this->get_table_name()} WHERE quiz_id = %d AND user_id = %d",
@@ -165,17 +194,27 @@ public function get( int $quiz_id, int $user_id ): ?Submission_Interface {
 		$row = $this->wpdb->get_row( $query );
 
 		if ( ! $row ) {
+			if ( Progress_Storage_Settings::is_cache_enabled() ) {
+				wp_cache_set( self::get_prefixed_key( $cache_key, self::CACHE_GROUP ), self::$cache_not_found, self::CACHE_GROUP );
+			}
+
 			return null;
 		}
 
-		return new Tables_Based_Submission(
+		$submission = new Tables_Based_Submission(
 			(int) $row->id,
 			(int) $row->quiz_id,
 			(int) $row->user_id,
 			$row->final_grade,
 			new DateTimeImmutable( $row->created_at, new DateTimeZone( 'UTC' ) ),
 			new DateTimeImmutable( $row->updated_at, new DateTimeZone( 'UTC' ) )
 		);
+
+		if ( Progress_Storage_Settings::is_cache_enabled() ) {
+			wp_cache_set( self::get_prefixed_key( $cache_key, self::CACHE_GROUP ), $submission, self::CACHE_GROUP );
+		}
+
+		return $submission;
 	}
 
 	/**
@@ -243,6 +282,11 @@ public function save( Submission_Interface $submission ): void {
 				'%d',
 			]
 		);
+
+		if ( Progress_Storage_Settings::is_cache_enabled() ) {
+			$cache_key = $submission->get_quiz_id() . '_' . $submission->get_user_id();
+			wp_cache_delete( self::get_prefixed_key( $cache_key, self::CACHE_GROUP ), self::CACHE_GROUP );
+		}
 	}
 
 	/**
@@ -264,6 +308,11 @@ public function delete( Submission_Interface $submission ): void {
 				'%d',
 			]
 		);
+
+		if ( Progress_Storage_Settings::is_cache_enabled() ) {
+			$cache_key = $submission->get_quiz_id() . '_' . $submission->get_user_id();
+			wp_cache_delete( self::get_prefixed_key( $cache_key, self::CACHE_GROUP ), self::CACHE_GROUP );
+		}
 	}
 
 	/**

includes/internal/services/class-progress-storage-settings.php

@@ -33,6 +33,13 @@ class Progress_Storage_Settings {
 	 */
 	public const TABLES_STORAGE = 'custom_tables';
 
+	/**
+	 * Memoized cache-enabled flag. Null means not yet computed.
+	 *
+	 * @var bool|null
+	 */
+	private static ?bool $cache_enabled = null;
+
 	/**
 	 * Get the storage repositories.
 	 *
@@ -89,4 +96,41 @@ public static function is_tables_repository(): bool {
 	public static function is_sync_enabled(): bool {
 		return Sensei()->settings->settings['experimental_progress_storage_synchronization'] ?? false;
 	}
+
+	/**
+	 * Returns true if HPPS caching is enabled.
+	 *
+	 * Defaults to true when using tables-based storage. Filterable via `sensei_hpps_cache_enabled`.
+	 *
+	 * @since $$next-version$$
+	 *
+	 * @return bool
+	 */
+	public static function is_cache_enabled(): bool {
+		if ( null === self::$cache_enabled ) {
+			/**
+			 * Filter whether HPPS caching is enabled.
+			 *
+			 * @hook sensei_hpps_cache_enabled
+			 *
+			 * @since $$next-version$$
+			 *
+			 * @param {bool} $enabled Whether caching is enabled.
+			 * @return {bool} Whether caching should be enabled.
+			 */
+			self::$cache_enabled = (bool) apply_filters( 'sensei_hpps_cache_enabled', self::is_tables_repository() );
+		}
+		return self::$cache_enabled;
+	}
+
+	/**
+	 * Reset the memoized cache-enabled flag. Useful for tests.
+	 *
+	 * @since $$next-version$$
+	 *
+	 * @internal
+	 */
+	public static function reset_cache_enabled(): void {
+		self::$cache_enabled = null;
+	}
 }