Cartalyst LLC.
Sentry by Cartalyst
4
176
0
327
1543

Introduction

A modern and framework agnostic authorization and authentication package featuring groups, permissions, custom hashing algorithms and additional security features.

The package follows the FIG standard PSR-0 to ensure a high level of interoperability between shared PHP code.

The package requires PHP 5.3+ and comes bundled with a Laravel 4 Facade and a Service Provider to simplify the optional framework integration.

Have a read through the Installation Guide and on how to Integrate it with Laravel 4.

Quick Example

Create a user

Sentry::register(array(
    'email'    => 'john.doe@example.com',
    'password' => 'foobar',
));

Authenticate a user

Sentry::authenticate(array(
    'email'    => 'john.doe@example.com',
    'password' => 'foobar',
));

Create a group

Sentry::createGroup(array(
    'name'        => 'Subscribers',
    'permissions' => array(
        'admin' => 1,
        'users' => 1,
    ),
));

Installation

The best and easiest way to install Sentry is with Composer.

Preparation

Open your composer.json file and add the following to the require array:

"cartalyst/sentry": "2.1.*"

Note: Make sure that after the required changes your composer.json file is valid by running composer validate.

Install the dependencies

Run Composer to install or update the new requirement.

php composer install

or

php composer update

Now you are able to require the vendor/autoload.php file to autoload the package.

Integration

Note: The database schema is located under vendor/cartalyst/sentry/schema/mysql.sql

Laravel 4

After you have installed the package, just follow the instructions.

Sentry has optional support for Laravel 4 and it comes bundled with a Service Provider and a Facade for easy integration.

After installing the package, open your Laravel config file app/config/app.php and add the following lines.

In the $providers array add the following service provider for this package.

'Cartalyst\Sentry\SentryServiceProvider',

In the $aliases array add the following facade for this package.

'Sentry' => 'Cartalyst\Sentry\Facades\Laravel\Sentry',

Migrations

php artisan migrate --package=cartalyst/sentry

Configuration

After installing, you can publish the package configuration file into your application by running the following command:

php artisan config:publish cartalyst/sentry

This will publish the config file to app/config/packages/cartalyst/sentry/config.php where you can modify the package configuration.

CodeIgniter 3.0-dev

After you have installed the package, just follow the instructions.

Visit application/config/config.php and right down the bottom, add the following:

class_alias('Cartalyst\Sentry\Facades\CI\Sentry', 'Sentry');

This will allow you to use Sentry as normal in CodeIgniter and sets up dependencies required for Sentry to run smoothly within the CI environment.

Note:: You must be running your database using the PDO driver (though this would be recommended anyway). Configuration for a MySQL database running PDO could be as follows (in application/config/database.php):

// Ensure the active group is the default config.
// Sentry always runs off your application's default
// database connection.
$active_group = 'default';

// Setup the default config
$db['default'] = array(

    // PDO requires the host, dbname and charset are all specified in the "dsn",
    // so we'll go ahead and do these now.
    'dsn'      => 'mysql:host=localhost;dbname=cartalyst_sentry;charset=utf8;',
    'hostname' => 'localhost',
    'username' => 'root',
    'password' => 'root',
    'database' => '',
    'dbdriver' => 'pdo',
    'dbprefix' => '',
    'pconnect' => TRUE,
    'db_debug' => TRUE,
    'cache_on' => FALSE,
    'cachedir' => '',
    'char_set' => 'utf8',
    'dbcollat' => 'utf8_general_ci',
    'swap_pre' => '',
    'autoinit' => TRUE,
    'encrypt'  => FALSE,
    'compress' => FALSE,
    'stricton' => FALSE,
    'failover' => array()
);

FuelPHP 1.x

After you have installed the package, just follow the instructions.

You must put the following in app/bootstrap.php below Autoloader::register():

// Enable composer based autoloading
require APPPATH.'vendor/autoload.php';

Great! You now have composer working with FuelPHP.

Just one more step is involved now, right at the bottom of that same file, app/bootstrap.php, put the following:

class_alias('Cartalyst\Sentry\Facades\FuelPHP\Sentry', 'Sentry');

This will mean you can use the FuelPHP Sentry facade as the class Sentry. Vòila! Sentry automatically works with your current database configuration, there is no further setup required.

Note:: Sentry will always run off the default database connection, so ensure this is working. We may look at adding support for alternate connections in the future however it is not implemented at this stage. Pull requests are welcome.

