authx - Tighten up names and docs for the PHP interface

ext/authx/Civi/Authx/UfInterface.php → ext/authx/Civi/Authx/AuthxInterface.php

@@ -11,37 +11,55 @@
 
 namespace Civi\Authx;
 
-interface UfInterface {
+/**
+ * Interface AuthxInterface
+ * @package Civi\Authx
+ *
+ * Each user-framework (Drupal, Joomla, etc) has a slightly different set of
+ * methods for authenticating users and establishing a login. Provide an
+ * implementation of this interface for each user-framework.
+ *
+ * This is conceptually similar to some methods in `CRM_Utils_System_*`,
+ * but with less sadism.
+ */
+interface AuthxInterface {
 
   /**
    * Determine if the password is correct for the user.
    *
    * @param string $username
+   *   The symbolic username known to the user.
    * @param string $password
+   *   The plaintext secret which identifies this user.
    *
-   * @return int|null
-   *   The UF user ID which has been successfully identified.
+   * @return int|string|NULL
+   *   If the password is correct, this returns the internal user ID.
+   *   If the password is incorrect (or if passwords are not supported), it returns NULL.
    */
   public function checkPassword(string $username, string $password);
 
   /**
    * Set the active user the in the CMS, binding the user ID durably to the session.
    *
    * @param int|string $userId
+   *   The UF's internal user ID.
    */
   public function loginSession($userId);
 
   /**
    * Set the active user the in the CMS -- but do *not* start a session.
    *
    * @param int|string $userId
+   *   The UF's internal user ID.
    */
   public function loginStateless($userId);
 
   /**
+   * Determine which (if any) user is currently logged in.
+   *
    * @return int|string|NULL
+   *   The UF's internal user ID for the active user.
    *   NULL indicates anonymous (not logged into CMS).
-   *   An int or string indicates an active user.
    */
   public function getCurrentUserId();
 

ext/authx/Civi/Authx/Drupal.php

@@ -11,27 +11,36 @@
 
 namespace Civi\Authx;
 
-class Drupal implements UfInterface {
+class Drupal implements AuthxInterface {
 
+  /**
+   * @inheritDoc
+   */
   public function checkPassword(string $username, string $password) {
     $uid = user_authenticate($username, $password);
     // Ensure strict nullness.
     return $uid ? $uid : NULL;
   }
 
+  /**
+   * @inheritDoc
+   */
   public function loginSession($userId) {
     global $user;
     $user = user_load($userId);
     user_login_finalize();
   }
 
+  /**
+   * @inheritDoc
+   */
   public function loginStateless($userId) {
     global $user;
     $user = user_load($userId);
   }
 
   /**
-   * @return int|string|NULL
+   * @inheritDoc
    */
   public function getCurrentUserId() {
     global $user;

ext/authx/Civi/Authx/None.php

@@ -11,16 +11,32 @@
 
 namespace Civi\Authx;
 
-class None implements UfInterface {
+class None implements AuthxInterface {
 
+  /**
+   * @inheritDoc
+   */
   public function checkPassword(string $username, string $password) {
     return NULL;
   }
 
-  public function loginSession($contactId, $userId, bool $useSession) {
+  /**
+   * @inheritDoc
+   */
+  public function loginSession($userId) {
     throw new \Exception("Cannot login: Unrecognized user framework");
   }
 
+  /**
+   * @inheritDoc
+   */
+  public function loginStateless($userId) {
+    throw new \Exception("Cannot login: Unrecognized user framework");
+  }
+
+  /**
+   * @inheritDoc
+   */
   public function getCurrentUserId() {
     throw new \Exception("Cannot determine active user: Unrecognized user framework");
   }

ext/authx/Civi/Authx/WordPress.php

@@ -11,8 +11,11 @@
 
 namespace Civi\Authx;
 
-class WordPress implements UfInterface {
+class WordPress implements AuthxInterface {
 
+  /**
+   * @inheritDoc
+   */
   public function checkPassword(string $username, string $password) {
     $user = wp_authenticate($username, $password);
     if (is_wp_error($user)) {
@@ -21,6 +24,9 @@ public function checkPassword(string $username, string $password) {
     return $user->ID;
   }
 
+  /**
+   * @inheritDoc
+   */
   public function loginSession($userId) {
     // We use wp_signon() to try to fire any session-related events.
     // Note that we've already authenticated the user, so we filter 'authenticate'
@@ -39,10 +45,16 @@ public function loginSession($userId) {
     }
   }
 
+  /**
+   * @inheritDoc
+   */
   public function loginStateless($userId) {
     wp_set_current_user($userId);
   }
 
+  /**
+   * @inheritDoc
+   */
   public function getCurrentUserId() {
     $id = \get_current_user_id();
     return empty($id) ? NULL : $id;

ext/authx/authx.php

@@ -29,7 +29,7 @@
 });
 
 /**
- * @return \Civi\Authx\UfInterface
+ * @return \Civi\Authx\AuthxInterface
  */
 function _authx_uf() {
   $class = 'Civi\\Authx\\' . CIVICRM_UF;