Clean up phpDoc and change the Identity driver so only one configuration can be active at a given time.

5 files changed, 87 insertions, 174 deletions

diff --git a/modules/gallery/helpers/group.php b/modules/gallery/helpers/group.php
index 17dd7f70..b87ed248 100644
--- a/modules/gallery/helpers/group.php
+++ b/modules/gallery/helpers/group.php
@@ -58,28 +58,21 @@ class group_Core {
   }
 
   /**
-   * Create a new group.
-   *
-   * @param string  $name
-   * @return Group_Core
+   * @see Identity_Driver::create.
    */
   static function create($name) {
     return Identity::instance()->create_group($name);
   }
 
   /**
-   * The group of all possible visitors.  This includes the guest user.
-   *
-   * @return Group_Core
+   * @see Identity_Driver::everbody.
    */
   static function everybody() {
     return Identity::instance()->everybody();
   }
 
   /**
-   * The group of all logged-in visitors.  This does not include guest users.
-   *
-   * @return Group_Core
+   * @see Identity_Driver::registered_users.
    */
   static function registered_users() {
     return Identity::instance()->everybody();
@@ -88,7 +81,7 @@ class group_Core {
   /**
    * Look up a group by id.
    * @param integer      $id the user id
-   * @return Group_Model  the group object, or null if the id was invalid.
+   * @return Group_Definition  the group object, or null if the id was invalid.
    */
   static function lookup($id) {
     return Identity::instance()->lookup_group_by_field("id", $id);
@@ -97,25 +90,21 @@ class group_Core {
   /**
    * Look up a group by name.
    * @param integer      $id the group name
-   * @return Group_Core  the group object, or null if the name was invalid.
+   * @return Group_Definition  the group object, or null if the name was invalid.
    */
   static function lookup_by_name($name) {
     return Identity::instance()->lookup_group_by_field("name", $name);
   }
 
   /**
-   * List the groups
-   * @param mixed      options to apply to the selection of the user (@see Database.php)
-   * @return array     the group list.
+   * @see Identity_Driver::get_group_list.
    */
   static function get_group_list($filter=array()) {
     return Identity::instance()->get_group_list($filter);
   }
 
   /**
-   * Return the edit rules associated with an group.
-   *
-   * @return stdClass containing the rules
+   * @see Identity_Driver::get_edit_rules.
    */
   static function get_edit_rules() {
     return Identity::instance()->get_edit_rules("group");
diff --git a/modules/gallery/helpers/user.php b/modules/gallery/helpers/user.php
index 84a29efc..f09e963e 100644
--- a/modules/gallery/helpers/user.php
+++ b/modules/gallery/helpers/user.php
@@ -246,43 +246,28 @@ class user_Core {
   }
 
   /**
-   * Return the guest user.
-   *
-   * @todo consider caching
-   *
-   * @return User_Model
+   * @see Identity_Driver::guest.
    */
-  static function guest() {
+static function guest() {
     return Identity::instance()->guest();
   }
 
   /**
-   * Create a new user.
-   *
-   * @param string  $name
-   * @param string  $full_name
-   * @param string  $password
-   * @return User_Model
+   * @see Identity_Driver::create_user.
    */
   static function create($name, $full_name, $password) {
     return Identity::instance()->create_user($name, $full_name, $password);
   }
 
   /**
-   * Is the password provided correct?
-   *
-   * @param user User Model
-   * @param string $password a plaintext password
-   * @return boolean true if the password is correct
+   * @see Identity_Driver::is_correct_password.
    */
   static function is_correct_password($user, $password) {
     return Identity::instance()->is_correct_password($user, $password);
   }
 
   /**
-   * Create the hashed passwords.
-   * @param string $password a plaintext password
-   * @return string hashed password
+   * @see Identity_Driver::hash_password.
    */
   static function hash_password($password) {
     return Identity::instance()->hash_password($password);
@@ -291,7 +276,7 @@ class user_Core {
   /**
    * Look up a user by id.
    * @param integer      $id the user id
-   * @return User_Model  the user object, or null if the id was invalid.
+   * @return User_Definition  the user object, or null if the id was invalid.
    */
   static function lookup($id) {
     return Identity::instance()->lookup_user_by_field("id", $id);
@@ -300,35 +285,30 @@ class user_Core {
   /**
    * Look up a user by name.
    * @param integer      $name the user name
-   * @return User_Model  the user object, or null if the name was invalid.
+   * @return User_Definition  the user object, or null if the name was invalid.
    */
   static function lookup_by_name($name) {
     return Identity::instance()->lookup_user_by_field("name", $name);
   }
 
-
   /**
    * Look up a user by hash.
    * @param string       $name the user name
-   * @return User_Model  the user object, or null if the name was invalid.
+   * @return User_Definition  the user object, or null if the name was invalid.
    */
   static function lookup_by_hash($hash) {
     return Identity::instance()->lookup_user_by_field("hash", $hash);
   }
 
   /**
-   * List the users
-   * @param mixed      options to apply to the selection of the user(optional)
-   * @return array     the group list.
+   * @see Identity_Driver::get_user_list.
    */
   static function get_user_list($filter=array()) {
     return Identity::instance()->get_user_list($filter);
   }
 
   /**
-   * Return the edit rules associated with an user.
-   *
-   * @return stdClass containing the rules
+   * @see Identity_Driver::get_edit_rules.
    */
   static function get_edit_rules() {
     return Identity::instance()->get_edit_rules("user");
diff --git a/modules/gallery/libraries/Identity.php b/modules/gallery/libraries/Identity.php
index 488cc535..88865913 100644
--- a/modules/gallery/libraries/Identity.php
+++ b/modules/gallery/libraries/Identity.php
@@ -22,7 +22,7 @@
  * Provides a driver-based interface for managing users and groups.
  */
 class Identity_Core {
-  protected static $instances = array();
+  protected static $instances;
 
   // Configuration
   protected $config;
@@ -32,17 +32,18 @@ class Identity_Core {
 
   /**
    * Returns a singleton instance of Identity.
+   * There can only be one Identity driver configured at a given point
    *
    * @param   string  configuration
    * @return  Identity_Core
    */
   static function & instance($config="default") {
-   if (!isset(Identity::$instances[$config])) {
+   if (!isset(Identity::$instances)) {
       // Create a new instance
-      Identity::$instances[$config] = new Identity($config);
+      Identity::$instances = new Identity($config);
     }
 
-    return Identity::$instances[$config];
+    return Identity::$instances;
   }
 
   /**
@@ -93,10 +94,9 @@ class Identity_Core {
   }
 
   /**
-   * Determine if a feature is supported by the driver.
+   * Determine if if the current driver supports updates.
    *
-   * @param  string  $feature the name of the feature to check
-   * @return boolean true if supported
+   * @return boolean true if the driver supports updates; false if read only
    */
   public function is_writable() {
     return !empty($this->config["allow_updates"]);
@@ -104,118 +104,84 @@ class Identity_Core {
 
 
   /**
-   * Return the guest user.
-   *
-   * @todo consider caching
-   *
-   * @return Identity_Model
+   * @see Identity_Driver::guest.
    */
   public function guest() {
     return $this->driver->guest();
   }
 
   /**
-   * Create a new user.
-   *
-   * @param string  $name
-   * @param string  $full_name
-   * @param string  $password
-   * @return Identity_Model
+   * @see Identity_Driver::create_user.
    */
   public function create_user($name, $full_name, $password) {
     return $this->driver->create_user($name, $full_name, $password);
   }
 
   /**
-   * Is the password provided correct?
-   *
-   * @param user Identity Model
-   * @param string $password a plaintext password
-   * @return boolean true if the password is correct
+   * @see Identity_Driver::is_correct_password.
    */
   public function is_correct_password($user, $password) {
     return $this->driver->is_correct_password($user, $password);
   }
 
   /**
-   * Create the hashed passwords.
-   * @param string $password a plaintext password
-   * @return string hashed password
+   * @see Identity_Driver::hash_password.
    */
   public function hash_password($password) {
     return $this->driver->hash_password($password);
   }
 
   /**
-   * Look up a user by field value.
-   * @param string      search field
-   * @param string      search value
-   * @return Identity_Model  the user object, or null if the name was invalid.
+   * @see Identity_Driver::lookup_user_by_field.
    */
   public function lookup_user_by_field($field_name, $value) {
     return $this->driver->lookup_user_by_field($field_name, $value);
   }
 
   /**
-   * Create a new group.
-   *
-   * @param string  $name
-   * @return Group_Model
+   * @see Identity_Driver::create_group.
    */
   public function create_group($name) {
     return $this->driver->create_group($name);
   }
 
   /**
-   * The group of all possible visitors.  This includes the guest user.
-   *
-   * @return Group_Model
+   * @see Identity_Driver::everybody.
    */
   public function everybody() {
     return $this->driver->everybody();
   }
 
   /**
-   * The group of all logged-in visitors.  This does not include guest users.
-   *
-   * @return Group_Model
+   * @see Identity_Driver::registered_users.
    */
   public function registered_users() {
     return $this->driver->everybody();
   }
 
   /**
-   * Look up a group by name.
-   * @param integer      $id the group name
-   * @return Group_Model  the group object, or null if the name was invalid.
+   * @see Identity_Driver::lookup_group_by_field.
    */
   public function lookup_group_by_field($field_name, $value) {
     return $this->driver->lookup_group_by_field($field_name, $value);
   }
 
   /**
-   * List the users
-   * @param mixed      options to apply to the selection of the user
-   * @return array     the group list.
+   * @see Identity_Driver::get_user_list.
    */
   public function get_user_list($filter=array()) {
     return $this->driver->get_user_list($filter);
   }
 
   /**
-   * List the groups
-   * @param mixed      options to apply to the selection of the user
-   * @return array     the group list.
+   * @see Identity_Driver::get_group_list.
    */
   public function get_group_list($filter=array()) {
     return $this->driver->get_group_list($filter);
   }
 
   /**
-   * Return the edit rules associated with an group.
-   *
-   * @param  string   $object_type to return rules for ("user"|"group")
-   * @return stdClass containing the rules
+   * @see Identity_Driver::get_edit_rules.
    */
   public function get_edit_rules($object_type) {
     return $this->driver->get_edit_rules($object_type);
diff --git a/modules/gallery/libraries/drivers/Identity.php b/modules/gallery/libraries/drivers/Identity.php
index ca80aad5..0b789908 100644
--- a/modules/gallery/libraries/drivers/Identity.php
+++ b/modules/gallery/libraries/drivers/Identity.php
@@ -21,9 +21,7 @@ interface Identity_Driver {
   /**
    * Return the guest user.
    *
-   * @todo consider caching
-   *
-   * @return User_Model
+   * @return User_Definition the user object
    */
   public function guest();
 
@@ -33,14 +31,14 @@ interface Identity_Driver {
    * @param string  $name
    * @param string  $full_name
    * @param string  $password
-   * @return User_Core
+   * @return User_Definition the user object
    */
   public function create_user($name, $full_name, $password);
 
   /**
    * Is the password provided correct?
    *
-   * @param user User Model
+   * @param user User_Definition the user object
    * @param string $password a plaintext password
    * @return boolean true if the password is correct
    */
@@ -57,7 +55,7 @@ interface Identity_Driver {
    * Look up a user by by search the specified field.
    * @param string      search field
    * @param string      search value
-   * @return User_Core  the user object, or null if the name was invalid.
+   * @return User_Definition the user object, or null if the name was invalid.
    */
   public function lookup_user_by_field($field, $value);
 
@@ -65,28 +63,33 @@ interface Identity_Driver {
    * Create a new group.
    *
    * @param string  $name
-   * @return Group_Model
+   * @return Group_Definition the group object
    */
   public function create_group($name);
 
   /**
    * The group of all possible visitors.  This includes the guest user.
    *
-   * @return Group_Model
+   * @return Group_Definition the group object
    */
   public function everybody();
 
   /**
    * The group of all logged-in visitors.  This does not include guest users.
    *
-   * @return Group_Model
+   * @return Group_Definition the group object
    */
   public function registered_users();
 
   /**
    * List the users
    * @param mixed      options to apply to the selection of the user
-   *                   @todo Do a longer write up on format of filters (@see Database.php)
+   *                   currently supported:
+   *                     "orderby" => array(<field name>, "ASC|DESC")
+   *                     "in" => array(<field name>, array(values, ...))
+   *                     "where" => array(<field name>, value)
+   *                        <field name> follows Kohana syntax where it could contain the first
+   *                                     half of a logical expression (i.e. "field IS NOT")
    * @return array     the group list.
    */
   public function get_user_list($filter=array());
@@ -94,7 +97,12 @@ interface Identity_Driver {
   /**
    * List the groups
    * @param mixed      options to apply to the selection of the group
-   *                   @todo Do a longer write up on format of filters (@see Database.php)
+   *                   currently supported:
+   *                     "orderby" => array(<field name>, "ASC|DESC")
+   *                     "in" => array(<field name>, array(values, ...))
+   *                     "where" => array(<field name>, value)
+   *                        <field name> follows Kohana syntax where it could contain the first
+   *                                     half of a logical expression (i.e. "field IS NOT")
    * @return array     the group list.
    */
   public function get_group_list($filter=array());
@@ -128,10 +136,8 @@ abstract class User_Definition {
     case "url":
     case "locale":
     case "groups":
-      return $this->user->$column;
     case "hashed_password":
-      throw new Exception("@todo WRITE ONLY FIELD: $column");
-      break;
+      return $this->user->$column;
     default:
       throw new Exception("@todo UNSUPPORTED FIELD: $column");
       break;
@@ -185,10 +191,9 @@ abstract class User_Definition {
     case "hash":
     case "url":
     case "locale":
+    case "hashed_password":
       unset($this->user->$column);
       break;
-    case "hashed_password":
-      throw new Exception("@todo WRITE ONLY FIELD: $column");
     default:
       throw new Exception("@todo UNSUPPORTED FIELD: $column");
       break;
@@ -214,7 +219,12 @@ abstract class User_Definition {
     return empty($this->user->full_name) ? $this->user->name : $this->user->full_name;
   }
 
-  public function uncloaked() {
+  /**
+   * Return the internal user object without the wrapper.
+   * This method is used by implementing classes to access the internal user object.
+   * Consider it pseudo private and only declared public as PHP as not internal or friend modifier
+   */
+  public function _uncloaked() {
     return $this->user;
   }
 
@@ -275,7 +285,12 @@ abstract class Group_Definition {
     }
   }
 
-  public function uncloaked() {
+  /**
+   * Return the internal group object without the wrapper.
+   * This method is used by implementing classes to access the internal group object.
+   * Consider it pseudo private and only declared public as PHP as not internal or friend modifier
+   */
+  public function _uncloaked() {
     return $this->group;
   }
 
diff --git a/modules/user/libraries/drivers/Identity/Gallery.php b/modules/user/libraries/drivers/Identity/Gallery.php
index f631bd63..013497b6 100644
--- a/modules/user/libraries/drivers/Identity/Gallery.php
+++ b/modules/user/libraries/drivers/Identity/Gallery.php
@@ -22,23 +22,14 @@
  */
 class Identity_Gallery_Driver implements Identity_Driver {
   /**
-   * Return the guest user.
-   *
-   * @todo consider caching
-   *
-   * @return User_Model
+   * @see Identity_Driver::guest.
    */
   public function guest() {
     return new Gallery_User(model_cache::get("user", 1));
   }
 
   /**
-   * Create a new user.
-   *
-   * @param string  $name
-   * @param string  $full_name
-   * @param string  $password
-   * @return User_Model
+   * @see Identity_Driver::create_user.
    */
   public function create_user($name, $full_name, $password) {
     $user = ORM::factory("user")->where("name", $name)->find();
@@ -51,19 +42,15 @@ class Identity_Gallery_Driver implements Identity_Driver {
     $user->password = $password;
 
     // Required groups
-    $user->add($this->everybody()->uncloaked());
-    $user->add($this->registered_users()->uncloaked());
+    $user->add($this->everybody()->_uncloaked());
+    $user->add($this->registered_users()->_uncloaked());
 
     $user->save();
     return new Gallery_User($user);
   }
 
   /**
-   * Is the password provided correct?
-   *
-   * @param user User Model
-   * @param string $password a plaintext password
-   * @return boolean true if the password is correct
+   * @see Identity_Driver::is_correct_password.
    */
   public function is_correct_password($user, $password) {
     $valid = $user->password;
@@ -94,9 +81,7 @@ class Identity_Gallery_Driver implements Identity_Driver {
   }
 
   /**
-   * Create the hashed passwords.
-   * @param string $password a plaintext password
-   * @return string hashed password
+   * @see Identity_Driver::hash_password.
    */
   public function hash_password($password) {
     require_once(MODPATH . "user/lib/PasswordHash.php");
@@ -105,10 +90,7 @@ class Identity_Gallery_Driver implements Identity_Driver {
   }
 
   /**
-   * Look up a user by field value.
-   * @param string      search field
-   * @param string      search value
-   * @return User_Core  the user object, or null if the name was invalid.
+   * @see Identity_Driver::lookup_user_by_field.
    */
   public function lookup_user_by_field($field_name, $value) {
     try {
@@ -125,10 +107,7 @@ class Identity_Gallery_Driver implements Identity_Driver {
   }
 
   /**
-   * Create a new group.
-   *
-   * @param string  $name
-   * @return Group_Model
+   * @see Identity_Driver::create_group.
    */
   public function create_group($name) {
     $group = ORM::factory("group")->where("name", $name)->find();
@@ -143,33 +122,26 @@ class Identity_Gallery_Driver implements Identity_Driver {
   }
 
   /**
-   * The group of all possible visitors.  This includes the guest user.
-   *
-   * @return Group_Model
+   * @see Identity_Driver::everybody.
    */
   public function everybody() {
     return new Gallery_Group(model_cache::get("group", 1));
   }
 
   /**
-   * The group of all logged-in visitors.  This does not include guest users.
-   *
-   * @return Group_Model
+   * @see Identity_Driver::registered_users.
    */
   public function registered_users() {
     return new Gallery_Group(model_cache::get("group", 2));
   }
 
   /**
-   * Look up a group by field value.
-   * @param string      search field
-   * @param string      search value
-   * @return Group_Core  the group object, or null if the name was invalid.
+   * @see Identity_Driver::lookup_group_by_field.
    */
   public function lookup_group_by_field($field_name, $value) {
     try {
-      $user = model_cache::get("group", $value, $field_name);
-      if ($user->loaded) {
+      $group = model_cache::get("group", $value, $field_name);
+      if ($group->loaded) {
         return new Gallery_Group($group);
       }
     } catch (Exception $e) {
@@ -180,11 +152,8 @@ class Identity_Gallery_Driver implements Identity_Driver {
     return null;
   }
 
-
   /**
-   * List the users
-   * @param mixed      options to apply to the selection of the user
-   * @return array     the group list.
+   * @see Identity_Driver::get_user_list.
    */
   public function get_user_list($filter=array()) {
     $results = $this->_do_search("user", $filter);
@@ -195,11 +164,8 @@ class Identity_Gallery_Driver implements Identity_Driver {
     return $users;
   }
 
-
   /**
-   * List the groups
-   * @param mixed      options to apply to the selection of the group
-   * @return array     the group list.
+   * @see Identity_Driver::get_group_list.
    */
   public function get_group_list($filter=array()) {
     $results = $this->_do_search("group", $filter);
@@ -211,10 +177,7 @@ class Identity_Gallery_Driver implements Identity_Driver {
   }
 
   /**
-   * Return the edit rules associated with an group.
-   *
-   * @param  string   $object_type to return rules for ("user"|"group")
-   * @return stdClass containing the rules
+   * @see Identity_Driver::get_edit_rules.
    */
   public function get_edit_rules($object_type) {
     return (object)ORM::factory($object_type)->rules;
@@ -284,10 +247,10 @@ class Gallery_Group extends Group_Definition {
   }
 
   public function add($user) {
-    $this->group->add($user->uncloaked());
+    $this->group->add($user->_uncloaked());
   }
 
   public function remove($user) {
-    $this->group->remove($user->uncloaked());
+    $this->group->remove($user->_uncloaked());
   }
 }