1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
|
# Users
We'll start with the **User** handling. Gatekeeper makes it simple to manage users and perform the usual CRUD (create, read update, delete) operations on their data.
Users are represented as objects in the code with the following properties:
- username
- password
- email
- firstName
- lastName
- status
- id
- resetCode
- resetCodeTimeout
- groups
- created
- updated
- groups (relational)
- permissions (relational)
- loginAttempts (relational)
You can access this data on a populated user object as you would any other object properties:
```php
<?php
echo 'Full name: '.$user->firstName.' '.$user->lastName."\n";
?>
```
## Creating Users
To create a user, you only need to provide the user details to the `register` method:
```php
<?php
$credentials = array(
'username' => 'ccornutt',
'password' => 'test1',
'email' => 'ccornutt@phpdeveloper.org',
'first_name' => 'Chris',
'last_name' => 'Cornutt'
);
Gatekeeper::register($credentials);
?>
```
The return value from the `register` call is a *boolean* indicating the pass/fail status of the registration.
Addiitonally, you can also link the user to permissions at create time:
```php
<?php
$credentials = array(
'username' => 'ccornutt',
'password' => 'test1',
'email' => 'ccornutt@phpdeveloper.org',
'first_name' => 'Chris',
'last_name' => 'Cornutt'
);
// Use can use permission names
$credentials['permissions'] = array('perm1', 'perm2');
// or use IDs
$credentials['permissions'] = array(1, 2);
Gatekeeper::register($credentials);
?>
```
**NOTE:** The permissions by the name/id you use must exist *before* the user, otherwise the link is not created.
You can also create groups the same way:
```php
<?php
$credentials = array(
'username' => 'ccornutt',
'password' => 'test1',
'email' => 'ccornutt@phpdeveloper.org',
'first_name' => 'Chris',
'last_name' => 'Cornutt'
);
// Use can use permission names
$credentials['groups'] = array('group1', 'group2');
// or use IDs
$credentials['groups'] = array(1, 2);
Gatekeeper::register($credentials);
?>
```
## Removing users
Deleteing user records can be done with the `deleteUserById` method:
```php
<?php
if (Gatekeeper::deleteUserById(1) === true) {
echo "User removed successfully!";
}
// Or, if you already have the User model object
Gatekeeper::deleteUser($user);
?>
```
## Activating/Deactivating Users
You can mark a user as active or inactive in the system easily. Inactive users will not be able to log in using the `authenticate` method. Changing the user status is easy:
```php
<?php
// Change the user status to active
Gatekeeper::findUserById(1)->activate();
// Change the user status to inactive
Gatekeeper::findUserById($userId)->deactivate();
?>
```
## Get User Groups
You can use the `groups` relational property to find the groups the user is a member of. It will return an iterable collection
you can use like any other array of data:
```php
<?php
$groups = Gatekeeper::findUserById($userId)->groups;
foreach($groups as $group) {
echo 'Group name: '.$group->name."\n";
}
?>
```
## See if a user is in a group
You can check to see if a user is in a group with the `inGroup` method:
```php
<?php
$groupId = 1;
if (Gatekeeper::findUserById(1)->inGroup($groupId) === true) {
echo 'The user is in the group!';
}
?>
```
## Adding a user to a group
You can add a user to a group by using the group ID:
```php
<?php
$groupId = 1;
if (Gatekeeper::findUserById($userId)->addGroup($groupId) === true) {
echo "User added successfullly!";
}
?>
```
## Get a list of user permissions
You can use the `permissions` property to get the full set of user permissions. These are the permissions **directly assigned** to the user, not to any groups they may be a part of:
```php
<?php
$permissions = Gatekeeper::findUserById(1)->permissions;
foreach ($permissions as $perm) {
echo $perm->description."\n";
}
?>
```
## Giving a user a permission
You can assign a permission **directly** to a user (not through a group) with the `addPermission` method:
```php
<?php
$userId = 1;
$permissionId = 1;
if (Gatekeeper::findUserById($userId)->addPermission($permissionId) === true) {
echo 'Permission added!';
}
?>
```
## Check if a user is currently banned (throttling)
If the user login has had too many failed attempts, they'll be marked as "banned" in the system. You can find a user's ban status with the `isBanned` check:
```php
<?php
if (Gatekeeper::findUserById(1)->isBanned() === true) {
echo "User is banned!";
}
?>
```
## Get full user throttle information
You can also get the full throttling information for a user using the `throttle` property:
```php
<?php
$throttle = Gatekeeper::findUserById(1)->throttle;
// This gives you properties like:
$throttle->attempts;
$throttle->status;
$throttle->lastAttempt;
$throttle->statusChange;
?>
```
## Get the number of login attempts
You can also get information about the number of times a login has been attempted for a user (valid or invalid) with the `loginAttempts` property:
```php
<?php
$attempts = Gatekeeper::findUserById(1)->loginAttempts;
echo "The user has tried to log in ".$attempts." times.";
?>
```
|
