Replacing lock-strict flag with lock-type enum for exam groups.

Author: krulis-martin

app/model/entity/Group.php

@@ -2,7 +2,7 @@
 
 namespace App\Model\Entity;
 
-use DateTime;
+use App\Model\GroupExamLockType;
 use Doctrine\Common\Collections\Collection;
 use Doctrine\Common\Collections\ReadableCollection;
 use Doctrine\Common\Collections\ArrayCollection;
@@ -11,6 +11,7 @@
 use Gedmo\Mapping\Annotation as Gedmo;
 use LogicException;
 use InvalidArgumentException;
+use DateTime;
 
 /**
  * @ORM\Entity
@@ -231,22 +232,25 @@ public function isDirectlyArchived(): bool
      * @ORM\Column(type="datetime", nullable=true)
      * When an exam in this groups begins. In the exam period, a user must lock in a group to be allowed
      * submitting solutions. This is completely independent of the isExam flag.
+     * @var DateTime|null
      */
     protected $examBegin = null;
 
     /**
      * @ORM\Column(type="datetime", nullable=true)
      * When an exam in this groups ends. In the exam period, a user must lock in a group to be allowed
      * submitting solutions. This is completely independent of the isExam flag.
+     * @var DateTime|null
      */
     protected $examEnd = null;
 
     /**
-     * @ORM\Column(type="boolean")
-     * Whether the group-lock for the exam should be strict
+     * @ORM\Column(type="string")
+     * The type of lock for the exam.
      * (under strict lock, the user cannot read data from other groups).
+     * @var string
      */
-    protected $examLockStrict = false;
+    protected $examLockType = GroupExamLockType::Visible->value;
 
     /**
      * @var Collection
@@ -260,9 +264,9 @@ public function isDirectlyArchived(): bool
      * Switch the group into an exam group by setting the begin and end dates of the exam.
      * @param DateTime $begin when the exam starts
      * @param DateTime $end when the exam ends
-     * @param bool $strict if true, locked users cannot access other groups (for reading)
+     * @param GroupExamLockType $type the type of lock for the exam
      */
-    public function setExamPeriod(DateTime $begin, DateTime $end, bool $strict = false): void
+    public function setExamPeriod(DateTime $begin, DateTime $end, GroupExamLockType $type): void
     {
         // asserts
         if ($begin >= $end) {
@@ -275,7 +279,7 @@ public function setExamPeriod(DateTime $begin, DateTime $end, bool $strict = fal
 
         $this->examBegin = $begin;
         $this->examEnd = $end;
-        $this->examLockStrict = $strict;
+        $this->examLockType = $type->value;
         $this->isOrganizational = false;
     }
 
@@ -286,7 +290,7 @@ public function removeExamPeriod(): void
     {
         $this->examBegin = null;
         $this->examEnd = null;
-        $this->examLockStrict = false;
+        $this->examLockType = GroupExamLockType::Visible->value;
     }
 
     /**
@@ -301,7 +305,12 @@ public function hasExamPeriodSet(?DateTime $at = null): bool
 
     public function isExamLockStrict(): bool
     {
-        return $this->examLockStrict;
+        return $this->examLockType === GroupExamLockType::Restricted->value;
+    }
+
+    public function getExamLockType(): GroupExamLockType
+    {
+        return GroupExamLockType::from($this->examLockType);
     }
 
     /**

app/model/entity/GroupExam.php

@@ -2,6 +2,7 @@
 
 namespace App\Model\Entity;
 
+use App\Model\GroupExamLockType;
 use Doctrine\ORM\Mapping as ORM;
 use DateTime;
 use JsonSerializable;
@@ -11,7 +12,7 @@
  * @ORM\Table(uniqueConstraints={@ORM\UniqueConstraint(columns={"group_id", "begin"})})
  * Holds history record of an exam that took place in a group.
  * The `examBegin`, `examEnd` fields are copied from group to `begin`, `end` fields here,
- * `examLockStrict` is copied to `lockStrict` field.
+ * `examLockType` is copied to `lockType` field.
  * This entity is created when the first user locks in (i.e., only exams with users are recorded in history).
  */
 class GroupExam implements JsonSerializable
@@ -20,58 +21,61 @@ class GroupExam implements JsonSerializable
      * @ORM\Id
      * @ORM\Column(type="integer")
      * @ORM\GeneratedValue(strategy="AUTO")
+     * @var int|null
      */
     protected $id;
 
     /**
      * @ORM\ManyToOne(targetEntity="Group", inversedBy="exams")
+     * @var Group
      */
     protected $group;
 
     /**
      * @ORM\Column(type="datetime")
-     * @var DateTime
+     * @var DateTime|null
      */
     protected $begin = null;
 
     /**
      * @ORM\Column(type="datetime")
-     * @var DateTime
+     * @var DateTime|null
      */
     protected $end = null;
 
     /**
-     * @ORM\Column(type="boolean")
-     * Saved value from examLockStrict flag.
+     * @ORM\Column(type="string")
+     * Saved value from examLockType flag.
+     * @var string
      */
-    protected $lockStrict = false;
+    protected $lockType = GroupExamLockType::Visible->value;
 
     /**
      * Constructor
      * @param Group $group
      * @param DateTime $begin
      * @param DateTime $end
-     * @param bool $strict
+     * @param GroupExamLockType $type
      */
-    public function __construct(Group $group, DateTime $begin, DateTime $end, bool $strict)
+    public function __construct(Group $group, DateTime $begin, DateTime $end, GroupExamLockType $type)
     {
         $this->group = $group;
         $this->begin = $begin;
         $this->end = $end;
-        $this->lockStrict = $strict;
+        $this->lockType = $type->value;
     }
 
     /**
      * Update the parameters (happens if pending exam is cut short, for instance).
      * @param DateTime $begin
      * @param DateTime $end
-     * @param bool $strict
+     * @param GroupExamLockType $type
      */
-    public function update(DateTime $begin, DateTime $end, bool $strict): void
+    public function update(DateTime $begin, DateTime $end, GroupExamLockType $type): void
     {
         $this->begin = $begin;
         $this->end = $end;
-        $this->lockStrict = $strict;
+        $this->lockType = $type->value;
     }
 
     public function jsonSerialize(): mixed
@@ -82,7 +86,9 @@ public function jsonSerialize(): mixed
             "groupId" => $group ? $group->getId() : null,
             "begin" => $this->getBegin()->getTimestamp(),
             "end" => $this->getEnd()->getTimestamp(),
-            "strict" => $this->lockStrict,
+            "type" => $this->lockType,
+            // BC only, DEPRECATED
+            "strict" => $this->lockType === GroupExamLockType::Restricted->value,
         ];
     }
 
