<?php
/**
 * Abstracts operations against Perforce users.
 *
 * The P4 User class differs from the 'user' spec definition in that it
 * does not have a password field. This is because the password does
 * not behave like other fields. To change a user's password, use the
 * setPassword() function. To test if a given string matches a user's
 * password, use the isPassword() method. It is not possible to get a
 * user's password.
 *
 * @copyright   2011 Perforce Software. All rights reserved.
 * @license     Please see LICENSE.txt in top-level folder of this distribution.
 * @version     <release>/<patch>
 */
 
namespace P4\Spec;
 
use P4\Validate;
use P4\Connection\Connection;
use P4\Spec\Exception\Exception;
use P4\Connection\ConnectionInterface;
use P4\Connection\Exception\CommandException;
use P4\Connection\Exception\LoginException;
use P4\Model\Fielded\Iterator as FieldedIterator;
 
class User extends PluralAbstract
{
    const SPEC_TYPE         = 'user';
    const ID_FIELD          = 'User';
 
    const OPERATOR_USER     = 'operator';
    const SERVICE_USER      = 'service';
    const STANDARD_USER     = 'standard';
 
    const FETCH_BY_NAME     = 'name';
 
    protected $fields       = array(
        'Email'         => array(
            'accessor'  => 'getEmail',
            'mutator'   => 'setEmail'
        ),
        'Update'        => array(
            'accessor'  => 'getUpdateDateTime'
        ),
        'Access'        => array(
            'accessor'  => 'getAccessDateTime'
        ),
        'FullName'      => array(
            'accessor'  => 'getFullName',
            'mutator'   => 'setFullName'
        ),
        'JobView'       => array(
            'accessor'  => 'getJobView',
            'mutator'   => 'setJobView'
        ),
        'Reviews'       => array(
            'accessor'  => 'getReviews',
            'mutator'   => 'setReviews'
        ),
        'Password'      => array(
            'accessor'  => 'getPassword',
            'mutator'   => 'setPassword'
        ),
        'Type'          => array(
            'accessor'  => 'getType',
            'mutator'   => 'setType'
        )
    );
 
    /**
     * Determine if the given user id exists.
     *
     * @param   string                      $id             the id to check for.
     * @param   ConnectionInterface         $connection     optional - a specific connection to use.
     * @return  bool    true if the given id matches an existing user.
     */
    public static function exists($id, ConnectionInterface $connection = null)
    {
        // check id for valid format
        if (!static::isValidId($id)) {
            return false;
        }
 
        $users = static::fetchAll(
            array(
                static::FETCH_BY_NAME => $id,
                static::FETCH_MAXIMUM => 1
            ),
            $connection
        );
 
        return (bool) count($users);
    }
 
    /**
     * Get all users from Perforce. Adds filtering option.
     *
     * @param   array   $options    optional - array of options to augment fetch behavior.
     *                              supported options are:
     *
     *                                  FETCH_MAXIMUM - set to integer value to limit to the
     *                                                  first 'max' number of entries.
     *                                  FETCH_BY_NAME - set to user name pattern (e.g. 'jdo*'),
     *                                                  can be a single string or array of strings.
     *
     * @param   ConnectionInterface     $connection optional - a specific connection to use.
     * @return  FieldedIterator         all records of this type.
     */
    public static function fetchAll($options = array(), ConnectionInterface $connection = null)
    {
        $connection = $connection ?: static::getDefaultConnection();
 
        // if not fetching by name, defer to parent
        if (!isset($options[static::FETCH_BY_NAME])) {
            return parent::fetchAll($options, $connection);
        }
 
        // get fetch max option and uset it from the options as we handle it manually
        $max = isset($options[static::FETCH_MAXIMUM]) ? $options[static::FETCH_MAXIMUM] : 0;
        unset($options[static::FETCH_MAXIMUM]);
 
        // sort names before fetching users from the server, so if max is set
        // we get the first max users (according to case-sensitivity of server)
        $names = (array) $options[static::FETCH_BY_NAME];
        if ($connection->isCaseSensitive()) {
            sort($names);
        } else {
            usort($names, 'strcasecmp');
        }
 
        // fetch users in several (as few as possible) runs as
        // there is a potential to exceed the arg-max on this command
        $users = new FieldedIterator;
        foreach ($connection->batchArgs($names) as $batch) {
            $options[static::FETCH_BY_NAME] = $batch;
            foreach (parent::fetchAll($options, $connection) as $user) {
                $users[$user->getId()] = $user;
 
                // exit loop if we've reached the max limit
                if ($max && $users->count() == $max) {
                    break(2);
                }
            }
        }
 
        return $users;
    }
 
