class.UserManager.php

Go to the documentation of this file.

<?php
/**
 * wCMF - wemove Content Management Framework
 * Copyright (C) 2005-2014 wemove digital solutions GmbH
 *
 * Licensed under the terms of any of the following licenses
 * at your choice:
 *
 * - GNU Lesser General Public License (LGPL)
 *   http://www.gnu.org/licenses/lgpl.html
 * - Eclipse Public License (EPL)
 *   http://www.eclipse.org/org/documents/epl-v10.php
 *
 * See the license.txt file distributed with this work for
 * additional information.
 *
 * $Id: class.UserManager.php 1462 2014-02-04 23:52:27Z iherwig $
 */
require_once(BASE."wcmf/lib/core/class.WCMFException.php");
require_once(BASE."wcmf/lib/util/class.Message.php");
require_once(BASE."wcmf/lib/persistence/class.PersistenceFacade.php");
require_once(BASE."wcmf/lib/util/class.InifileParser.php");

/**
 * Some constants describing user properties
 */
define("USER_PROPERTY_LOGIN", "login");
define("USER_PROPERTY_NAME", "name");
define("USER_PROPERTY_FIRSTNAME", "firstname");
define("USER_PROPERTY_CONFIG", "config");
define("ROLE_PROPERTY_NAME", "name");

/**
 * @class UserManager
 * @ingroup Security
 * @brief UserManager is used to edit users and roles.
 *        UserManager supports the following operations:
 *        - create/remove a user
 *        - create/remove a role
 *        - add/remove a user to/from a role
 *        - change a users password
 *
 * This class defines abstract methods that subclasses must implement to support
 * different user repositories. The UserManager implementation class is defined by
 * the configuration key 'UserManager' in the [implementation] section.
 *
 * @todo - Use RightsManager to restrict access to methods (except changePassword)
 *       - Transaction support
 *
 * @author      ingo herwig <ingo@wemove.com>
 */
class UserManager
{
  var $_initParams = null;
  var $_userRepository = null;
  var $_roleConfig = null;

  /**
   * Creates a UserManager Object.
   * @param params Initialization data given in an associative array as needed to load the user repository
   */
  function UserManager($params)
  {
    $this->_initParams = $params;
    $this->_userRepository = $this->initialize($this->_initParams);

    // load role config if existing
    $parser = &InifileParser::getInstance();
    if (($roleConfig = $parser->getSection('roleconfig')) !== false) {
      $this->_roleConfig = $roleConfig;
    }
  }

  /**
   * Encrypt a password using the md5 algorithm.
   * @param password The password to encrypt
   * @return The encrypted password.
   */
  function encryptPassword($password)
  {
    return md5($password);
  }

  /**
   * Internal error method. Rollback transaction and call WCMFException::throwEx.
   */
  function onError($message, $file='', $line='')
  {
    $this->rollbackTransaction();
    WCMFException::throwEx($message, $file, $line);
  }

  /**
   * Start a transaction. If implemented, the UserManager will collect a number of actions
   * and execute them on commitTransaction().
   * If not implemented the UserManager will execute these actions on every call of the appropriate function.
   */
  function startTransaction() {}

  /**
   * Commit a transaction. If implemented, the UserManager will execute a number of actions
   * that it collected since the call to startTransaction().
   * If not implemented the UserManager will execute these actions on every call of the appropriate function.
   */
  function commitTransaction() {}

  /**
   * Rollback a transaction. If implemented, the UserManager will rollback a number of actions
   * that it collected since the call to startTransaction().
   * If not implemented the UserManager will execute these actions on every call of the appropriate function.
   */
  function rollbackTransaction() {}

  /**
   * Create a user login with a given password.
   * @param name The name of the user
   * @param firstname The first name of the user
   * @param login The login of the user
   * @param password The password of the user
   * @param passwordRepeated The password of the user again
   * @return A reference to the created user.
   */
  function &createUser($name, $firstname, $login, $password, $passwordRepeated)
  {
    if ($password != $passwordRepeated) {
      $this->onError(Message::get("The given passwords don't match"), __FILE__, __LINE__);
    }
    if ($login == '') {
      $this->onError(Message::get("The user requires a login name"), __FILE__, __LINE__);
    }
    if ($this->getUser($login) != null) {
      $this->onError(Message::get("The login '%1%' already exists", array($login)), __FILE__, __LINE__);
    }
    // encrypt password
    $password = $this->encryptPassword($password);

    $user = &$this->createUserImpl($name, $firstname, $login, $password);

    // update user repository
    $this->_userRepository['users'][sizeof($this->_userRepository['users'])] = &$user;

    return $user;
  }

