add docs to realm class

[catagits/Catalyst-Plugin-Authentication.git] / lib / Catalyst / Plugin / Authentication / Realm.pm

diff --git a/lib/Catalyst/Plugin/Authentication/Realm.pm b/lib/Catalyst/Plugin/Authentication/Realm.pm
index d9ec742..23c842d 100644 (file)
--- a/lib/Catalyst/Plugin/Authentication/Realm.pm
+++ b/lib/Catalyst/Plugin/Authentication/Realm.pm
@@ -2,6 +2,7 @@ package Catalyst::Plugin::Authentication::Realm;
 
 use strict;
 use warnings;
+
 use base qw/Class::Accessor::Fast/;
 
 BEGIN {
@@ -17,13 +18,12 @@ sub new {
     $self->name($realmname);
     
     $app->log->debug("Setting up auth realm $realmname") if $app->debug;
-    if (!exists($config->{'store'}{'class'})) {
-        Carp::croak "Couldn't setup the authentication realm named '$realmname', no class defined";
+
+    # use the Null store as a default
+    if( ! exists $config->{store}{class} ) {
+        $config->{store}{class} = '+Catalyst::Plugin::Authentication::Store::Null';
+        $app->log->debug( qq(No Store specified for realm "$realmname", using the Null store.) );
     } 
-        
-    $config->{store}{class} ||= '+Catalyst::Plugin::Authentication::Store::Null';
-    
-    # use the 
     my $storeclass = $config->{'store'}{'class'};
     
     ## follow catalyst class naming - a + prefix means a fully qualified class, otherwise it's
@@ -33,7 +33,6 @@ sub new {
     } else {
         $storeclass = $1;
     }
-    
 
     # a little niceness - since most systems seem to use the password credential class, 
     # if no credential class is specified we use password.
@@ -89,11 +88,11 @@ sub find_user {
     my $res = $self->store->find_user($authinfo, $c);
     
     if (!$res) {
-      if ($self->config->{'auto_create'} && $self->store->can('auto_create') ) {
-          $res = $self->store->auto_create($authinfo, $c);
+      if ($self->config->{'auto_create_user'} && $self->store->can('auto_create_user') ) {
+          $res = $self->store->auto_create_user($authinfo, $c);
       }
-    } elsif ($self->config->{'auto_update'} && $self->store->can('auto_update')) {
-        $res = $self->store->auto_update($authinfo, $c);
+    } elsif ($self->config->{'auto_update_user'} && $self->store->can('auto_update_user')) {
+        $res = $self->store->auto_update_user($authinfo, $c, $res);
     } 
     
     return $res;
@@ -135,4 +134,69 @@ sub from_session {
 
 __PACKAGE__;
 
-__END__
\ No newline at end of file
+__END__
+
+=pod
+
+=head1 NAME
+
+Catalyst::Plugin::Authentication::Realm - Base class for realm objects.
+
+=head1 DESCRIPTION
+
+=head1 CONFIGURATION
+
+=over 4
+
+=item class
+
+By default this class is the default realm class. You can specify a custom
+realm class with this config parameter.
+
+=item auto_create_user
+
+Set this to true if you wish this realm to auto-create user accounts when the
+user doesn't exist (most useful for remote authentication schemes).
+
+=item auto_update_user
+
+Set this to true if you wish this realm to auto-update user accounts after
+authentication (most useful for remote authentication schemes).
+
+=back
+
+=head1 METHODS
+
+=head2 new( )
+
+Instantiantes this realm, plus the specified store and credential classes.
+
+=head2 store( )
+
+Holds an instance of the store object for this realm.
+
+=head2 credential( )
+
+Holds an instance of the credential object for this realm.
+
+=head2 find_user( )
+
+Delegates to the store object. Will also re-delegate auto_create_user and
+auto_update_user at this time, if necessary.
+
+=head2 authenticate( )
+
+Delegates to the credential objects and sets the authenticated user on success.
+
+=head2 save_user_in_session( )
+
+Delegates to the store object.
+
+=head2 from_session( )
+
+Delegates to the store object.
+
+=back
+
+=cut
+