    /**
     * Save this user to Perforce. This will not save changes to the
     * password field. Passwords must be set via setPassword().
     *
     * @return  SpecAbstract    provides a fluent interface
     * @throws  Exception       if no id has been set.
     */
    public function save()
    {
        // ensure all required fields have values.
        $this->validateRequiredFields();
 
        // set 'password' field to '******' otherwise password
        // will be deleted under certain security levels.
        $values = $this->getRawValues();
        $values['Password'] = '******';
 
        // initialize command flags with first arg.
        $flags = array("-i");
 
        // if we are connected with super user privileges, add in the -f flag.
        // otherwise, if not connected as this user, connect as this user.
        $connection = $this->getConnection();
        if ($connection->isSuperUser()) {
            $flags[] = "-f";
        } elseif ($connection->getUser() != $this->getId()) {
            $connection = Connection::factory(
                $connection->getPort(),
                $this->getId()
            );
        }
 
        // send user spec to server.
        $password = $this->getRawValue('Password');
        try {
            $connection->run(static::SPEC_TYPE, $flags, $values);
        } catch (CommandException $e) {
 
            // if saving user failed because password has not been
            // set, and the caller supplied a password, try setting
            // the password first, then saving user again.
            //
            // @todo This workaround relies on the fact, that user has been created although previous
            // command had failed. At the moment it seems, that when adding a new user (with non-superuser
            // connection) this error cannot be avoided.
            $errors = $e->getResult()->getErrors();
            if (stristr($errors[0], "password must be set") && is_array($password) && isset($password[0])) {
                $this->changePassword($password[0], null, $connection);
                $connection->run(static::SPEC_TYPE, $flags, $values);
                // avoid redundant password change
                $password[0] = null;
            } else {
                throw $e;
            }
        }
 
        // change the users password if they have set a new one.
        if (is_array($password) && $password[0] !== null) {
            $this->changePassword($password[0], $password[1], $connection);
        }
 
        // should re-populate (server may change values).
        $this->deferPopulate(true);
 
        return $this;
    }
 
    /**
     * Remove this user from Perforce.
     *
     * @return  SpecAbstract    provides a fluent interface
     * @throws  Exception       if no id has been set.
     */
    public function delete()
    {
        if ($this->getId() === null) {
            throw new Exception("Cannot delete. No id has been set.");
        }
 
        // initialize command flags with first arg.
        $flags = array("-d");
 
        // if we are connected with super user privileges, add in the -f flag.
        // otherwise, if not connected as this user, connect as this user.
        $connection = $this->getConnection();
        if ($connection->isSuperUser()) {
            $flags[] = "-f";
        } elseif ($connection->getUser() != $this->getId()) {
            $connection = Connection::factory(
                $connection->getPort(),
                $this->getId()
            );
        }
 
        // issue delete user command.
        $flags[] = $this->getId();
        $result = $connection->run(static::SPEC_TYPE, $flags);
 
        // should re-populate.
        $this->deferPopulate(true);
 
        return $this;
    }
 
    /**
     * Get the in-memory password (if one is set).
     *
     * @return  string|null the in-memory password.
     */
    public function getPassword()
    {
        $password = $this->getRawValue('Password');
        return is_array($password) ? $password[0] : null;
    }
 
    /**
     * Set the user's password to the given password.
     * Does not take effect until save() is called.
     *
     * @param   string|null     $newPassword    the new password string or
     *                                          null to clear in-memory password.
     * @param   string          $oldPassword    optional - existing password.
     * @return  User            provides fluent interface.
     */
    public function setPassword($newPassword, $oldPassword = null)
    {
        $this->setRawValue('Password', array($newPassword, $oldPassword));
 
        return $this;
    }
 
    /**
     * Test if the given password is correct for this user.
     *
     * @param   string  $password   the password to test.
     * @return  bool    true if the password is correct, false otherwise.
     */
    public function isPassword($password)
    {
        $p4 = Connection::factory(
            $this->getConnection()->getPort(),
            $this->getId(),
            null,
            $password
        );
 
        try {
            $p4->login();
            return true;
        } catch (LoginException $e) {
            return false;
        }
    }
 
    /**
     * Get the type for this account. Expected to be one of 'service', 'operator' or 'standard'.
     *
     * @return  the 'type' of this user, by default 'standard'
     */
    public function getType()
    {
        return $this->hasField('Type') && $this->getRawValue('Type')
            ? $this->getRawValue('Type')
            : static::STANDARD_USER;
    }
 
    /**
     * Set the user's type.
     *
     * @param   string|null $type   the type, expected to be one of 'service', 'operator' or 'standard'.
     * @return  User        provides fluent interface.
     * @throws  \InvalidArgumentException   if type field doesn't exist and a value other than null/standard is passed
     */
    public function setType($type)
    {
        $type = $type ?: 'standard';
        if (!$this->hasField('Type') && $type != static::STANDARD_USER) {
            throw new \InvalidArgumentException(
                'The user spec lacks a Type field, setting to a value other than null or standard is not supported'
            );
        }
 
        return $this->setRawValue('Type', $type);
    }
 
