sentry laravel
DESCRIPTION
laravel with sentry documentationTRANSCRIPT
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.';
}