From ec6348943c4cb109b17e598258ff9cc728a2348d Mon Sep 17 00:00:00 2001
From: Michael O'Connell <moconnell@citylifestyle.com>
Date: Wed, 11 Oct 2023 11:04:27 -0500
Subject: [PATCH] introduce more enum classes and introduce a base enum class

---
 src/Enum/AlgebraicOperation.php               | 16 ++++++++++++++
 src/Enum/BaseEnum.php                         | 22 +++++++++++++++++++
 src/Enum/LookupPermissionship.php             | 16 ++++++++++++++
 src/Enum/Permissionship.php                   | 17 ++++++++------
 src/Enum/PreconditionOperation.php            | 15 +++++++++++++
 .../{Operation.php => UpdateOperation.php}    |  8 ++-----
 src/Model/AlgebraicSubjectSet.php             |  5 ++++-
 src/Model/LookupResourcesResponse.php         |  5 ++++-
 src/Model/LookupSubjectsResponse.php          |  5 ++++-
 src/Model/Precondition.php                    | 12 +++++++++-
 src/Model/RelationshipUpdate.php              | 22 +++++++------------
 src/Model/ResolvedSubject.php                 |  5 ++++-
 src/Model/SubjectReference.php                |  4 ----
 test/ClientTest.php                           |  6 ++---
 14 files changed, 119 insertions(+), 39 deletions(-)
 create mode 100644 src/Enum/AlgebraicOperation.php
 create mode 100644 src/Enum/BaseEnum.php
 create mode 100644 src/Enum/LookupPermissionship.php
 create mode 100644 src/Enum/PreconditionOperation.php
 rename src/Enum/{Operation.php => UpdateOperation.php} (70%)

diff --git a/src/Enum/AlgebraicOperation.php b/src/Enum/AlgebraicOperation.php
new file mode 100644
index 0000000..897df0b
--- /dev/null
+++ b/src/Enum/AlgebraicOperation.php
@@ -0,0 +1,16 @@
+<?php
+
+namespace Chiphpotle\Rest\Enum;
+
+
+final class AlgebraicOperation extends BaseEnum
+{
+    public const UNSPECIFIED = 'OPERATION_UNSPECIFIED';
+    public const UNION = 'OPERATION_UNION';
+    public const INTERSECTION = 'OPERATION_INTERSECTION';
+    public const EXCLUSION = 'OPERATION_EXCLUSION';
+    public static function allowableValues(): array
+    {
+        return [self::UNION, self::INTERSECTION, self::EXCLUSION];
+    }
+}
diff --git a/src/Enum/BaseEnum.php b/src/Enum/BaseEnum.php
new file mode 100644
index 0000000..f6aa9c9
--- /dev/null
+++ b/src/Enum/BaseEnum.php
@@ -0,0 +1,22 @@
+<?php
+
+namespace Chiphpotle\Rest\Enum;
+
+use Chiphpotle\Rest\Runtime\Normalizer\ValidationException;
+
+abstract class BaseEnum
+{
+    /**
+     * @return string[]
+     */
+    abstract public static function allowableValues(): array;
+
+    public static function validate(string $value): void
+    {
+        if (!in_array($value, static::allowableValues())) {
+            $class = get_called_class();
+            $shortClass = substr($class, strrpos($class, '\\') + 1);
+            throw new ValidationException("Invalid enum value for $shortClass");
+        }
+    }
+}
diff --git a/src/Enum/LookupPermissionship.php b/src/Enum/LookupPermissionship.php
new file mode 100644
index 0000000..f7dbede
--- /dev/null
+++ b/src/Enum/LookupPermissionship.php
@@ -0,0 +1,16 @@
+<?php
+
+namespace Chiphpotle\Rest\Enum;
+
+
+final class LookupPermissionship extends BaseEnum
+{
+    public const UNSPECIFIED = 'LOOKUP_PERMISSIONSHIP_UNSPECIFIED';
+    public const HAS_PERMISSION = 'LOOKUP_PERMISSIONSHIP_HAS_PERMISSION';
+    public const CONDITIONAL_PERMISSION = 'LOOKUP_PERMISSIONSHIP_CONDITIONAL_PERMISSION';
+
+    public static function allowableValues(): array
+    {
+        return [self::HAS_PERMISSION, self::CONDITIONAL_PERMISSION];
+    }
+}
diff --git a/src/Enum/Permissionship.php b/src/Enum/Permissionship.php
index 92df5bf..6b561ba 100644
--- a/src/Enum/Permissionship.php
+++ b/src/Enum/Permissionship.php
@@ -2,7 +2,11 @@
 
 namespace Chiphpotle\Rest\Enum;
 