  /**
   * Remove a user login.
   * @param login The login of the user
   */
  function removeUser($login)
  {
    if (($user = $this->getUser($login)) == null) {
      $this->onError(Message::get("The login '%1%' does not exist", array($login)), __FILE__, __LINE__);
    }
    $this->removeUserImpl($user);

    // update user repository
    for($i=0; $i<sizeof($this->_userRepository['users']); $i++)
    {
      if ($this->_userRepository['users'][$i]->getLogin() == $login) {
        array_splice($this->_userRepository['users'][$i], $i, 1);
      }
    }
  }

  /**
   * Set a user property.
   * @param login The login of the user
   * @param property One of the USER_PROPERTY constants
   * @param value The value to set this property to
   */
  function setUserProperty($login, $property, $value)
  {
    if (!in_array($property, array(USER_PROPERTY_LOGIN, USER_PROPERTY_NAME, USER_PROPERTY_FIRSTNAME, USER_PROPERTY_CONFIG))) {
      $this->onError(Message::get("Unknown user property: '%1%'", array($property)), __FILE__, __LINE__);
    }
    if (($property == USER_PROPERTY_LOGIN) && ($value == '')) {
      $this->onError(Message::get("The user requires a login name"), __FILE__, __LINE__);
    }
    if (($property == USER_PROPERTY_LOGIN) && ($this->getUser($value) != null)) {
      $this->onError(Message::get("The login '%1%' already exists", array($value)), __FILE__, __LINE__);
    }
    if (($user = $this->getUser($login)) == null) {
      $this->onError(Message::get("The login '%1%' does not exist", array($login)), __FILE__, __LINE__);
    }
    // get the repository user first, because the login may change
    $user = &$this->getUser($login);

    // validate the value
    $validationMsg = $user->validateValue($property, $value, DATATYPE_ATTRIBUTE);
    if (strlen($validationMsg) > 0) {
      $this->onError($validationMsg, __FILE__, __LINE__);
    }
    else {
      $this->setUserPropertyImpl($user, $property, $value);
    }

    // update user repository
    $user->setValue($property, $value, DATATYPE_ATTRIBUTE);
  }

  /**
   * Reset a users password.
   * @param login The login of the user
   * @param newPassword The new password for the user
   * @param newPasswordRepeated The new password of the user again
   */
  function resetPassword($login, $newPassword, $newPasswordRepeated)
  {
    if (($user = $this->getUser($login)) == null) {
      $this->onError(Message::get("The login '%1%' does not exist", array($login)), __FILE__, __LINE__);
    }

    if ($newPassword != $newPasswordRepeated) {
      $this->onError(Message::get("The given passwords don't match"), __FILE__, __LINE__);
    }
    // encrypt password
    $newPassword = $this->encryptPassword($newPassword);

    $this->setUserPropertyImpl($user, 'password', $newPassword);

    // update user repository
    $user = &$this->getUser($login);
    $user->setPassword($newPassword);
  }

  /**
   * Change a users password.
   * @param login The login of the user
   * @param oldPassword The old password of the user
   * @param newPassword The new password for the user
   * @param newPasswordRepeated The new password of the user again
   */
  function changePassword($login, $oldPassword, $newPassword, $newPasswordRepeated)
  {
    if (($user = $this->getUser($login)) == null) {
      $this->onError(Message::get("The login '%1%' does not exist", array($login)), __FILE__, __LINE__);
    }
    // encrypt password
    $oldPassword = $this->encryptPassword($oldPassword);

    if ($user->getPassword() != $oldPassword) {
      $this->onError(Message::get("The old password is incorrect"), __FILE__, __LINE__);
    }
    if ($newPassword != $newPasswordRepeated) {
      $this->onError(Message::get("The given passwords don't match"), __FILE__, __LINE__);
    }
    // encrypt password
    $newPassword = $this->encryptPassword($newPassword);

    $this->setUserPropertyImpl($user, 'password', $newPassword);

    // update user repository
    $user = &$this->getUser($login);
    $user->setPassword($newPassword);
  }

