Permalink
Browse files

Merge branch '3.2/develop' into 3.2/master

  • Loading branch information...
2 parents 24073ab + 5ee08a9 commit 8e9c29f28e604b07f662d672a8f025ec77975430 @zombor zombor committed Aug 24, 2012
View
18 classes/kohana/auth.php
@@ -5,7 +5,7 @@
*
* @package Kohana/Auth
* @author Kohana Team
- * @copyright (c) 2007-2010 Kohana Team
+ * @copyright (c) 2007-2012 Kohana Team
* @license http://kohanaframework.org/license
*/
abstract class Kohana_Auth {
@@ -47,6 +47,7 @@ public static function instance()
/**
* Loads Session and configuration options.
*
+ * @param array $config Config Options
* @return void
*/
public function __construct($config = array())
@@ -67,6 +68,7 @@ public function __construct($config = array())
* Gets the currently logged in user from the session.
* Returns NULL if no user is currently logged in.
*
+ * @param mixed $default Default value to return if the user is currently not logged in.
* @return mixed
*/
public function get_user($default = NULL)
@@ -77,9 +79,9 @@ public function get_user($default = NULL)
/**
* Attempt to log in a user by using an ORM object and plain-text password.
*
- * @param string username to log in
- * @param string password to check against
- * @param boolean enable autologin
+ * @param string $username Username to log in
+ * @param string $password Password to check against
+ * @param boolean $remember Enable autologin
* @return boolean
*/
public function login($username, $password, $remember = FALSE)
@@ -93,8 +95,8 @@ public function login($username, $password, $remember = FALSE)
/**
* Log out a user by removing the related session variables.
*
- * @param boolean completely destroy the session
- * @param boolean remove all tokens for user
+ * @param boolean $destroy Completely destroy the session
+ * @param boolean $logout_all Remove all tokens for user
* @return boolean
*/
public function logout($destroy = FALSE, $logout_all = FALSE)
@@ -121,7 +123,7 @@ public function logout($destroy = FALSE, $logout_all = FALSE)
* Check if there is an active session. Optionally allows checking for a
* specific role.
*
- * @param string role name
+ * @param string $role role name
* @return mixed
*/
public function logged_in($role = NULL)
@@ -134,7 +136,7 @@ public function logged_in($role = NULL)
* method is deprecated, [Auth::hash] should be used instead.
*
* @deprecated
- * @param string plaintext password
+ * @param string $password Plaintext password
*/
public function hash_password($password)
{
View
16 classes/kohana/auth/file.php
@@ -5,7 +5,7 @@
*
* @package Kohana/Auth
* @author Kohana Team
- * @copyright (c) 2007-2010 Kohana Team
+ * @copyright (c) 2007-2012 Kohana Team
* @license http://kohanaframework.org/license
*/
class Kohana_Auth_File extends Auth {
@@ -27,9 +27,9 @@ public function __construct($config = array())
/**
* Logs a user in.
*
- * @param string username
- * @param string password
- * @param boolean enable autologin (not supported)
+ * @param string $username Username
+ * @param string $password Password
+ * @param boolean $remember Enable autologin (not supported)
* @return boolean
*/
protected function _login($username, $password, $remember)
@@ -53,7 +53,7 @@ protected function _login($username, $password, $remember)
/**
* Forces a user to be logged in, without specifying a password.
*
- * @param mixed username
+ * @param mixed $username Username
* @return boolean
*/
public function force_login($username)
@@ -65,7 +65,7 @@ public function force_login($username)
/**
* Get the stored password for a username.
*
- * @param mixed username
+ * @param mixed $username Username
* @return string
*/
public function password($username)
@@ -76,7 +76,7 @@ public function password($username)
/**
* Compare password with original (plain text). Works for current (logged in) user
*
- * @param string $password
+ * @param string $password Password
* @return boolean
*/
public function check_password($password)
@@ -91,4 +91,4 @@ public function check_password($password)
return ($password === $this->password($username));
}
-} // End Auth File
+} // End Auth File
View
23 config/userguide.php
@@ -0,0 +1,23 @@
+<?php defined('SYSPATH') or die('No direct script access.');
+
+return array(
+ // Leave this alone
+ 'modules' => array(
+
+ // This should be the path to this modules userguide pages, without the 'guide/'. Ex: '/guide/modulename/' would be 'modulename'
+ 'auth' => array(
+
+ // Whether this modules userguide pages should be shown
+ 'enabled' => TRUE,
+
+ // The name that should show up on the userguide index page
+ 'name' => 'Auth',
+
+ // A short description of this module, shown on the index page
+ 'description' => 'User authentication and authorization.',
+
+ // Copyright message, shown in the footer for this module
+ 'copyright' => '&copy; 2008–2012 Kohana Team',
+ )
+ )
+);
View
13 guide/auth/config.md
@@ -0,0 +1,13 @@
+# Configuration
+
+The default configuration file is located in `MODPATH/auth/config/auth.php`. You should copy this file to `APPPATH/config/auth.php` and make changes there, in keeping with the [cascading filesystem](../kohana/files).
+
+[Config merging](../kohana/config#config-merging) allows these default configuration settings to apply if you don't overwrite them in your application configuration file.
+
+Name | Type | Default | Description
+-----|------|---------|------------
+driver | `string` | file | The name of the auth driver to use.
+hash_method | `string` | sha256 | The hashing function to use on the passwords.
+hash_key | `string` | NULL | The key to use when hashing the password.
+session_type | `string` | [Session::$default] | The type of session to use when storing the auth user.
+session_key | `string` | auth_user | The name of the session variable used to save the user.
View
79 guide/auth/driver/develop.md
@@ -0,0 +1,79 @@
+# Developing Drivers
+
+## Real World Example
+
+Sometimes the best way to learn is to jump right in and read the code from another module. The [ORM](https://github.com/kohana/orm/blob/3.2/develop/classes/kohana/auth/orm.php) module comes with an auth driver you can learn from.
+
+[!!] We will be developing an `example` driver. In your own driver you will substitute `example` with your driver name.
+
+This example file would be saved at `APPPATH/classes/auth/example.php` (or `MODPATH` if you are creating a module).
+
+---
+
+## Quick Example
+
+First we will show you a quick example and then break down what is going on.
+
+~~~
+class Auth_Example extends Auth
+{
+ protected function _login($username, $password, $remember)
+ {
+ // Do username/password check here
+ }
+
+ public function password($username)
+ {
+ // Return the password for the username
+ }
+
+ public function check_password($password)
+ {
+ // Check to see if the logged in user has the given password
+ }
+
+ public function logged_in($role = NULL)
+ {
+ // Check to see if the user is logged in, and if $role is set, has all roles
+ }
+
+ public function get_user($default = NULL)
+ {
+ // Get the logged in user, or return the $default if a user is not found
+ }
+}
+~~~
+
+## Extending Auth
+
+All drivers must extend the [Auth] class.
+
+ class Auth_Example extends Auth
+
+## Abstract Methods
+
+The `Auth` class has 3 abstract methods that must be defined in your new driver.
+
+~~~
+abstract protected function _login($username, $password, $remember);
+
+abstract public function password($username);
+
+abstract public function check_password($user);
+~~~
+
+## Extending Functionality
+
+Given that every auth system is going to check if users exist and if they have roles or not you will more than likely have to change some default functionality.
+
+Here are a few functions that you should pay attention to.
+
+~~~
+public function logged_in($role = NULL)
+
+public function get_user($default = NULL)
+~~~
+
+## Activating the Driver
+
+After you create your driver you will want to use it. It is a easy as setting the `driver` [configuration](config) option to the name of your driver (in our case `example`).
View
19 guide/auth/driver/file.md
@@ -0,0 +1,19 @@
+# File Driver
+
+The [Auth::File] driver is included with the auth module.
+
+Below are additional configuration options that can be set for this driver.
+
+Name | Type | Default | Description
+-----|------|---------|-------------
+users | `array` | array() | A user => password (_hashed_) array of all the users in your application
+
+## Forcing Login
+
+[Auth_File::force_login] allows you to force a user login without a password.
+
+~~~
+// Force the user with a username of admin to be logged into your application
+Auth::instance()->force_login('admin');
+$user = Auth::instance()->get_user();
+~~~
View
0 guide/auth/edit.md
No changes.
View
19 guide/auth/index.md
@@ -0,0 +1,19 @@
+# Auth
+
+User authentication and authorization is provided by the auth module.
+
+The auth module is included with Kohana, but needs to be enabled before you can use it. To enable, open your `application/bootstrap.php` file and modify the call to [Kohana::modules] by including the auth module like so:
+
+~~~
+Kohana::modules(array(
+ ...
+ 'auth' => MODPATH.'auth',
+ ...
+));
+~~~
+
+Next, you will then need to [configure](config) the auth module.
+
+The auth module provides the [Auth::File] driver for you. There is also an auth driver included with the ORM module.
+
+As your application needs change you may need to find another driver or [develop](driver/develop) your own.
View
62 guide/auth/login.md
@@ -0,0 +1,62 @@
+# Log in and out
+
+The auth module provides methods to help you log users in and out of your application.
+
+## Log in
+
+The [Auth::login] method handles the login.
+
+~~~
+// Handled from a form with inputs with names email / password
+$post = $this->request->post();
+$success = Auth::instance()->login($post['email'], $post['password']);
+
+if ($success)
+{
+ // Login successful, send to app
+}
+else
+{
+ // Login failed, send back to form with error message
+}
+~~~
+
+## Logged in User
+
+There are two ways to check if a user is logged in. If you just need to check if the user is logged in use [Auth::logged_in].
+
+~~~
+if (Auth::instance()->logged_in())
+{
+ // User is logged in, continue on
+}
+else
+{
+ // User isn't logged in, redirect to the login form.
+}
+~~~
+
+You can also get the logged in user object by using [Auth::get_user]. If the user is null, then no user was found.
+
+~~~
+$user = Auth::instance()->get_user();
+
+// Check for a user (NULL if not user is found)
+if ($user !== null)
+{
+ // User is found, continue on
+}
+else
+{
+ // User was not found, redirect to the login form
+}
+~~~
+
+## Log out
+
+The [Auth::logout] method will take care of logging out a user.
+
+~~~
+Auth::instance()->logout();
+// Redirect the user back to login page
+~~~
View
9 guide/auth/menu.md
@@ -1,7 +1,6 @@
## [Auth]()
-- [Config](config)
-- [User Model](user)
-- [Register Users](register)
+- [Configuration](config)
- [Log in and out](login)
-- [Edit User](edit)
-- [Using Roles](roles)
+- Drivers
+ - [File](driver/file)
+ - [Developing](driver/develop)
View
0 guide/auth/register.md
No changes.
View
0 guide/auth/roles.md
No changes.
View
0 guide/auth/user.md
No changes.

0 comments on commit 8e9c29f

Please sign in to comment.