Sentry

Sentry is a PHP 5.3+ fully-featured authentication & authorization system. It also provides additional features such as user groups and additional security features.

Sentry is a framework agnostic set of interfaces with default implementations, though you can substitute any implementations you see fit.

Features

It also provides additional features such as user groups and additional security features:

Configurable authentication (can use any type of authentication required, such as username or email)
Authorization
Activation of user (optional)
Groups and group permissions
"Remember me"
User suspension
Login throttling (optional)
User banning
Password resetting
User data
Interface driven - switch out your own implementations at will

Installation

Installation of Sentry is very easy. We've got a number of guides to get Sentry working with your favorite framework or on it's own:

Install Sentry

Getting Started

Upgrading

Currently, we do not have an upgrade method from Sentry 1, however we may be able to publish one before the stable release of Sentry 2.0. When upgrading between betas or release-candidates, please see our changelog.

Support

We offer support through our help forums, on IRC at #cartalyst and through GitHub issues (bugs only).

If you like Sentry, consider subscribing to our Arsenal. It allows us to keep creating awesome software and afford to eat at night. Subscribers also get priority support with all of our packages, both free and subscriber-only.

= = +============++++++===== = = Documentation +=+===++++============+++++++=+=======++ SENTRY BY CARTALYST 8477372871304 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.

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.

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
}

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
}

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
}

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.

jumper-forked / sentry

Sentry

Features

Installation

Getting Started

Upgrading

Support

About

Languages