<?php

/*

 * This file is part of the FOSUserBundle package.

 *

 * (c) FriendsOfSymfony <http://friendsofsymfony.github.com/>

 *

 * For the full copyright and license information, please view the LICENSE

 * file that was distributed with this source code.

 */

namespace FOS\UserBundle\Model;

use Symfony\Component\Validator\Constraint;

/**

 * Interface to be implemented by user managers. This adds an additional level

 * of abstraction between your application, and the actual repository.

 *

 * All changes to users should happen through this interface.

 *

 * The class also contains ACL annotations which will only work if you have the

 * SecurityExtraBundle installed, otherwise they will simply be ignored.

 *

 * @author Gordon Franke <info@nevalon.de>

 * @author Thibault Duplessis <thibault.duplessis@gmail.com>

 * @author Johannes M. Schmitt <schmittjoh@gmail.com>

 */

interface UserManagerInterface

{

    /**

     * Creates an empty user instance.

     *

     * @return UserInterface

     */

    function createUser();

    /**

     * Deletes a user.

     *

     * @param UserInterface $user

     */

    function deleteUser(UserInterface $user);

    /**

     * Finds one user by the given criteria.

     *

     * @param array $criteria

     * @return UserInterface

     */

    function findUserBy(array $criteria);

    /**

     * Find a user by its username.

     *

     * @param string  $username

     * @return UserInterface or null if user does not exist

     */

    function findUserByUsername($username);

    /**

     * Finds a user by its email.

     *

     * @param string  $email

     * @return UserInterface or null if user does not exist

     */

    function findUserByEmail($email);

    /**

     * Finds a user by its username or email.

     *

     * @param string  $usernameOrEmail

     * @return UserInterface or null if user does not exist

     */

    function findUserByUsernameOrEmail($usernameOrEmail);

    /**

     * Finds a user by its confirmationToken.

     *

     * @param string  $token

     * @return UserInterface or null if user does not exist

     */

    function findUserByConfirmationToken($token);

    /**

     * Returns a collection with all user instances.

     *

     * @return \Traversable

     */

    function findUsers();

    /**

     * Returns the user's fully qualified class name.

     *

     * @return string

     */

    function getClass();

    /**

     * Reloads a user.

     *

     * @param UserInterface $user

     */

    function reloadUser(UserInterface $user);

    /**

     * Updates a user.

     *

     * @param UserInterface $user

     */

    function updateUser(UserInterface $user);

    /**

     * Updates the canonical username and email fields for a user.

     *

     * @param UserInterface $user

     */

    function updateCanonicalFields(UserInterface $user);

    /**

     * Updates a user password if a plain password is set.

     *

     * @param UserInterface $user

     */

    function updatePassword(UserInterface $user);

    /**

     * Checks the uniqueness of the given fields, returns true if its unique.

     *

     * @param UserInterface $value

     * @param Constraint $constraint

     * @return Boolean

     */

    function validateUnique(UserInterface $value, Constraint $constraint);

}