  /**
   * Create a role.
   * @param name The name of the role
   * @return A reference to the created role.
   */
  function &createRole($name)
  {
    if ($name == '') {
      $this->onError(Message::get("The role requires a name"), __FILE__, __LINE__);
    }
    if ($this->getRole($name) != null) {
      $this->onError(Message::get("The role '%1%' already exists", array($name)), __FILE__, __LINE__);
    }
    $role = &$this->createRoleImpl($name);

    // update user repository
    $this->_userRepository['roles'][sizeof($this->_userRepository['roles'])] = &$role;

    return $role;
  }

  /**
   * Remove a role.
   * @param name The name of the role
   */
  function removeRole($name)
  {
    if (($role = $this->getRole($name)) == null) {
      $this->onError(Message::get("The role '%1%' does not exist", array($name)), __FILE__, __LINE__);
    }
    $this->removeRoleImpl($role);

    // update user repository
    for($i=0; $i<sizeof($this->_userRepository['roles']); $i++)
    {
      if ($this->_userRepository['roles'][$i]->getName() == $name) {
        array_splice($this->_userRepository['roles'][$i], $i, 1);
      }
    }
  }

  /**
   * Set a role property.
   * @param name The name of the role
   * @param property One of the ROLE_PROPERTY constants
   * @param value The value to set this property to
   */
  function setRoleProperty($name, $property, $value)
  {
    if (!in_array($property, array(ROLE_PROPERTY_NAME))) {
      $this->onError(Message::get("Unknown role property: '%1%'", array($property)), __FILE__, __LINE__);
    }
    if (($property == ROLE_PROPERTY_NAME) && ($value == '')) {
      $this->onError(Message::get("The role requires a name"), __FILE__, __LINE__);
    }
    if (($property == ROLE_PROPERTY_NAME) && ($this->getRole($value) != null)) {
      $this->onError(Message::get("The role '%1%' already exists", array($value)), __FILE__, __LINE__);
    }
    if (($role = $this->getRole($name)) == null) {
      $this->onError(Message::get("The role '%1%' does not exist", array($name)), __FILE__, __LINE__);
    }
    // get the repository role first, because the name may change
    $role = &$this->getRole($name);

    // validate the value
    $validationMsg = $role->validateValue($property, $value, DATATYPE_ATTRIBUTE);
    if (strlen($validationMsg) > 0) {
      $this->onError($validationMsg, __FILE__, __LINE__);
    }
    else {
      $this->setRolePropertyImpl($role, $property, $value);
    }

    // update user repository
    $role->setValue($property, $value, DATATYPE_ATTRIBUTE);
  }

  /**
   * Add a user to a role.
   * @param rolename The name of the role
   * @param login The login of the user
   */
  function addUserToRole($rolename, $login)
  {
    if (($role = $this->getRole($rolename)) == null) {
      $this->onError(Message::get("The role '%1%' does not exist", array($rolename)), __FILE__, __LINE__);
    }
    if (($user = $this->getUser($login)) == null) {
      $this->onError(Message::get("The login '%1%' does not exist", array($login)), __FILE__, __LINE__);
    }
    if ($user != null && $user->hasRole($rolename)) {
      $this->onError(Message::get("The user '%1%' already has the role '%2%'", array($login, $rolename)), __FILE__, __LINE__);
    }
    $this->addUserToRoleImpl($role, $user);

    // set role config
    if ($this->_roleConfig && isset($this->_roleConfig[$rolename])) {
      $this->setUserProperty($login, USER_PROPERTY_CONFIG, $this->_roleConfig[$rolename]);
    }
  }