@@ -113,6 +119,11 @@ public function getEnd(): DateTime
 
     public function isLockStrict(): bool
     {
-        return $this->lockStrict;
+        return $this->lockType === GroupExamLockType::Restricted->value;
+    }
+
+    public function getLockType(): GroupExamLockType
+    {
+        return GroupExamLockType::from($this->lockType);
     }
 }

app/model/entity/GroupExamLockType.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace App\Model;
+
+/**
+ * Defines the type of lock for a group exam.
+ * The lock type defines the level of access to the student's solutions previously submitted in other groups.
+ */
+enum GroupExamLockType: string
+{
+    /**
+     * No access to other groups.
+     */
+    case Restricted = 'restricted';
+
+    /**
+     * Solutions that were marked as accepted in other groups are visible.
+     */
+    case Accepted = 'accepted';
+
+    /**
+     * Solutions that were marked as accepted or reviewed in other groups are visible.
+     */
+    case Reviewed = 'reviewed';
+
+    /**
+     * All solutions from other groups are visible.
+     */
+    case Visible = 'visible';
+
+
+    public static function values(): array
+    {
+        return array_map(fn($case) => $case->value, self::cases());
+    }
+}

app/model/entity/User.php

@@ -2,6 +2,7 @@
 
 namespace App\Model\Entity;
 
+use App\Model\GroupExamLockType;
 use App\Security\Roles;
 use Doctrine\Common\Collections\Collection;
 use Doctrine\ORM\Mapping as ORM;
@@ -420,6 +421,7 @@ public function updateLastAuthenticationAt(?DateTime $time = null)
      * @ORM\Column(type="string", nullable=true)
      * IP address (either IPv4 or IPv6) the user is locked to. API requests from different addresses
      * will be treated as unauthorized.
+     * @var string|null
      */
     protected $ipLock = null;
 
@@ -499,13 +501,16 @@ public function verifyIpLock(string $currentIp): bool
      * @ORM\ManyToOne(targetEntity="Group")
      * If set, any user actions will be restricted to this group only.
      * (except for fundamental operations like listing groups or getting group name)
+     * @var Group|null
      */
     protected $groupLock = null;
 
     /**
-     * @ORM\Column(type="boolean")
+     * @ORM\Column(type="string")
+     * String representation of the GroupExamLockType enum (copied from the group exam).
+     * @var string
      */