Native

// Include the composer autoload file
include_once "vendor/autoload.php";

// Import the necessary classes
use Illuminate\Database\Capsule\Manager as Capsule;

// Create the Sentry alias
class_alias('Cartalyst\Sentry\Facades\Native\Sentry', 'Sentry');

// Create a new Database connection
$capsule = new Capsule;

$capsule->addConnection([
    'driver'    => 'mysql',
    'host'      => 'localhost',
    'database'  => 'database',
    'username'  => 'root',
    'password'  => '',
    'charset'   => 'utf8',
    'collation' => 'utf8_unicode_ci',
]);

$capsule->bootEloquent();

The integration is done and you can now use all the available methods, here's an example:

// Find a user using the user email address
$user = Sentry::findUserByLogin('john.doe@example.com');

Usage

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.

Param Required Default Type Description
$credentials true null array Array that should contain the user credentials like email and password.
$remember false false bool Flag to wether Sentry should remember the user. It sets a Cookie.

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.

Exception Description
Cartalyst\Sentry\Users\LoginRequiredException When you don't provide the required login field, this exception will be thrown.
Cartalyst\Sentry\Users\PasswordRequiredException When you don't provide the password field, this exception will be thrown.
Cartalyst\Sentry\Users\UserNotActivatedException When the provided user is not activated, this exception will be thrown.
Cartalyst\Sentry\Users\UserNotFoundException If the provided user was not found, this exception will be thrown.
Cartalyst\Sentry\Users\WrongPasswordException When the provided password is incorrect, this exception will be thrown.
Cartalyst\Sentry\Throttling\UserSuspendedException When the provided user is suspended, this exception will be thrown.
Cartalyst\Sentry\Throttling\UserBannedException When the provided user is banned, this exception will be thrown.

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.

Param Required Default Type Description
$user true null object A user object Cartalyst\Sentry\Users\UserInterface.
$remember false false bool Flag to wether Sentry should remember the user. It sets a Cookie.

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.

Exception Description
Cartalyst\Sentry\Users\LoginRequiredException When you don't provide the required login field, this exception will be thrown.
Cartalyst\Sentry\Users\UserNotFoundException If the provided user was not found, this exception will be thrown.
Cartalyst\Sentry\Users\UserNotActivatedException When the provided user is not activated, this exception will be thrown.
Cartalyst\Sentry\Throttling\UserSuspendedException When the provided user is suspended, this exception will be thrown.
Cartalyst\Sentry\Throttling\UserBannedException When the provided user is banned, this exception will be thrown.

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
}

Permissions

In this section we will cover how Sentry 2 permissions work and how the user
permission inheritance behaves.

Please be aware that Sentry 2 permissions works practically the same way as in
Sentry 1.

That said, here are the values that your groups and users permissions can have:

Groups Permissions
0 : Deny
1 : Allow
Users Permissions
-1 : Deny
 1 : Allow
 0 : Inherit

Permission Inheritance

Just as permissions are defined for groups and individual users, the permission
inheritance model depends on a user's group.

An Administrator can assign different permissions to a user than is assigned to a group:

  • If a user is not assigned a permission, or if the user is assigned a permission of 0 then the user will inherit permissions from the group
  • If a user is assigned a permission of -1 or 1, then the user's permission will override the group permission

Note: Permission Inheritance only works for users permissions, an example
is provided on this page to help you
better understand how this exactly works.

Administrator Group

Let's say you want to have two groups, an Administrator group and a Moderator
group, for each group you can define their own permissions:

{
    "name" : "Administrator",
    "permissions" : {
        "user.create" : 1,
        "user.delete" : 1,
        "user.view"   : 1,
        "user.update" : 1
    }
}
Moderator Group
{
    "name" : "Moderator",
    "permissions" : {
        "user.create" : 0,
        "user.delete" : 0,
        "user.view"   : 1,
        "user.update" : 1
    }
}

And you have these three users, one as an Administrator, one as a Moderator
and the last one has the Administrator and Moderator groups assigned.

User - John Rambo
{
    "id" : 1,
    "first_name" : "John",
    "last_name" : "Rambo",
    "groups" : ["administrator"],
    "permissions" : null
}
Actions he can execute

This user has access to everything and can execute every action on your application.

