Files
myep-team/src/Entity/QuestionnaireResponse.php
T

214 lines
6.2 KiB
PHP

<?php
namespace App\Entity;
use App\Entity\Traits\BlameableEntity;
use App\Entity\Traits\TimestampableEntity;
use App\Enum\BusLeg;
use App\Enum\QuestionnaireResponseStatus;
use App\Model\Questionnaire\Definition;
use App\Repository\QuestionnaireResponseRepository;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Uid\Uuid;
/**
* One respondent's answers to one questionnaire (config/questionnaires/), a draft until submitted.
*
* Answers are keyed by question key and only mean something together with the definition of
* $questionnaire in $version. $context holds what the subject already knew - for a disposition,
* who, where, when and the escort pickup - so those questions are not asked and the response stays
* readable when the assignment is edited later.
*
* A per-bus-leg questionnaire (Definition::$perBusLeg) has one response per escorted leg, the
* others one per disposition.
*
* Its subject is a Disposition today. A questionnaire about something else gets a nullable foreign
* key of its own beside $disposition, not a generic subject column.
*
* Not soft-deletable: nothing in the UI deletes a response, and it goes with its disposition.
*/
#[ORM\Entity(repositoryClass: QuestionnaireResponseRepository::class)]
#[ORM\HasLifecycleCallbacks]
#[ORM\UniqueConstraint(name: 'questionnaire_disposition_leg', columns: ['questionnaire', 'disposition_id', 'leg'])]
class QuestionnaireResponse implements BlameableEntityInterface, TimestampableEntityInterface
{
use BlameableEntity;
use TimestampableEntity;
#[ORM\Id]
#[ORM\GeneratedValue]
#[ORM\Column]
private ?int $id = null;
#[ORM\Column(type: 'string', length: 36, unique: true)]
private string $uuid;
#[ORM\Column(length: 64)]
private string $questionnaire;
#[ORM\Column]
private int $version;
#[ORM\Column(length: 16, enumType: QuestionnaireResponseStatus::class)]
private QuestionnaireResponseStatus $status = QuestionnaireResponseStatus::DRAFT;
#[ORM\Column(nullable: true)]
private ?\DateTimeImmutable $submittedAt = null;
/**
* @var array<string, mixed>
*/
#[ORM\Column(type: Types::JSON)]
private array $answers = [];
/**
* @var array<string, mixed>
*/
#[ORM\Column(type: Types::JSON)]
private array $context = [];
#[ORM\ManyToOne]
#[ORM\JoinColumn(onDelete: 'CASCADE')]
private ?Disposition $disposition = null;
/**
* A BusLeg value, or '' for a questionnaire without legs rather than null: part of the unique
* key, and MariaDB lets NULLs repeat in one.
*/
#[ORM\Column(length: 16, options: ['default' => ''])]
private string $leg = '';
private function __construct(Definition $definition)
{
$this->uuid = Uuid::v4();
$this->questionnaire = $definition->key;
$this->version = $definition->version;
}
/**
* @param BusLeg|null $leg required for a per-bus-leg questionnaire, refused for any other
*/
public static function forDisposition(Definition $definition, Disposition $disposition, ?BusLeg $leg = null): static
{
if ($definition->perBusLeg !== (null !== $leg)) {
throw new \LogicException(sprintf('Questionnaire "%s" %s a bus leg', $definition->key, $definition->perBusLeg ? 'needs' : 'takes no'));
}
$instance = new static($definition);
$instance->disposition = $disposition;
$instance->leg = $leg->value ?? '';
return $instance;
}
/**
* Keeps every answer, including those to questions that are hidden right now: switching an
* answer back restores the follow-up already written.
*
* @param array<string, mixed> $answers
* @param array<string, mixed> $context
*/
public function saveDraft(array $answers, array $context): static
{
$this->assertDraft();
$this->answers = $answers;
$this->context = $context;
return $this;
}
/**
* Final. Keeps only the answers to questions that are shown, and records the definition version
* they were given under - the draft may have been started under an older one.
*
* @param array<string, mixed> $answers
* @param array<string, mixed> $context
*/
public function submit(Definition $definition, array $answers, array $context, \DateTimeImmutable $now): static
{
$this->assertDraft();
if ($definition->key !== $this->questionnaire) {
throw new \LogicException(sprintf('Response to "%s" cannot be submitted with "%s"', $this->questionnaire, $definition->key));
}
$this->answers = $definition->withoutHiddenAnswers($answers);
$this->context = $context;
$this->version = $definition->version;
$this->status = QuestionnaireResponseStatus::SUBMITTED;
$this->submittedAt = $now;
return $this;
}
public function isSubmitted(): bool
{
return QuestionnaireResponseStatus::SUBMITTED === $this->status;
}
public function getId(): ?int
{
return $this->id;
}
public function getUuid(): string
{
return $this->uuid;
}
public function getQuestionnaire(): string
{
return $this->questionnaire;
}
public function getVersion(): int
{
return $this->version;
}
public function getStatus(): QuestionnaireResponseStatus
{
return $this->status;
}
public function getSubmittedAt(): ?\DateTimeImmutable
{
return $this->submittedAt;
}
/**
* @return array<string, mixed>
*/
public function getAnswers(): array
{
return $this->answers;
}
/**
* @return array<string, mixed>
*/
public function getContext(): array
{
return $this->context;
}
public function getDisposition(): ?Disposition
{
return $this->disposition;
}
public function getLeg(): ?BusLeg
{
return BusLeg::tryFrom($this->leg);
}
private function assertDraft(): void
{
if ($this->isSubmitted()) {
throw new \LogicException(sprintf('Questionnaire response %s is already submitted', $this->uuid));
}
}
}