-    protected $groupLockStrict = false;
+    protected $groupLockType = GroupExamLockType::Visible->value;
 
     /**
      * @ORM\Column(type="datetime", nullable=true)
@@ -528,7 +533,7 @@ public function isGroupLocked(): bool
      */
     public function isGroupLockStrict(): bool
     {
-        return $this->groupLockStrict;
+        return $this->groupLockType === GroupExamLockType::Restricted->value;
     }
 
     /**
@@ -548,9 +553,9 @@ public function getGroupLockExpiration(): ?DateTimeInterface
      * Lock the user within a group.
      * @param Group $group
      * @param DateTime|null $expiration of the lock, if null, the lock will never expire
-     * @param bool $strict if true, the user may not even access other groups for reading
+     * @param GroupExamLockType $type if true, the user may not even access other groups for reading
      */
-    public function setGroupLock(Group $group, ?DateTime $expiration = null, bool $strict = false): void
+    public function setGroupLock(Group $group, ?DateTime $expiration, GroupExamLockType $type): void
     {
         // basic asserts to be on the safe side
         if (!$group->hasExamPeriodSet()) {
@@ -562,14 +567,14 @@ public function setGroupLock(Group $group, ?DateTime $expiration = null, bool $s
 
         $this->groupLock = $group;
         $this->groupLockExpiration = $expiration;
-        $this->groupLockStrict = $strict;
+        $this->groupLockType = $type->value;
     }
 
     public function removeGroupLock(): void
     {
         $this->groupLock = null;
         $this->groupLockExpiration = null;
-        $this->groupLockStrict = false;
+        $this->groupLockType = GroupExamLockType::Visible->value;
     }
 
 

app/model/repository/GroupExams.php

@@ -4,6 +4,7 @@
 
 use App\Model\Entity\Group;
 use App\Model\Entity\GroupExam;
+use App\Model\GroupExamLockType;
 use Doctrine\ORM\EntityManagerInterface;
 use Doctrine\DBAL\Exception\UniqueConstraintViolationException;
 use DateTime;
@@ -45,10 +46,10 @@ public function findPendingForGroup(Group $group): ?GroupExam
      * @param Group $group
      * @param DateTime $begin
      * @param DateTime $end
-     * @param bool $strict
+     * @param GroupExamLockType $type
      * @return GroupExam|null
      */
-    private function tryFindOrCreate(Group $group, DateTime $begin, DateTime $end, bool $strict): ?GroupExam
+    private function tryFindOrCreate(Group $group, DateTime $begin, DateTime $end, GroupExamLockType $type): ?GroupExam
     {
         $exam = $this->findBy(["group" => $group, "begin" => $begin]);
         if (count($exam) > 1) {
@@ -58,12 +59,12 @@ private function tryFindOrCreate(Group $group, DateTime $begin, DateTime $end, b
         if (!$exam) {
             try {
                 $this->em->getConnection()->executeQuery(
-                    "INSERT INTO group_exam (group_id, begin, end, lock_strict) VALUES (:gid, :begin, :end, :strict)",
+                    "INSERT INTO group_exam (group_id, begin, end, lock_type) VALUES (:gid, :begin, :end, :type)",
                     [
                         'gid' => $group->getId(),
                         'begin' => $begin->format('Y-m-d H:i:s'),
                         'end' => $end->format('Y-m-d H:i:s'),
-                        'strict' => $strict ? 1 : 0
+                        'type' => $type->value
                     ]
                 );
             } catch (UniqueConstraintViolationException) {
@@ -82,21 +83,21 @@ private function tryFindOrCreate(Group $group, DateTime $begin, DateTime $end, b
      * @param Group $group
      * @param DateTime|null $begin if null, exam begin from the group is taken
      * @param DateTime|null $end if null, exam end from the group is taken
-     * @param bool|null $strict if null, examLockStrict value is taken
+     * @param GroupExamLockType|null $type if null, examLockType value is taken
      * @return GroupExam
      */
     public function findOrCreate(
         Group $group,
         ?DateTime $begin = null,
         ?DateTime $end = null,
-        ?bool $strict = null
+        ?GroupExamLockType $type = null
     ): GroupExam {
         $begin = $begin ?? $group->getExamBegin();
         $end = $end ?? $group->getExamEnd();
-        $strict = $strict === null ? $group->isExamLockStrict() : $strict;
+        $type = $type ?? $group->getExamLockType();
 
         for ($retries = 0; $retries < 3; $retries++) {
-            $exam = $this->tryFindOrCreate($group, $begin, $end, $strict);
+            $exam = $this->tryFindOrCreate($group, $begin, $end, $type);
             if ($exam !== null) {
                 return $exam;
             }