  /**
   * Remove a user from a role.
   * @param rolename The name of the role
   * @param login The login of the user
   */
  function removeUserFromRole($rolename, $login)
  {
    if (($role = $this->getRole($rolename)) == null) {
      $this->onError(Message::get("The role '%1%' does not exist", array($rolename)), __FILE__, __LINE__);
    }
    if (($user = $this->getUser($login)) == null) {
      $this->onError(Message::get("The login '%1%' does not exist", array($login)), __FILE__, __LINE__);
    }
    if ($user != null && !$user->hasRole($rolename)) {
      $this->onError(Message::get("The user '%1%' does not have the role '%2%'", array($login, $rolename)), __FILE__, __LINE__);
    }
    $this->removeUserFromRoleImpl($role, $user);

    // remove role config
    if ($this->_roleConfig && isset($this->_roleConfig[$rolename])) {
      $this->setUserProperty($login, USER_PROPERTY_CONFIG, '');
    }
  }

  /**
   * Get list of all users.
   * @return An array containing all login names
   */
  function listUsers()
  {
    $result = array();
    for($i=0; $i<sizeof($this->_userRepository['users']); $i++) {
      array_push($result, $this->_userRepository['users'][$i]->getLogin());
    }
    return $result;
  }

  /**
   * Get list of all roles.
   * @return An array containing all role names
   */
  function listRoles()
  {
    $result = array();
    for($i=0; $i<sizeof($this->_userRepository['roles']); $i++) {
      array_push($result, $this->_userRepository['roles'][$i]->getName());
    }
    return $result;
  }

  /**
   * Get list of all roles a user has.
   * @return An array containing all role names of the user
   */
  function listUserRoles($login)
  {
    if (($user = &$this->getUser($login)) == null) {
      $this->onError(Message::get("The login '%1%' does not exist", array($login)), __FILE__, __LINE__);
    }
    $roles = $user->getRoles();
    $result = array();
    for($i=0; $i<sizeof($roles); $i++) {
      array_push($result, $roles[$i]->getName());
    }
    return $result;
  }

  /**
   * Get list of all users that have a role.
   * @return An array containing all login names of the role members
   */
  function listRoleMembers($rolename)
  {
    if (($role = &$this->getRole($rolename)) == null) {
      $this->onError(Message::get("The role '%1%' does not exist", array($rolename)), __FILE__, __LINE__);
    }
    $result = array();
    for($i=0; $i<sizeof($this->_userRepository['users']); $i++)
    {
      $curUser = &$this->_userRepository['users'][$i];
      $roles = $this->listUserRoles($curUser->getLogin());
      if (in_array($rolename, $roles)) {
        array_push($result, $curUser->getLogin());
      }
    }
    return $result;
  }

  /**
   * Get a user from the repository.
   * @param login The login of the user
   * @return A reference to the matching User object or null if the user does not exist
   */
  function &getUser($login)
  {
    for($i=0; $i<sizeof($this->_userRepository['users']); $i++)
    {
      $curUser = &$this->_userRepository['users'][$i];
      if ($curUser->getLogin() == $login) {
        return $curUser;
      }
    }
    return null;
  }

  /**
   * Get a role from the repository.
   * @param name The name of the role
   * @return A reference to the matching Role object or null if the role does not exist
   */
  function &getRole($name)
  {
    for($i=0; $i<sizeof($this->_userRepository['roles']); $i++)
    {
      $curRole = &$this->_userRepository['roles'][$i];
      if ($curRole->getName() == $name) {
        return $curRole;
      }
    }
    return null;
  }

  /**
   * Get a principal (type: user/role) from the repository.
   * @param oid The oid of the principal
   * @return A reference to the matching User/Role object or null if the principal does not exist
   */
  function &getPrincipal($oid)
  {
    $principal = null;
    $oidParts = PersistenceFacade::decomposeOID($oid);
    if ($oidParts['type'] == UserManager::getUserClassName()) {
      $principalArray = &$this->_userRepository['users'];
    }
    elseif ($oidParts['type'] == UserManager::getRoleClassName()) {
      $principalArray = &$this->_userRepository['roles'];
    }
    else {
      $this->onError(Message::get("Unknown object type: '%1%'", array($oidParts['type'])), __FILE__, __LINE__);
    }
    for($i=0; $i<sizeof($principalArray); $i++)
    {
      $curPrincipal = &$principalArray[$i];
      if ($curPrincipal->getDBID() == $oidParts['id'][0]) {
        $principal = &$curPrincipal;
      }
    }
    return $principal;
  }

