<?php
/**
* File containing the Tables_Based_Submission_Repository class.
*
* @package sensei
*/
namespace Sensei\Internal\Quiz_Submission\Submission\Repositories;
use DateTimeImmutable;
use DateTimeZone;
use Sensei\Internal\Cache_Prefix;
use Sensei\Internal\Persistence_Exception;
use Sensei\Internal\Quiz_Submission\Answer\Repositories\Tables_Based_Answer_Repository;
use Sensei\Internal\Quiz_Submission\Grade\Repositories\Tables_Based_Grade_Repository;
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;
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Class Tables_Based_Submission_Repository.
*
* @internal
*
* @since 4.16.1
*/
class Tables_Based_Submission_Repository implements Submission_Repository_Interface {
use Cache_Prefix;
/**
* Cache group for quiz submissions.
*
* @since 4.26.0
*
* @var string
*/
private const CACHE_GROUP = 'sensei_quiz_submissions';
/**
* WordPress database object.
*
* @var wpdb
*/
private $wpdb;
/**
* Constructor.
*
* @internal
*
* @param wpdb $wpdb WordPress database object.
*/
public function __construct( wpdb $wpdb ) {
$this->wpdb = $wpdb;
}
/**
* Creates a new quiz submission.
*
* @internal
*
* @param int $quiz_id The quiz ID.
* @param int $user_id The user ID.
* @param float|null $final_grade The final grade.
*
* @return Submission_Interface The quiz submission.
* @throws \Sensei\Internal\Persistence_Exception If required quiz data cannot be persisted.
*/
public function create( int $quiz_id, int $user_id, ?float $final_grade = null ): Submission_Interface {
/**
* Filters the quiz ID when quiz submission is created.
*
* @hook sensei_quiz_submission_create_quiz_id
*
* @since 4.23.1
*
* @param {int} $quiz_id The quiz ID.
* @return {int} The quiz ID.
*/
$quiz_id = (int) apply_filters( 'sensei_quiz_submission_create_quiz_id', $quiz_id );
$current_datetime = new DateTimeImmutable( 'now', new DateTimeZone( 'UTC' ) );
$date_format = 'Y-m-d H:i:s';
$result = $this->wpdb->insert(
$this->get_table_name(),
[
'quiz_id' => $quiz_id,
'user_id' => $user_id,
'final_grade' => $final_grade,
'created_at' => $current_datetime->format( $date_format ),
'updated_at' => $current_datetime->format( $date_format ),
],
[
'%d',
'%d',
is_null( $final_grade ) ? null : '%f',
'%s',
'%s',
]
);
if ( false === $result ) {
// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- Safe persistence diagnostics.
throw new Persistence_Exception(
'quiz_submission',
'tables',
// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- Exception context contains numeric IDs.
$quiz_id,
// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- Exception context contains numeric IDs.
$user_id,
'insert_failed'
);
}
$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() ) {
wp_cache_set( self::get_prefixed_key( $this->get_cache_key( $quiz_id, $user_id ), self::CACHE_GROUP ), $submission, self::CACHE_GROUP );
}
return $submission;
}
/**
* Get or create a new quiz submission if it doesn't exist.
*
* @internal
*
* @param int $quiz_id The quiz ID.
* @param int $user_id The user ID.
* @param float|null $final_grade The final grade.
*
* @return Submission_Interface The quiz submission.
* @throws \Sensei\Internal\Persistence_Exception If required quiz data cannot be persisted.
*/
public function get_or_create( int $quiz_id, int $user_id, ?float $final_grade = null ): Submission_Interface {
/**
* Filters the quiz ID when quiz submission is created.
*
* @hook sensei_quiz_submission_get_or_create_quiz_id
*
* @since 4.23.1
*
* @param {int} $quiz_id The quiz ID.
* @return {int} The quiz ID.
*/
$quiz_id = (int) apply_filters( 'sensei_quiz_submission_get_or_create_quiz_id', $quiz_id );
$submission = $this->get( $quiz_id, $user_id );
if ( $submission ) {
return $submission;
}
return $this->create( $quiz_id, $user_id, $final_grade );
}
/**
* Gets a quiz submission.
*
* @internal
*
* @param int $quiz_id The quiz ID.
* @param int $user_id The user ID.
*
* @return Submission_Interface|null The quiz submission.
*/
public function get( int $quiz_id, int $user_id ): ?Submission_Interface {
/**
* Filters the quiz ID when quiz submission is retrieved.
*
* @hook sensei_quiz_submission_get_quiz_id
*
* @since 4.23.1
*
* @param {int} $quiz_id The quiz ID.
* @return {int} The quiz ID.
*/
$quiz_id = (int) apply_filters( 'sensei_quiz_submission_get_quiz_id', $quiz_id );
$cache_key = $this->get_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",
$quiz_id,
$user_id
);
// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared
$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;
}
$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;
}
/**
* Get the questions related to the quiz submission.
*
* @internal
*
* @param int $submission_id The quiz submission ID.
*
* @return array An array of question post IDs.
*/
public function get_question_ids( int $submission_id ): array {
/**
* Filters the quiz submission ID when question IDs are retrieved.
*
* @hook sensei_quiz_submission_get_question_ids_submission_id
*
* @since 4.23.1
*
* @param {int} $submission_id The quiz submission ID.
* @param {string} $context The context.
* @return {int} The quiz submission ID.
*/
$submission_id = apply_filters( 'sensei_quiz_submission_get_question_ids_submission_id', $submission_id, 'tables' );
$quiz_answers_table = $this->wpdb->prefix . 'sensei_lms_quiz_answers';
$query = $this->wpdb->prepare(
// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
"SELECT question_id FROM {$quiz_answers_table} WHERE submission_id = %d ORDER BY id ASC",
$submission_id
);
// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared
$question_ids = $this->wpdb->get_col( $query );
return array_map( 'intval', $question_ids );
}
/**
* Save quiz submission.
*
* @internal
*
* @param Submission_Interface $submission The quiz submission.
* @throws \Sensei\Internal\Persistence_Exception If required quiz data cannot be persisted.
*/
public function save( Submission_Interface $submission ): void {
$updated_at = new DateTimeImmutable( 'now', new DateTimeZone( 'UTC' ) );
$submission->set_updated_at( $updated_at );
$result = $this->wpdb->update(
$this->get_table_name(),
[
'final_grade' => $submission->get_final_grade(),
'updated_at' => $submission->get_updated_at()->format( 'Y-m-d H:i:s' ),
],
[
'id' => $submission->get_id(),
],
[
is_null( $submission->get_final_grade() ) ? null : '%f',
'%s',
],
[
'%d',
]
);
if ( Progress_Storage_Settings::is_cache_enabled() ) {
wp_cache_delete( self::get_prefixed_key( $this->get_cache_key( $submission->get_quiz_id(), $submission->get_user_id() ), self::CACHE_GROUP ), self::CACHE_GROUP );
}
if ( false === $result ) {
// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- Safe persistence diagnostics.
throw new Persistence_Exception( 'quiz_submission', 'tables', $submission->get_quiz_id(), $submission->get_user_id(), 'update_failed', 'save' );
}
}
/**
* Delete the quiz submission.
*
* @internal
*
* @param Submission_Interface $submission The quiz submission.
* @throws Persistence_Exception If the submission row cannot be deleted.
*/
public function delete( Submission_Interface $submission ): void {
$result = $this->wpdb->delete(
$this->get_table_name(),
[
'quiz_id' => $submission->get_quiz_id(),
'user_id' => $submission->get_user_id(),
],
[
'%d',
'%d',
]
);
if ( false === $result ) {
// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- Exception messages contain safe diagnostics and are not rendered.
throw new Persistence_Exception( 'quiz_submission', 'tables', $submission->get_quiz_id(), $submission->get_user_id(), 'delete_failed', 'delete' );
}
if ( Progress_Storage_Settings::is_cache_enabled() ) {
wp_cache_delete( self::get_prefixed_key( $this->get_cache_key( $submission->get_quiz_id(), $submission->get_user_id() ), self::CACHE_GROUP ), self::CACHE_GROUP );
}
}
/**
* Delete a student's submission and its grades and answers for one quiz.
*
* @internal
* @since $$next-version$$
*
* @param int $quiz_id The quiz ID.
* @param int $user_id The student ID.
* @throws Persistence_Exception If required data cannot be deleted.
*/
public function delete_for_student( int $quiz_id, int $user_id ): void {
$submission = $this->get( $quiz_id, $user_id );
if ( ! $submission ) {
return;
}
( new Tables_Based_Grade_Repository( $this->wpdb ) )->delete_all( $submission );
( new Tables_Based_Answer_Repository( $this->wpdb ) )->delete_all( $submission );
$this->delete( $submission );
}
/**
* Delete every student's submission, grades, and answers for one quiz.
*
* @internal
* @since $$next-version$$
*
* @param int $quiz_id The quiz ID.
* @throws Persistence_Exception If submissions cannot be read or required data cannot be deleted.
*/
public function delete_for_quiz( int $quiz_id ): void {
$query = $this->wpdb->prepare( 'SELECT user_id FROM %i WHERE quiz_id = %d', $this->get_table_name(), $quiz_id );
// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- Prepared with placeholders above.
$result = $this->wpdb->query( $query );
if ( false === $result ) {
// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- Safe persistence diagnostics.
throw new Persistence_Exception( 'quiz_submission', 'tables', $quiz_id, 0, 'lookup_failed', 'delete' );
}
// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- Read the successful SELECT above without running another query.
$user_ids = $this->wpdb->get_col( null );
foreach ( $user_ids as $user_id ) {
$this->delete_for_student( $quiz_id, (int) $user_id );
}
}
/**
* Get the cache key for a quiz submission.
*
* @since 4.26.0
*
* @param int $quiz_id The quiz ID.
* @param int $user_id The user ID.
* @return string The cache key.
*/
private function get_cache_key( int $quiz_id, int $user_id ): string {
return $quiz_id . '_' . $user_id;
}
/**
* Get the quiz submission table name.
*
* @return string
*/
private function get_table_name(): string {
return $this->wpdb->prefix . 'sensei_lms_quiz_submissions';
}
}