User - Rocky Balboa
{
    "id" : 2,
    "first_name" : "Rocky",
    "last_name" : "Balboa",
    "groups" : ["moderator"],
    "permissions" : {
        "user.update" : 0
    }
}
Actions he can execute

View and Update users

Actions he cannot execute

Create or Delete users

Note: We are using Permission Inheritance here, hence the user.update : 0 which means whatever you define on your group permission
this user permission will inherit that permission, which means that in this
case the user is allowed to update users.

User - Bruce Wayne
{
    "id" : 3,
    "first_name" : "Bruce",
    "last_name" : "Wayne",
    "groups" : ["administrator", "moderator"],
    "permissions" : {
        "user.delete" : -1,
        "user.create" : 1
    }
}
Actions he can execute

Create, Update and View users

Actions he cannot execute

Delete users

Since this is a special user, mainly because this user has two assigned groups,
there are some things that you should know when assigning multiple groups to
an user.

When a user has two or more groups assigned, if those groups have the same
permissions but different permission access's are assigned,
once one of those group permissions are denied, the user will be denied access
to that permission no matter what the other groups has as a permission value.

Which means for you to allow a permission to this specific user, you need to
change the user permissions.

In this specific case, we allowed the user to create a new user by changing the user.create : 1 permission.

Notice that we are denying the user.delete permission of this user, in this
example, you don't need to do this, but let's say that in your group you are
allowing your users to delete other users, but for this specific user you don't
want him to be able to do that? To achieve this you deny this user permission
directly on the user, so no matter what your group permission looks like, this
user will never be able to delete other users.

Groups

Create a group

Creating new Groups is very easy and in this section you will learn how to create one.

Param Required Default Type Description
$attributes true null array The group attributes.

Below we'll list all the valid keys that you can pass through the $attributes.

Key Required Type Description
name true string The name of the group.
permissions false array The group permissions, pass a key/value pair.

Example

try
{
    // Create the group
    $group = Sentry::createGroup(array(
        'name'        => 'Moderator',
        'permissions' => array(
            'admin' => 1,
            'users' => 1,
        ),
    ));
}
catch (Cartalyst\Sentry\Groups\NameRequiredException $e)
{
    echo 'Name field is required';
}
catch (Cartalyst\Sentry\Groups\GroupExistsException $e)
{
    echo 'Group already exists';
}

Exceptions

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

Exception Description
Cartalyst\Sentry\Groups\NameRequiredException If you don't provide the group name, this exception will be thrown.
Cartalyst\Sentry\Groups\GroupExistsException This exception will be thrown when the group you are trying to create already exists on your database.

Update a group

Example

try
{
    // Find the group using the group id
    $group = Sentry::findGroupById(1);

    // Update the group details
    $group->name = 'Users';
    $group->permissions = array(
        'admin' => 1,
        'users' => 1,
    );

    // Update the group
    if ($group->save())
    {
        // Group information was updated
    }
    else
    {
        // Group information was not updated
    }
}
catch (Cartalyst\Sentry\Groups\NameRequiredException $e)
{
    echo 'Name field is required';
}
catch (Cartalyst\Sentry\Groups\GroupExistsException $e)
{
    echo 'Group already exists.';
}
catch (Cartalyst\Sentry\Groups\GroupNotFoundException $e)
{
    echo 'Group was not found.';
}

Exceptions

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

Exception Description
Cartalyst\Sentry\Groups\NameRequiredException If you don't provide the group name, this exception will be thrown.
Cartalyst\Sentry\Groups\GroupExistsException This exception will be thrown when the group you are trying to create already exists on your database.
Cartalyst\Sentry\Groups\GroupNotFoundException If the provided group was not found, this exception will be thrown.

Delete a Group

Example

try
{
    // Find the group using the group id
    $group = Sentry::findGroupById(1);

    // Delete the group
    $group->delete();
}
catch (Cartalyst\Sentry\Groups\GroupNotFoundException $e)
{
    echo 'Group was not found.';
}

Exceptions

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

Exception Description
Cartalyst\Sentry\Groups\GroupNotFoundException If the provided group was not found, this exception will be thrown.

Finding Groups

Sentry provides simple methods to find you your groups.

Find all the Groups

This will return all the groups.

$groups = Sentry::findAllGroups();

Find a group by its ID

Find a group by it's ID.

