sentry laravel

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

Upload: xhiko-tanaka

Post on 27-Oct-2015

328 views

Category:

Documents


1 download

DESCRIPTION

laravel with sentry documentation

TRANSCRIPT

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 : AllowUsers 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' => '[email protected]',

'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' => '[email protected]',

'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' => '[email protected]',

'password' => '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' => '[email protected]',

'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 = '[email protected]';

$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 = '[email protected]';

$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('[email protected]');

// 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' => '[email protected]',

'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('[email protected]');

}

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('[email protected]');

// 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('[email protected]');

// 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('[email protected]');

}

catch (Cartalyst\Sentry\Users\UserNotFoundException $e)

{

echo 'User was not found.';

}