updating docs with a "common operations" page and removing that content from the other pages0.7

3 files changed, 58 insertions, 67 deletions

diff --git a/docs/groups.md b/docs/groups.md
index b838384..ce54856 100644
--- a/docs/groups.md
+++ b/docs/groups.md
@@ -23,29 +23,6 @@ Gatekeeper::createGroup($attrs);
 ?>
 ```
 
-## Finding Groups
-
-And, like users, you can find groups by their IDs:
-
-```php
-<?php
-$group = Gatekeeper::findGroupById(1);
-?>
-```
-
-If the group is not found, a `GroupNotFoundException` will be thrown.
-
-Additionally, you can find `Groups` by other properties:
-
-```php
-<?php
-$group = Gatekeeper::findGroupByName('group1');
-$group = Gatekeeper::findGroupByDescription('Group #1');
-
-// etc....
-?>
-```
-
 ## Getting Group Users
 
 Much like you can easily get the groups the user belongs to, you can also get the members of a group. This will return a collection of user objects:
diff --git a/docs/users.md b/docs/users.md
index dba3a32..d3dd665 100644
--- a/docs/users.md
+++ b/docs/users.md
@@ -46,50 +46,6 @@ Gatekeeper::register($credentials);
 
 The return value from the `register` call is a *boolean* indicating the pass/fail status of the registration.
 
-## Finding Users
-
-You can use the `findByUserId` method to locate a user by their ID number:
-
-```php
-<?php
-$userId = 1;
-$user = Gatekeeper::findUserById($userId);
-
-// Or, to get a property directly
-$username = Gatekeeper::findUserById($userId)->username;
-?>
-```
-
-The return value is an instance of the `UserModel` with the properties populated with the user data (if it was found). A `UserNotFoundException` will be thrown if the user is not found.
-
-Additionally, you can run a "find by" on any property in the `User` model, not just the ID value:
-
-```php
-<?php
-$user = Gatekeeper::findUserByUsername('ccornutt');
-$user = Gatekeeper::findUserByFirstName('Chris');
-
-// etc...
-?>
-```
-
-## Deleting Users
-
-You can delete users in much the same way you can find them. It's usually the best idea to use the `ID` (primary key) value if you're wanting to delete a specific user as that will definitely only find one user.
-
-```php
-<?php
-// This will delete the one user by ID
-Gatekeeper::deleteUserById(1);
-
-// If there's more than one "Chris" this will return false
-Gatekeeper::deleteUserByFirstName('Chris');
-
-?>
-```
-
-If you provide details and the system finds more than one record matching it, it will return `false` and not perform the `delete` operation.
-
 ## 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:
diff --git a/docs/working-with-objects.md b/docs/working-with-objects.md
new file mode 100644
index 0000000..0f3b18c
--- /dev/null
+++ b/docs/working-with-objects.md
@@ -0,0 +1,58 @@
+# 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
+<?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
+<?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`).
+
+## Deleteing
+
+You can also use common functionality to delete records from the system. This uses a format simialr to the "find by" methods but instead uses a "delete by".
+
+```php
+<?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
+<?php
+$user = Gatekeeper::findUserByUsername('ccornutt');
+$user->delete();
+?>
+```