    /**
     * Get an Iterator of all the Clients this user owns.
     *
     * @return  FieldedIterator     Iterator of Clients owned by current user
     * @throws  Exception           If no ID is set for this user
     */
    public function getClients()
    {
        if (!static::isValidId($this->getId())) {
            throw new Exception("Cannot get clients. No user id has been set.");
        }
 
        return Client::fetchAll(
            array(Client::FETCH_BY_OWNER => $this->getId()),
            $this->getConnection()
        );
    }
 
    /**
     * Get the names of groups that this user belongs to.
     *
     * @return  FieldedIterator     Iterator of Groups this user belongs to.
     */
    public function getGroups()
    {
        if (!static::isValidId($this->getId())) {
            throw new Exception("Cannot get groups. No user id has been set.");
        }
 
        return Group::fetchAll(
            array(Group::FETCH_BY_USER => $this->getId(), Group::FETCH_INDIRECT),
            $this->getConnection()
        );
    }
 
    /**
     * Add this user to the named group.
     *
     * @param   string  $group  the name of the group to add the user to.
     * @return  User    provides fluent interface.
     */
    public function addToGroup($group)
    {
        $group = Group::fetch($group, $this->getConnection())
            ->addUser($this->getId())
            ->save();
 
        return $this;
    }
 
    /**
     * Get the user's full name.
     *
     * @return  string|null the user's full name.
     */
    public function getFullName()
    {
        return $this->getRawValue('FullName');
    }
 
    /**
     * Set the user's full name.
     *
     * @param   string|null $name   the full name to give the user.
     * @return  User    provides fluent interface.
     * @throws  \InvalidArgumentException   if given name is not a string.
     */
    public function setFullName($name)
    {
        if ($name !== null && !is_string($name)) {
            throw new \InvalidArgumentException("Cannot set full name. Invalid type given.");
        }
        return $this->setRawValue('FullName', $name);
    }
 
    /**
     * Get the user's email address.
     *
     * @return  string|null the user's email address.
     */
    public function getEmail()
    {
        return $this->getRawValue('Email');
    }
 
    /**
     * Set the user's email address. We don't require a valid email
     * address here because Perforce doesn't enforce one. If we did
     * then users with invalid emails would be innaccessible.
     *
     * @param   string|null $email  the email of the user.
     * @return  User    provides fluent interface.
     * @throws  \InvalidArgumentException   if given email is not a string.
     */
    public function setEmail($email)
    {
        if ($email !== null && !is_string($email)) {
            throw new \InvalidArgumentException("Cannot set email. Invalid type given.");
        }
        return $this->setRawValue("Email", $email);
    }
 
    /**
     * Get the user's job view (selects jobs for inclusion during changelist creation).
     *
     * @return  string|null the user's job view.
     */
    public function getJobView()
    {
        return $this->getRawValue('JobView');
    }
 
    /**
     * Set the user's job view (selects jobs for inclusion during changelist creation).
     *
     * @param   string|null $jobView    the user's job view.
     * @return  User    provides fluent interface.
     * @throws  \InvalidArgumentException   if given job view is not a string.
     */
    public function setJobView($jobView)
    {
        if ($jobView !== null && !is_string($jobView)) {
            throw new \InvalidArgumentException("Cannot set job view. Invalid type given.");
        }
        return $this->setRawValue("JobView", $jobView);
    }
 
 
    /**
     * Get the reviews for this client (depot paths to notify user of changes to).
     *
     * @return  array   list of filespec strings.
     */
    public function getReviews()
    {
        return $this->getRawValue('Reviews') ?: array();
    }
 
    /**
     * Set the reviews for this user (depot paths to notify user of changes to).
     * Reviews is passed as an array of filespec strings.
     *
     * @param   array   $reviews    Review entries - an array of filespec strings.
     * @return  User    provides a fluent interface.
     * @throws  \InvalidArgumentException   if reviews is not an array.
     */
    public function setReviews($reviews)
    {
        if (!is_array($reviews)) {
            throw new \InvalidArgumentException('Reviews must be passed as array.');
        }
 
        return $this->setRawValue('Reviews', $reviews);
    }
 
    /**
     * Get the last update time for this user spec.
     * This value is read only, no setUpdateTime function is provided.
     *
     * If this is a brand new spec, null will be returned in lieu of a time.
     *
     * @return  string|null  Date/Time of last update, formatted "2009/11/23 12:57:06" or null
     */
    public function getUpdateDateTime()
    {
        return $this->getRawValue('Update');
    }
 