  /**
   * Remove a principal (type: user/role) from the repository.
   * @param oid The oid of the principal
   */
  function removePrincipal($oid)
  {
    $oidParts = PersistenceFacade::decomposeOID($oid);

    $principal = $this->getPrincipal($oid);
    if ($principal != null)
    {
      if ($oidParts['type'] == UserManager::getUserClassName()) {
        $this->removeUser($principal->getLogin());
      }
      elseif ($oidParts['type'] == UserManager::getRoleClassName()) {
        $this->removeRole($principal->getName());
      }
      else {
        $this->onError(Message::get("Unknown object type: '%1%'", array($oidParts['type'])), __FILE__, __LINE__);
      }
    }
    else {
      $this->onError(Message::get("The principal does not exist: '%1%'", array($oid)), __FILE__, __LINE__);
    }
  }

  /**
   * Get the user implemenataion class name as configured in config section
   * 'implementation' key 'User'. Maybe used in a static way.
   * @return The class name
   */
  function getUserClassName()
  {
    $parser = &InifileParser::getInstance();
    if (($className = $parser->getValue('User', 'implementation')) === false) {
      $this->onError($parser->getErrorMsg());
    }
    return $className;
  }

  /**
   * Get the role implemenataion class name as configured in config section
   * 'implementation' key 'Role'. Maybe used in a static way.
   * @return The class name
   */
  function getRoleClassName()
  {
    $parser = &InifileParser::getInstance();
    if (($className = $parser->getValue('Role', 'implementation')) === false) {
      $this->onError($parser->getErrorMsg());
    }
    return $className;
  }

  /**
   * Methods to be implemented by subclasses.
   */

  /**
   * Get the user and roles. This method is called before any operation on the repository.
   * Subclasses will override this method to get the data from the application repository.
   * @param params Initialization data given in an associative array as needed to load the user repository
   * @return An assoziative array with the keys 'users' and 'roles' holding user and role objects respectively
   */
  function initialize($params)
  {
    WCMFException::throwEx("initialize() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }

  /**
   * Create a user login with a given password.
   * @param name The name of the user
   * @param firstname The first name of the user
   * @param login The login of the user
   * @param password The encrypted password of the user
   * @return A reference to the created user
   * @note Precondition: The login does not exist
   */
  function &createUserImpl($name, $firstname, $login, $password)
  {
    WCMFException::throwEx("createUserImpl() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }

  /**
   * Remove a user.
   * @param user A reference to the user
   * @note This method is responsible for removing the user from all roles it has
   * @note Precondition: The login does exist
   */
  function removeUserImpl(&$user)
  {
    WCMFException::throwEx("removeUserImpl() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }

  /**
   * Set a user property.
   * @param user A reference to the user
   * @param property One of the USER_PROPERTY constants or 'password'
   * @param value The value to set this property to
   */
  function setUserPropertyImpl(&$user, $property, $value)
  {
    WCMFException::throwEx("setUserPropertyImpl() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }

  /**
   * Create a role.
   * @param name The name of the role
   * @return A reference to the created role
   * @note Precondition: The role does not exist
   */
  function &createRoleImpl($name)
  {
    WCMFException::throwEx("createRoleImpl() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }

  /**
   * Remove a role.
   * @param role A reference to the role
   * @note This method is responsible for removing the role from all users it is attached to
   * @note Precondition: The role does exist
   */
  function removeRoleImpl(&$role)
  {
    WCMFException::throwEx("removeRoleImpl() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }

  /**
   * Set a role property.
   * @param role A reference to the role
   * @param property One of the ROLE_PROPERTY constants
   * @param value The value to set this property to
   */
  function setRolePropertyImpl(&$role, $property, $value)
  {
    WCMFException::throwEx("setRolePropertyImpl() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }

  /**
   * Add a user to a role.
   * @param role A reference to the role
   * @param user A reference to the user
   * @note Precondition: user and role do exist and the user does not have the role
   */
  function addUserToRoleImpl(&$role, &$user)
  {
    WCMFException::throwEx("addUserToRoleImpl() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }

  /**
   * Remove a user from a role.
   * @param role A reference to the role
   * @param user A reference to the user
   * @note Precondition: user and role do exist and the user does have the role
   */
  function removeUserFromRoleImpl(&$role, &$user)
  {
    WCMFException::throwEx("removeUserFromRoleImpl() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
}
?>