-final class Permissionship
+/**
+ * Permissionship communicates whether or not the subject has the requested permission or has a relationship with the
+ * given resource, over the given relation.
+ */
+final class Permissionship extends BaseEnum
 {
     public const UNSPECIFIED = 'PERMISSIONSHIP_UNSPECIFIED';
 
@@ -10,15 +14,14 @@ final class Permissionship
 
     public const HAS_PERMISSION = 'PERMISSIONSHIP_HAS_PERMISSION';
 
-    /**
-     * @return string[]
-     */
-    public static function getAllowableEnumValues(): array
+    public const CONDITIONAL_PERMISSION = 'PERMISSIONSHIP_CONDITIONAL_PERMISSION';
+
+    public static function allowableValues(): array
     {
         return [
-            self::UNSPECIFIED,
             self::NO_PERMISSION,
-            self::HAS_PERMISSION
+            self::HAS_PERMISSION,
+            self::CONDITIONAL_PERMISSION
         ];
     }
 }
diff --git a/src/Enum/PreconditionOperation.php b/src/Enum/PreconditionOperation.php
new file mode 100644
index 0000000..51a4008
--- /dev/null
+++ b/src/Enum/PreconditionOperation.php
@@ -0,0 +1,15 @@
+<?php
+
+namespace Chiphpotle\Rest\Enum;
+
+final class PreconditionOperation extends BaseEnum
+{
+    public const UNSPECIFIED = 'OPERATION_UNSPECIFIED';
+    public const MUST_MATCH = 'OPERATION_MUST_MATCH';
+    public const MUST_NOT_MATCH = 'OPERATION_MUST_NOT_MATCH';
+
+    public static function allowableValues(): array
+    {
+        return [self::MUST_MATCH, self::MUST_NOT_MATCH];
+    }
+}
diff --git a/src/Enum/Operation.php b/src/Enum/UpdateOperation.php
similarity index 70%
rename from src/Enum/Operation.php
rename to src/Enum/UpdateOperation.php
index 6ebb118..afd7ca5 100644
--- a/src/Enum/Operation.php
+++ b/src/Enum/UpdateOperation.php
@@ -2,7 +2,7 @@
 
 namespace Chiphpotle\Rest\Enum;
 