    /**
     * Get the last access time for this user spec.
     * This value is read only, no setAccessTime function is provided.
     *
     * If this is a brand new spec, null will be returned in lieu of a time.
     *
     * @return  string|null  Date/Time of last access, formatted "2009/11/23 12:57:06" or null
     */
    public function getAccessDateTime()
    {
        return $this->getRawValue('Access');
    }
 
    /**
     * Check if automatic user creation is enabled.
     *
     * @param   ConnectionInterface         $connection     optional - a specific connection to use.
     * @return  bool                        true if auto user creation is enabled, false otherwise.
     * @throws  Exception                   if we exceed the maximum number of unlikely usernames
     */
    public static function isAutoUserCreationEnabled(ConnectionInterface $connection = null)
    {
        // if no connection given, use default.
        $connection = $connection ?: static::getDefaultConnection();
 
        $port = $connection->getPort();
 
        // limit the number of 'unlikely' username lookups to 3.
        $maxLookups = 3;
        for ($i = 0; $i < $maxLookups; $i++) {
            // generate an unlikely user name.
            $username = md5(mt_rand());
 
            // try to run p4 users as the unlikely user
            // (perforce won't create an account for this lookup).
            try {
                $connection = Connection::factory($port, $username);
                $result = $connection->run('users', $username);
            } catch (CommandException $e) {
                return false;
            }
 
            // ensure unlikely user doesn't exist.
            if (!$result->getData()) {
                return true;
            }
        }
 
        throw new \Exception(
            "Failed to determine if auto user creation is enabled."
            . "Exceeded the maximum of $maxLookups 'unlikely' username lookups."
        );
    }
 
    /**
     * Produce set of flags for the spec list command, given fetch all options array.
     * Extends parent to add support for filter option.
     *
     * @param   array   $options    array of options to augment fetch behavior.
     *                              see fetchAll for documented options.
     * @return  array   set of flags suitable for passing to spec list command.
     */
    protected static function getFetchAllFlags($options)
    {
        $flags = parent::getFetchAllFlags($options);
 
        // ensure we include service/operator users
        $flags[] = '-a';
 
        if (isset($options[static::FETCH_BY_NAME])) {
            $name = $options[static::FETCH_BY_NAME];
 
            if ((!is_array($name) || !count($name)) && (!is_string($name) || trim($name) === "")) {
                throw new \InvalidArgumentException(
                    'Filter by Name expects a non-empty string or an non-empty array as input'
                );
            }
 
            // if array is given, ensure values are non-empty strings
            if (is_array($name)) {
                $names    = $name;
                $filtered = array_filter($names, 'is_string');
                $filtered = array_filter($filtered, 'trim');
 
                if (count($names) !== count($filtered)) {
                    throw new \InvalidArgumentException(
                        'Filter by Name expects all names in the input array to be non-empty strings'
                    );
                }
                $flags = array_merge($flags, $names);
            } else {
                $flags[] = $name;
            }
        }
 
        return $flags;
    }
 
    /**
     * Check if the given id is in a valid format for user specs.
     *
     * @param   string      $id     the id to check
     * @return  bool        true if id is valid, false otherwise
     */
    protected static function isValidId($id)
    {
        $validator = new Validate\UserName;
        return $validator->isValid($id);
    }
 
    /**
     * Immediately set the user's password to the given password.
     * If the current password is given, it will be validated.
     *
     * @param   string                      $newPassword    the new password.
     * @param   string                      $oldPassword    optional - existing password.
     * @param   ConnectionInterface         $connection     optional - a specific connection to use.
     * @return  User                        provides fluent interface.
     * @throws  Exception                   if the password can't be set.
     */
    protected function changePassword(
        $newPassword,
        $oldPassword = null,
        ConnectionInterface $connection = null
    ) {
        $input = array();
 
        // if caller supplied an old password, prepend it to input array.
        if ($oldPassword) {
            $input[] = $oldPassword;
        }
 
        // always confirm old password
        $input[] = $newPassword;
        $input[] = $newPassword;
 
        // if no connection given, use default.
        $connection = $connection ?: $this->getConnection();
 
        // if not connected as this user, supply user id.
        $flags = array();
        if ($connection->getUser() !== $this->getId()) {
            $flags[] = $this->getId();
        }
 
        // attempt to set password.
        $result = $connection->run("password", $flags, $input);
 
        // change connection credentials if password for connected user has been changed
        // if we don't do this automatically, subsequent commands will fail when using
        // the command-line connection, but would succeed using the P4PHP extension.
        if ($connection->getUser() === $this->getId()) {
            $connection->setPassword($newPassword);
            if ($connection->getTicket()) {
                $connection->login($connection->isTicketUnlocked());
            }
        }
 
        return $this;
    }
}