One of the changes to the 3.1 release of Kohana has been the removal of the ORM driver as part of the official Auth module. To avoid the confusion that the Auth module required the ORM module, Auth now ships with only a file driver.
This has left some people under the impression that in order to use the ORM, porting a driver is necessary. This is not the case, in fact, the ORM Auth driver is now living in the ORM module with all the database schema examples in MySQL and PostgreSQL.
To get started, you are first going to need to have Kohana 3.1 installed with the Auth, Database, and ORM modules enabled and configured. In your APP_PATH/config directory your auth.php configuration file needs to have the driver set to use the ORM, and a hash_key must be specified. Here is an example of a complete auth.php config file:
Auth configuration: config/auth.php
Once this is accomplished, you will want to add the necessary database tables to allow the ORM driver to function properly.
Supplied in the ORM module, you will find the example database schemas, and you can view them here for MySQL and PostgreSQL. These are basic, example schemas that show the core functionality, and these can be used as foundations to build your final user authentication solution.
For this tutorial, we will be using MySQL for our database. If you are using Postgres, there should not be too many differences as the ORM is database agnostic.
Looking over the public methods for the Kohana_Auth_ORM class let's us see the basic functionality that is included in the driver:
logged_in - checks if a user is currently logged in, and optionally checks against a role or set of roles.
force_login - logs in a user without a password
auto_login - logs a user in based on cookie settings, great for "remember me" functionality
get_user - returns the currently logged in user, automatically logging them in if necessary. Returns FALSE if no user is logged in.
logout - logs the user out and can optionally remove any auto-logins for that user
password - gets the password for the user
check_password - compares a password with the stored hashed password for the user
These methods cover all of the necessary functionality to get user authentication up and running in an application. For this tutorial, we will construct a controller with a basic set of actions and views to allow the creation, login, logout, password reset, and logout actions for a user. A quick glance at the Model_Auth_User class supplied with the ORM reveals that most of the heavy lifting has been done for us.
We can begin by creating a new controller where we can create actions to demonstrate how to use the module in real code. For this example, we will create a User controller with actions for creating an account, logging in and out, and viewing user info when logged in. This example does support the "remember me" functionality.
User Controller: classes/controller/user.php
As you see here, we are using the Template controller to make it simple to display our views. This is an example template that is included in the source files for this tutorial:
Now we can create simple view scripts and display them inside our template. This will make the rest of the views small, and simple to read. In the controller we are loading the user/create view into the $content view variable, so let's create a new folder in our view directory named users and add the following views:
User signup view: create.php
Login view: login.php
User info view: info.php
Here we have a basic form, with an area to display a success or failure message, sticky form fields, and error messages displayed for each user. We are almost ready to begin creating users, right after we complete the custom messages for validation failures. In the controller actions we specified the location of our messages in the models directory, so you will need to create a new directory named models in your messages directory inside your APP_PATH and add a file named user.php with the following contents:
This covers almost all the messages for validators in the Model_Auth_User class, but there still is the _external validator for password confirmation. To provide a custom message for that also, you will need to crete a new directory named user inside messages/models (so the path is APP_PATH/messages/models/user), and add a file named _external.php with the following contents:
You are now ready to begin adding users to this example application, complete with remember me functionality. Adding additional features like updating user information, changing passwords, or adding more user information should all be relatively simple.
The source code for this tutorial can be downloaded here. Please feel free to use the comment section below to post any questions or concerns.