try
{
    $group = Sentry::findGroupById(1);
}
catch (Cartalyst\Sentry\Groups\GroupNotFoundException $e)
{
    echo 'Group was not found.';
}

Find a Group by it's Name

Find a group by it's name.

try
{
    $group = Sentry::findGroupByName('admin');
}
catch (Cartalyst\Sentry\Groups\GroupNotFoundException $e)
{
    echo 'Group was not found.';
}

Exceptions

Below is a list of exceptions that the methods can throw.

Exception Description
Cartalyst\Sentry\Groups\GroupNotFoundException If the provided group was not found, this exception will be thrown.

Helpers

getPermissions()

Returns the permissions of a group.

try
{
    // Find the group using the group id
    $group = Sentry::findGroupById(1);

    // Get the group permissions
    $groupPermissions = $group->getPermissions();
}
catch (Cartalyst\Sentry\Groups\GroupNotFoundException $e)
{
    echo 'Group does not exist.';
}

Users

In this section we'll cover how you can create or register users, assign groups and permissions to users.

Sentry::createUser()

To create a new user you need to pass an array() of user fields into the create() method, please note, that the login field and the password are required, all the other fields are optional.

Param Required Default Type Description
$credentials true null array The user credentials and attributes.

Examples

Create a User and assign this new user an existing group.

try
{
    // Create the user
    $user = Sentry::createUser(array(
        'email'     => 'john.doe@example.com',
        'password'  => 'test',
        'activated' => true,
    ));

    // Find the group using the group id
    $adminGroup = Sentry::findGroupById(1);

    // Assign the group to the user
    $user->addGroup($adminGroup);
}
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\UserExistsException $e)
{
    echo 'User with this login already exists.';
}
catch (Cartalyst\Sentry\Groups\GroupNotFoundException $e)
{
    echo 'Group was not found.';
}

Create a new user and set permissions on this user.

This example does pretty much the same as the previous one with the exception that we are not assigning him any group, but we are granting this user some permissions.

try
{
    // Create the user
    $user = Sentry::createUser(array(
        'email'       => 'john.doe@example.com',
        'password'    => 'test',
        'activated'   => true,
        'permissions' => array(
            'user.create' => -1,
            'user.delete' => -1,
            'user.view'   => 1,
            'user.update' => 1,
        ),
    ));
}
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\UserExistsException $e)
{
    echo 'User with this login already exists.';
}

Exceptions

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

Exception Description
Cartalyst\Sentry\Users\LoginRequiredException When you don't provide the required login field, this exception will be thrown.
Cartalyst\Sentry\Users\PasswordRequiredException When you don't provide the password field, this exception will be thrown.
Cartalyst\Sentry\Users\UserExistsException This exception will be thrown when the user you are trying to create already exists on your database.
Cartalyst\Sentry\Groups\GroupNotFoundException This exception will be thrown when the group that's being assigned to the user doesn't exist.

Sentry::register()

Registering a user will require the user to be manually activated but you can bypass this passing a boolean of true as a second parameter.

If the user already exists but is not activated, it will create a new activation code.

Param Required Default Type Description
$credentials true null array The user credentials and attributes.
$activate false false boolean Flag to wether activate the user or not.

Example

try
{
    // Let's register a user.
    $user = Sentry::register(array(
        'email'    => 'john.doe@example.com',
        'password' => 'test',
    ));

    // Let's get the activation code
    $activationCode = $user->getActivationCode();

    // Send activation code to the user so he can activate the account
}
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\UserExistsException $e)
{
    echo 'User with this login already exists.';
}

Exceptions

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

Exception Description
Cartalyst\Sentry\Users\LoginRequiredException When you don't provide the required login field, this exception will be thrown.
Cartalyst\Sentry\Users\PasswordRequiredException When you don't provide the required password field, this exception will be thrown.
Cartalyst\Sentry\Users\UserExistsException This exception will be thrown when the user you are trying to create already exists on your database.

Update a User

Updating users information is very easy with Sentry, you just need to find the user you want to update and update their information. You can add or remove groups from users as well.

Examples

In this example we are just updating the user information.

Note: If you provide another email address, and that email address is already registered in your system, the following Exception Cartalyst\Sentry\Users\UserExistsException will be thrown.

