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 that is assigned to a group, and if that group has different access permissions, the user's access is always determined by the group access.

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

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:
Administrator Group

{ "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 : 1permission. Notice that we are denying the user.delete permission of this user, in this example, you don't need to to 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.

Authenticate
Authenticates a user based on the provided credentials.

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

Exceptions
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.

Example
try {

// Set login credentials $credentials = array( 'email' => 'john.doe@example.com',

'password' => 'test', );

// Try to 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 throttle is enabled catch (Cartalyst\Sentry\Throttling\UserSuspendedException $e) { echo 'User is suspended.'; } catch (Cartalyst\Sentry\Throttling\UserBannedException $e) { echo 'User is banned.'; }

Authenticate and Remember

Authenticates and Remembers a user based on credentials. This is an helper function for theauthenticate() 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);

Logs a User In
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.

Exceptions
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.

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

// Log the user in

Sentry::login($user, false); } catch (Cartalyst\Sentry\Users\LoginRequiredException $e) { echo 'Login field is required.'; } catch (Cartalyst\Sentry\Users\UserNotActivatedException $e) { echo 'User not activated.'; } catch (Cartalyst\Sentry\Users\UserNotFoundException $e) { echo 'User not found.'; }

// 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.'; }

Login and Remember

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);

Logs a User Out

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
// Logs the user out Sentry::logout();

Helpers

Check if the User is Logged In

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 }

Create a new User

In this section you will learn how to create a user and assign him a group. 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.

When you are creating your user, and something goes wrong, you most likely want to know where is the problem, well, Sentry got you covered, and if a problem arises, individual Exceptions are thrown, one for each error you have.

Exceptions
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. What this means is, if your login field is email and that email address is already registerd on your database, you can't use this email for this user.

Examples
Create a User and assign him an existing Group

try { // Create the user $user = Sentry::getUserProvider()->create(array( 'email' => 'john.doe@example.com',

'password' => 'test', ));

// Find the group using the group id $adminGroup = Sentry::getGroupProvider()->findById(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.'; }

In this example we are creating a new user and assigning him with a group. As you can see there is an extra Exception Cartalyst\Sentry\Groups\GroupNotFoundException, that is not referenced on the list above, this is because, we are fetching the group that we want to assign, and if that group does not exist, this Exception will be thrown.

Create an user and Grant Permissions

try { // Create the user $user = Sentry::getUserProvider()->create(array( 'email' 'password' => 'john.doe@example.com', => 'test',

'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 login already exists.'; }

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.

Register a User
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.

Exceptions
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. What this means is, if your login field is email and that email address is already registerd on your database, you can't use this email for this user.

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.'; }

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.

Exceptions
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. What this means is, if your login field is email and that email address is already registered in your database, you can't use this email for this user.
Cartalyst\Sentry\Users\UserNotFoundException

If the provided user was not found, this exception will be thrown.

Examples
Update the User details

try { // Find the user using the user id $user = Sentry::getUserProvider()->findById(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.'; }

In this example we are just updating the user information. If you provide another email address, and that email address is already registered in your system, an ExceptionCartalyst\Sentry\Users\UserExistsException will be thrown.

Assign a new Group to a User

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

// Find the group using the group id $adminGroup = Sentry::getGroupProvider()->findById(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.'; }

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.

Remove a Group from the User

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

// Find the group using the group id $adminGroup = Sentry::getGroupProvider()->findById(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.'; }

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.

Update the User details and assign a new Group

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

// Find the group using the group id $adminGroup = Sentry::getGroupProvider()->findById(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.'; }

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..

Note: If the

Delete a user
Deleting users is very simple and easy.

Exceptions
Cartalyst\Sentry\Users\UserNotFoundException

If the provided user was not found, this exception will be thrown.

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

// Delete the user $user->delete(); } catch (Cartalyst\Sentry\Users\UserNotFoundException $e) {

echo 'User was not found.'; }

Activating a User
User activation is very easy with Sentry, you need to first find the user you want to activate, then use theattemptActivation() method and provide the activation code, if the activation passes it will return trueotherwise, it will return false . If the user you are trying to activate, is already activated, an ExceptionCartalyst\Sentry\Users\UserAlreadyActivatedException will be thrown.

Exceptions
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.

Example
try

