lib/Catalyst/Plugin/Authentication/User.pm

   1 #!/usr/bin/perl
   2
   3 package Catalyst::Plugin::Authentication::User;
   4
   5 use strict;
   6 use warnings;
   7
   8
   9 ## chances are you want to override this.
  10 sub id { shift->get('id'); }
  11
  12 ## returns the realm the user came from - not a good idea to override this.
  13 sub auth_realm {
  14     my $self = shift;
  15     $self->{'realm'};
  16 }
  17
  18
  19 ## this relies on 'supported_features' being implemented by the subclass..
  20 ## but it is not an error if it is not.  it just means you support nothing.
  21 ## nihilist user objects are welcome here.
  22 sub supports {
  23     my ( $self, @spec ) = @_;
  24
  25     my $cursor = undef;
  26     if ($self->can('supported_features')) {
  27         $cursor = $self->supported_features;
  28
  29         # traverse the feature list,
  30         for (@spec) {
  31             #die "bad feature spec: @spec" if ref($cursor) ne "HASH";
  32             return if ref($cursor) ne "HASH";
  33
  34             $cursor = $cursor->{$_};
  35         }
  36     }
  37
  38     return $cursor;
  39 }
  40
  41 ## REQUIRED.
  42 ## get should return the value of the field specified as it's single argument from the underlying
  43 ## user object.  This is here to provide a simple, standard way of accessing individual elements of a user
  44 ## object - ensuring no overlap between C::P::A::User methods and actual fieldnames.
  45 ## this is not the most effecient method, since it uses introspection.  If you have an underlying object
  46 ## you most likely want to write this yourself.
  47 sub get {
  48     my ($self, $field) = @_;
  49
  50     my $object;
  51     if ($object = $self->get_object && $object->can($field)) {
  52         return $object->$field();
  53     } else {
  54         return undef;
  55     }
  56 }
  57
  58 ## REQUIRED.
  59 ## get_object should return the underlying user object.  This is for when more advanced uses of the
  60 ## user is required.  Modifications to the existing user, etc.  Changes in the object returned
  61 ## by this routine may not be reflected in the C::P::A::User object - if this is required, re-authenticating
  62 ## the user is probably the best route to take.
  63 ## note that it is perfectly acceptable to return $self in cases where there is no underlying object.
  64 sub get_object {
  65     return shift;
  66 }
  67
  68 ## this is an internal routine.  I suggest you don't rely on it's presence.
  69 ## sets the realm the user came from.
  70 sub _set_auth_realm {
  71     my ($self, $realmname) = @_;
  72     $self->{'realm'} = $realmname;
  73 }
  74
  75 ## Backwards Compatibility
  76 ## you probably want auth_realm, in fact.  but this does work for backwards compatibility.
  77 sub store {
  78     my ($self) = @_;
  79     return $self->auth_realm->{store};
  80 }
  81
  82 __PACKAGE__;
  83
  84 __END__
  85
  86 =pod
  87
  88 =head1 NAME
  89
  90 Catalyst::Plugin::Authentication::User - Base class for user objects.
  91
  92 =head1 SYNOPSIS
  93
  94         package MyStore::User;
  95         use base qw/Catalyst::Plugin::Authentication::User/;
  96
  97 =head1 DESCRIPTION
  98
  99 This is the base class for authenticated
 100
 101 =head1 METHODS
 102
 103 =over 4
 104
 105 =item id
 106
 107 A unique ID by which a user can be retrieved from the store.
 108
 109 =item store
 110
 111 Should return a class name that can be used to refetch the user using it's
 112 ID.
 113
 114 =item supports
 115
 116 An introspection method used to determine what features a user object has, to support credential and authorization plugins.
 117
 118 =item
 119
 120 =back
 121
 122 =cut
 123
 124