(REF) AuthorizeEvent - Extract AuthorizedTrait

The primary purpose of this is to provide a trait (`AuthorizedTrait`) to
describe the common semantics of of coarse-grained authorization check and
the upcoming fine-grained authorization check.

The extracted trait makes a few small changes:

* Change the default value from `FALSE` to `NULL`.  In grepping universe for
  consumers of `isAuthorized(0`, I could only find consumers that used
  bool-ish values.  So this should be the same for them.  However, for
  future cases, it will allow some distinction between NULL/FALSE.

* Use more type-hints. The type should be nullable-boolean.

* Mutators should be amenable to fluent style (e.g. `$event->authorize()->stopPropagation()`).

diff --git a/Civi/API/Event/AuthorizeEvent.php b/Civi/API/Event/AuthorizeEvent.php
index 9d146a9b40f6824976ff62101ba3b02d02c9f526..164677a01b241f6e327a5a0f218e1b3770a61188 100644 (file)
--- a/Civi/API/Event/AuthorizeEvent.php
+++ b/Civi/API/Event/AuthorizeEvent.php
@@ -22,24 +22,7 @@ namespace Civi\API\Event;
  * Event name: 'civi.api.authorize'
  */
 class AuthorizeEvent extends Event {
-  /**
-   * @var bool
-   */
-  private $authorized = FALSE;
 
-  /**
-   * Mark the request as authorized.
-   */
-  public function authorize() {
-    $this->authorized = TRUE;
-  }
-
-  /**
-   * @return bool
-   *   TRUE if the request has been authorized.
-   */
-  public function isAuthorized() {
-    return $this->authorized;
-  }
+  use AuthorizedTrait;
 
 }

diff --git a/Civi/API/Event/AuthorizedTrait.php b/Civi/API/Event/AuthorizedTrait.php
new file mode 100644 (file)
index 0000000..af3367a
--- /dev/null
+++ b/Civi/API/Event/AuthorizedTrait.php
@@ -0,0 +1,48 @@
+<?php
+
+namespace Civi\API\Event;
+
+/**
+ * Trait AuthorizedTrait
+ * @package Civi\API\Event
+ */
+trait AuthorizedTrait {
+
+  /**
+   * @var bool|null
+   *   - TRUE: The action is explicitly authorized.
+   *   - FALSE: The action is explicitly prohibited.
+   *   - NULL: The authorization status has not been determined.
+   */
+  private $authorized = NULL;
+
+  /**
+   * Mark the request as authorized.
+   *
+   * @return static
+   */
+  public function authorize() {
+    $this->authorized = TRUE;
+    return $this;
+  }
+
+  /**
+   * @return bool|null
+   *   TRUE if the request has been authorized.
+   */
+  public function isAuthorized(): ?bool {
+    return $this->authorized;
+  }
+
+  /**
+   * Change the authorization status.
+   *
+   * @param bool|null $authorized
+   * @return static
+   */
+  public function setAuthorized(?bool $authorized) {
+    $this->authorized = $authorized;
+    return $this;
+  }
+
+}