guide/auth/driver/develop.md

   1 # Developing Drivers
   2
   3 ## Real World Example
   4
   5 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.
   6
   7 [!!] We will be developing an `example` driver. In your own driver you will substitute `example` with your driver name.
   8
   9 This example file would be saved at `APPPATH/classes/auth/example.php` (or `MODPATH` if you are creating a module).
  10
  11 ---
  12
  13 ## Quick Example
  14
  15 First we will show you a quick example and then break down what is going on.
  16
  17 ~~~
  18 class Auth_Example extends Auth
  19 {
  20         protected function _login($username, $password, $remember)
  21         {
  22                 // Do username/password check here
  23         }
  24
  25         public function password($username)
  26         {
  27                 // Return the password for the username
  28         }
  29
  30         public function check_password($password)
  31         {
  32                 // Check to see if the logged in user has the given password
  33         }
  34
  35         public function logged_in($role = NULL)
  36         {
  37                 // Check to see if the user is logged in, and if $role is set, has all roles
  38         }
  39
  40         public function get_user($default = NULL)
  41         {
  42                 // Get the logged in user, or return the $default if a user is not found
  43         }
  44 }
  45 ~~~
  46
  47 ## Extending Auth
  48
  49 All drivers must extend the [Auth] class.
  50
  51         class Auth_Example extends Auth
  52
  53 ## Abstract Methods
  54
  55 The `Auth` class has 3 abstract methods that must be defined in your new driver.
  56
  57 ~~~
  58 abstract protected function _login($username, $password, $remember);
  59
  60 abstract public function password($username);
  61
  62 abstract public function check_password($user);
  63 ~~~
  64
  65 ## Extending Functionality
  66
  67 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.
  68
  69 Here are a few functions that you should pay attention to.
  70
  71 ~~~
  72 public function logged_in($role = NULL)
  73
  74 public function get_user($default = NULL)
  75 ~~~
  76
  77 ## Activating the Driver
  78
  79 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`).