Authentication

In this section, we will cover authentication and login.

Sentry::authenticate()

Authenticates a user based on the provided credentials.

If the authentication was successful, password reset fields and any invalid authentication attempts will be cleared.

Example

try
{
    // Login credentials
    $credentials = array(
        'email'    => 'john.doe@example.com',
        'password' => 'password',
    );
    // Authenticate the user
    $user = Sentry::authenticate($credentials, false);
}
catch (Cartalyst\Sentry\Users\LoginRequiredException $e)
{
    echo 'Login field is required.';
}
catch (Cartalyst\Sentry\Users\PasswordRequiredException $e)
{
    echo 'Password field is required.';
}
catch (Cartalyst\Sentry\Users\WrongPasswordException $e)
{
    echo 'Wrong password, try again.';
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}
catch (Cartalyst\Sentry\Users\UserNotActivatedException $e)
{
    echo 'User is not activated.';
}
// The following is only required if the throttling is enabled
catch (Cartalyst\Sentry\Throttling\UserSuspendedException $e)
{
    echo 'User is suspended.';
}
catch (Cartalyst\Sentry\Throttling\UserBannedException $e)
{
    echo 'User is banned.';
}

Exceptions

In this section, we provide a list of all exceptions that are thrown by Sentry.

Sentry::authenticateAndRemember()

Authenticates and Remembers a user based on credentials. This is an helper function for the authenticate() which sets the $remember flag to true so the user is remembered (using a cookie). This is the “remember me” you are used to see on web sites.

Example

Sentry::authenticateAndRemember($credentials);

Sentry::login()

Logs in the provided user and sets properties in the session.

If the login is successful, password reset fields and any invalid authentication attempts will be cleared.

Example

try
{
    // Find the user using the user id
    $user = Sentry::findUserById(1);
    // Log the user in
    Sentry::login($user, false);
}
catch (Cartalyst\Sentry\Users\LoginRequiredException $e)
{
    echo 'Login field is required.';
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User not found.';
}
catch (Cartalyst\Sentry\Users\UserNotActivatedException $e)
{
    echo 'User not activated.';
}
// Following is only needed if throttle is enabled
catch (Cartalyst\Sentry\Throttling\UserSuspendedException $e)
{
    $time = $throttle->getSuspensionTime();
    echo "User is suspended for [$time] minutes.";
}
catch (Cartalyst\Sentry\Throttling\UserBannedException $e)
{
    echo 'User is banned.';
}

Exceptions

Below is a list of exceptions that this method can throw.

Sentry::loginAndRemember()

Logs in and Remembers a user based on credentials. This is an helper function for the login() which sets the $remember flag to true so the user is remembered (using a cookie). This is the “remember me” you are used to see on web sites.

Example

Sentry::loginAndRemember($user);

Sentry::logout()

The logout method logs the user out and destroys all Sentry sessions / cookies for the user.

This method does not fail or throw any Exceptions if there is no user logged in.

Example

Sentry::logout();

Sentry::check()

The check method returns a bool of whether the user is logged in or not, or if the user is not activated.

If it’s logged in, the current User is set in Sentry so you can easily access it via getUser().

A user must be activated to pass check().

Example

if ( ! Sentry::check())
{
    // User is not logged in, or is not activated
}
else
{
    // User is logged in
}