Working with Objects
Each item in the system is represented by an object (a model
type). When you perform an operation like a find
or create
, an instance of the corresponding model is created. There's some common things that you can do on models all across the system. Rather than duplicate that information across multiple pages of the documentation, I'm going to put it here in one place.
Finding
You can use the magic "find by" handling to locate records of the various types. Most commonly, this would be used to locate a record by its unique ID number (all records have this). Here's some examples:
<?php
// Finding a User
$user = Gatekeeper::findUserById(1);
// Or a Group, maybe a Permission
$group = Gatekeeper::findGroupById(1);
$permission = Gatekeeper::findPermissionById(1);
?>
Each of these will return an object you can pull properties from. For example, a User
object has properties like username
, email
and firstName
. These can be accessed directly just like any other PHP property:
<?php
$user = Gatekeeper::findUserById(1);
echo 'My name is '.$user->firstName.', username is '.$user->username.' and email is '.$user->email;
?>
If no records are found given the criteria you provided, one of the "not found" Exception
options will be thrown.
NOTE: You can find the list of properties on the pages for each of the different types (like Users
and Groups
).
Deleting
You can also use common functionality to delete records from the system. This uses a format similar to the "find by" methods but instead uses a "delete by".
<?php
if (Gatekeeper::deleteUserById(1) === true) {
echo 'User deleted!';
}
// Or by username:
Gatekeeper::deleteUserByUsername('ccornutt');
?>
The delete calls can also use any property on the object, but there is one thing to watch out for. If you provide information that matches more than one record in the system, the operation will fail. For example, if there were five users with a first name of "Chris", the call doesn't know which one you want to remove, so it returns false.
In this case, you'll need to run a find
operation and locate the record you want. When you have the model instance you want, you can just call delete
directly on it:
<?php
$user = Gatekeeper::findUserByUsername('ccornutt');
$user->delete();
?>
Cloning
You can clone certain kinds of objects in the Gatekeeper system, duplicating the type of object and its relations.
Users
You can clone a user with the Gatekeeper::cloneUser
method. This will create a new user with the data provided and link this new user to the same permissions and groups as the user you're cloning.
<?php
$user1 = Gatekeeper::findUserByUsername('ccornutt');
$result = Gatekeeper::cloneUser($user1, [
'username' => 'ccornutt1',
'password' => 'super-secret',
'email' => 'ccornut2@mydomain.com',
'firstName' => 'Chris',
'lastName' => 'Cornutt2'
]);
if ($result === true) {
echo 'User cloned successfully!';
}
?>
In this case user cornutt1
will have the same permissions and groups as ccornutt
. The result of the cloneUser
function call is the success/fail status of the creation.