-final class Operation
+final class UpdateOperation extends BaseEnum
 {
     public const UNSPECIFIED = 'OPERATION_UNSPECIFIED';
 
@@ -12,13 +12,9 @@ final class Operation
 
     public const DELETE = 'OPERATION_DELETE';
 
-    /**
-     * @return string[]
-     */
-    public static function getAllowableEnumValues(): array
+    public static function allowableValues(): array
     {
         return [
-            self::UNSPECIFIED,
             self::CREATE,
             self::TOUCH,
             self::DELETE
diff --git a/src/Model/AlgebraicSubjectSet.php b/src/Model/AlgebraicSubjectSet.php
index 874291e..c1d9033 100644
--- a/src/Model/AlgebraicSubjectSet.php
+++ b/src/Model/AlgebraicSubjectSet.php
@@ -2,6 +2,8 @@
 
 namespace Chiphpotle\Rest\Model;
 
+use Chiphpotle\Rest\Enum\AlgebraicOperation;
+
 /**
  * AlgebraicSubjectSet is a subject set which is computed based on applying the
  * specified operation to the operands according to the algebra of sets.
@@ -16,7 +18,7 @@
  */
 final class AlgebraicSubjectSet
 {
-    protected string $operation = 'OPERATION_UNSPECIFIED';
+    protected string $operation = AlgebraicOperation::UNSPECIFIED;
 
     /**
      * @var PermissionRelationshipTree[]
@@ -30,6 +32,7 @@ public function getOperation(): string
 
     public function setOperation(string $operation): self
     {
+        AlgebraicOperation::validate($operation);
         $this->operation = $operation;
         return $this;
     }
diff --git a/src/Model/LookupResourcesResponse.php b/src/Model/LookupResourcesResponse.php
index e1a5e57..19536c1 100644
--- a/src/Model/LookupResourcesResponse.php
+++ b/src/Model/LookupResourcesResponse.php
@@ -2,6 +2,8 @@
 
 namespace Chiphpotle\Rest\Model;
 
+use Chiphpotle\Rest\Enum\LookupPermissionship;
+
 /**
  * LookupResourcesResponse contains a single matching resource object ID for the
  * requested object type, permission, and subject.
@@ -12,7 +14,7 @@ final class LookupResourcesResponse
 
     protected string $resourceObjectId;
 
-    protected string $permissionship = 'LOOKUP_PERMISSIONSHIP_UNSPECIFIED';
+    protected string $permissionship = LookupPermissionship::UNSPECIFIED;
 
     protected PartialCaveatInfo $partialCaveatInfo;
 
@@ -47,6 +49,7 @@ public function getPermissionship(): string
 
     public function setPermissionship(string $permissionship): self
     {
+        LookupPermissionship::validate($permissionship);
         $this->permissionship = $permissionship;
         return $this;
     }
diff --git a/src/Model/LookupSubjectsResponse.php b/src/Model/LookupSubjectsResponse.php
index 2059c36..a2c86a2 100644
--- a/src/Model/LookupSubjectsResponse.php
+++ b/src/Model/LookupSubjectsResponse.php
@@ -2,6 +2,8 @@
 
 namespace Chiphpotle\Rest\Model;
 
+use Chiphpotle\Rest\Enum\LookupPermissionship;
+
 /**
  * LookupSubjectsResponse contains a single matching subject object ID for the
  * requested subject object type on the permission or relation.
@@ -18,7 +20,7 @@ final class LookupSubjectsResponse
 
     protected array $excludedSubjectIds;
 
-    protected string $permissionship = 'LOOKUP_PERMISSIONSHIP_UNSPECIFIED';
+    protected string $permissionship = LookupPermissionship::UNSPECIFIED;
 
     protected ?PartialCaveatInfo $partialCaveatInfo;
 
@@ -83,6 +85,7 @@ public function getPermissionship(): string
 
     public function setPermissionship(string $permissionship): self
     {
+        LookupPermissionship::validate($permissionship);
         $this->permissionship = $permissionship;
         return $this;
     }
diff --git a/src/Model/Precondition.php b/src/Model/Precondition.php
index f708ef9..fdcd7d9 100644
--- a/src/Model/Precondition.php
+++ b/src/Model/Precondition.php
@@ -2,9 +2,18 @@
 
 namespace Chiphpotle\Rest\Model;
 
+use Chiphpotle\Rest\Enum\PreconditionOperation;
+
+/**
+ * Precondition specifies how and the existence or absence of certain relationships as expressed through the
+ * accompanying filter should affect whether or not the operation proceeds.
+ *
+ * MUST_NOT_MATCH will fail the parent request if any relationships match the relationships filter.
+ * MUST_MATCH will fail the parent request if there are no relationships that match the filter.
+ */
 final class Precondition
 {
-    protected string $operation = 'OPERATION_UNSPECIFIED';
+    protected string $operation = PreconditionOperation::UNSPECIFIED;
 
     protected RelationshipFilter $filter;
 
@@ -15,6 +24,7 @@ public function getOperation(): string
 
     public function setOperation(string $operation): self
     {
+        PreconditionOperation::validate($operation);
         $this->operation = $operation;
         return $this;
     }
diff --git a/src/Model/RelationshipUpdate.php b/src/Model/RelationshipUpdate.php
index f22414a..e826fe1 100644
--- a/src/Model/RelationshipUpdate.php
+++ b/src/Model/RelationshipUpdate.php
@@ -2,44 +2,38 @@
 
 namespace Chiphpotle\Rest\Model;
 
-use Chiphpotle\Rest\Enum\Operation;
+use Chiphpotle\Rest\Enum\UpdateOperation;
 
 final class RelationshipUpdate
 {
-    protected string $operation = "OPERATION_UNSPECIFIED";
+    protected string $operation = UpdateOperation::UNSPECIFIED;
     protected Relationship $relationship;
 
     public function __construct(string $operation, Relationship $relationship)
     {
-        if (
-            !in_array(
-                $operation,
-                Operation::getAllowableEnumValues()
-            )
-        ) {
-            throw new \Exception("Invalid relationship update operation type");
-        }
+        UpdateOperation::validate($operation);
         $this->operation = $operation;
         $this->relationship = $relationship;
     }
 
-    public function getOperation(): ?string
+    public function getOperation(): string
     {
         return $this->operation;
     }
 
-    public function setOperation(?string $operation): self
+    public function setOperation(string $operation): self
     {
+        UpdateOperation::validate($operation);
         $this->operation = $operation;
         return $this;
     }
 
-    public function getRelationship(): ?Relationship
+    public function getRelationship(): Relationship
     {
         return $this->relationship;
     }
 
-    public function setRelationship(?Relationship $relationship): self
+    public function setRelationship(Relationship $relationship): self
     {
         $this->relationship = $relationship;
         return $this;
diff --git a/src/Model/ResolvedSubject.php b/src/Model/ResolvedSubject.php
index 05b4de1..05a2820 100644
--- a/src/Model/ResolvedSubject.php
+++ b/src/Model/ResolvedSubject.php
@@ -2,6 +2,8 @@
 
 namespace Chiphpotle\Rest\Model;
 
+use Chiphpotle\Rest\Enum\LookupPermissionship;
+
 /**
  * ResolvedSubject is a single subject resolved within LookupSubjects.
  */
@@ -15,7 +17,7 @@ final class ResolvedSubject
     */
     protected ?string $subjectObjectId;
 
-    protected string $permissionship = 'LOOKUP_PERMISSIONSHIP_UNSPECIFIED';
+    protected string $permissionship = LookupPermissionship::UNSPECIFIED;
 
     protected ?PartialCaveatInfo $partialCaveatInfo;
 
@@ -37,6 +39,7 @@ public function getPermissionship(): string
 
     public function setPermissionship(string $permissionship): self
     {
+        LookupPermissionship::validate($permissionship);
         $this->permissionship = $permissionship;
         return $this;
     }
diff --git a/src/Model/SubjectReference.php b/src/Model/SubjectReference.php
index 63b4a4e..539dd84 100644
--- a/src/Model/SubjectReference.php
+++ b/src/Model/SubjectReference.php
@@ -12,10 +12,6 @@ final class SubjectReference
 
     protected ?string $optionalRelation = null;
 
-    /**
-     * @param ObjectReference|null $object
-     * @param string|null $optionalRelation
-     */
     public function __construct(ObjectReference $object = null, ?string $optionalRelation = null)
     {
         $this->object = $object;
diff --git a/test/ClientTest.php b/test/ClientTest.php
index 46db860..e507c4e 100644
--- a/test/ClientTest.php
+++ b/test/ClientTest.php
@@ -3,7 +3,7 @@
 namespace Chiphpotle\Rest\Test;
 
 use Chiphpotle\Rest\Client;
-use Chiphpotle\Rest\Enum\Operation;
+use Chiphpotle\Rest\Enum\UpdateOperation;
 use Chiphpotle\Rest\Enum\Permissionship;
 use Chiphpotle\Rest\Model\BulkCheckPermissionRequest;
 use Chiphpotle\Rest\Model\BulkCheckPermissionRequestItem;
@@ -86,7 +86,7 @@ public function testRelationshipDelete()
             SubjectReference::create("user", "jimmy")
         );
         $update = new RelationshipUpdate(
-            Operation::DELETE,
+            UpdateOperation::DELETE,
             $relationship
         );
         $request = new WriteRelationshipsRequest([$update]);
@@ -311,7 +311,7 @@ private function writeRelationship(string $objectType, string $objectId, string
             $caveat
         );
         $update = new RelationshipUpdate(
-            Operation::TOUCH,
+            UpdateOperation::TOUCH,
             $relationship
         );
         $request = new WriteRelationshipsRequest([$update]);