{ // Find the user using the user id $user = Sentry::getUserProvider()->findById(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.'; }

Reset a User Password

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

Exceptions
Cartalyst\Sentry\Users\UserNotFoundException

If the provided user was not found, this exception will be thrown.

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::getUserProvider()->findByLogin('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::getUserProvider()->findById(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.'; }

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

Exceptions
Cartalyst\Sentry\Users\UserNotFoundException

If the provided user was not found, this exception will be thrown.

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, usecheck() instead.
Example

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.
Example

$users = Sentry::getUserProvider()->findAll();

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

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

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

Find all the Users in a Group

Finds all users assigned to a group.

Example
$group = Sentry::getGroupProvider()->findById(1);

$users = Sentry::getUserProvider()->findAllInGroup($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.

Example

try { $user = Sentry::getUserProvider()->findByCredentials(array( 'email' => 'john.doe@example.com',

'password' => 'test', 'first_name' => 'John', )); }

// The following Exception is a subclass of UserNotFoundException // and must be put first if you choose to use it. There may be // security consequences by telling the user their password is wrong // but the username is correct, however the choice is there. See // https://github.com/cartalyst/sentry/issues/148 catch (Cartalyst\Sentry\Users\WrongPasswordException $e) { echo 'User was found however the password you provided did not match.'; }

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

Find a User by their Id

Find a user by their ID.
Example

try { $user = Sentry::getUserProvider()->findById(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.
Example

try { $user = Sentry::getUserProvider()->findByLogin('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.
Example

try { $user = Sentry::getUserProvider()>findByActivationCode('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.
Example

try {

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

Helpers checkPassword()
Checks if the provided password matches the user's current password.
Example

try { // Find the user using the user id $user = Sentry::getUserProvider()->findById(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.
Example

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

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

getPermissions()
Returns the user permissions.
Example

try { // Find the user using the user id $user = Sentry::getUserProvider()->findById(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.
Example

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.
Example

try { // Find the user using the user id $user = Sentry::getUserProvider()->findById(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.
Example

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.
Example

try {

// Find the user $user = Sentry::getUserProvider()->findByLogin('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.

Example
try {

// Find the user $user = Sentry::getUserProvider()->findByLogin('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.
Example

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

// Find the Administrator group $admin = Sentry::getGroupProvider()->findByName('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.'; }

Create a new Group

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

Exceptions
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.

Example
try { // Create the group $group = Sentry::getGroupProvider()->create(array( 'name' => 'Users',

'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'; }

Update a Group
In this section you will learn how easy it is to update a Group.

Exceptions
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\Users\GroupNotFoundException

If the provided group was not found, this exception will be thrown.

Example
try

{ // Find the group using the group id $group = Sentry::getGroupProvider()->findById(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\GroupExistsException $e) { echo 'Group already exists.'; } catch (Cartalyst\Sentry\Groups\GroupNotFoundException $e) { echo 'Group was not found.';

Delete a Group
Deleting groups is very simple and easy.

Exceptions
Cartalyst\Sentry\Groups\GroupNotFoundException

If the provided group was not found, this exception will be thrown.

Example
try { // Find the group using the group id $group = Sentry::getGroupProvider()->findById(1);

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

Finding Groups
Sentry provides simple methods to find you your groups.

Exceptions
Cartalyst\Sentry\Groups\GroupNotFoundException

If the provided group was not found, this exception will be thrown.

Find all the Groups

This will return all the groups.
Example

$groups = Sentry::getGroupProvider()->findAll();

Find a group by it's ID.

Find a group by it's ID.
Example

try {

$group = Sentry::getGroupProvider()->findById(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.

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

Helpers

getPermissions()
Returns the permissions of a group.
Example

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

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

Throttling Management
..

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
..

Exceptions
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\Throttling\UserBannedException

When the provided user is banned, this exception will be thrown.

Ban user(s)
Bans the user associated with the throttle.
Example

try { // Find the user using the user id $throttle = Sentry::getThrottleProvider()->findByUserId(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.
Example

try

{ // Find the user using the user id $throttle = Sentry::getThrottleProvider()->findByUserId(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.
Example

try { $throttle = Sentry::getThrottleProvider()->findByUserId(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).
Example

try { // Find the user using the user id $throttle = Sentry::getThrottleProvider()->findByUserId(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.
Example

try { // Find the user using the user id $throttle = Sentry::getThrottleProvider()->findByUserId(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.
Example

try { $throttle = Sentry::getThrottleProvider()->findByUserId(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.
Example

try { $throttle = Sentry::getThrottleProvider()->findByUserId(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.
Example

try { $throttle = Sentry::getThrottleProvider()->findByUserId(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.
Example

try

{ $throttle = Sentry::getThrottleProvider()->findByUserId(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.
Example

try { $throttle = Sentry::getThrottleProvider()->findByUserId(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.
Example

try { $throttle = Sentry::getThrottleProvider()->findByUserId(1);

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

Check the Throttle Status

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

try

{ $throttle = Sentry::getThrottleProvider()->findByUserId(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.

Example

try { $throttle = Sentry::getThrottleProvider()->findByUserId(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.
Example

try { $throttle = Sentry::getThrottleProvider()->findByUserId(1);

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

Find User(s) Exceptions

Cartalyst\Sentry\Users\UserNotFoundException

If the provided user was not found, this exception will be thrown.

Find a User by their Id

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

try { $throttle = Sentry::getThrottleProvider()->findByUserId(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.
Example

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