First, you need to create the table (or use your existing one). Let's use MySql here. My table looks like this:

CREATE TABLE `auth` (
  `id` int(11) NOT NULL auto_increment,
  `handle` varchar(15) NOT NULL,
  `password` varchar(32) NOT NULL,
  PRIMARY KEY  (`id`)
);

Next, we'll configure Solar_Auth to use the table we just created. Edit your Solar config file to have this:

<?php
// Solar.config.php:

$config = array();

// use the SQL adapter
$config['Solar_Auth']['adapter'] = 'Solar_Auth_Adapter_Sql';

// use the table we just created
$config['Solar_Auth_Adapter_Sql']['table'] = 'auth';

// set the names of both handle (username) and password column
$config['Solar_Auth_Adapter_Sql']['handle_col'] = 'handle';
$config['Solar_Auth_Adapter_Sql']['passwd_col'] = 'password';

// use some salt for the passwords
$config['Solar_Auth_Adapter_Sql']['salt'] = 'random noice';

return $config;
?>

I expect you to have configured your database connection already in your config file so I left it out from there.

Next, let's create a sign-in form. Our sign-in page is called login.

<?php
// login.php:

echo $this->form()
          ->text(array(
                'name'    => 'handle',
                'label'   => 'Username',
          ))
          ->password(array(
                'name'    => 'passwd',
                'label'   => 'Password',
          ))
          ->submit(array(
                'name'    => 'process',
                'value'   => $this->getTextRaw('PROCESS_LOGIN'),
          ))
          ->fetch();
?>

That form doesn't display any status messages like "authentication failed", even though Solar_Auth has this functionality built-in. You can see a more complete sign-in form here.

When a user submits that form, Solar checks to see if there is in fact a login attempt by looking at $_POST['process']. If it matches the value we set for it in the form, the authentication kicks in.

You can configure almost every aspect of this process. You can name the $_POST keys that the form uses or you can set it to authenticate by checking for credentials in $_GET instead of $_POST and so on. We'll use the default config values for this example so no need to edit any config keys. Here's the full list of configuration options (scroll down to Protected).

Solar instantiates the Solar_User object out-of-the-box if you extend Solar_App_Base in your application class. Solar_User itself instantiates Solar_Auth which is needed for user authentication. If you don't extend Solar_App_Base or you have overwritten the method _setup() in your application class, this is what you need to put in your _setup():

<?php
// register a Solar_Sql object if not already
if (! Solar_Registry::exists('sql')) {
    Solar_Registry::set('sql', Solar::factory('Solar_Sql'));
}

// register a Solar_User object if not already.
// this will trigger the authentication process.
if (! Solar_Registry::exists('user')) {
    Solar_Registry::set('user', Solar::factory('Solar_User'));
}
?>

We make sure Solar_Sql is available for the SQL auth adapter and we instantiate the Solar_User class. This will start the authentication process.

That's all there is to it to get SQL-based authentication working with Solar. This is one of the many tools in Solar that help you Stop Writing Loner Applications. Using Solar_Auth_Adapter_Sql you could easily use your existing user table for authenticating users in your Solar app.

This was a planned segway for my next blog post about enabling Persistent Logins on your site using Solar. So keep your eye on that! :-)

Update: I wrote about persistent logins like I promised. See it here. Also, take a look at Raymond Kolbe's blog entry about SQL based authentication.