[Catalyst] [patch] Catalyst::Authentication::Store::DBIx::Class's authenticate parameters Documentation

[Greg Matheson]

t0m and others on #catalyst helped me understand that the 
'username' key-value pair I was passing to authenticate was 
resulting in the first user in the user_class table being 
authenticated, a problem that has apparently been met by others 
too. See the message at 
http://lists.scsys.co.uk/pipermail/catalyst/2008-August/019560.html.

I had a different table column in id_field.

I thought the POD could be made more informative about this 
problem, so prepared a patch.

What it does is replace 'username' as the keyname passed to 
authenticate with 'user_id', the value of the id_field 
configuration option used in the example in the Synopsis.

However, the exchange between Matt Trout and Jay Kuri following 
the above message has muddied my understanding and I haven't 
cleared this confusion by reading the source or by reading about 
DBIx::Class's search routine.

So feel freee to ignore this patch if it makes what appears to be 
'widespread' confusion worse.

[drbean at localhost dic]$ diff -u Class.pm.orig Class.pm
--- Class.pm.orig	2008-09-15 17:39:37.000000000 +0800
+++ Class.pm	2008-09-15 17:48:30.000000000 +0800
@@ -127,7 +127,7 @@
         my ( $self, $c ) = @_;
         
         $c->authenticate({  
-                          username => $c->req->params->username,
+                          user_id => $c->req->params->username,
                           password => $c->req->params->password,
                           status => [ 'registered', 'loggedin', 'active']
                           }))
@@ -270,7 +270,7 @@
 is below:
 
     if ($c->authenticate({  
-                          username => $c->req->params->{'username'},
+                          user_id => $c->req->params->{'username'},
                           password => $c->req->params->{'password'},
                           status => [ 'registered', 'active', 'loggedin']
                          })) {
@@ -278,11 +278,12 @@
         # ... authenticated user code here
     }
 
-The above example would attempt to retrieve a user whose username column
-matched the username provided, and whose status column matched one of the
-values provided. These name => value pairs are used more or less directly in
-the DBIx::Class' search() routine, so in most cases, you can use DBIx::Class
-syntax to retrieve the user according to whatever rules you have.
+The above example would attempt to retrieve a user whose username column (here,
+'user_id') matched the username provided, and whose status column matched one
+of the values provided. (The username column name may be specified by the
+id_field configuration option.) These name => value pairs are used more or less
+directly in the DBIx::Class' search() routine, so in most cases, you can use
+DBIx::Class syntax to retrieve the user according to whatever rules you have.
 
 NOTE: Because the password in most cases is encrypted - it is not used
 directly but it's encryption and comparison with the value provided is usually