diff options
Diffstat (limited to 'docs/site/index.html')
| -rw-r--r-- | docs/site/index.html | 225 |
1 files changed, 208 insertions, 17 deletions
diff --git a/docs/site/index.html b/docs/site/index.html index e661ac1..e1e7285 100644 --- a/docs/site/index.html +++ b/docs/site/index.html @@ -9,7 +9,7 @@ <link rel="shortcut icon" href="./img/favicon.ico"> - <title>My Docs</title> + <title>Gatekeeper</title> <link href="./css/bootstrap-custom.min.css" rel="stylesheet"> <link href="./css/font-awesome-4.0.3.css" rel="stylesheet"> @@ -35,7 +35,7 @@ <!-- Main title --> - <a class="navbar-brand" href=".">My Docs</a> + <a class="navbar-brand" href=".">Gatekeeper</a> </div> <!-- Expanded navigation --> @@ -52,32 +52,223 @@ <div class="col-md-3"><div class="bs-sidebar hidden-print affix well" role="complementary"> <ul class="nav bs-sidenav"> - <li class="main active"><a href="#welcome-to-mkdocs">Welcome to MkDocs</a></li> + <li class="main active"><a href="#gatekeeper-an-authentication-authorization-library">Gatekeeper: An Authentication & Authorization Library</a></li> - <li><a href="#commands">Commands</a></li> + <li><a href="#introduction">Introduction</a></li> - <li><a href="#project-layout">Project layout</a></li> + <li><a href="#dependencies">Dependencies</a></li> + + <li><a href="#setup">Setup</a></li> + + <li><a href="#authentication">Authentication</a></li> + + <li><a href="#users">Users</a></li> + + <li><a href="#groups">Groups</a></li> + + <li><a href="#password-reset-handling">Password Reset Handling</a></li> + + <li><a href="#contact">Contact</a></li> </ul> </div></div> <div class="col-md-9" role="main"> -<h1 id="welcome-to-mkdocs">Welcome to MkDocs</h1> -<p>For full documentation visit <a href="http://mkdocs.org">mkdocs.org</a>.</p> -<h2 id="commands">Commands</h2> +<h2 id="gatekeeper-an-authentication-authorization-library"><strong>Gatekeeper:</strong> An Authentication & Authorization Library</h2> +<h3 id="introduction">Introduction</h3> +<p>The <strong>Gatekeeper</strong> library is a simple drop-in library that can be used to manage users, permissions and groups for +your application. The goal is to make securing your application as simple as possible why still providing a solid and +secure foundation to base your user system around.</p> +<p><em>Gatekeeper</em> is best classified as a Role-Base Access Control (RBAC) system with users, groups and permissions. It is +framework-agnostic and is set up to use its own database for the user handling.</p> +<h3 id="dependencies">Dependencies</h3> +<p><em>Gatekeeper</em> makes use of several other PHP dependencies to help reduce code duplication:</p> +<ul> +<li><a href="http://github.com/enygma/modler">Modler</a></li> +<li><a href="http://github.com/robmorgan/phinx">Phinx</a></li> +<li><a href="http://github.com/ircmaxell/password-compat">password_compat</a></li> +<li><a href="http://github.com/rvlucas/phpdotenv">phpdotenv</a></li> +</ul> +<h3 id="setup">Setup</h3> +<p>There's a few things you'll need to do before using the system. First off, it uses <a href="https://phinx.org">Phinx</a> for working +with the database tables (creation and all). Second it uses the handy <a href="https://github.com/vlucas/phpdotenv">phpdotenv</a> library +to handle the loading of environment values. This helps you understand the installation and usage a bit better.</p> +<ol> +<li>Create a database named <code>gatekeeper</code> and create a user for it (this is configured later)</li> +</ol> +<pre><code>create database gatekeeper; +grant all on gatekeeper.* to 'gk-user'@'localhost' identified by 'some-password-here'; +flush privileges; +</code></pre> + +<ol> +<li>Copy the <code>.env.dist</code> file from the <em>Gatekeeper</em> vendor directory to the (non-<code>DOCUMENT_ROOT</code>) place of your choosing and rename it to <code>.env</code>.</li> +<li>Copy the <code>phinx.dist.xml</code> file to the place of your choosing (again, non-<code>DOCUMENT_ROOT</code>) and rename it to <code>phinx.yml</code>.</li> +</ol> +<pre><code>cp vendor/psecio/gatekeeper/.env.dist /tmp/someplace/.env +cp vendor/psecio/gatekeeper/phinx.dist.yml /tmp/someplace/phinx.yml +</code></pre> + +<ol> +<li>Open both of these files and update the <strong>connection information</strong> to match the database you created earlier.</li> +<li>Now we run the migrations:</li> +</ol> +<pre><code>vendor/bin/phinx migrate -c /tmp/somplace/phinx.yml +</code></pre> + +<p>Where the <code>/tmp/someplace/phinx.yml</code> is the path to where you put your <code>phinx.yml</code> file (again, not in the document root <strong>please!</strong>).</p> +<p>If you get errors here, be sure the connection information is correct.</p> +<ol> +<li>You're ready to go!</li> +</ol> +<p>You can now start using the <em>Gatekeeper</em> functionality in your application. You only need to call the <code>init</code> function to set +up the connection and get the instance configured:</p> +<pre><code class="php"><?php +require_once 'vendor/autoload.php'; +Gatekeeper::init(); +?> +</code></pre> + +<h3 id="authentication">Authentication</h3> +<p>One of the main features of the library is validating a <code>username</code> and <code>password</code> combination against a current user record. Is it achieved with the <code>authenticate</code> method:</p> +<pre><code class="php"><?php +$credentials = array( + 'username' => 'ccornutt', + 'password' => 'valid-password' +); +if (Gatekeeper::authenticate($credentials) == true) { + echo 'valid!'; +} +?> +</code></pre> + +<h3 id="users">Users</h3> +<p>We'll start with the <em>User</em> handling. <em>Gatekeeper</em> makes it simple to manage users and perform the usual CRUD (create, read +update, delete) operations on their data.</p> +<p>Users are represented as objects in the code with the following properties:</p> <ul> -<li><code>mkdocs new [dir-name]</code> - Create a new project.</li> -<li><code>mkdocs serve</code> - Start the live-reloading docs server.</li> -<li><code>mkdocs build</code> - Build the documentation site.</li> -<li><code>mkdocs help</code> - Print this help message.</li> +<li>username</li> +<li>password</li> +<li>email</li> +<li>firstName</li> +<li>lastName</li> +<li>status</li> +<li>id</li> +<li>resetCode</li> +<li>resetCodeTimeout</li> +<li>groups</li> +<li>created</li> +<li>updated</li> </ul> -<h2 id="project-layout">Project layout</h2> -<pre><code>mkdocs.yml # The configuration file. -docs/ - index.md # The documentation homepage. - ... # Other markdown pages, images and other files. +<p>You can access this data on a populated user object as you would any other object properties:</p> +<pre><code class="php"><?php +echo 'Full name: '.$user->firstName.' '.$user->lastName."\n"; +?> +</code></pre> + +<h4 id="creating-users">Creating Users</h4> +<p>To create a user, you only need to provide the user details to the <code>register</code> method:</p> +<pre><code class="php"><?php +$credentials = array( + 'username' => 'ccornutt', + 'password' => 'test1', + 'email' => 'ccornutt@phpdeveloper.org', + 'first_name' => 'Chris', + 'last_name' => 'Cornutt' +); +Gatekeeper::register($credentials); +?> </code></pre> + +<p>The return value from the <code>register</code> call is a <em>boolean</em> indicating the pass/fail status of the registration.</p> +<h4 id="finding-users">Finding Users</h4> +<p>You can use the <code>findByUserId</code> method to locate a user by their ID number:</p> +<pre><code class="php"><?php +$userId = 1; +$user = Gatekeeper::findUserById($userId); + +// Or, to get a property directly +$username = Gatekeeper::findUserById($userId)->username; +?> +</code></pre> + +<p>The return value is an instance of the <code>UserModel</code> with the properties populated with the user data (if it was found). A <code>UserNotFoundException</code> will be thrown if the user is not found.</p> +<h4 id="activatingdeactivating-users">Activating/Deactivating Users</h4> +<p>You can mark a user as active or inactive in the system easily. Inactive users will not be able to log in using the <code>authenticate</code> method. Changing the user status is easy:</p> +<pre><code class="php"><?php +// Change the user status to active +Gatekeeper::findUserById(1)->activate(); + +// Change the user status to inactive +Gatekeeper::findUserById($userId)->deactivate(); +?> +</code></pre> + +<h4 id="get-user-groups">Get User Groups</h4> +<p>You can use the <code>groups</code> 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:</p> +<pre><code class="php"><?php +$groups = Gatekeeper::findUserById($userId)->groups; +foreach($groups as $group) { + echo 'Group name: '.$group->name."\n"; +} +?> +</code></pre> + +<h3 id="groups">Groups</h3> +<h4 id="creating-a-group">Creating a Group</h4> +<p>Making a new group is as easy as making a new user. One thing to note, the <em>group name</em> must be *<em>unique</em>:</p> +<pre><code class="php"><?php +$attrs = array( + 'name' => 'Group #1' +); +Gatekeeper::createGroup($attrs); +?> +</code></pre> + +<h4 id="finding-groups">Finding Groups</h4> +<p>And, like users, you can find groups by their IDs:</p> +<pre><code class="php"><?php +$group = Gatekeeper::findGroupById(1); +?> +</code></pre> + +<p>If the group is not found, a <code>GroupNotFoundException</code> will be thrown.</p> +<h4 id="getting-group-users">Getting Group Users</h4> +<p>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:</p> +<pre><code class="php"><?php +$users = Gatekeeper::findGroupById(1)->users; + +foreach ($users as $user) { + echo 'Username: '.$user->username."\n"; +} +?> +</code></pre> + +<h3 id="password-reset-handling">Password Reset Handling</h3> +<p><em>Gatekeeper</em> also includes some password reset handling functionality. It doesn't try to send an email or output a web page +with the functionality. Instead, it provides methods to generate and validate a unique code. When the code is generated, it is +added into the user's record and stored for evaluation.</p> +<p>The code will expire in <em>one hour</em> from the time it was generated.</p> +<pre><code class="php"><?php +$user = Gatekeeper::findUserById(1); +$code = $user->getResetPasswordCode(); + +echo 'Your password reset code is: '.$code."\n"; + +// Now lets verify it... +$code = $_GET['code']; +if ($user->checkResetPasswordCode($code) === true) { + echo 'valid!'; +} +?> +</code></pre> + +<p>If the code is valid, it and the timeout are cleared from the user's record.</p> +<h3 id="contact">Contact</h3> +<p>If you have any questions or suggestions about this library, please let me know by adding an issue <a href="https://github.com/psecio/gatekeeper/issues">in the Gatekeeper Issues list</a> on GitHub.</p> +<p>Thanks! I hope you find <em>Gatekeeper</em> useful!</p> </div> </div> |