try
{
    // Find the user using the user id
    $user = Sentry::findUserById(1);

    // Update the user details
    $user->email = 'john.doe@example.com';
    $user->first_name = 'John';

    // Update the user
    if ($user->save())
    {
        // User information was updated
    }
    else
    {
        // User information was not updated
    }
}
catch (Cartalyst\Sentry\Users\UserExistsException $e)
{
    echo 'User with this login already exists.';
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Assign a new Group to a User

In this example we are assigning the provided Group to the provided User.

Note: If the provided Group is not found an Exception Cartalyst\Sentry\Groups\GroupNotFoundException will be thrown.

try
{
    // Find the user using the user id
    $user = Sentry::findUserById(1);

    // Find the group using the group id
    $adminGroup = Sentry::findGroupById(1);

    // Assign the group to the user
    if ($user->addGroup($adminGroup))
    {
        // Group assigned successfully
    }
    else
    {
        // Group was not assigned
    }
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}
catch (Cartalyst\Sentry\Groups\GroupNotFoundException $e)
{
    echo 'Group was not found.';
}

Remove a Group from the User

In this example we are removing the provided Group from the provided User.

Note: If the provided Group is not found an Exception Cartalyst\Sentry\Groups\GroupNotFoundException will be thrown.

try
{
    // Find the user using the user id
    $user = Sentry::findUserById(1);

    // Find the group using the group id
    $adminGroup = Sentry::findGroupById(1);

    // Assign the group to the user
    if ($user->removeGroup($adminGroup))
    {
        // Group removed successfully
    }
    else
    {
        // Group was not removed
    }
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}
catch (Cartalyst\Sentry\Groups\GroupNotFoundException $e)
{
    echo 'Group was not found.';
}

Update the User details and assign a new Group

This is a combination of the previous examples, where we are updating the user information and assigning a new Group the provided User.

Note: If the provided Group is not found an Exception Cartalyst\Sentry\Groups\GroupNotFoundException will be thrown.

try
{
    // Find the user using the user id
    $user = Sentry::findUserById(1);

    // Find the group using the group id
    $adminGroup = Sentry::findGroupById(1);

    // Assign the group to the user
    if ($user->addGroup($adminGroup))
    {
        // Group assigned successfully
    }
    else
    {
        // Group was not assigned
    }

    // Update the user details
    $user->email = 'john.doe@example.com';
    $user->first_name = 'John';

    // Update the user
    if ($user->save())
    {
        // User information was updated
    }
    else
    {
        // User information was not updated
    }
}
catch (Cartalyst\Sentry\Users\UserExistsException $e)
{
    echo 'User with this login already exists.';
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}
catch (Cartalyst\Sentry\Groups\GroupNotFoundException $e)
{
    echo 'Group was not found.';
}

Exceptions

Below is a list of exceptions that the methods can throw.

Exception Description
Cartalyst\Sentry\Users\LoginRequiredException When you don't provide the required login field, this exception will be thrown.
Cartalyst\Sentry\Users\UserExistsException This exception will be thrown when the user you are trying to create already exists in your database.
Cartalyst\Sentry\Users\UserNotFoundException If the provided user was not found, this exception will be thrown.
Cartalyst\Sentry\Groups\GroupNotFoundException This exception will be thrown when the group that's being assigned to the user doesn't exist.

Delete a user

Deleting users is very simple and easy.

Example

try
{
    // Find the user using the user id
    $user = Sentry::findUserById(1);

    // Delete the user
    $user->delete();
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Exceptions

Below is a list of exceptions that the methods can throw.

Exception Description
Cartalyst\Sentry\Users\UserNotFoundException If the provided user was not found, this exception will be thrown.

Activating a User

User activation is very easy with Sentry, you need to first find the user you want to activate, then use the attemptActivation() method and provide the activation code, if the activation passes it will return true otherwise, it will return false .

Note: If the user you are trying to activate, is already activated, the following Exception Cartalyst\Sentry\Users\UserAlreadyActivatedException will be thrown.

Example

try
{
    // Find the user using the user id
    $user = Sentry::findUserById(1);

    // Attempt to activate the user
    if ($user->attemptActivation('8f1Z7wA4uVt7VemBpGSfaoI9mcjdEwtK8elCnQOb'))
    {
        // User activation passed
    }
    else
    {
        // User activation failed
    }
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}
catch (Cartalyst\Sentry\Users\UserAlreadyActivatedException $e)
{
    echo 'User is already activated.';
}

Exceptions

Below is a list of exceptions that the methods can throw.

Exception Description
Cartalyst\Sentry\Users\UserAlreadyActivatedException If the provided user is already activated, this exception will be thrown.
Cartalyst\Sentry\Users\UserNotFoundException If the provided user was not found, this exception will be thrown.

Reset a User Password

In this section you will learn how easy it is to reset a user password with Sentry 2.

Step 1

The first step is to get a password reset code, to do this we use the getResetPasswordCode() method.

Example
try
{
    // Find the user using the user email address
    $user = Sentry::findUserByLogin('john.doe@example.com');

    // Get the password reset code
    $resetCode = $user->getResetPasswordCode();

    // Now you can send this code to your user via email for example.
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Step 2

After your user received the password reset code you need to provide a way for them to validate that code, and reset their password.

All the logic part on how you pass the reset password code is all up to you.

Example

try
{
    // Find the user using the user id
    $user = Sentry::findUserById(1);

    // Check if the reset password code is valid
    if ($user->checkResetPasswordCode('8f1Z7wA4uVt7VemBpGSfaoI9mcjdEwtK8elCnQOb'))
    {
        // Attempt to reset the user password
        if ($user->attemptResetPassword('8f1Z7wA4uVt7VemBpGSfaoI9mcjdEwtK8elCnQOb', 'new_password'))
        {
            // Password reset passed
        }
        else
        {
            // Password reset failed
        }
    }
    else
    {
        // The provided password reset code is Invalid
    }
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Exceptions

Below is a list of exceptions that the methods can throw.

Exception Description
Cartalyst\Sentry\Users\UserNotFoundException If the provided user was not found, this exception will be thrown.

Finding Users

Finding users can sometimes be difficult and harsh, well, Sentry provides you simple methods to find your users.

Get the Current Logged in User

Returns the user that's set with Sentry, does not check if a user is logged in or not. To do that, use check() instead.

try
{
    // Get the current active/logged in user
    $user = Sentry::getUser();
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    // User wasn't found, should only happen if the user was deleted
    // when they were already logged in or had a "remember me" cookie set
    // and they were deleted.
}

Find all the Users

This will return all the users.

$users = Sentry::findAllUsers();

Find all the Users with access to a permissions(s)

Finds all users with access to a permission(s).

// Feel free to pass a string for just one permission instead
$users = Sentry::findAllUsersWithAccess(array('admin', 'other'));

Find all the Users in a Group

Finds all users assigned to a group.

$group = Sentry::findGroupByName('admin');

$users = Sentry::findAllUsersInGroup($group);

Find a User by their Credentials

Find a user by an array of credentials, which must include the login column. Hashed fields will be hashed and checked against their value in the database.

try
{
    $user = Sentry::findUserByCredentials(array(
        'email'      => 'john.doe@example.com',
        'password'   => 'test',
        'first_name' => 'John',
    ));
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Find a User by their Id

Find a user by their ID.

try
{
    $user = Sentry::findUserById(1);
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Find a User by their Login Id

Find a user by their login ID.

try
{
    $user = Sentry::findUserByLogin('john.doe@example.com');
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Find a User by their Activation Code

Find a user by their registration activation code.

try
{
    $user = Sentry::findUserByActivationCode('8f1Z7wA4uVt7VemBpGSfaoI9mcjdEwtK8elCnQOb');
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Find a User by their Reset Password Code

Find a user by their reset password code.

try
{
    $user = Sentry::findUserByResetPasswordCode('8f1Z7wA4uVt7VemBpGSfaoI9mcjdEwtK8elCnQOb');
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Exceptions

Below is a list of exceptions that the methods can throw.

Exception Description
Cartalyst\Sentry\Users\UserNotFoundException If the provided user was not found, this exception will be thrown.

Helpers

checkPassword()

Checks if the provided password matches the user's current password.

try
{
    // Find the user using the user id
    $user = Sentry::findUserById(1);

    if($user->checkPassword('mypassword'))
    {
        echo 'Password matches.';
    }
    else
    {
        echo 'Password does not match.';
    }
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

getGroups()

Returns the user groups.

try
{
    // Find the user using the user id
    $user = Sentry::findUserByID(1);

    // Get the user groups
    $groups = $user->getGroups();
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

getPermissions()

Returns the user permissions.

try
{
    // Find the user using the user id
    $user = Sentry::findUserByID(1);

    // Get the user permissions
    $permissions = $user->getPermissions();
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

getMergedPermissions()

Returns an array of merged permissions from groups and the user permissions.

try
{
    // Find the user using the user id
    $user = Sentry::getUserProvider()->findById(1);

    // Get the user permissions
    $permissions = $user->getMergedPermissions();
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

hasAccess($permission)

Checks to see if a user been granted a certain permission. This includes any
permissions given to them by groups they may be apart of as well. Users may
also have permissions with a value of '-1'. This value is used to deny users of
permissions that may have been assigned to them from a group.

Any user with superuser permissions automatically has access to everything,
regardless of the user permissions and group permissions.

try
{
    // Find the user using the user id
    $user = Sentry::findUserByID(1);

    // Check if the user has the 'admin' permission. Also,
    // multiple permissions may be used by passing an array
    if ($user->hasAccess('admin'))
    {
        // User has access to the given permission
    }
    else
    {
        // User does not have access to the given permission
    }
}
catch (Cartalyst\Sentry\UserNotFoundException $e)
{
    echo 'User was not found.';
}

hasAnyAccess($permissions)

This method calls the hasAccess() method, and it is used to check if an user
has access to any of the provided permissions.

If one of the provided permissions is found it will return true even though the
user may not have access to the other provided permissions.

try
{
    // Find the user using the user id
    $user = Sentry::getUserProvider()->findById(1);

    // Check if the user has the 'admin' and 'foo' permission.
    if ($user->hasAnyAccess(array('admin', 'foo')))
    {
        // User has access to one of the given permissions
    }
    else
    {
        // User does not have access to any of the given permissions
    }
}
catch (Cartalyst\Sentry\UserNotFoundException $e)
{
    echo 'User was not found.';
}

isActivated()

Checks if a user is activated.

try
{
    // Find the user
    $user = Sentry::findUserByLogin('jonh.doe@example.com');

    // Check if the user is activated or not
    if ($user->isActivated())
    {
        // User is Activated
    }
    else
    {
        // User is Not Activated
    }
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

isSuperUser()

Returns if the user is a super user, it means, that has access to everything regardless of permissions.

try
{
    // Find the user
    $user = Sentry::findUserByLogin('jonh.doe@example.com');

    // Check if this user is a super user
    if ($user->isSuperUser())
    {
        // User is a super user
    }
    else
    {
        // User is not a super user
    }
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

inGroup($group)

Checks if a user is in a certain group.

try
{
    // Find the user using the user id
    $user = Sentry::findUserByID(1);

    // Find the Administrator group
    $admin = Sentry::findGroupByName('Administrator');

    // Check if the user is in the administrator group
    if ($user->inGroup($admin))
    {
        // User is in Administrator group
    }
    else
    {
        // User is not in Administrator group
    }
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}
catch (Cartalyst\Sentry\Groups\GroupNotFoundException $e)
{
    echo 'Group was not found.';
}

Throttle

Disable the Throttling Feature

Disables the throttling feature.

Can be done on the throttle provider (global) level or on a throttle instance itself.

Example

// Get the Throttle Provider
$throttleProvider = Sentry::getThrottleProvider();

// Disable the Throttling Feature
$throttleProvider->disable();

Enable the Throttling Feature

Enables the throttling feature.

Can be done on the throttle provider (global) level or on a throttle instance itself.

Example

// Get the Throttle Provider
$throttleProvider = Sentry::getThrottleProvider();

// Enable the Throttling Feature
$throttleProvider->enable();

Check the Throttling Feature Status

Checks to see if the throttling feature is enabled or disabled.

Example

// Get the Throttle Provider
$provider = Sentry::getThrottleProvider();

// Check if the Throttling feature is enabled or disabled
if($provider->isEnabled())
{
    // The Throttling Feature is Enabled
}
else
{
    // The Throttling Feature is Disabled
}

User Throttling

Ban user(s)

Bans the user associated with the throttle.

try
{
    // Find the user using the user id
    $throttle = Sentry::findThrottlerByUserId(1);

    // Ban the user
    $throttle->ban();
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Unban user(s)

Unbans the user associated with the throttle.

try
{
    // Find the user using the user id
    $throttle = Sentry::findThrottlerByUserId(1);

    // Unban the user
    $throttle->unBan();
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Check if a User is Banned

Checks to see if the user is banned.

try
{
    $throttle = Sentry::findThrottlerByUserId(1);

    if($banned = $throttle->isBanned())
    {
        // User is Banned
    }
    else
    {
        // User is not Banned
    }
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Suspend user(s)

Suspends a user temporarily. Length of the suspension is set by the driver or setSuspensionTime($minutes).

try
{
    // Find the user using the user id
    $throttle = Sentry::findThrottlerByUserId(1);

    // Suspend the user
    $throttle->suspend();
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Unsuspend user(s)

Unsuspends a login. This also clears all previous attempts by the specified login if they were suspended.

try
{
    // Find the user using the user id
    $throttle = Sentry::findThrottlerByUserId(1);

    // Unsuspend the user
    $throttle->unsuspend();
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Check if a User is Suspended

Checks to see if the user is suspended.

try
{
    $throttle = Sentry::findThrottlerByUserId(1);

    if($suspended = $throttle->isSuspended())
    {
        // User is Suspended
    }
    else
    {
        // User is not Suspended
    }
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Set the User Suspension Time

Sets the length of the suspension.

try
{
    $throttle = Sentry::findThrottlerByUserId(1);

    $throttle->setSuspensionTime(10);
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Get the User Suspension Time

Retrieves the length of the suspension time set by the throttling driver.

try
{
    $throttle = Sentry::findThrottlerByUserId(1);

    $suspensionTime = $throttle->getSuspensionTime();
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Add a Login Attempt

Adds an attempt to the throttle object.

try
{
    $throttle = Sentry::findThrottlerByUserId(1);

    $throttle->addLoginAttempt();
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Get Login Attempts

Retrieves the number of attempts a user currently has tried. Checks suspension time to see if login attempts can be reset. This may happen if the suspension time was (for example) 10 minutes however the last login was 15 minutes ago, attempts will be reset to 0.

try
{
    $throttle = Sentry::findThrottlerByUserId(1);

    $attempts = $throttle->getLoginAttempts();
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Clear Login Attempts

Clears all login attempts, it also unsuspends them. This does not unban a login.

try
{
    $throttle = Sentry::findThrottlerByUserId(1);

    $throttle->clearLoginAttempts();
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Check the User Throttle Status

Checks the login throttle status and throws a number of Exceptions upon failure.

try
{
    $throttle = Sentry::findThrottlerByUserId(1);

    if ($throttle->check())
    {
        echo 'Good to go.';
    }
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}
catch (Cartalyst\Sentry\Throttling\UserSuspendedException $e)
{
    $time = $throttle->getSuspensionTime();

    echo "User is suspended for [$time] minutes.";
}
catch (Cartalyst\Sentry\Throttling\UserBannedException $e)
{
    ehco 'User is banned.';
}

Set Attempt Limit

Sets the number of attempts allowed before suspension.

try
{
    $throttle = Sentry::findThrottlerByUserId(1);

    $throttle->setAttemptLimit(3);
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Get Attempt Limit

Retrieves the number of attempts allowed by the throttle object.

try
{
    $throttle = Sentry::findThrottlerByUserId(1);

    $attemptLimit = $throttle->getAttemptLimit();
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Exceptions

Below is a list of exceptions that the methods can throw.

Exception Description
Cartalyst\Sentry\Throttle\UserNotFoundException If the provided user was not found, this exception will be thrown.
Cartalyst\Sentry\Throttling\UserSuspendedException When the provided user is suspended, this exception will be thrown.
Cartalyst\Sentry\Users\UserBannedException When the provided user is banned, this exception will be thrown.

Find User(s)

Find a User by their Id

Retrieves a throttle object based on the user ID provided. Will always retrieve a throttle object.

try
{
    $throttle = Sentry::findThrottlerByUserId(1);
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Find a User by their Login

Retrieves a throttle object based on the user login provided. Will always retrieve a throttle object.

try
{
    $throttle = Sentry::findThrottlerByUserLogin('john.doe@example.com');
}
catch (Cartalyst\Sentry\Users\UserNotFoundException $e)
{
    echo 'User was not found.';
}

Exceptions

Below is a list of exceptions that the methods can throw.

Exception Description
Cartalyst\Sentry\Users\UserNotFoundException If the provided user was not found, this exception will be thrown.

You wont find fancy lifestyle graphics and marketing bravado here. Just cold... hard... code...

Code Well, Rock On!
Processing Payment...