quiz-6.0.0-alpha4/src/QuizAnswerInterface.php

<?php

namespace Drupal\quiz;

use Drupal\quiz\Entity\QuizQuestion;
use Drupal\quiz\Entity\QuizQuestionRelationship;
use Drupal\quiz\Entity\QuizResult;

/**
 * Provides an interface for quiz answers.
 *
 * Each question type must store its own answer data and be able to calculate
 * a score for that data.
 */
interface QuizAnswerInterface {

  /**
   * Get the question of this question answer.
   *
   * @return \Drupal\quiz\Entity\QuizQuestion
   *   Question to the answer.
   */
  public function getQuizQuestion(): QuizQuestion;

  /**
   * Get the result of this question response.
   *
   * @return \Drupal\quiz\Entity\QuizResult
   *   Result of the question response.
   */
  public function getQuizResult(): QuizResult;

  /**
   * Get the result ID of this question response.
   *
   * @return int
   *   Quiz result ID.
   */
  public function getQuizResultId(): int;

  /**
   * Indicate whether the response has been evaluated (scored) yet.
   *
   * Questions that require human scoring (e.g. essays) may need to manually
   * toggle this.
   *
   * @return bool
   *   If the response has been scored.
   */
  public function isEvaluated(): bool;

  /**
   * Check to see if the answer is marked as correct.
   *
   * This default version returns TRUE if the score is equal to the maximum
   * possible score. Each question type can determine on its own if the question
   * response is "correct". For example a multiple choice question with 4
   * correct answers could be considered correct in different configurations.
   *
   * @return bool
   *   If the answer to the question is correct.
   */
  public function isCorrect(): bool;

  /**
   * Get the scaled awarded points.
   *
   * @return int
   *   The user's scaled awarded points for this question.
   */
  public function getPoints(): int;

  /**
   * Get the related question relationship from this quiz result answer.
   *
   * @return \Drupal\quiz\Entity\QuizQuestionRelationship|null
   *   Relationship between question and answer. NULL if relationship
   *   doesn't exist.
   */
  public function getQuestionRelationship(): ?QuizQuestionRelationship;

  /**
   * Get the weighted max score of this question response.
   *
   * This is the score that is entered on the manage questions screen.
   * For example if a multiple choice question is worth 4 points, but 8 points
   * are entered on the manage questions screen, 8 points is returned here.
   *
   * @return int
   *   The weighted max score of this question response.
   */
  public function getMaxScore(): int;

  /**
   * Creates the report form for the admin pages.
   *
   * @return array
   *   A renderable FAPI array
   */
  public function getReportForm(): array;

  /**
   * Get the response part of the report form.
   *
   * @return array
   *   Array of response data, with each item being an answer to a response. For
   *   an example, see MultichoiceResponse::getFeedbackValues(). The sub items
   *   are keyed by the feedback type. Providing a NULL option means that
   *   feedback will not be shown. See an example at
   *   LongAnswerResponse::getFeedbackValues().
   */
  public function getFeedbackValues(): array;

  /**
   * Calculate the unscaled score in points for this question response.
   *
   * @param array $values
   *   A part of form state values with the question input from the user.
   *
   * @return int|null
   *   The unscaled point value of the answer. If a point value is final,
   *   questions should make sure to run setEvaluated(). return NULL if the
   *   answer is not automatically scored.
   */
  public function score(array $values): ?int;

  /**
   * Get the user's response.
   *
   * @return mixed
   *   The answer given by the user
   */
  public function getResponse();

  /**
   * Can the quiz taker view the requested review?
   *
   * @param string $option
   *   An option key.
   *
   * @return bool
   *   If the quiz can be viewed.
   */
  public function canReview(string $option): bool;

  /**
   * Get the weighted score ratio.
   *
   * This returns the ratio of the weighted score of this question versus the
   * question score. For example, if the question is worth 10 points in the
   * associated quiz, but it is a 3 point multichoice question, the weighted
   * ratio is 3.33.
   *
   * This is marked as final to make sure that no question overrides this and
   * causes reporting issues.
   *
   * @return float|int
   *   The weight of the question
   */
  public function getWeightedRatio(): float|int;

  /**
   * Indicate whether the response has been evaluated (scored) yet.
   *
   * Questions that require human scoring (e.g. essays) may need to manually
   * toggle this.
   *
   * @return bool
   *   If the response has been scored.
   */
  public function isAnswered(): bool;

  /**
   * Indicate if the question was marked as skipped.
   *
   * @return bool
   *   If the question is supposed to be skipped.
   */
  public function isSkipped(): bool;

  /**
   * Set that the answer has been evaluated.
   *
   * If the point value is final and does not require instructor action.
   *
   * @param bool $evaluated
   *   If the answer is evaluated.
   *
   * @return $this
   */
  public function setEvaluated(bool $evaluated = TRUE);

  /**
   * Get answers for a question in a result.
   *
   * This static method assists in building views for the mass export of
   * question answers.
   *
   * It is not as easy as instantiating all the question responses and returning
   * the answer. To do this in views at scale we have to gather the data
   * carefully.
   *
   * This base method provides a very poor way of gathering the data.
   *
   * @see views_handler_field_prerender_list
   *
   * @see MultichoiceResponse::viewsGetAnswers()
   * @see TrueFalseResponse::viewsGetAnswers()
   */
  public static function viewsGetAnswers(array $result_answer_ids = []): array;

}