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.